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