| 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="5"> |
| 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 wl_buffers. |
| 35 |
|
| 36 |
Clients can use the get_surface_feedback request to get dmabuf feedback |
| 37 |
for a particular surface. If the client wants to retrieve feedback not |
| 38 |
tied to a surface, they can use the get_default_feedback request. |
| 39 |
|
| 40 |
The following are required from clients: |
| 41 |
|
| 42 |
- Clients must ensure that either all data in the dma-buf is |
| 43 |
coherent for all subsequent read access or that coherency is |
| 44 |
correctly handled by the underlying kernel-side dma-buf |
| 45 |
implementation. |
| 46 |
|
| 47 |
- Don't make any more attachments after sending the buffer to the |
| 48 |
compositor. Making more attachments later increases the risk of |
| 49 |
the compositor not being able to use (re-import) an existing |
| 50 |
dmabuf-based wl_buffer. |
| 51 |
|
| 52 |
The underlying graphics stack must ensure the following: |
| 53 |
|
| 54 |
- The dmabuf file descriptors relayed to the server will stay valid |
| 55 |
for the whole lifetime of the wl_buffer. This means the server may |
| 56 |
at any time use those fds to import the dmabuf into any kernel |
| 57 |
sub-system that might accept it. |
| 58 |
|
| 59 |
However, when the underlying graphics stack fails to deliver the |
| 60 |
promise, because of e.g. a device hot-unplug which raises internal |
| 61 |
errors, after the wl_buffer has been successfully created the |
| 62 |
compositor must not raise protocol errors to the client when dmabuf |
| 63 |
import later fails. |
| 64 |
|
| 65 |
To create a wl_buffer from one or more dmabufs, a client creates a |
| 66 |
zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params |
| 67 |
request. All planes required by the intended format are added with |
| 68 |
the 'add' request. Finally, a 'create' or 'create_immed' request is |
| 69 |
issued, which has the following outcome depending on the import success. |
| 70 |
|
| 71 |
The 'create' request, |
| 72 |
- on success, triggers a 'created' event which provides the final |
| 73 |
wl_buffer to the client. |
| 74 |
- on failure, triggers a 'failed' event to convey that the server |
| 75 |
cannot use the dmabufs received from the client. |
| 76 |
|
| 77 |
For the 'create_immed' request, |
| 78 |
- on success, the server immediately imports the added dmabufs to |
| 79 |
create a wl_buffer. No event is sent from the server in this case. |
| 80 |
- on failure, the server can choose to either: |
| 81 |
- terminate the client by raising a fatal error. |
| 82 |
- mark the wl_buffer as failed, and send a 'failed' event to the |
| 83 |
client. If the client uses a failed wl_buffer as an argument to any |
| 84 |
request, the behaviour is compositor implementation-defined. |
| 85 |
|
| 86 |
For all DRM formats and unless specified in another protocol extension, |
| 87 |
pre-multiplied alpha is used for pixel values. |
| 88 |
|
| 89 |
Unless specified otherwise in another protocol extension, implicit |
| 90 |
synchronization is used. In other words, compositors and clients must |
| 91 |
wait and signal fences implicitly passed via the DMA-BUF's reservation |
| 92 |
mechanism. |
| 93 |
|
| 94 |
Disclaimer: This protocol extension has been marked stable. This copy is |
| 95 |
no longer used and only retained for backwards compatibility. The |
| 96 |
canonical version can be found in the stable/ directory. |
| 97 |
</description> |
| 98 |
|
| 99 |
<request name="destroy" type="destructor"> |
| 100 |
<description summary="unbind the factory"> |
| 101 |
Objects created through this interface, especially wl_buffers, will |
| 102 |
remain valid. |
| 103 |
</description> |
| 104 |
</request> |
| 105 |
|
| 106 |
<request name="create_params"> |
| 107 |
<description summary="create a temporary object for buffer parameters"> |
| 108 |
This temporary object is used to collect multiple dmabuf handles into |
| 109 |
a single batch to create a wl_buffer. It can only be used once and |
| 110 |
should be destroyed after a 'created' or 'failed' event has been |
| 111 |
received. |
| 112 |
</description> |
| 113 |
<arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1" |
| 114 |
summary="the new temporary"/> |
| 115 |
</request> |
| 116 |
|
| 117 |
<event name="format"> |
| 118 |
<description summary="supported buffer format"> |
| 119 |
This event advertises one buffer format that the server supports. |
| 120 |
All the supported formats are advertised once when the client |
| 121 |
binds to this interface. A roundtrip after binding guarantees |
| 122 |
that the client has received all supported formats. |
| 123 |
|
| 124 |
For the definition of the format codes, see the |
| 125 |
zwp_linux_buffer_params_v1::create request. |
| 126 |
|
| 127 |
Starting version 4, the format event is deprecated and must not be |
| 128 |
sent by compositors. Instead, use get_default_feedback or |
| 129 |
get_surface_feedback. |
| 130 |
</description> |
| 131 |
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
| 132 |
</event> |
| 133 |
|
| 134 |
<event name="modifier" since="3"> |
| 135 |
<description summary="supported buffer format modifier"> |
| 136 |
This event advertises the formats that the server supports, along with |
| 137 |
the modifiers supported for each format. All the supported modifiers |
| 138 |
for all the supported formats are advertised once when the client |
| 139 |
binds to this interface. A roundtrip after binding guarantees that |
| 140 |
the client has received all supported format-modifier pairs. |
| 141 |
|
| 142 |
For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == |
| 143 |
0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. |
| 144 |
It indicates that the server can support the format with an implicit |
| 145 |
modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it |
| 146 |
is as if no explicit modifier is specified. The effective modifier |
| 147 |
will be derived from the dmabuf. |
| 148 |
|
| 149 |
A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for |
| 150 |
a given format supports both explicit modifiers and implicit modifiers. |
| 151 |
|
| 152 |
For the definition of the format and modifier codes, see the |
| 153 |
zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add |
| 154 |
requests. |
| 155 |
|
| 156 |
Starting version 4, the modifier event is deprecated and must not be |
| 157 |
sent by compositors. Instead, use get_default_feedback or |
| 158 |
get_surface_feedback. |
| 159 |
</description> |
| 160 |
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
| 161 |
<arg name="modifier_hi" type="uint" |
| 162 |
summary="high 32 bits of layout modifier"/> |
| 163 |
<arg name="modifier_lo" type="uint" |
| 164 |
summary="low 32 bits of layout modifier"/> |
| 165 |
</event> |
| 166 |
|
| 167 |
<!-- Version 4 additions --> |
| 168 |
|
| 169 |
<request name="get_default_feedback" since="4"> |
| 170 |
<description summary="get default feedback"> |
| 171 |
This request creates a new wp_linux_dmabuf_feedback object not bound |
| 172 |
to a particular surface. This object will deliver feedback about dmabuf |
| 173 |
parameters to use if the client doesn't support per-surface feedback |
| 174 |
(see get_surface_feedback). |
| 175 |
</description> |
| 176 |
<arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/> |
| 177 |
</request> |
| 178 |
|
| 179 |
<request name="get_surface_feedback" since="4"> |
| 180 |
<description summary="get feedback for a surface"> |
| 181 |
This request creates a new wp_linux_dmabuf_feedback object for the |
| 182 |
specified wl_surface. This object will deliver feedback about dmabuf |
| 183 |
parameters to use for buffers attached to this surface. |
| 184 |
|
| 185 |
If the surface is destroyed before the wp_linux_dmabuf_feedback object, |
| 186 |
the feedback object becomes inert. |
| 187 |
</description> |
| 188 |
<arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/> |
| 189 |
<arg name="surface" type="object" interface="wl_surface"/> |
| 190 |
</request> |
| 191 |
</interface> |
| 192 |
|
| 193 |
<interface name="zwp_linux_buffer_params_v1" version="5"> |
| 194 |
<description summary="parameters for creating a dmabuf-based wl_buffer"> |
| 195 |
This temporary object is a collection of dmabufs and other |
| 196 |
parameters that together form a single logical buffer. The temporary |
| 197 |
object may eventually create one wl_buffer unless cancelled by |
| 198 |
destroying it before requesting 'create'. |
| 199 |
|
| 200 |
Single-planar formats only require one dmabuf, however |
| 201 |
multi-planar formats may require more than one dmabuf. For all |
| 202 |
formats, an 'add' request must be called once per plane (even if the |
| 203 |
underlying dmabuf fd is identical). |
| 204 |
|
| 205 |
You must use consecutive plane indices ('plane_idx' argument for 'add') |
| 206 |
from zero to the number of planes used by the drm_fourcc format code. |
| 207 |
All planes required by the format must be given exactly once, but can |
| 208 |
be given in any order. Each plane index can be set only once. |
| 209 |
</description> |
| 210 |
|
| 211 |
<enum name="error"> |
| 212 |
<entry name="already_used" value="0" |
| 213 |
summary="the dmabuf_batch object has already been used to create a wl_buffer"/> |
| 214 |
<entry name="plane_idx" value="1" |
| 215 |
summary="plane index out of bounds"/> |
| 216 |
<entry name="plane_set" value="2" |
| 217 |
summary="the plane index was already set"/> |
| 218 |
<entry name="incomplete" value="3" |
| 219 |
summary="missing or too many planes to create a buffer"/> |
| 220 |
<entry name="invalid_format" value="4" |
| 221 |
summary="format not supported"/> |
| 222 |
<entry name="invalid_dimensions" value="5" |
| 223 |
summary="invalid width or height"/> |
| 224 |
<entry name="out_of_bounds" value="6" |
| 225 |
summary="offset + stride * height goes out of dmabuf bounds"/> |
| 226 |
<entry name="invalid_wl_buffer" value="7" |
| 227 |
summary="invalid wl_buffer resulted from importing dmabufs via |
| 228 |
the create_immed request on given buffer_params"/> |
| 229 |
</enum> |
| 230 |
|
| 231 |
<request name="destroy" type="destructor"> |
| 232 |
<description summary="delete this object, used or not"> |
| 233 |
Cleans up the temporary data sent to the server for dmabuf-based |
| 234 |
wl_buffer creation. |
| 235 |
</description> |
| 236 |
</request> |
| 237 |
|
| 238 |
<request name="add"> |
| 239 |
<description summary="add a dmabuf to the temporary set"> |
| 240 |
This request adds one dmabuf to the set in this |
| 241 |
zwp_linux_buffer_params_v1. |
| 242 |
|
| 243 |
The 64-bit unsigned value combined from modifier_hi and modifier_lo |
| 244 |
is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the |
| 245 |
fb modifier, which is defined in drm_mode.h of Linux UAPI. |
| 246 |
This is an opaque token. Drivers use this token to express tiling, |
| 247 |
compression, etc. driver-specific modifications to the base format |
| 248 |
defined by the DRM fourcc code. |
| 249 |
|
| 250 |
Starting from version 4, the invalid_format protocol error is sent if |
| 251 |
the format + modifier pair was not advertised as supported. |
| 252 |
|
| 253 |
Starting from version 5, the invalid_format protocol error is sent if |
| 254 |
all planes don't use the same modifier. |
| 255 |
|
| 256 |
This request raises the PLANE_IDX error if plane_idx is too large. |
| 257 |
The error PLANE_SET is raised if attempting to set a plane that |
| 258 |
was already set. |
| 259 |
</description> |
| 260 |
<arg name="fd" type="fd" summary="dmabuf fd"/> |
| 261 |
<arg name="plane_idx" type="uint" summary="plane index"/> |
| 262 |
<arg name="offset" type="uint" summary="offset in bytes"/> |
| 263 |
<arg name="stride" type="uint" summary="stride in bytes"/> |
| 264 |
<arg name="modifier_hi" type="uint" |
| 265 |
summary="high 32 bits of layout modifier"/> |
| 266 |
<arg name="modifier_lo" type="uint" |
| 267 |
summary="low 32 bits of layout modifier"/> |
| 268 |
</request> |
| 269 |
|
| 270 |
<enum name="flags" bitfield="true"> |
| 271 |
<entry name="y_invert" value="1" summary="contents are y-inverted"/> |
| 272 |
<entry name="interlaced" value="2" summary="content is interlaced"/> |
| 273 |
<entry name="bottom_first" value="4" summary="bottom field first"/> |
| 274 |
</enum> |
| 275 |
|
| 276 |
<request name="create"> |
| 277 |
<description summary="create a wl_buffer from the given dmabufs"> |
| 278 |
This asks for creation of a wl_buffer from the added dmabuf |
| 279 |
buffers. The wl_buffer is not created immediately but returned via |
| 280 |
the 'created' event if the dmabuf sharing succeeds. The sharing |
| 281 |
may fail at runtime for reasons a client cannot predict, in |
| 282 |
which case the 'failed' event is triggered. |
| 283 |
|
| 284 |
The 'format' argument is a DRM_FORMAT code, as defined by the |
| 285 |
libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the |
| 286 |
authoritative source on how the format codes should work. |
| 287 |
|
| 288 |
The 'flags' is a bitfield of the flags defined in enum "flags". |
| 289 |
'y_invert' means the that the image needs to be y-flipped. |
| 290 |
|
| 291 |
Flag 'interlaced' means that the frame in the buffer is not |
| 292 |
progressive as usual, but interlaced. An interlaced buffer as |
| 293 |
supported here must always contain both top and bottom fields. |
| 294 |
The top field always begins on the first pixel row. The temporal |
| 295 |
ordering between the two fields is top field first, unless |
| 296 |
'bottom_first' is specified. It is undefined whether 'bottom_first' |
| 297 |
is ignored if 'interlaced' is not set. |
| 298 |
|
| 299 |
This protocol does not convey any information about field rate, |
| 300 |
duration, or timing, other than the relative ordering between the |
| 301 |
two fields in one buffer. A compositor may have to estimate the |
| 302 |
intended field rate from the incoming buffer rate. It is undefined |
| 303 |
whether the time of receiving wl_surface.commit with a new buffer |
| 304 |
attached, applying the wl_surface state, wl_surface.frame callback |
| 305 |
trigger, presentation, or any other point in the compositor cycle |
| 306 |
is used to measure the frame or field times. There is no support |
| 307 |
for detecting missed or late frames/fields/buffers either, and |
| 308 |
there is no support whatsoever for cooperating with interlaced |
| 309 |
compositor output. |
| 310 |
|
| 311 |
The composited image quality resulting from the use of interlaced |
| 312 |
buffers is explicitly undefined. A compositor may use elaborate |
| 313 |
hardware features or software to deinterlace and create progressive |
| 314 |
output frames from a sequence of interlaced input buffers, or it |
| 315 |
may produce substandard image quality. However, compositors that |
| 316 |
cannot guarantee reasonable image quality in all cases are recommended |
| 317 |
to just reject all interlaced buffers. |
| 318 |
|
| 319 |
Any argument errors, including non-positive width or height, |
| 320 |
mismatch between the number of planes and the format, bad |
| 321 |
format, bad offset or stride, may be indicated by fatal protocol |
| 322 |
errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, |
| 323 |
OUT_OF_BOUNDS. |
| 324 |
|
| 325 |
Dmabuf import errors in the server that are not obvious client |
| 326 |
bugs are returned via the 'failed' event as non-fatal. This |
| 327 |
allows attempting dmabuf sharing and falling back in the client |
| 328 |
if it fails. |
| 329 |
|
| 330 |
This request can be sent only once in the object's lifetime, after |
| 331 |
which the only legal request is destroy. This object should be |
| 332 |
destroyed after issuing a 'create' request. Attempting to use this |
| 333 |
object after issuing 'create' raises ALREADY_USED protocol error. |
| 334 |
|
| 335 |
It is not mandatory to issue 'create'. If a client wants to |
| 336 |
cancel the buffer creation, it can just destroy this object. |
| 337 |
</description> |
| 338 |
<arg name="width" type="int" summary="base plane width in pixels"/> |
| 339 |
<arg name="height" type="int" summary="base plane height in pixels"/> |
| 340 |
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
| 341 |
<arg name="flags" type="uint" enum="flags" summary="see enum flags"/> |
| 342 |
</request> |
| 343 |
|
| 344 |
<event name="created"> |
| 345 |
<description summary="buffer creation succeeded"> |
| 346 |
This event indicates that the attempted buffer creation was |
| 347 |
successful. It provides the new wl_buffer referencing the dmabuf(s). |
| 348 |
|
| 349 |
Upon receiving this event, the client should destroy the |
| 350 |
zwp_linux_buffer_params_v1 object. |
| 351 |
</description> |
| 352 |
<arg name="buffer" type="new_id" interface="wl_buffer" |
| 353 |
summary="the newly created wl_buffer"/> |
| 354 |
</event> |
| 355 |
|
| 356 |
<event name="failed"> |
| 357 |
<description summary="buffer creation failed"> |
| 358 |
This event indicates that the attempted buffer creation has |
| 359 |
failed. It usually means that one of the dmabuf constraints |
| 360 |
has not been fulfilled. |
| 361 |
|
| 362 |
Upon receiving this event, the client should destroy the |
| 363 |
zwp_linux_buffer_params_v1 object. |
| 364 |
</description> |
| 365 |
</event> |
| 366 |
|
| 367 |
<request name="create_immed" since="2"> |
| 368 |
<description summary="immediately create a wl_buffer from the given |
| 369 |
dmabufs"> |
| 370 |
This asks for immediate creation of a wl_buffer by importing the |
| 371 |
added dmabufs. |
| 372 |
|
| 373 |
In case of import success, no event is sent from the server, and the |
| 374 |
wl_buffer is ready to be used by the client. |
| 375 |
|
| 376 |
Upon import failure, either of the following may happen, as seen fit |
| 377 |
by the implementation: |
| 378 |
- the client is terminated with one of the following fatal protocol |
| 379 |
errors: |
| 380 |
- INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, |
| 381 |
in case of argument errors such as mismatch between the number |
| 382 |
of planes and the format, bad format, non-positive width or |
| 383 |
height, or bad offset or stride. |
| 384 |
- INVALID_WL_BUFFER, in case the cause for failure is unknown or |
| 385 |
platform specific. |
| 386 |
- the server creates an invalid wl_buffer, marks it as failed and |
| 387 |
sends a 'failed' event to the client. The result of using this |
| 388 |
invalid wl_buffer as an argument in any request by the client is |
| 389 |
defined by the compositor implementation. |
| 390 |
|
| 391 |
This takes the same arguments as a 'create' request, and obeys the |
| 392 |
same restrictions. |
| 393 |
</description> |
| 394 |
<arg name="buffer_id" type="new_id" interface="wl_buffer" |
| 395 |
summary="id for the newly created wl_buffer"/> |
| 396 |
<arg name="width" type="int" summary="base plane width in pixels"/> |
| 397 |
<arg name="height" type="int" summary="base plane height in pixels"/> |
| 398 |
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
| 399 |
<arg name="flags" type="uint" enum="flags" summary="see enum flags"/> |
| 400 |
</request> |
| 401 |
</interface> |
| 402 |
|
| 403 |
<interface name="zwp_linux_dmabuf_feedback_v1" version="5"> |
| 404 |
<description summary="dmabuf feedback"> |
| 405 |
This object advertises dmabuf parameters feedback. This includes the |
| 406 |
preferred devices and the supported formats/modifiers. |
| 407 |
|
| 408 |
The parameters are sent once when this object is created and whenever they |
| 409 |
change. The done event is always sent once after all parameters have been |
| 410 |
sent. When a single parameter changes, all parameters are re-sent by the |
| 411 |
compositor. |
| 412 |
|
| 413 |
Compositors can re-send the parameters when the current client buffer |
| 414 |
allocations are sub-optimal. Compositors should not re-send the |
| 415 |
parameters if re-allocating the buffers would not result in a more optimal |
| 416 |
configuration. In particular, compositors should avoid sending the exact |
| 417 |
same parameters multiple times in a row. |
| 418 |
|
| 419 |
The tranche_target_device and tranche_formats events are grouped by |
| 420 |
tranches of preference. For each tranche, a tranche_target_device, one |
| 421 |
tranche_flags and one or more tranche_formats events are sent, followed |
| 422 |
by a tranche_done event finishing the list. The tranches are sent in |
| 423 |
descending order of preference. All formats and modifiers in the same |
| 424 |
tranche have the same preference. |
| 425 |
|
| 426 |
To send parameters, the compositor sends one main_device event, tranches |
| 427 |
(each consisting of one tranche_target_device event, one tranche_flags |
| 428 |
event, tranche_formats events and then a tranche_done event), then one |
| 429 |
done event. |
| 430 |
</description> |
| 431 |
|
| 432 |
<request name="destroy" type="destructor"> |
| 433 |
<description summary="destroy the feedback object"> |
| 434 |
Using this request a client can tell the server that it is not going to |
| 435 |
use the wp_linux_dmabuf_feedback object anymore. |
| 436 |
</description> |
| 437 |
</request> |
| 438 |
|
| 439 |
<event name="done"> |
| 440 |
<description summary="all feedback has been sent"> |
| 441 |
This event is sent after all parameters of a wp_linux_dmabuf_feedback |
| 442 |
object have been sent. |
| 443 |
|
| 444 |
This allows changes to the wp_linux_dmabuf_feedback parameters to be |
| 445 |
seen as atomic, even if they happen via multiple events. |
| 446 |
</description> |
| 447 |
</event> |
| 448 |
|
| 449 |
<event name="format_table"> |
| 450 |
<description summary="format and modifier table"> |
| 451 |
This event provides a file descriptor which can be memory-mapped to |
| 452 |
access the format and modifier table. |
| 453 |
|
| 454 |
The table contains a tightly packed array of consecutive format + |
| 455 |
modifier pairs. Each pair is 16 bytes wide. It contains a format as a |
| 456 |
32-bit unsigned integer, followed by 4 bytes of unused padding, and a |
| 457 |
modifier as a 64-bit unsigned integer. The native endianness is used. |
| 458 |
|
| 459 |
The client must map the file descriptor in read-only private mode. |
| 460 |
|
| 461 |
Compositors are not allowed to mutate the table file contents once this |
| 462 |
event has been sent. Instead, compositors must create a new, separate |
| 463 |
table file and re-send feedback parameters. Compositors are allowed to |
| 464 |
store duplicate format + modifier pairs in the table. |
| 465 |
</description> |
| 466 |
<arg name="fd" type="fd" summary="table file descriptor"/> |
| 467 |
<arg name="size" type="uint" summary="table size, in bytes"/> |
| 468 |
</event> |
| 469 |
|
| 470 |
<event name="main_device"> |
| 471 |
<description summary="preferred main device"> |
| 472 |
This event advertises the main device that the server prefers to use |
| 473 |
when direct scan-out to the target device isn't possible. The |
| 474 |
advertised main device may be different for each |
| 475 |
wp_linux_dmabuf_feedback object, and may change over time. |
| 476 |
|
| 477 |
There is exactly one main device. The compositor must send at least |
| 478 |
one preference tranche with tranche_target_device equal to main_device. |
| 479 |
|
| 480 |
Clients need to create buffers that the main device can import and |
| 481 |
read from, otherwise creating the dmabuf wl_buffer will fail (see the |
| 482 |
wp_linux_buffer_params.create and create_immed requests for details). |
| 483 |
The main device will also likely be kept active by the compositor, |
| 484 |
so clients can use it instead of waking up another device for power |
| 485 |
savings. |
| 486 |
|
| 487 |
In general the device is a DRM node. The DRM node type (primary vs. |
| 488 |
render) is unspecified. Clients must not rely on the compositor sending |
| 489 |
a particular node type. Clients cannot check two devices for equality |
| 490 |
by comparing the dev_t value. |
| 491 |
|
| 492 |
If explicit modifiers are not supported and the client performs buffer |
| 493 |
allocations on a different device than the main device, then the client |
| 494 |
must force the buffer to have a linear layout. |
| 495 |
</description> |
| 496 |
<arg name="device" type="array" summary="device dev_t value"/> |
| 497 |
</event> |
| 498 |
|
| 499 |
<event name="tranche_done"> |
| 500 |
<description summary="a preference tranche has been sent"> |
| 501 |
This event splits tranche_target_device and tranche_formats events in |
| 502 |
preference tranches. It is sent after a set of tranche_target_device |
| 503 |
and tranche_formats events; it represents the end of a tranche. The |
| 504 |
next tranche will have a lower preference. |
| 505 |
</description> |
| 506 |
</event> |
| 507 |
|
| 508 |
<event name="tranche_target_device"> |
| 509 |
<description summary="target device"> |
| 510 |
This event advertises the target device that the server prefers to use |
| 511 |
for a buffer created given this tranche. The advertised target device |
| 512 |
may be different for each preference tranche, and may change over time. |
| 513 |
|
| 514 |
There is exactly one target device per tranche. |
| 515 |
|
| 516 |
The target device may be a scan-out device, for example if the |
| 517 |
compositor prefers to directly scan-out a buffer created given this |
| 518 |
tranche. The target device may be a rendering device, for example if |
| 519 |
the compositor prefers to texture from said buffer. |
| 520 |
|
| 521 |
The client can use this hint to allocate the buffer in a way that makes |
| 522 |
it accessible from the target device, ideally directly. The buffer must |
| 523 |
still be accessible from the main device, either through direct import |
| 524 |
or through a potentially more expensive fallback path. If the buffer |
| 525 |
can't be directly imported from the main device then clients must be |
| 526 |
prepared for the compositor changing the tranche priority or making |
| 527 |
wl_buffer creation fail (see the wp_linux_buffer_params.create and |
| 528 |
create_immed requests for details). |
| 529 |
|
| 530 |
If the device is a DRM node, the DRM node type (primary vs. render) is |
| 531 |
unspecified. Clients must not rely on the compositor sending a |
| 532 |
particular node type. Clients cannot check two devices for equality by |
| 533 |
comparing the dev_t value. |
| 534 |
|
| 535 |
This event is tied to a preference tranche, see the tranche_done event. |
| 536 |
</description> |
| 537 |
<arg name="device" type="array" summary="device dev_t value"/> |
| 538 |
</event> |
| 539 |
|
| 540 |
<event name="tranche_formats"> |
| 541 |
<description summary="supported buffer format modifier"> |
| 542 |
This event advertises the format + modifier combinations that the |
| 543 |
compositor supports. |
| 544 |
|
| 545 |
It carries an array of indices, each referring to a format + modifier |
| 546 |
pair in the last received format table (see the format_table event). |
| 547 |
Each index is a 16-bit unsigned integer in native endianness. |
| 548 |
|
| 549 |
For legacy support, DRM_FORMAT_MOD_INVALID is an allowed modifier. |
| 550 |
It indicates that the server can support the format with an implicit |
| 551 |
modifier. When a buffer has DRM_FORMAT_MOD_INVALID as its modifier, it |
| 552 |
is as if no explicit modifier is specified. The effective modifier |
| 553 |
will be derived from the dmabuf. |
| 554 |
|
| 555 |
A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for |
| 556 |
a given format supports both explicit modifiers and implicit modifiers. |
| 557 |
|
| 558 |
Compositors must not send duplicate format + modifier pairs within the |
| 559 |
same tranche or across two different tranches with the same target |
| 560 |
device and flags. |
| 561 |
|
| 562 |
This event is tied to a preference tranche, see the tranche_done event. |
| 563 |
|
| 564 |
For the definition of the format and modifier codes, see the |
| 565 |
wp_linux_buffer_params.create request. |
| 566 |
</description> |
| 567 |
<arg name="indices" type="array" summary="array of 16-bit indexes"/> |
| 568 |
</event> |
| 569 |
|
| 570 |
<enum name="tranche_flags" bitfield="true"> |
| 571 |
<entry name="scanout" value="1" summary="direct scan-out tranche"/> |
| 572 |
</enum> |
| 573 |
|
| 574 |
<event name="tranche_flags"> |
| 575 |
<description summary="tranche flags"> |
| 576 |
This event sets tranche-specific flags. |
| 577 |
|
| 578 |
The scanout flag is a hint that direct scan-out may be attempted by the |
| 579 |
compositor on the target device if the client appropriately allocates a |
| 580 |
buffer. How to allocate a buffer that can be scanned out on the target |
| 581 |
device is implementation-defined. |
| 582 |
|
| 583 |
This event is tied to a preference tranche, see the tranche_done event. |
| 584 |
</description> |
| 585 |
<arg name="flags" type="uint" enum="tranche_flags" summary="tranche flags"/> |
| 586 |
</event> |
| 587 |
</interface> |
| 588 |
|
| 589 |
</protocol> |