\hypertarget{page_linux_dmabuf_unstable_v1_page_ifaces_linux_dmabuf_unstable_v1}{}\section{Interfaces}\label{page_linux_dmabuf_unstable_v1_page_ifaces_linux_dmabuf_unstable_v1}

\begin{DoxyItemize}
\item \mbox{\hyperlink{page_iface_zwp_linux_dmabuf_v1}{zwp\+\_\+linux\+\_\+dmabuf\+\_\+v1}} -\/ factory for creating dmabuf-\/based wl\+\_\+buffers
\item \mbox{\hyperlink{page_iface_zwp_linux_buffer_params_v1}{zwp\+\_\+linux\+\_\+buffer\+\_\+params\+\_\+v1}} -\/ parameters for creating a dmabuf-\/based wl\+\_\+buffer 
\end{DoxyItemize}\hypertarget{page_linux_dmabuf_unstable_v1_page_copyright_linux_dmabuf_unstable_v1}{}\section{Copyright}\label{page_linux_dmabuf_unstable_v1_page_copyright_linux_dmabuf_unstable_v1}

\begin{DoxyPre}\end{DoxyPre}



\begin{DoxyPre}Copyright © 2014, 2015 Collabora, Ltd.\end{DoxyPre}



\begin{DoxyPre}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:\end{DoxyPre}



\begin{DoxyPre}The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.\end{DoxyPre}



\begin{DoxyPre}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.
\end{DoxyPre}
 \hypertarget{page_iface_zwp_linux_dmabuf_v1}{}\section{zwp\+\_\+linux\+\_\+dmabuf\+\_\+v1}\label{page_iface_zwp_linux_dmabuf_v1}
