Signed-off-by: Jonas Ådahl <jadahl@gmail.com> Reviewed-by: Mariusz Ceier <mceier+wayland@gmail.com> Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>dev
Jonas Ådahl
9 years ago
committed by
Pekka Paalanen
parent
496adb3bb3
commit
57e48f023c
@ -1,274 +0,0 @@ |
|||||||
<?xml version="1.0" encoding="UTF-8"?> |
|
||||||
<protocol name="linux_dmabuf"> |
|
||||||
|
|
||||||
<copyright> |
|
||||||
Copyright © 2014, 2015 Collabora, Ltd. |
|
||||||
|
|
||||||
Permission to use, copy, modify, distribute, and sell this |
|
||||||
software and its documentation for any purpose is hereby granted |
|
||||||
without fee, provided that the above copyright notice appear in |
|
||||||
all copies and that both that copyright notice and this permission |
|
||||||
notice appear in supporting documentation, and that the name of |
|
||||||
the copyright holders not be used in advertising or publicity |
|
||||||
pertaining to distribution of the software without specific, |
|
||||||
written prior permission. The copyright holders make no |
|
||||||
representations about the suitability of this software for any |
|
||||||
purpose. It is provided "as is" without express or implied |
|
||||||
warranty. |
|
||||||
|
|
||||||
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS |
|
||||||
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND |
|
||||||
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY |
|
||||||
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
|
||||||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
|
||||||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, |
|
||||||
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF |
|
||||||
THIS SOFTWARE. |
|
||||||
</copyright> |
|
||||||
|
|
||||||
<interface name="zlinux_dmabuf" version="1"> |
|
||||||
<description summary="factory for creating dmabuf-based wl_buffers"> |
|
||||||
Following the interfaces from: |
|
||||||
https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt |
|
||||||
and the Linux DRM sub-system's AddFb2 ioctl. |
|
||||||
|
|
||||||
This interface offers a way to create generic dmabuf-based |
|
||||||
wl_buffers. Immediately after a client binds to this interface, |
|
||||||
the set of supported formats is sent with 'format' events. |
|
||||||
|
|
||||||
The following are required from clients: |
|
||||||
|
|
||||||
- Clients must ensure that either all data in the dma-buf is |
|
||||||
coherent for all subsequent read access or that coherency is |
|
||||||
correctly handled by the underlying kernel-side dma-buf |
|
||||||
implementation. |
|
||||||
|
|
||||||
- Don't make any more attachments after sending the buffer to the |
|
||||||
compositor. Making more attachments later increases the risk of |
|
||||||
the compositor not being able to use (re-import) an existing |
|
||||||
dmabuf-based wl_buffer. |
|
||||||
|
|
||||||
The underlying graphics stack must ensure the following: |
|
||||||
|
|
||||||
- The dmabuf file descriptors relayed to the server will stay valid |
|
||||||
for the whole lifetime of the wl_buffer. This means the server may |
|
||||||
at any time use those fds to import the dmabuf into any kernel |
|
||||||
sub-system that might accept it. |
|
||||||
|
|
||||||
To create a wl_buffer from one or more dmabufs, a client creates a |
|
||||||
zlinux_dmabuf_params object with zlinux_dmabuf.create_params |
|
||||||
request. All planes required by the intended format are added with |
|
||||||
the 'add' request. Finally, 'create' request is issued. The server |
|
||||||
will reply with either 'created' event which provides the final |
|
||||||
wl_buffer or 'failed' event saying that it cannot use the dmabufs |
|
||||||
provided. |
|
||||||
</description> |
|
||||||
|
|
||||||
<request name="destroy" type="destructor"> |
|
||||||
<description summary="unbind the factory"> |
|
||||||
Objects created through this interface, especially wl_buffers, will |
|
||||||
remain valid. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="create_params"> |
|
||||||
<description summary="create a temporary object for buffer parameters"> |
|
||||||
This temporary object is used to collect multiple dmabuf handles into |
|
||||||
a single batch to create a wl_buffer. It can only be used once and |
|
||||||
should be destroyed after an 'created' or 'failed' event has been |
|
||||||
received. |
|
||||||
</description> |
|
||||||
<arg name="params_id" type="new_id" interface="zlinux_buffer_params" |
|
||||||
summary="the new temporary"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<event name="format"> |
|
||||||
<description summary="supported buffer format"> |
|
||||||
This event advertises one buffer format that the server supports. |
|
||||||
All the supported formats are advertised once when the client |
|
||||||
binds to this interface. A roundtrip after binding guarantees, |
|
||||||
that the client has received all supported formats. |
|
||||||
|
|
||||||
For the definition of the format codes, see create request. |
|
||||||
|
|
||||||
XXX: Can a compositor ever enumerate them? |
|
||||||
</description> |
|
||||||
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
|
||||||
</event> |
|
||||||
|
|
||||||
</interface> |
|
||||||
|
|
||||||
<interface name="zlinux_buffer_params" version="1"> |
|
||||||
<description summary="parameters for creating a dmabuf-based wl_buffer"> |
|
||||||
This temporary object is a collection of dmabufs and other |
|
||||||
parameters that together form a single logical buffer. The temporary |
|
||||||
object may eventually create one wl_buffer unless cancelled by |
|
||||||
destroying it before requesting 'create'. |
|
||||||
|
|
||||||
Single-planar formats only require one dmabuf, however |
|
||||||
multi-planar formats may require more than one dmabuf. For all |
|
||||||
formats, 'add' request must be called once per plane (even if the |
|
||||||
underlying dmabuf fd is identical). |
|
||||||
|
|
||||||
You must use consecutive plane indices ('plane_idx' argument for 'add') |
|
||||||
from zero to the number of planes used by the drm_fourcc format code. |
|
||||||
All planes required by the format must be given exactly once, but can |
|
||||||
be given in any order. Each plane index can be set only once. |
|
||||||
</description> |
|
||||||
|
|
||||||
<enum name="error"> |
|
||||||
<entry name="already_used" value="0" |
|
||||||
summary="the dmabuf_batch object has already been used to create a wl_buffer"/> |
|
||||||
|
|
||||||
<entry name="plane_idx" value="1" |
|
||||||
summary="plane index out of bounds"/> |
|
||||||
|
|
||||||
<entry name="plane_set" value="2" |
|
||||||
summary="the plane index was already set"/> |
|
||||||
|
|
||||||
<entry name="incomplete" value="3" |
|
||||||
summary="missing or too many planes to create a buffer"/> |
|
||||||
|
|
||||||
<entry name="invalid_format" value="4" |
|
||||||
summary="format not supported"/> |
|
||||||
|
|
||||||
<entry name="invalid_dimensions" value="5" |
|
||||||
summary="invalid width or height"/> |
|
||||||
|
|
||||||
<entry name="out_of_bounds" value="6" |
|
||||||
summary="offset + stride * height goes out of dmabuf bounds"/> |
|
||||||
</enum> |
|
||||||
|
|
||||||
<request name="destroy" type="destructor"> |
|
||||||
<description summary="delete this object, used or not"> |
|
||||||
Cleans up the temporary data sent to the server for dmabuf-based |
|
||||||
wl_buffer creation. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="add"> |
|
||||||
<description summary="add a dmabuf to the temporary set"> |
|
||||||
This request adds one dmabuf to the set in this zlinux_buffer_params. |
|
||||||
|
|
||||||
The 64-bit unsigned value combined from modifier_hi and modifier_lo |
|
||||||
is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the |
|
||||||
fb modifier, which is defined in drm_mode.h of Linux UAPI. |
|
||||||
This is an opaque token. Drivers use this token to express tiling, |
|
||||||
compression, etc. driver-specific modifications to the base format |
|
||||||
defined by the DRM fourcc code. |
|
||||||
|
|
||||||
This request raises the PLANE_IDX error if plane_idx is too large. |
|
||||||
The error PLANE_SET is raised if attempting to set a plane that |
|
||||||
was already set. |
|
||||||
</description> |
|
||||||
|
|
||||||
<arg name="fd" type="fd" summary="dmabuf fd"/> |
|
||||||
<arg name="plane_idx" type="uint" summary="plane index"/> |
|
||||||
<arg name="offset" type="uint" summary="offset in bytes"/> |
|
||||||
<arg name="stride" type="uint" summary="stride in bytes"/> |
|
||||||
<arg name="modifier_hi" type="uint" |
|
||||||
summary="high 32 bits of layout modifier"/> |
|
||||||
<arg name="modifier_lo" type="uint" |
|
||||||
summary="low 32 bits of layout modifier"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<enum name="flags"> |
|
||||||
<entry name="y_invert" value="1" summary="contents are y-inverted"/> |
|
||||||
<entry name="interlaced" value="2" summary="content is interlaced"/> |
|
||||||
<entry name="bottom_first" value="4" summary="bottom field first"/> |
|
||||||
</enum> |
|
||||||
|
|
||||||
<request name="create"> |
|
||||||
<description summary="create a wl_buffer from the given dmabufs"> |
|
||||||
This asks for creation of a wl_buffer from the added dmabuf |
|
||||||
buffers. The wl_buffer is not created immediately but returned via |
|
||||||
the 'created' event if the dmabuf sharing succeeds. The sharing |
|
||||||
may fail at runtime for reasons a client cannot predict, in |
|
||||||
which case the 'failed' event is triggered. |
|
||||||
|
|
||||||
The 'format' argument is a DRM_FORMAT code, as defined by the |
|
||||||
libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the |
|
||||||
authoritative source on how the format codes should work. |
|
||||||
|
|
||||||
The 'flags' is a bitfield of the flags defined in enum "flags". |
|
||||||
'y_invert' means the that the image needs to be y-flipped. |
|
||||||
|
|
||||||
Flag 'interlaced' means that the frame in the buffer is not |
|
||||||
progressive as usual, but interlaced. An interlaced buffer as |
|
||||||
supported here must always contain both top and bottom fields. |
|
||||||
The top field always begins on the first pixel row. The temporal |
|
||||||
ordering between the two fields is top field first, unless |
|
||||||
'bottom_first' is specified. It is undefined whether 'bottom_first' |
|
||||||
is ignored if 'interlaced' is not set. |
|
||||||
|
|
||||||
This protocol does not convey any information about field rate, |
|
||||||
duration, or timing, other than the relative ordering between the |
|
||||||
two fields in one buffer. A compositor may have to estimate the |
|
||||||
intended field rate from the incoming buffer rate. It is undefined |
|
||||||
whether the time of receiving wl_surface.commit with a new buffer |
|
||||||
attached, applying the wl_surface state, wl_surface.frame callback |
|
||||||
trigger, presentation, or any other point in the compositor cycle |
|
||||||
is used to measure the frame or field times. There is no support |
|
||||||
for detecting missed or late frames/fields/buffers either, and |
|
||||||
there is no support whatsoever for cooperating with interlaced |
|
||||||
compositor output. |
|
||||||
|
|
||||||
The composited image quality resulting from the use of interlaced |
|
||||||
buffers is explicitly undefined. A compositor may use elaborate |
|
||||||
hardware features or software to deinterlace and create progressive |
|
||||||
output frames from a sequence of interlaced input buffers, or it |
|
||||||
may produce substandard image quality. However, compositors that |
|
||||||
cannot guarantee reasonable image quality in all cases are recommended |
|
||||||
to just reject all interlaced buffers. |
|
||||||
|
|
||||||
Any argument errors, including non-positive width or height, |
|
||||||
mismatch between the number of planes and the format, bad |
|
||||||
format, bad offset or stride, may be indicated by fatal protocol |
|
||||||
errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, |
|
||||||
OUT_OF_BOUNDS. |
|
||||||
|
|
||||||
Dmabuf import errors in the server that are not obvious client |
|
||||||
bugs are returned via the 'failed' event as non-fatal. This |
|
||||||
allows attempting dmabuf sharing and falling back in the client |
|
||||||
if it fails. |
|
||||||
|
|
||||||
This request can be sent only once in the object's lifetime, after |
|
||||||
which the only legal request is destroy. This object should be |
|
||||||
destroyed after issuing 'create' request. Attempting to use this |
|
||||||
object after issuing 'create' raises ALREADY_USED protocol error. |
|
||||||
|
|
||||||
It is not mandatory to issue 'create'. If a client wants to |
|
||||||
cancel the buffer creation, it can just destroy this object. |
|
||||||
</description> |
|
||||||
<arg name="width" type="int" summary="base plane width in pixels"/> |
|
||||||
<arg name="height" type="int" summary="base plane height in pixels"/> |
|
||||||
<arg name="format" type="uint" summary="DRM_FORMAT code"/> |
|
||||||
<arg name="flags" type="uint" summary="see enum flags"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<event name="created"> |
|
||||||
<description summary="buffer creation succeeded"> |
|
||||||
This event indicates that the attempted buffer creation was |
|
||||||
successful. It provides the new wl_buffer referencing the dmabuf(s). |
|
||||||
|
|
||||||
Upon receiving this event, the client should destroy the |
|
||||||
zlinux_dmabuf_params object. |
|
||||||
</description> |
|
||||||
<arg name="buffer" type="new_id" interface="wl_buffer" |
|
||||||
summary="the newly created wl_buffer"/> |
|
||||||
</event> |
|
||||||
|
|
||||||
<event name="failed"> |
|
||||||
<description summary="buffer creation failed"> |
|
||||||
This event indicates that the attempted buffer creation has |
|
||||||
failed. It usually means that one of the dmabuf constraints |
|
||||||
has not been fulfilled. |
|
||||||
|
|
||||||
Upon receiving this event, the client should destroy the |
|
||||||
zlinux_buffer_params object. |
|
||||||
</description> |
|
||||||
</event> |
|
||||||
|
|
||||||
</interface> |
|
||||||
|
|
||||||
</protocol> |
|
||||||
Loading…
Reference in new issue