1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="surface_augmenter"> 3 4 <copyright> 5 Copyright 2021 The Chromium Authors 6 7 Permission is hereby granted, free of charge, to any person obtaining a 8 copy of this software and associated documentation files (the "Software"), 9 to deal in the Software without restriction, including without limitation 10 the rights to use, copy, modify, merge, publish, distribute, sublicense, 11 and/or sell copies of the Software, and to permit persons to whom the 12 Software is furnished to do so, subject to the following conditions: 13 14 The above copyright notice and this permission notice (including the next 15 paragraph) shall be included in all copies or substantial portions of the 16 Software. 17 18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 21 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 24 DEALINGS IN THE SOFTWARE. 25 </copyright> 26 27 <interface name="surface_augmenter" version="12"> 28 <description summary="surface composition delegation"> 29 The global interface exposing surface delegated composition 30 capabilities is used to instantiate an interface extension for a 31 wl_surface object. This extended interface will then allow 32 delegated compostion of the surface contents, effectively 33 disconnecting the direct relationship between the buffer and the 34 surface content (adding support for solid quads and rounded corner 35 for instance). 36 </description> 37 38 <request name="destroy" type="destructor"> 39 <description summary="Destroy the surface augmenter."> 40 Informs the server that the client will not be using this 41 protocol object anymore. This does not affect any other objects, 42 augmenter objects included. 43 </description> 44 </request> 45 46 <enum name="error"> 47 <entry name="augmented_surface_exists" value="0" 48 summary="the surface already has a augmenter object 49 associated"/> 50 </enum> 51 52 <request name="create_solid_color_buffer"> 53 <description summary="creates a solid color buffer"> 54 Instantiate a buffer of the given size for the purpose of a solid color 55 quad of a given color. 56 57 <!-- Version 12 additions --> 58 This buffer does not require resources in the compositor, so it is immediately 59 reusable and shareable. So it is not responsible for sending wl_buffer.release 60 or zwp_linux_buffer_release_v1.*_release events. 61 </description> 62 <arg name="id" type="new_id" interface="wl_buffer"/> 63 <arg name="color" type="array" summary="quad color represented by a SkColor4f"/> 64 <arg name="width" type="int"/> 65 <arg name="height" type="int"/> 66 </request> 67 68 <request name="get_augmented_surface"> 69 <description summary="extend surface interface for delegation"> 70 Instantiate an interface extension for the given wl_surface to 71 extend composition of its content. If the given wl_surface already has 72 a augmentation object associated, the delegate_exists protocol error is 73 raised. 74 75 <!-- Version 12 additions --> 76 If needs to be called, this must be called before a surface role object is 77 created. 78 </description> 79 <arg name="id" type="new_id" interface="augmented_surface" 80 summary="the new augmenter interface id"/> 81 <arg name="surface" type="object" interface="wl_surface" 82 summary="the surface"/> 83 </request> 84 85 <!-- Version 2 additions --> 86 87 <request name="get_augmented_subsurface" since="2"> 88 <description summary="extend sub surface interface for delegation"> 89 Instantiate an interface extension for the given wl_subsurface to 90 extend composition of its content. If the given wl_subsurface already has 91 a augmentation object associated, the delegate_exists protocol error is 92 raised. 93 </description> 94 <arg name="id" type="new_id" interface="augmented_sub_surface" 95 summary="the new augmenter interface id"/> 96 <arg name="subsurface" type="object" interface="wl_subsurface" 97 summary="the subsurface"/> 98 </request> 99 </interface> 100 101 <interface name="augmented_surface" version="12"> 102 <description summary="delegate composition of a wl_surface"> 103 An additional interface to a wl_surface object, which allows the 104 client to specify the delegated composition of the surface 105 contents. 106 107 <!-- Version 12 additions --> 108 This makes the surface an object only used to composite its parent 109 surface. This means the surface will be clipped to the parent bounds, will 110 not receive input events or display enter/leave events, etc. 111 112 Use wl_subsurface role objects to express which parent surface this will 113 perform delegate composition for. 114 115 The commits to this surface is assumed to behave synchronized with its 116 parent commits, as a synchronized wl_subsurface would. 117 118 The compositor does not perform fine-grained damage extension calculation 119 that is introduced by an augmented_surface moving, resizing, changing 120 stacking, or disappearing. A client performing such operations should 121 account for it and damage the parent non-augmented wl_surface accordingly. 122 123 Various changes like adding or removing an augmented sub-surface, changing 124 its position or stacking order, will not introduce extra damage on the 125 compositor side. The parent wl_surface should account for the extra damage 126 introduced. 127 128 This surface, using a wl_subsurface role of its parent, cannot be stacked 129 relative to non-augmented sub-surfaces of the parent, but can be stacked 130 relative to other augmented children. Nor can this surface have 131 non-augmented sub-surface children. 132 133 A mixed tree structure of using augmented_surfaces to delegate composite 134 wl_surfaces would look like this: 135 136 wl_surface@1:{ augmented_surface@1,2,3 } 137 / \_____ 138 / \ 139 wl_surface@2: wl_surface@3: 140 { augmented_surface@4,5 } { augmented_surface@6 } 141 142 Every wl_surface has a list of augmented_surfaces. Assuming the 143 wl_surface stacking order, from bottom to top, is: 144 wl_surface@1, wl_surface@2, wl_surface@3 145 146 Then the final composition order, from bottom to top, is: 147 wl_surface@1, augmented_surface@1,2,3, wl_surface@2, augmented_surface@4,5, 148 wl_surface@3, augmented_surface@6 149 </description> 150 <request name="destroy" type="destructor"> 151 <description summary="remove delegated composition of the surface"> 152 Client will no longer be able to control the delegated composition properties 153 of this surface. This does not change the existing delegated composition 154 behavior. 155 </description> 156 </request> 157 158 <enum name="error"> 159 <entry name="bad_value" value="0" 160 summary="negative values in radius or size"/> 161 <entry name="no_surface" value="1" 162 summary="the wl_surface was destroyed"/> 163 <entry name="bad_surface" value="2" 164 summary="incompatible surface"/> 165 </enum> 166 167 <request name="set_rounded_corners"> 168 <!-- Note that this might be moved to a different protocol if there is 169 usage for it outside of Chrome OS --> 170 <description summary="set the surface rounded corners"> 171 [Deprecated]. Use set_rounded_corners_clip_bounds request below. 172 173 Informs the server that it must apply the rounded corners 174 mask filter that shall be applied on next commit. Use 175 set_rounded_corners_bounds instead. 176 </description> 177 <arg name="top_left" type="fixed" summary="top left corner"/> 178 <arg name="top_right" type="fixed" summary="top right corner"/> 179 <arg name="bottom_right" type="fixed" summary="bottom right corner"/> 180 <arg name="bottom_left" type="fixed" summary="bottom left corner"/> 181 </request> 182 183 <!-- Version 2 additions --> 184 185 <request name="set_destination_size" since="2"> 186 <description summary="set the surface destination viewport size, with subpixel accuracy"> 187 Sets the surface destination viewport size, with subpixel accuracy. 188 This state is double-buffered, and is applied on the next wl_surface.commit. 189 </description> 190 <arg name="width" type="fixed" summary="width of the surface"/> 191 <arg name="height" type="fixed" summary="height of the surface"/> 192 </request> 193 194 <request name="set_rounded_clip_bounds" since="2"> 195 <!-- Note that this might be moved to a different protocol if there is 196 usage for it outside of Chrome OS --> 197 <description summary="set the surface rounded clip bounds"> 198 [Deprecated]. Use set_rounded_corners_clip_bounds request below. 199 200 Informs the server that it must apply the rounded clipping mask filter 201 that shall be applied on next commit. The mask can be uniform for 202 several surfaces and applied uniformally so that two or more 203 surfaces visually look as a single surface with rounded corners. 204 Please note this is can only be used on surfaces that are used as 205 overlays, which must not have any subtrees. The rounding will be 206 ignored if the bounds are outside of the surface. 207 </description> 208 <arg name="x" type="int"/> 209 <arg name="y" type="int"/> 210 <arg name="width" type="int"/> 211 <arg name="height" type="int"/> 212 <arg name="top_left" type="fixed" summary="top left corner"/> 213 <arg name="top_right" type="fixed" summary="top right corner"/> 214 <arg name="bottom_right" type="fixed" summary="bottom right corner"/> 215 <arg name="bottom_left" type="fixed" summary="bottom left corner"/> 216 </request> 217 218 <!-- Version 3 additions --> 219 220 <request name="set_background_color" since="3"> 221 <description summary="sets a background color of this surface"> 222 Sets a background color of a this surface. This information will be 223 associated with the next buffer commit. Please note this is different 224 from solid color buffers, which creates a new buffer instance, and 225 rather provides additional information how the buffer should be 226 composited. Passing empty array means the background color is reset. 227 The default value is determined by the Wayland compositor then. 228 </description> 229 <arg name="color" type="array" 230 summary="overlay color represented by a SkColor4f"/> 231 </request> 232 233 <!-- Version 6 additions --> 234 235 <request name="set_trusted_damage" since="6"> 236 <description summary="sets the trusted damage state of this surface"> 237 [Deprecated] When set, this surface trusts all damage reported to this 238 surface and descendant sub-surfaces is accurate, and will not try to 239 recompute it. If not set, various changes like adding or removing a 240 sub-surface, changing its position or stacking order, can cause full 241 damage on this surface. 242 243 The initial state is disabled. 244 </description> 245 <arg name="enabled" type="int"/> 246 </request> 247 248 <!-- Version 7 additions --> 249 250 <request name="set_rounded_corners_clip_bounds" since="7"> 251 <!-- Note that this might be moved to a different protocol if there is 252 usage for it outside of Chrome OS --> 253 <description summary="set the surface rounded corners clip bounds"> 254 Informs the server that it must apply the rounded clipping mask filter 255 that shall be applied on next commit. The mask can be uniform for 256 several surfaces and applied uniformally so that two or more 257 surfaces visually look as a single surface with rounded corners. 258 259 Since version 9, the bounds will be placed with its origin (top left 260 corner pixel) at the location x, y of the surface local coordinate 261 system. On version 8 or before, it is placed with its root surface 262 coordinates, but this is deperecated. 263 264 Please note this is can only be used on surfaces that are used as 265 overlays, which must not have any subtrees. The rounding will be 266 ignored if the bounds are outside of the surface. 267 </description> 268 <arg name="x" type="fixed"/> 269 <arg name="y" type="fixed"/> 270 <arg name="width" type="fixed"/> 271 <arg name="height" type="fixed"/> 272 <arg name="top_left" type="fixed" summary="top left corner"/> 273 <arg name="top_right" type="fixed" summary="top right corner"/> 274 <arg name="bottom_right" type="fixed" summary="bottom right corner"/> 275 <arg name="bottom_left" type="fixed" summary="bottom left corner"/> 276 </request> 277 278 <!-- Version 8 additions --> 279 280 <request name="set_clip_rect" since="8"> 281 <description summary="sets a subsurface clip rect on surface local coordinates"> 282 This schedules a clip rect to be applied when drawing this sub-surface. 283 The clip will be placed with its origin (top left corner pixel) at the 284 location x, y of the surface local coordinate system. The coordinates are not 285 restricted to the surface area. Negative x and y values are allowed. 286 287 If all of x, y, width and height are -1.0, the clip rect is unset instead. 288 289 Initially, surfaces have no clip set. 290 This state is double-buffered, and is applied on the next wl_surface.commit. 291 </description> 292 <arg name="x" type="fixed" summary="x coordinate in the surface local coordinates"/> 293 <arg name="y" type="fixed" summary="y coordinate in the surface local coordinates"/> 294 <arg name="width" type="fixed" summary="width of the clip rect"/> 295 <arg name="height" type="fixed" summary="height of the clip rect"/> 296 </request> 297 298 <!-- Version 9 additions --> 299 300 <!-- 301 This version updates `set_rounded_corners_clip_bounds` behavior. 302 No protocol is added for this version. 303 --> 304 305 <!-- Version 10 additions --> 306 307 <!-- 308 This version updates the inner implementation of surface coordinate. 309 No protocol is added for this version. 310 --> 311 312 <!-- Version 11 additions --> 313 <request name="set_frame_trace_id" since="11"> 314 <description summary="sets a trace ID for tracking frame submission flow"> 315 This sets a trace ID to connect the frame submission trace event flow at 316 the client and the server side. 317 This state is double-buffered, and is applied on the next 318 wl_surface.commit. 319 </description> 320 <arg name="id_hi" type="uint" summary="high 32 bits of the trace ID"/> 321 <arg name="id_lo" type="uint" summary="low 32 bits of the trace ID"/> 322 </request> 323 324 </interface> 325 326 <interface name="augmented_sub_surface" version="5"> 327 <description summary="delegate composition of a wl_subsurface"> 328 An additional interface to a wl_subsurface object, which allows the 329 client to specify the delegated composition of the surface 330 contents. 331 </description> 332 <request name="destroy" type="destructor"> 333 <description summary="remove delegated composition of the surface"> 334 The associated wl_surface's augmenter is removed. 335 The change is applied on the next wl_surface.commit. 336 </description> 337 </request> 338 <request name="set_position"> 339 <description summary="sets a subsurface position with subpixel accuracy"> 340 This schedules a sub-surface position change. 341 The sub-surface will be moved so that its origin (top left 342 corner pixel) will be at the location x, y of the parent surface 343 coordinate system. The coordinates are not restricted to the parent 344 surface area. Negative values are allowed. 345 346 The scheduled coordinates will take effect whenever the state of the 347 parent surface is applied. When this happens depends on whether the 348 parent surface is in synchronized mode or not. See 349 wl_subsurface.set_sync and wl_subsurface.set_desync for details. 350 351 If more than one set_position request is invoked by the client before 352 the commit of the parent surface, the position of a new request always 353 replaces the scheduled position from any previous request. 354 355 The initial position is 0, 0. 356 This state is double-buffered, and is applied on the next wl_surface.commit. 357 </description> 358 <arg name="x" type="fixed" summary="x coordinate in the parent surface"/> 359 <arg name="y" type="fixed" summary="y coordinate in the parent surface"/> 360 </request> 361 <request name="set_clip_rect" since="4"> 362 <description summary="sets a subsurface clip rect with subpixel accuracy"> 363 [Deprecated] Use set_clip_rect on augmented_surface instead. 364 This schedules a clip rect to be applied when drawing this sub-surface. 365 The clip will be placed with its origin (top left corner pixel) at the 366 location x, y of the parent surface coordinate system. The coordinates are not 367 restricted to the parent surface area. Negative x and y values are allowed. 368 369 If all of x, y, width and height are -1.0, the clip rect is unset instead. 370 371 Initially, surfaces have no clip set. 372 This state is double-buffered, and is applied on the next wl_surface.commit. 373 </description> 374 <arg name="x" type="fixed" summary="x coordinate in the parent surface"/> 375 <arg name="y" type="fixed" summary="y coordinate in the parent surface"/> 376 <arg name="width" type="fixed" summary="width of the clip rect"/> 377 <arg name="height" type="fixed" summary="height of the clip rect"/> 378 </request> 379 <request name="set_transform" since="5"> 380 <description summary="sets a subsurface transform as an affine matrix"> 381 This schedules a transform to be applied when drawing this sub-surface. 382 This transform does not apply to any child surfaces of this sub-surface. 383 384 The matrix should be passed as an array of 6 floats in column major 385 order. An empty array can be sent to set the transform to the identity 386 matrix. 387 388 The initial transform is identity. 389 This state is double-buffered, and is applied on the next 390 wl_surface.commit. 391 </description> 392 <arg name="matrix" type="array" summary="size 6 affine matrix, or size 0 for identity matrix"/> 393 </request> 394 395 <enum name="error"> 396 <entry name="invalid_size" value="0" 397 summary="array sent with invalid dimensions"/> 398 </enum> 399 </interface> 400 401</protocol> 402