1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="linux_dmabuf_unstable_v1"> 3 4 <copyright> 5 Copyright © 2014, 2015 Collabora, Ltd. 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="zwp_linux_dmabuf_v1" version="3"> 28 <description summary="factory for creating dmabuf-based wl_buffers"> 29 Following the interfaces from: 30 https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt 31 https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt 32 and the Linux DRM sub-system's AddFb2 ioctl. 33 34 This interface offers ways to create generic dmabuf-based 35 wl_buffers. Immediately after a client binds to this interface, 36 the set of supported formats and format modifiers is sent with 37 'format' and 'modifier' events. 38 39 The following are required from clients: 40 41 - Clients must ensure that either all data in the dma-buf is 42 coherent for all subsequent read access or that coherency is 43 correctly handled by the underlying kernel-side dma-buf 44 implementation. 45 46 - Don't make any more attachments after sending the buffer to the 47 compositor. Making more attachments later increases the risk of 48 the compositor not being able to use (re-import) an existing 49 dmabuf-based wl_buffer. 50 51 The underlying graphics stack must ensure the following: 52 53 - The dmabuf file descriptors relayed to the server will stay valid 54 for the whole lifetime of the wl_buffer. This means the server may 55 at any time use those fds to import the dmabuf into any kernel 56 sub-system that might accept it. 57 58 To create a wl_buffer from one or more dmabufs, a client creates a 59 zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params 60 request. All planes required by the intended format are added with 61 the 'add' request. Finally, a 'create' or 'create_immed' request is 62 issued, which has the following outcome depending on the import success. 63 64 The 'create' request, 65 - on success, triggers a 'created' event which provides the final 66 wl_buffer to the client. 67 - on failure, triggers a 'failed' event to convey that the server 68 cannot use the dmabufs received from the client. 69 70 For the 'create_immed' request, 71 - on success, the server immediately imports the added dmabufs to 72 create a wl_buffer. No event is sent from the server in this case. 73 - on failure, the server can choose to either: 74 - terminate the client by raising a fatal error. 75 - mark the wl_buffer as failed, and send a 'failed' event to the 76 client. If the client uses a failed wl_buffer as an argument to any 77 request, the behaviour is compositor implementation-defined. 78 79 Warning! The protocol described in this file is experimental and 80 backward incompatible changes may be made. Backward compatible changes 81 may be added together with the corresponding interface version bump. 82 Backward incompatible changes are done by bumping the version number in 83 the protocol and interface names and resetting the interface version. 84 Once the protocol is to be declared stable, the 'z' prefix and the 85 version number in the protocol and interface names are removed and the 86 interface version number is reset. 87 </description> 88 89 <request name="destroy" type="destructor"> 90 <description summary="unbind the factory"> 91 Objects created through this interface, especially wl_buffers, will 92 remain valid. 93 </description> 94 </request> 95 96 <request name="create_params"> 97 <description summary="create a temporary object for buffer parameters"> 98 This temporary object is used to collect multiple dmabuf handles into 99 a single batch to create a wl_buffer. It can only be used once and 100 should be destroyed after a 'created' or 'failed' event has been 101 received. 102 </description> 103 <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1" 104 summary="the new temporary"/> 105 </request> 106 107 <event name="format"> 108 <description summary="supported buffer format"> 109 This event advertises one buffer format that the server supports. 110 All the supported formats are advertised once when the client 111 binds to this interface. A roundtrip after binding guarantees 112 that the client has received all supported formats. 113 114 For the definition of the format codes, see the 115 zwp_linux_buffer_params_v1::create request. 116 117 Warning: the 'format' event is likely to be deprecated and replaced 118 with the 'modifier' event introduced in zwp_linux_dmabuf_v1 119 version 3, described below. Please refrain from using the information 120 received from this event. 121 </description> 122 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 123 </event> 124 125 <event name="modifier" since="3"> 126 <description summary="supported buffer format modifier"> 127 This event advertises the formats that the server supports, along with 128 the modifiers supported for each format. All the supported modifiers 129 for all the supported formats are advertised once when the client 130 binds to this interface. A roundtrip after binding guarantees that 131 the client has received all supported format-modifier pairs. 132 133 For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == 134 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. 135 It indicates that the server can support the format with an implicit 136 modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it 137 is as if no explicit modifier is specified. The effective modifier 138 will be derived from the dmabuf. 139 140 For the definition of the format and modifier codes, see the 141 zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add 142 requests. 143 </description> 144 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 145 <arg name="modifier_hi" type="uint" 146 summary="high 32 bits of layout modifier"/> 147 <arg name="modifier_lo" type="uint" 148 summary="low 32 bits of layout modifier"/> 149 </event> 150 </interface> 151 152 <interface name="zwp_linux_buffer_params_v1" version="3"> 153 <description summary="parameters for creating a dmabuf-based wl_buffer"> 154 This temporary object is a collection of dmabufs and other 155 parameters that together form a single logical buffer. The temporary 156 object may eventually create one wl_buffer unless cancelled by 157 destroying it before requesting 'create'. 158 159 Single-planar formats only require one dmabuf, however 160 multi-planar formats may require more than one dmabuf. For all 161 formats, an 'add' request must be called once per plane (even if the 162 underlying dmabuf fd is identical). 163 164 You must use consecutive plane indices ('plane_idx' argument for 'add') 165 from zero to the number of planes used by the drm_fourcc format code. 166 All planes required by the format must be given exactly once, but can 167 be given in any order. Each plane index can be set only once. 168 </description> 169 170 <enum name="error"> 171 <entry name="already_used" value="0" 172 summary="the dmabuf_batch object has already been used to create a wl_buffer"/> 173 <entry name="plane_idx" value="1" 174 summary="plane index out of bounds"/> 175 <entry name="plane_set" value="2" 176 summary="the plane index was already set"/> 177 <entry name="incomplete" value="3" 178 summary="missing or too many planes to create a buffer"/> 179 <entry name="invalid_format" value="4" 180 summary="format not supported"/> 181 <entry name="invalid_dimensions" value="5" 182 summary="invalid width or height"/> 183 <entry name="out_of_bounds" value="6" 184 summary="offset + stride * height goes out of dmabuf bounds"/> 185 <entry name="invalid_wl_buffer" value="7" 186 summary="invalid wl_buffer resulted from importing dmabufs via 187 the create_immed request on given buffer_params"/> 188 </enum> 189 190 <request name="destroy" type="destructor"> 191 <description summary="delete this object, used or not"> 192 Cleans up the temporary data sent to the server for dmabuf-based 193 wl_buffer creation. 194 </description> 195 </request> 196 197 <request name="add"> 198 <description summary="add a dmabuf to the temporary set"> 199 This request adds one dmabuf to the set in this 200 zwp_linux_buffer_params_v1. 201 202 The 64-bit unsigned value combined from modifier_hi and modifier_lo 203 is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the 204 fb modifier, which is defined in drm_mode.h of Linux UAPI. 205 This is an opaque token. Drivers use this token to express tiling, 206 compression, etc. driver-specific modifications to the base format 207 defined by the DRM fourcc code. 208 209 Warning: It should be an error if the format/modifier pair was not 210 advertised with the modifier event. This is not enforced yet because 211 some implementations always accept DRM_FORMAT_MOD_INVALID. Also 212 version 2 of this protocol does not have the modifier event. 213 214 This request raises the PLANE_IDX error if plane_idx is too large. 215 The error PLANE_SET is raised if attempting to set a plane that 216 was already set. 217 </description> 218 <arg name="fd" type="fd" summary="dmabuf fd"/> 219 <arg name="plane_idx" type="uint" summary="plane index"/> 220 <arg name="offset" type="uint" summary="offset in bytes"/> 221 <arg name="stride" type="uint" summary="stride in bytes"/> 222 <arg name="modifier_hi" type="uint" 223 summary="high 32 bits of layout modifier"/> 224 <arg name="modifier_lo" type="uint" 225 summary="low 32 bits of layout modifier"/> 226 </request> 227 228 <enum name="flags" bitfield="true"> 229 <entry name="y_invert" value="1" summary="contents are y-inverted"/> 230 <entry name="interlaced" value="2" summary="content is interlaced"/> 231 <entry name="bottom_first" value="4" summary="bottom field first"/> 232 </enum> 233 234 <request name="create"> 235 <description summary="create a wl_buffer from the given dmabufs"> 236 This asks for creation of a wl_buffer from the added dmabuf 237 buffers. The wl_buffer is not created immediately but returned via 238 the 'created' event if the dmabuf sharing succeeds. The sharing 239 may fail at runtime for reasons a client cannot predict, in 240 which case the 'failed' event is triggered. 241 242 The 'format' argument is a DRM_FORMAT code, as defined by the 243 libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the 244 authoritative source on how the format codes should work. 245 246 The 'flags' is a bitfield of the flags defined in enum "flags". 247 'y_invert' means the that the image needs to be y-flipped. 248 249 Flag 'interlaced' means that the frame in the buffer is not 250 progressive as usual, but interlaced. An interlaced buffer as 251 supported here must always contain both top and bottom fields. 252 The top field always begins on the first pixel row. The temporal 253 ordering between the two fields is top field first, unless 254 'bottom_first' is specified. It is undefined whether 'bottom_first' 255 is ignored if 'interlaced' is not set. 256 257 This protocol does not convey any information about field rate, 258 duration, or timing, other than the relative ordering between the 259 two fields in one buffer. A compositor may have to estimate the 260 intended field rate from the incoming buffer rate. It is undefined 261 whether the time of receiving wl_surface.commit with a new buffer 262 attached, applying the wl_surface state, wl_surface.frame callback 263 trigger, presentation, or any other point in the compositor cycle 264 is used to measure the frame or field times. There is no support 265 for detecting missed or late frames/fields/buffers either, and 266 there is no support whatsoever for cooperating with interlaced 267 compositor output. 268 269 The composited image quality resulting from the use of interlaced 270 buffers is explicitly undefined. A compositor may use elaborate 271 hardware features or software to deinterlace and create progressive 272 output frames from a sequence of interlaced input buffers, or it 273 may produce substandard image quality. However, compositors that 274 cannot guarantee reasonable image quality in all cases are recommended 275 to just reject all interlaced buffers. 276 277 Any argument errors, including non-positive width or height, 278 mismatch between the number of planes and the format, bad 279 format, bad offset or stride, may be indicated by fatal protocol 280 errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, 281 OUT_OF_BOUNDS. 282 283 Dmabuf import errors in the server that are not obvious client 284 bugs are returned via the 'failed' event as non-fatal. This 285 allows attempting dmabuf sharing and falling back in the client 286 if it fails. 287 288 This request can be sent only once in the object's lifetime, after 289 which the only legal request is destroy. This object should be 290 destroyed after issuing a 'create' request. Attempting to use this 291 object after issuing 'create' raises ALREADY_USED protocol error. 292 293 It is not mandatory to issue 'create'. If a client wants to 294 cancel the buffer creation, it can just destroy this object. 295 </description> 296 <arg name="width" type="int" summary="base plane width in pixels"/> 297 <arg name="height" type="int" summary="base plane height in pixels"/> 298 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 299 <arg name="flags" type="uint" enum="flags" summary="see enum flags"/> 300 </request> 301 302 <event name="created"> 303 <description summary="buffer creation succeeded"> 304 This event indicates that the attempted buffer creation was 305 successful. It provides the new wl_buffer referencing the dmabuf(s). 306 307 Upon receiving this event, the client should destroy the 308 zlinux_dmabuf_params object. 309 </description> 310 <arg name="buffer" type="new_id" interface="wl_buffer" 311 summary="the newly created wl_buffer"/> 312 </event> 313 314 <event name="failed"> 315 <description summary="buffer creation failed"> 316 This event indicates that the attempted buffer creation has 317 failed. It usually means that one of the dmabuf constraints 318 has not been fulfilled. 319 320 Upon receiving this event, the client should destroy the 321 zlinux_buffer_params object. 322 </description> 323 </event> 324 325 <request name="create_immed" since="2"> 326 <description summary="immediately create a wl_buffer from the given 327 dmabufs"> 328 This asks for immediate creation of a wl_buffer by importing the 329 added dmabufs. 330 331 In case of import success, no event is sent from the server, and the 332 wl_buffer is ready to be used by the client. 333 334 Upon import failure, either of the following may happen, as seen fit 335 by the implementation: 336 - the client is terminated with one of the following fatal protocol 337 errors: 338 - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, 339 in case of argument errors such as mismatch between the number 340 of planes and the format, bad format, non-positive width or 341 height, or bad offset or stride. 342 - INVALID_WL_BUFFER, in case the cause for failure is unknown or 343 plaform specific. 344 - the server creates an invalid wl_buffer, marks it as failed and 345 sends a 'failed' event to the client. The result of using this 346 invalid wl_buffer as an argument in any request by the client is 347 defined by the compositor implementation. 348 349 This takes the same arguments as a 'create' request, and obeys the 350 same restrictions. 351 </description> 352 <arg name="buffer_id" type="new_id" interface="wl_buffer" 353 summary="id for the newly created wl_buffer"/> 354 <arg name="width" type="int" summary="base plane width in pixels"/> 355 <arg name="height" type="int" summary="base plane height in pixels"/> 356 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 357 <arg name="flags" type="uint" enum="flags" summary="see enum flags"/> 358 </request> 359 360 </interface> 361 362</protocol> 363