libsingle_pixel_buffer_v1_client_la_CFLAGS = @WAYLAND_CLIENT_CFLAGS@
libsingle_pixel_buffer_v1_client_la_LIBADD = @WAYLAND_CLIENT_LIBS@
+### linux-dmabuf-v1
+protocol_LTLIBRARIES += \
+ liblinux-dmabuf-v1-server.la \
+ liblinux-dmabuf-v1-client.la
+pkgconfig_DATA += \
+ src/liblinux-dmabuf-v1-server.pc \
+ src/liblinux-dmabuf-v1-client.pc
+protocolinclude_HEADERS += \
+ protocol/stable/linux-dmabuf-v1-server-protocol.h \
+ protocol/stable/linux-dmabuf-v1-client-protocol.h
+liblinux_dmabuf_v1_server_la_SOURCES = protocol/stable/linux-dmabuf-v1-protocol.c
+liblinux_dmabuf_v1_server_la_CFLAGS = @WAYLAND_SERVER_CFLAGS@
+liblinux_dmabuf_v1_server_la_LIBADD = @WAYLAND_SERVER_LIBS@
+liblinux_dmabuf_v1_client_la_SOURCES = protocol/stable/linux-dmabuf-v1-protocol.c
+liblinux_dmabuf_v1_client_la_CFLAGS = @WAYLAND_CLIENT_CFLAGS@
+liblinux_dmabuf_v1_client_la_LIBADD = @WAYLAND_CLIENT_LIBS@
+
### wayland-protocols
unstable_protocols = \
protocol/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml \
protocol/unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml \
- protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml \
protocol/unstable/text-input/text-input-unstable-v1.xml \
protocol/unstable/text-input/text-input-unstable-v3.xml \
protocol/unstable/input-method/input-method-unstable-v1.xml \
protocol/stable/presentation-time/presentation-time.xml \
protocol/stable/viewporter/viewporter.xml \
protocol/stable/xdg-shell/xdg-shell.xml \
+ protocol/stable/linux-dmabuf/linux-dmabuf-v1.xml \
$(NULL)
tizen_protocols = \
--- /dev/null
+Linux DMA-BUF protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk>
+Daniel Stone <daniels@collabora.com>
--- /dev/null
+.. Copyright 2021 Simon Ser
+
+.. contents::
+
+
+linux-dmabuf feedback introduction
+==================================
+
+linux-dmabuf feedback allows compositors and clients to negotiate optimal buffer
+allocation parameters. This document will assume that the compositor is using a
+rendering API such as OpenGL or Vulkan and KMS as the presentation API: even if
+linux-dmabuf feedback isn't restricted to this use-case, it's the most common.
+
+linux-dmabuf feedback introduces the following concepts:
+
+1. A main device. This is the render device that the compositor is using to
+ perform composition. Compositors should always be able to display a buffer
+ submitted by a client, so this device can be used as a fallback in case none
+ of the more optimized code-paths work. Clients should allocate buffers such
+ that they can be imported and textured from the main device.
+
+2. One or more tranches. Each tranche consists of a target device, allocation
+ flags and a set of format/modifier pairs. A tranche can be seen as a set of
+ formats/modifier pairs that are compatible with the target device.
+
+ A tranche can have the ``scanout`` flag. It means that the target device is
+ a KMS device, and that buffers allocated with one of the format/modifier
+ pairs in the tranche are eligible for direct scanout.
+
+ Clients should use the tranches in order to allocate buffers with the most
+ appropriate format/modifier and also to avoid allocating in private device
+ memory when cross-device operations are going to happen.
+
+linux-dmabuf feedback implementation notes
+==========================================
+
+This section contains recommendations for client and compositor implementations.
+
+For clients
+-----------
+
+Clients are expected to either pick a fixed DRM format beforehand, or
+perform the following steps repeatedly until they find a suitable format.
+
+Basic clients may only support static buffer allocation on startup. These
+clients should do the following:
+
+1. Send a ``get_default_feedback`` request to get global feedback.
+2. Select the device indicated by ``main_device`` for allocation.
+3. For each tranche:
+
+ 1. If ``tranche_target_device`` doesn't match the allocation device, ignore
+ the tranche.
+ 2. Accumulate allocation flags from ``tranche_flags``.
+ 3. Accumulate format/modifier pairs received via ``tranche_formats`` in a
+ list.
+ 4. When the ``tranche_done`` event is received, try to allocate the buffer
+ with the accumulated list of modifiers and allocation flags. If that
+ fails, proceed with the next tranche. If that succeeds, stop the loop.
+
+4. Destroy the feedback object.
+
+Tranches are ordered by preference: the more optimized tranches come first. As
+such, clients should use the first tranche that happens to work.
+
+Some clients may have already selected the device they want to use beforehand.
+These clients can ignore the ``main_device`` event, and ignore tranches whose
+``tranche_target_device`` doesn't match the selected device. Such clients need
+to be prepared for the ``wp_linux_buffer_params.create`` request to potentially
+fail.
+
+If the client allocates a buffer without specifying explicit modifiers on a
+device different from the one indicated by ``main_device``, then the client
+must force a linear layout.
+
+Some clients might support re-negotiating the buffer format/modifier on the
+fly. These clients should send a ``get_surface_feedback`` request and keep the
+feedback object alive after the initial allocation. Each time a new set of
+feedback parameters is received (ended by the ``done`` event), they should
+perform the same steps as basic clients described above. They should detect
+when the optimal allocation parameters didn't change (same
+format/modifier/flags) to avoid needlessly re-allocating their buffers.
+
+Some clients might additionally support switching the device used for
+allocations on the fly. Such clients should send a ``get_surface_feedback``
+request. For each tranche, select the device indicated by
+``tranche_target_device`` for allocation. Accumulate allocation flags (received
+via ``tranche_flags``) and format/modifier pairs (received via
+``tranche_formats``) as usual. When the ``tranche_done`` event is received, try
+to allocate the buffer with the accumulated list of modifiers and the
+allocation flags. Try to import the resulting buffer by sending a
+``wp_linux_buffer_params.create`` request (this might fail). Repeat with each
+tranche until an allocation and import succeeds. Each time a new set of
+feedback parameters is received, they should perform these steps again. They
+should detect when the optimal allocation parameters didn't change (same
+device/format/modifier/flags) to avoid needlessly re-allocating their buffers.
+
+For compositors
+---------------
+
+Basic compositors may only support texturing the DMA-BUFs via a rendering API
+such as OpenGL or Vulkan. Such compositors can send a single tranche as a reply
+to both ``get_default_feedback`` and ``get_surface_feedback``. Set the
+``main_device`` to the rendering device. Send the tranche with
+``tranche_target_device`` set to the rendering device and all of the DRM
+format/modifier pairs supported by the rendering API. Do not set the
+``scanout`` flag in the ``tranche_flags`` event.
+
+Some compositors may support direct scan-out for full-screen surfaces. These
+compositors can re-send the feedback parameters when a surface becomes
+full-screen or leaves full-screen mode if the client has used the
+``get_surface_feedback`` request. The non-full-screen feedback parameters are
+the same as basic compositors described above. The full-screen feedback
+parameters have two tranches: one with the format/modifier pairs supported by
+the KMS plane, with the ``scanout`` flag set in the ``tranche_flags`` event and
+with ``tranche_target_device`` set to the KMS scan-out device; the other with
+the rest of the format/modifier pairs (supported for texturing, but not for
+scan-out), without the ``scanout`` flag set in the ``tranche_flags`` event, and
+with the ``tranche_target_device`` set to the rendering device.
+
+Some compositors may support direct scan-out for all surfaces. These
+compositors can send two tranches for surfaces that become candidates for
+direct scan-out, similarly to compositors supporting direct scan-out for
+fullscreen surfaces. When a surface stops being a candidate for direct
+scan-out, compositors should re-send the feedback parameters optimized for
+texturing only. The way candidates for direct scan-out are selected is
+compositor policy, a possible implementation is to select as many surfaces as
+there are available hardware planes, starting from surfaces closer to the eye.
+
+Some compositors may support multiple devices at the same time. If the
+compositor supports rendering with a fixed device and direct scan-out on a
+secondary device, it may send a separate tranche for surfaces displayed on
+the secondary device that are candidates for direct scan-out. The
+``tranche_target_device`` for this tranche will be the secondary device and
+will not match the ``main_device``.
+
+Some compositors may support switching their rendering device at runtime or
+changing their rendering device depending on the surface. When the rendering
+device changes for a surface, such compositors may re-send the feedback
+parameters with a different ``main_device``. However there is a risk that
+clients don't support switching their device at runtime and continue using the
+previous device. For this reason, compositors should always have a fallback
+rendering device that they initially send as ``main_device``, such that these
+clients use said fallback device.
+
+Compositors should not change the ``main_device`` on-the-fly when explicit
+modifiers are not supported, because there's a risk of importing buffers
+with an implicit non-linear modifier as a linear buffer, resulting in
+misinterpreted buffer contents.
+
+Compositors should not send feedback parameters if they don't have a fallback
+path. For instance, compositors shouldn't send a format/modifier supported for
+direct scan-out but not supported by the rendering API for texturing.
+
+Compositors can decide to use multiple tranches to describe the allocation
+parameters optimized for texturing. For example, if there are formats which
+have a fast texturing path and formats which have a slower texturing path, the
+compositor can decide to expose two separate tranches.
+
+Compositors can decide to use intermediate tranches to describe code-paths
+slower than direct scan-out but faster than texturing. For instance, a
+compositor could insert an intermediate tranche if it's possible to use a
+mem2mem device to convert buffers to be able to use scan-out.
+
+``dev_t`` encoding
+==================
+
+The protocol carries ``dev_t`` values on the wire using arrays. A compositor
+written in C can encode the values as follows:
+
+.. code-block:: c
+
+ struct stat drm_node_stat;
+ struct wl_array dev_array = {
+ .size = sizeof(drm_node_stat.st_rdev),
+ .data = &drm_node_stat.st_rdev,
+ };
+
+A client can decode the values as follows:
+
+.. code-block:: c
+
+ dev_t dev;
+ assert(dev_array->size == sizeof(dev));
+ memcpy(&dev, dev_array->data, sizeof(dev));
+
+Because two DRM nodes can refer to the same DRM device while having different
+``dev_t`` values, clients should use ``drmDevicesEqual`` to compare two
+devices.
+
+``format_table`` encoding
+=========================
+
+The ``format_table`` event carries a file descriptor containing a list of
+format + modifier pairs. The list is an array of pairs which can be accessed
+with this C structure definition:
+
+.. code-block:: c
+
+ struct dmabuf_format_modifier {
+ uint32_t format;
+ uint32_t pad; /* unused */
+ uint64_t modifier;
+ };
+
+Integration with other APIs
+===========================
+
+- libdrm: ``drmGetDeviceFromDevId`` returns a ``drmDevice`` from a device ID.
+- EGL: the `EGL_EXT_device_drm_render_node`_ extension may be used to query the
+ DRM device render node used by a given EGL display. When unavailable, the
+ older `EGL_EXT_device_drm`_ extension may be used as a fallback.
+- Vulkan: the `VK_EXT_physical_device_drm`_ extension may be used to query the
+ DRM device used by a given ``VkPhysicalDevice``.
+
+.. _EGL_EXT_device_drm: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm.txt
+.. _EGL_EXT_device_drm_render_node: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm_render_node.txt
+.. _VK_EXT_physical_device_drm: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_physical_device_drm.html
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="linux_dmabuf_v1">
+
+ <copyright>
+ Copyright © 2014, 2015 Collabora, Ltd.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zwp_linux_dmabuf_v1" version="5">
+ <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
+ https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt
+ and the Linux DRM sub-system's AddFb2 ioctl.
+
+ This interface offers ways to create generic dmabuf-based wl_buffers.
+
+ Clients can use the get_surface_feedback request to get dmabuf feedback
+ for a particular surface. If the client wants to retrieve feedback not
+ tied to a surface, they can use the get_default_feedback request.
+
+ 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.
+
+ However, when the underlying graphics stack fails to deliver the
+ promise, because of e.g. a device hot-unplug which raises internal
+ errors, after the wl_buffer has been successfully created the
+ compositor must not raise protocol errors to the client when dmabuf
+ import later fails.
+
+ To create a wl_buffer from one or more dmabufs, a client creates a
+ zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params
+ request. All planes required by the intended format are added with
+ the 'add' request. Finally, a 'create' or 'create_immed' request is
+ issued, which has the following outcome depending on the import success.
+
+ The 'create' request,
+ - on success, triggers a 'created' event which provides the final
+ wl_buffer to the client.
+ - on failure, triggers a 'failed' event to convey that the server
+ cannot use the dmabufs received from the client.
+
+ For the 'create_immed' request,
+ - on success, the server immediately imports the added dmabufs to
+ create a wl_buffer. No event is sent from the server in this case.
+ - on failure, the server can choose to either:
+ - terminate the client by raising a fatal error.
+ - mark the wl_buffer as failed, and send a 'failed' event to the
+ client. If the client uses a failed wl_buffer as an argument to any
+ request, the behaviour is compositor implementation-defined.
+
+ For all DRM formats and unless specified in another protocol extension,
+ pre-multiplied alpha is used for pixel values.
+
+ Unless specified otherwise in another protocol extension, implicit
+ synchronization is used. In other words, compositors and clients must
+ wait and signal fences implicitly passed via the DMA-BUF's reservation
+ mechanism.
+ </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 a 'created' or 'failed' event has been
+ received.
+ </description>
+ <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1"
+ 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 the
+ zwp_linux_buffer_params_v1::create request.
+
+ Starting version 4, the format event is deprecated and must not be
+ sent by compositors. Instead, use get_default_feedback or
+ get_surface_feedback.
+ </description>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ </event>
+
+ <event name="modifier" since="3">
+ <description summary="supported buffer format modifier">
+ This event advertises the formats that the server supports, along with
+ the modifiers supported for each format. All the supported modifiers
+ for 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 format-modifier pairs.
+
+ For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi ==
+ 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event.
+ It indicates that the server can support the format with an implicit
+ modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it
+ is as if no explicit modifier is specified. The effective modifier
+ will be derived from the dmabuf.
+
+ A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for
+ a given format supports both explicit modifiers and implicit modifiers.
+
+ For the definition of the format and modifier codes, see the
+ zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add
+ requests.
+
+ Starting version 4, the modifier event is deprecated and must not be
+ sent by compositors. Instead, use get_default_feedback or
+ get_surface_feedback.
+ </description>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ <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"/>
+ </event>
+
+ <!-- Version 4 additions -->
+
+ <request name="get_default_feedback" since="4">
+ <description summary="get default feedback">
+ This request creates a new wp_linux_dmabuf_feedback object not bound
+ to a particular surface. This object will deliver feedback about dmabuf
+ parameters to use if the client doesn't support per-surface feedback
+ (see get_surface_feedback).
+ </description>
+ <arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/>
+ </request>
+
+ <request name="get_surface_feedback" since="4">
+ <description summary="get feedback for a surface">
+ This request creates a new wp_linux_dmabuf_feedback object for the
+ specified wl_surface. This object will deliver feedback about dmabuf
+ parameters to use for buffers attached to this surface.
+
+ If the surface is destroyed before the wp_linux_dmabuf_feedback object,
+ the feedback object becomes inert.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_linux_buffer_params_v1" version="5">
+ <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, an '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"/>
+ <entry name="invalid_wl_buffer" value="7"
+ summary="invalid wl_buffer resulted from importing dmabufs via
+ the create_immed request on given buffer_params"/>
+ </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
+ zwp_linux_buffer_params_v1.
+
+ 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.
+
+ Starting from version 4, the invalid_format protocol error is sent if
+ the format + modifier pair was not advertised as supported.
+
+ Starting from version 5, the invalid_format protocol error is sent if
+ all planes don't use the same modifier.
+
+ 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" bitfield="true">
+ <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 a '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" enum="flags" 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
+ zwp_linux_buffer_params_v1 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
+ zwp_linux_buffer_params_v1 object.
+ </description>
+ </event>
+
+ <request name="create_immed" since="2">
+ <description summary="immediately create a wl_buffer from the given
+ dmabufs">
+ This asks for immediate creation of a wl_buffer by importing the
+ added dmabufs.
+
+ In case of import success, no event is sent from the server, and the
+ wl_buffer is ready to be used by the client.
+
+ Upon import failure, either of the following may happen, as seen fit
+ by the implementation:
+ - the client is terminated with one of the following fatal protocol
+ errors:
+ - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS,
+ in case of argument errors such as mismatch between the number
+ of planes and the format, bad format, non-positive width or
+ height, or bad offset or stride.
+ - INVALID_WL_BUFFER, in case the cause for failure is unknown or
+ plaform specific.
+ - the server creates an invalid wl_buffer, marks it as failed and
+ sends a 'failed' event to the client. The result of using this
+ invalid wl_buffer as an argument in any request by the client is
+ defined by the compositor implementation.
+
+ This takes the same arguments as a 'create' request, and obeys the
+ same restrictions.
+ </description>
+ <arg name="buffer_id" type="new_id" interface="wl_buffer"
+ summary="id for the newly created wl_buffer"/>
+ <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" enum="flags" summary="see enum flags"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_linux_dmabuf_feedback_v1" version="5">
+ <description summary="dmabuf feedback">
+ This object advertises dmabuf parameters feedback. This includes the
+ preferred devices and the supported formats/modifiers.
+
+ The parameters are sent once when this object is created and whenever they
+ change. The done event is always sent once after all parameters have been
+ sent. When a single parameter changes, all parameters are re-sent by the
+ compositor.
+
+ Compositors can re-send the parameters when the current client buffer
+ allocations are sub-optimal. Compositors should not re-send the
+ parameters if re-allocating the buffers would not result in a more optimal
+ configuration. In particular, compositors should avoid sending the exact
+ same parameters multiple times in a row.
+
+ The tranche_target_device and tranche_formats events are grouped by
+ tranches of preference. For each tranche, a tranche_target_device, one
+ tranche_flags and one or more tranche_formats events are sent, followed
+ by a tranche_done event finishing the list. The tranches are sent in
+ descending order of preference. All formats and modifiers in the same
+ tranche have the same preference.
+
+ To send parameters, the compositor sends one main_device event, tranches
+ (each consisting of one tranche_target_device event, one tranche_flags
+ event, tranche_formats events and then a tranche_done event), then one
+ done event.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the feedback object">
+ Using this request a client can tell the server that it is not going to
+ use the wp_linux_dmabuf_feedback object anymore.
+ </description>
+ </request>
+
+ <event name="done">
+ <description summary="all feedback has been sent">
+ This event is sent after all parameters of a wp_linux_dmabuf_feedback
+ object have been sent.
+
+ This allows changes to the wp_linux_dmabuf_feedback parameters to be
+ seen as atomic, even if they happen via multiple events.
+ </description>
+ </event>
+
+ <event name="format_table">
+ <description summary="format and modifier table">
+ This event provides a file descriptor which can be memory-mapped to
+ access the format and modifier table.
+
+ The table contains a tightly packed array of consecutive format +
+ modifier pairs. Each pair is 16 bytes wide. It contains a format as a
+ 32-bit unsigned integer, followed by 4 bytes of unused padding, and a
+ modifier as a 64-bit unsigned integer. The native endianness is used.
+
+ The client must map the file descriptor in read-only private mode.
+
+ Compositors are not allowed to mutate the table file contents once this
+ event has been sent. Instead, compositors must create a new, separate
+ table file and re-send feedback parameters. Compositors are allowed to
+ store duplicate format + modifier pairs in the table.
+ </description>
+ <arg name="fd" type="fd" summary="table file descriptor"/>
+ <arg name="size" type="uint" summary="table size, in bytes"/>
+ </event>
+
+ <event name="main_device">
+ <description summary="preferred main device">
+ This event advertises the main device that the server prefers to use
+ when direct scan-out to the target device isn't possible. The
+ advertised main device may be different for each
+ wp_linux_dmabuf_feedback object, and may change over time.
+
+ There is exactly one main device. The compositor must send at least
+ one preference tranche with tranche_target_device equal to main_device.
+
+ Clients need to create buffers that the main device can import and
+ read from, otherwise creating the dmabuf wl_buffer will fail (see the
+ wp_linux_buffer_params.create and create_immed requests for details).
+ The main device will also likely be kept active by the compositor,
+ so clients can use it instead of waking up another device for power
+ savings.
+
+ In general the device is a DRM node. The DRM node type (primary vs.
+ render) is unspecified. Clients must not rely on the compositor sending
+ a particular node type. Clients cannot check two devices for equality
+ by comparing the dev_t value.
+
+ If explicit modifiers are not supported and the client performs buffer
+ allocations on a different device than the main device, then the client
+ must force the buffer to have a linear layout.
+ </description>
+ <arg name="device" type="array" summary="device dev_t value"/>
+ </event>
+
+ <event name="tranche_done">
+ <description summary="a preference tranche has been sent">
+ This event splits tranche_target_device and tranche_formats events in
+ preference tranches. It is sent after a set of tranche_target_device
+ and tranche_formats events; it represents the end of a tranche. The
+ next tranche will have a lower preference.
+ </description>
+ </event>
+
+ <event name="tranche_target_device">
+ <description summary="target device">
+ This event advertises the target device that the server prefers to use
+ for a buffer created given this tranche. The advertised target device
+ may be different for each preference tranche, and may change over time.
+
+ There is exactly one target device per tranche.
+
+ The target device may be a scan-out device, for example if the
+ compositor prefers to directly scan-out a buffer created given this
+ tranche. The target device may be a rendering device, for example if
+ the compositor prefers to texture from said buffer.
+
+ The client can use this hint to allocate the buffer in a way that makes
+ it accessible from the target device, ideally directly. The buffer must
+ still be accessible from the main device, either through direct import
+ or through a potentially more expensive fallback path. If the buffer
+ can't be directly imported from the main device then clients must be
+ prepared for the compositor changing the tranche priority or making
+ wl_buffer creation fail (see the wp_linux_buffer_params.create and
+ create_immed requests for details).
+
+ If the device is a DRM node, the DRM node type (primary vs. render) is
+ unspecified. Clients must not rely on the compositor sending a
+ particular node type. Clients cannot check two devices for equality by
+ comparing the dev_t value.
+
+ This event is tied to a preference tranche, see the tranche_done event.
+ </description>
+ <arg name="device" type="array" summary="device dev_t value"/>
+ </event>
+
+ <event name="tranche_formats">
+ <description summary="supported buffer format modifier">
+ This event advertises the format + modifier combinations that the
+ compositor supports.
+
+ It carries an array of indices, each referring to a format + modifier
+ pair in the last received format table (see the format_table event).
+ Each index is a 16-bit unsigned integer in native endianness.
+
+ For legacy support, DRM_FORMAT_MOD_INVALID is an allowed modifier.
+ It indicates that the server can support the format with an implicit
+ modifier. When a buffer has DRM_FORMAT_MOD_INVALID as its modifier, it
+ is as if no explicit modifier is specified. The effective modifier
+ will be derived from the dmabuf.
+
+ A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for
+ a given format supports both explicit modifiers and implicit modifiers.
+
+ Compositors must not send duplicate format + modifier pairs within the
+ same tranche or across two different tranches with the same target
+ device and flags.
+
+ This event is tied to a preference tranche, see the tranche_done event.
+
+ For the definition of the format and modifier codes, see the
+ wp_linux_buffer_params.create request.
+ </description>
+ <arg name="indices" type="array" summary="array of 16-bit indexes"/>
+ </event>
+
+ <enum name="tranche_flags" bitfield="true">
+ <entry name="scanout" value="1" summary="direct scan-out tranche"/>
+ </enum>
+
+ <event name="tranche_flags">
+ <description summary="tranche flags">
+ This event sets tranche-specific flags.
+
+ The scanout flag is a hint that direct scan-out may be attempted by the
+ compositor on the target device if the client appropriately allocates a
+ buffer. How to allocate a buffer that can be scanned out on the target
+ device is implementation-defined.
+
+ This event is tied to a preference tranche, see the tranche_done event.
+ </description>
+ <arg name="flags" type="uint" enum="tranche_flags" summary="tranche flags"/>
+ </event>
+ </interface>
+
+</protocol>
+++ /dev/null
-Linux DMA-BUF protocol
-
-Maintainers:
-Pekka Paalanen <pekka.paalanen@collabora.co.uk>
-Daniel Stone <daniels@collabora.com>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<protocol name="linux_dmabuf_unstable_v1">
-
- <copyright>
- Copyright © 2014, 2015 Collabora, Ltd.
-
- Permission is hereby granted, free of charge, to any person obtaining a
- copy of this software and associated documentation files (the "Software"),
- to deal in the Software without restriction, including without limitation
- the rights to use, copy, modify, merge, publish, distribute, sublicense,
- and/or sell copies of the Software, and to permit persons to whom the
- Software is furnished to do so, subject to the following conditions:
-
- The above copyright notice and this permission notice (including the next
- paragraph) shall be included in all copies or substantial portions of the
- Software.
-
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
- DEALINGS IN THE SOFTWARE.
- </copyright>
-
- <interface name="zwp_linux_dmabuf_v1" version="3">
- <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
- https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt
- and the Linux DRM sub-system's AddFb2 ioctl.
-
- This interface offers ways to create generic dmabuf-based
- wl_buffers. Immediately after a client binds to this interface,
- the set of supported formats and format modifiers is sent with
- 'format' and 'modifier' 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
- zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params
- request. All planes required by the intended format are added with
- the 'add' request. Finally, a 'create' or 'create_immed' request is
- issued, which has the following outcome depending on the import success.
-
- The 'create' request,
- - on success, triggers a 'created' event which provides the final
- wl_buffer to the client.
- - on failure, triggers a 'failed' event to convey that the server
- cannot use the dmabufs received from the client.
-
- For the 'create_immed' request,
- - on success, the server immediately imports the added dmabufs to
- create a wl_buffer. No event is sent from the server in this case.
- - on failure, the server can choose to either:
- - terminate the client by raising a fatal error.
- - mark the wl_buffer as failed, and send a 'failed' event to the
- client. If the client uses a failed wl_buffer as an argument to any
- request, the behaviour is compositor implementation-defined.
-
- Warning! The protocol described in this file is experimental and
- backward incompatible changes may be made. Backward compatible changes
- may be added together with the corresponding interface version bump.
- Backward incompatible changes are done by bumping the version number in
- the protocol and interface names and resetting the interface version.
- Once the protocol is to be declared stable, the 'z' prefix and the
- version number in the protocol and interface names are removed and the
- interface version number is reset.
- </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 a 'created' or 'failed' event has been
- received.
- </description>
- <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1"
- 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 the
- zwp_linux_buffer_params_v1::create request.
-
- Warning: the 'format' event is likely to be deprecated and replaced
- with the 'modifier' event introduced in zwp_linux_dmabuf_v1
- version 3, described below. Please refrain from using the information
- received from this event.
- </description>
- <arg name="format" type="uint" summary="DRM_FORMAT code"/>
- </event>
-
- <event name="modifier" since="3">
- <description summary="supported buffer format modifier">
- This event advertises the formats that the server supports, along with
- the modifiers supported for each format. All the supported modifiers
- for 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 format-modifier pairs.
-
- For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi ==
- 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event.
- It indicates that the server can support the format with an implicit
- modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it
- is as if no explicit modifier is specified. The effective modifier
- will be derived from the dmabuf.
-
- For the definition of the format and modifier codes, see the
- zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add
- requests.
- </description>
- <arg name="format" type="uint" summary="DRM_FORMAT code"/>
- <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"/>
- </event>
- </interface>
-
- <interface name="zwp_linux_buffer_params_v1" version="3">
- <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, an '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"/>
- <entry name="invalid_wl_buffer" value="7"
- summary="invalid wl_buffer resulted from importing dmabufs via
- the create_immed request on given buffer_params"/>
- </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
- zwp_linux_buffer_params_v1.
-
- 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.
-
- Warning: It should be an error if the format/modifier pair was not
- advertised with the modifier event. This is not enforced yet because
- some implementations always accept DRM_FORMAT_MOD_INVALID. Also
- version 2 of this protocol does not have the modifier event.
-
- 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 a '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>
-
- <request name="create_immed" since="2">
- <description summary="immediately create a wl_buffer from the given
- dmabufs">
- This asks for immediate creation of a wl_buffer by importing the
- added dmabufs.
-
- In case of import success, no event is sent from the server, and the
- wl_buffer is ready to be used by the client.
-
- Upon import failure, either of the following may happen, as seen fit
- by the implementation:
- - the client is terminated with one of the following fatal protocol
- errors:
- - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS,
- in case of argument errors such as mismatch between the number
- of planes and the format, bad format, non-positive width or
- height, or bad offset or stride.
- - INVALID_WL_BUFFER, in case the cause for failure is unknown or
- plaform specific.
- - the server creates an invalid wl_buffer, marks it as failed and
- sends a 'failed' event to the client. The result of using this
- invalid wl_buffer as an argument in any request by the client is
- defined by the compositor implementation.
-
- This takes the same arguments as a 'create' request, and obeys the
- same restrictions.
- </description>
- <arg name="buffer_id" type="new_id" interface="wl_buffer"
- summary="id for the newly created wl_buffer"/>
- <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>
-
- </interface>
-
-</protocol>
projects / platform / core / uifw / wayland-extension.git / commitdiff