\hypertarget{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_desc}{}\subsection{Description}\label{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_desc}
Following the interfaces from\+: \href{https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt}{\tt https\+://www.\+khronos.\+org/registry/egl/extensions/\+E\+X\+T/\+E\+G\+L\+\_\+\+E\+X\+T\+\_\+image\+\_\+dma\+\_\+buf\+\_\+import.\+txt} and the Linux D\+RM sub-\/system\textquotesingle{}s Add\+Fb2 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 \textquotesingle{}format\textquotesingle{} and \textquotesingle{}modifier\textquotesingle{} events.

The following are required from clients\+:


\begin{DoxyItemize}
\item 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.
\item Don\textquotesingle{}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.
\end{DoxyItemize}

The underlying graphics stack must ensure the following\+:


\begin{DoxyItemize}
\item 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.
\end{DoxyItemize}

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 \textquotesingle{}add\textquotesingle{} request. Finally, a \textquotesingle{}create\textquotesingle{} or \textquotesingle{}create\+\_\+immed\textquotesingle{} request is issued, which has the following outcome depending on the import success.

The \textquotesingle{}create\textquotesingle{} request,
\begin{DoxyItemize}
\item on success, triggers a \textquotesingle{}created\textquotesingle{} event which provides the final wl\+\_\+buffer to the client.
\item on failure, triggers a \textquotesingle{}failed\textquotesingle{} event to convey that the server cannot use the dmabufs received from the client.
\end{DoxyItemize}

For the \textquotesingle{}create\+\_\+immed\textquotesingle{} request,
\begin{DoxyItemize}
\item on success, the server immediately imports the added dmabufs to create a wl\+\_\+buffer. No event is sent from the server in this case.
\item on failure, the server can choose to either\+:
\item terminate the client by raising a fatal error.
\item mark the wl\+\_\+buffer as failed, and send a \textquotesingle{}failed\textquotesingle{} event to the client. If the client uses a failed wl\+\_\+buffer as an argument to any request, the behaviour is compositor implementation-\/defined.
\end{DoxyItemize}

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 \textquotesingle{}z\textquotesingle{} prefix and the version number in the protocol and interface names are removed and the interface version number is reset. \hypertarget{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_api}{}\subsection{A\+PI}\label{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_api}
See \mbox{\hyperlink{group__iface__zwp__linux__dmabuf__v1}{The zwp\+\_\+linux\+\_\+dmabuf\+\_\+v1 interface}}. \hypertarget{page_iface_zwp_linux_buffer_params_v1}{}\section{zwp\+\_\+linux\+\_\+buffer\+\_\+params\+\_\+v1}\label{page_iface_zwp_linux_buffer_params_v1}
\hypertarget{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_desc}{}\subsection{Description}\label{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_desc}
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 \textquotesingle{}create\textquotesingle{}.

Single-\/planar formats only require one dmabuf, however multi-\/planar formats may require more than one dmabuf. For all formats, an \textquotesingle{}add\textquotesingle{} request must be called once per plane (even if the underlying dmabuf fd is identical).

You must use consecutive plane indices (\textquotesingle{}plane\+\_\+idx\textquotesingle{} argument for \textquotesingle{}add\textquotesingle{}) 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. \hypertarget{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_api}{}\subsection{A\+PI}\label{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_api}
See \mbox{\hyperlink{group__iface__zwp__linux__buffer__params__v1}{The zwp\+\_\+linux\+\_\+buffer\+\_\+params\+\_\+v1 interface}}. \hypertarget{page_iface_zwp_linux_dmabuf_v1}{}\section{zwp\+\_\+linux\+\_\+dmabuf\+\_\+v1}\label{page_iface_zwp_linux_dmabuf_v1}
\hypertarget{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_desc}{}\subsection{Description}\label{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_desc}
Following the interfaces from\+: \href{https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt}{\tt https\+://www.\+khronos.\+org/registry/egl/extensions/\+E\+X\+T/\+E\+G\+L\+\_\+\+E\+X\+T\+\_\+image\+\_\+dma\+\_\+buf\+\_\+import.\+txt} and the Linux D\+RM sub-\/system\textquotesingle{}s Add\+Fb2 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 \textquotesingle{}format\textquotesingle{} and \textquotesingle{}modifier\textquotesingle{} events.

The following are required from clients\+:


\begin{DoxyItemize}
\item 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.
\item Don\textquotesingle{}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.
\end{DoxyItemize}

The underlying graphics stack must ensure the following\+:


\begin{DoxyItemize}
\item 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.
\end{DoxyItemize}

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 \textquotesingle{}add\textquotesingle{} request. Finally, a \textquotesingle{}create\textquotesingle{} or \textquotesingle{}create\+\_\+immed\textquotesingle{} request is issued, which has the following outcome depending on the import success.

The \textquotesingle{}create\textquotesingle{} request,
\begin{DoxyItemize}
\item on success, triggers a \textquotesingle{}created\textquotesingle{} event which provides the final wl\+\_\+buffer to the client.
\item on failure, triggers a \textquotesingle{}failed\textquotesingle{} event to convey that the server cannot use the dmabufs received from the client.
\end{DoxyItemize}

For the \textquotesingle{}create\+\_\+immed\textquotesingle{} request,
\begin{DoxyItemize}
\item on success, the server immediately imports the added dmabufs to create a wl\+\_\+buffer. No event is sent from the server in this case.
\item on failure, the server can choose to either\+:
\item terminate the client by raising a fatal error.
\item mark the wl\+\_\+buffer as failed, and send a \textquotesingle{}failed\textquotesingle{} event to the client. If the client uses a failed wl\+\_\+buffer as an argument to any request, the behaviour is compositor implementation-\/defined.
\end{DoxyItemize}

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 \textquotesingle{}z\textquotesingle{} prefix and the version number in the protocol and interface names are removed and the interface version number is reset. \hypertarget{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_api}{}\subsection{A\+PI}\label{page_iface_zwp_linux_dmabuf_v1_page_iface_zwp_linux_dmabuf_v1_api}
See \mbox{\hyperlink{group__iface__zwp__linux__dmabuf__v1}{The zwp\+\_\+linux\+\_\+dmabuf\+\_\+v1 interface}}. \hypertarget{page_iface_zwp_linux_buffer_params_v1}{}\section{zwp\+\_\+linux\+\_\+buffer\+\_\+params\+\_\+v1}\label{page_iface_zwp_linux_buffer_params_v1}
\hypertarget{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_desc}{}\subsection{Description}\label{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_desc}
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 \textquotesingle{}create\textquotesingle{}.

Single-\/planar formats only require one dmabuf, however multi-\/planar formats may require more than one dmabuf. For all formats, an \textquotesingle{}add\textquotesingle{} request must be called once per plane (even if the underlying dmabuf fd is identical).

You must use consecutive plane indices (\textquotesingle{}plane\+\_\+idx\textquotesingle{} argument for \textquotesingle{}add\textquotesingle{}) 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. \hypertarget{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_api}{}\subsection{A\+PI}\label{page_iface_zwp_linux_buffer_params_v1_page_iface_zwp_linux_buffer_params_v1_api}
See \mbox{\hyperlink{group__iface__zwp__linux__buffer__params__v1}{The zwp\+\_\+linux\+\_\+buffer\+\_\+params\+\_\+v1 interface}}. 