.TH "wayland::zwp_linux_buffer_params_v1_t" 3 "Wed May 3 2023" "Version 1.0.0" "Wayland++" \" -*- nroff -*- .ad l .nh .SH NAME wayland::zwp_linux_buffer_params_v1_t \- parameters for creating a dmabuf-based wl_buffer .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBwayland::proxy_t\fP\&. .SS "Public Types" .in +1c .ti -1c .RI "enum class \fBwrapper_type\fP { \fBstandard\fP, \fBdisplay\fP, \fBforeign\fP, \fBproxy_wrapper\fP }" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "void \fBadd\fP (int fd, uint32_t plane_idx, uint32_t offset, uint32_t stride, uint32_t modifier_hi, uint32_t modifier_lo)" .br .RI "add a dmabuf to the temporary set " .ti -1c .RI "void \fBcreate\fP (int32_t width, int32_t height, uint32_t format, zwp_linux_buffer_params_v1_flags const &flags)" .br .RI "create a wl_buffer from the given dmabufs " .ti -1c .RI "\fBbuffer_t\fP \fBcreate_immed\fP (int32_t width, int32_t height, uint32_t format, zwp_linux_buffer_params_v1_flags const &flags)" .br .RI "immediately create a wl_buffer from the given dmabufs " .ti -1c .RI "bool \fBcan_create_immed\fP () const" .br .RI "Check whether the \fBcreate_immed\fP function is available with the currently bound version of the protocol\&. " .ti -1c .RI "std::function< void(\fBbuffer_t\fP)> & \fBon_created\fP ()" .br .RI "buffer creation succeeded " .ti -1c .RI "std::function< void()> & \fBon_failed\fP ()" .br .RI "buffer creation failed " .ti -1c .RI "uint32_t \fBget_id\fP () const" .br .RI "Get the id of a proxy object\&. " .ti -1c .RI "std::string \fBget_class\fP () const" .br .RI "Get the interface name (class) of a proxy object\&. " .ti -1c .RI "uint32_t \fBget_version\fP () const" .br .RI "Get the protocol object version of a proxy object\&. " .ti -1c .RI "\fBwrapper_type\fP \fBget_wrapper_type\fP () const" .br .RI "Get the type of a proxy object\&. " .ti -1c .RI "void \fBset_queue\fP (\fBevent_queue_t\fP queue)" .br .RI "Assign a proxy to an event queue\&. " .ti -1c .RI "wl_proxy * \fBc_ptr\fP () const" .br .RI "Get a pointer to the underlying C struct\&. " .ti -1c .RI "bool \fBproxy_has_object\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "\fBoperator bool\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "bool \fBoperator==\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to the same object\&. " .ti -1c .RI "bool \fBoperator!=\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to different objects\&. " .ti -1c .RI "void \fBproxy_release\fP ()" .br .RI "Release the wrapped object (if any), making this an empty wrapper\&. " .in -1c .SS "Static Public Attributes" .in +1c .ti -1c .RI "static constexpr std::uint32_t \fBadd_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBadd\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBcreate_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBcreate\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBcreate_immed_since_version\fP = 2" .br .RI "Minimum protocol version required for the \fBcreate_immed\fP function\&. " .in -1c .SH "Detailed Description" .PP 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'\&. .PP 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)\&. .PP 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\&. .PP Definition at line \fB1670\fP of file \fBwayland\-client\-protocol\-unstable\&.hpp\fP\&. .SH "Member Enumeration Documentation" .PP .SS "enum class \fBwayland::proxy_t::wrapper_type\fP\fC [strong]\fP, \fC [inherited]\fP" Underlying wl_proxy type and properties of a \fBproxy_t\fP that affect construction, destruction, and event handling .PP \fBEnumerator\fP .in +1c .TP \fB\fIstandard \fP\fP C pointer is a standard type compatible with wl_proxy*\&. Events are dispatched and it is destructed when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIdisplay \fP\fP C pointer is a wl_display*\&. No events are dispatched, wl_display_disconnect is called when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIforeign \fP\fP C pointer is a standard type compatible with wl_proxy*, but another library owns it and it should not be touched in a way that could affect the operation of the other library\&. No events are dispatched, wl_proxy_destroy is not called when the \fBproxy_t\fP is destructed, user data is not touched\&. Consequently, there is no reference counting for the \fBproxy_t\fP\&. Lifetime of such wrappers should preferably be short to minimize the chance that the owning library decides to destroy the wl_proxy\&. .TP \fB\fIproxy_wrapper \fP\fP C pointer is a wl_proxy* that was constructed with wl_proxy_create_wrapper\&. No events are dispatched, wl_proxy_wrapper_destroy is called when the \fBproxy_t\fP is destroyed\&. Reference counting is active\&. A reference to the \fBproxy_t\fP creating this proxy wrapper is held to extend its lifetime until after the proxy wrapper is destroyed\&. .PP Definition at line \fB115\fP of file \fBwayland\-client\&.hpp\fP\&. .SH "Member Function Documentation" .PP .SS "void zwp_linux_buffer_params_v1_t::add (int fd, uint32_t plane_idx, uint32_t offset, uint32_t stride, uint32_t modifier_hi, uint32_t modifier_lo)" .PP add a dmabuf to the temporary set .PP \fBParameters\fP .RS 4 \fIfd\fP dmabuf fd .br \fIplane_idx\fP plane index .br \fIoffset\fP offset in bytes .br \fIstride\fP stride in bytes .br \fImodifier_hi\fP high 32 bits of layout modifier .br \fImodifier_lo\fP low 32 bits of layout modifier .RE .PP This request adds one dmabuf to the set in this zwp_linux_buffer_params_v1\&. .PP 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\&. .PP Starting from version 4, the invalid_format protocol error is sent if the format + modifier pair was not advertised as supported\&. .PP 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\&. .PP Definition at line \fB5324\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "wl_proxy * wayland::proxy_t::c_ptr () const\fC [inherited]\fP" .PP Get a pointer to the underlying C struct\&. .PP \fBReturns\fP .RS 4 The underlying wl_proxy wrapped by this \fBproxy_t\fP if it exists, otherwise an exception is thrown .RE .PP .SS "bool zwp_linux_buffer_params_v1_t::can_create_immed () const" .PP Check whether the \fBcreate_immed\fP function is available with the currently bound version of the protocol\&. .PP Definition at line \fB5342\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "void zwp_linux_buffer_params_v1_t::create (int32_t width, int32_t height, uint32_t format, zwp_linux_buffer_params_v1_flags const & flags)" .PP create a wl_buffer from the given dmabufs .PP \fBParameters\fP .RS 4 \fIwidth\fP base plane width in pixels .br \fIheight\fP base plane height in pixels .br \fIformat\fP DRM_FORMAT code .br \fIflags\fP see enum flags .RE .PP 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\&. .PP 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\&. .PP The 'flags' is a bitfield of the flags defined in enum 'flags'\&. 'y_invert' means the that the image needs to be y-flipped\&. .PP 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\&. .PP 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\&. .PP 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\&. .PP 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\&. .PP 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\&. .PP 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\&. .PP It is not mandatory to issue 'create'\&. If a client wants to cancel the buffer creation, it can just destroy this object\&. .PP Definition at line \fB5330\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "\fBbuffer_t\fP zwp_linux_buffer_params_v1_t::create_immed (int32_t width, int32_t height, uint32_t format, zwp_linux_buffer_params_v1_flags const & flags)" .PP immediately create a wl_buffer from the given dmabufs .PP \fBReturns\fP .RS 4 id for the newly created wl_buffer .RE .PP \fBParameters\fP .RS 4 \fIwidth\fP base plane width in pixels .br \fIheight\fP base plane height in pixels .br \fIformat\fP DRM_FORMAT code .br \fIflags\fP see enum flags .RE .PP This asks for immediate creation of a wl_buffer by importing the added dmabufs\&. .PP In case of import success, no event is sent from the server, and the wl_buffer is ready to be used by the client\&. .PP Upon import failure, either of the following may happen, as seen fit by the implementation: .IP "\(bu" 2 the client is terminated with one of the following fatal protocol errors: .IP " \(bu" 4 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\&. .IP " \(bu" 4 INVALID_WL_BUFFER, in case the cause for failure is unknown or plaform specific\&. .PP .IP "\(bu" 2 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\&. .PP .PP This takes the same arguments as a 'create' request, and obeys the same restrictions\&. .PP Definition at line \fB5336\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "std::string wayland::proxy_t::get_class () const\fC [inherited]\fP" .PP Get the interface name (class) of a proxy object\&. .PP \fBReturns\fP .RS 4 The interface name of the object associated with the proxy .RE .PP .SS "uint32_t wayland::proxy_t::get_id () const\fC [inherited]\fP" .PP Get the id of a proxy object\&. .PP \fBReturns\fP .RS 4 The id the object associated with the proxy .RE .PP .SS "uint32_t wayland::proxy_t::get_version () const\fC [inherited]\fP" .PP Get the protocol object version of a proxy object\&. Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API\&. .PP A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object's real version\&. .PP \fBdisplay_t\fP will always return version 0\&. .PP \fBReturns\fP .RS 4 The protocol object version of the proxy or 0 .RE .PP .SS "\fBwrapper_type\fP wayland::proxy_t::get_wrapper_type () const\fC [inline]\fP, \fC [inherited]\fP" .PP Get the type of a proxy object\&. .PP Definition at line \fB301\fP of file \fBwayland\-client\&.hpp\fP\&. .SS "std::function< void(\fBbuffer_t\fP)> & zwp_linux_buffer_params_v1_t::on_created ()" .PP buffer creation succeeded .PP \fBParameters\fP .RS 4 \fIbuffer\fP the newly created wl_buffer .RE .PP This event indicates that the attempted buffer creation was successful\&. It provides the new wl_buffer referencing the dmabuf(s)\&. .PP Upon receiving this event, the client should destroy the zlinux_dmabuf_params object\&. .PP Definition at line \fB5348\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "std::function< void()> & zwp_linux_buffer_params_v1_t::on_failed ()" .PP 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\&. .PP Upon receiving this event, the client should destroy the zlinux_buffer_params object\&. .PP Definition at line \fB5353\fP of file \fBwayland\-client\-protocol\-unstable\&.cpp\fP\&. .SS "wayland::proxy_t::operator bool () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "bool wayland::proxy_t::operator!= (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to different objects\&. .SS "bool wayland::proxy_t::operator== (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to the same object\&. .SS "bool wayland::proxy_t::proxy_has_object () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "void wayland::proxy_t::proxy_release ()\fC [inherited]\fP" .PP Release the wrapped object (if any), making this an empty wrapper\&. Note that \fBdisplay_t\fP instances cannot be released this way\&. Attempts to do so are ignored\&. .PP \fBExamples\fP .in +1c \fBforeign_display\&.cpp\fP\&. .SS "void wayland::proxy_t::set_queue (\fBevent_queue_t\fP queue)\fC [inherited]\fP" .PP Assign a proxy to an event queue\&. .PP \fBParameters\fP .RS 4 \fIqueue\fP The event queue that will handle this proxy .RE .PP Assign proxy to event queue\&. Events coming from proxy will be queued in queue instead of the display's main queue\&. .PP See also: \fBdisplay_t::dispatch_queue()\fP\&. .PP \fBExamples\fP .in +1c \fBproxy_wrapper\&.cpp\fP\&. .SH "Member Data Documentation" .PP .SS "constexpr std::uint32_t wayland::zwp_linux_buffer_params_v1_t::add_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBadd\fP function\&. .PP Definition at line \fB1724\fP of file \fBwayland\-client\-protocol\-unstable\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::zwp_linux_buffer_params_v1_t::create_immed_since_version = 2\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBcreate_immed\fP function\&. .PP Definition at line \fB1835\fP of file \fBwayland\-client\-protocol\-unstable\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::zwp_linux_buffer_params_v1_t::create_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBcreate\fP function\&. .PP Definition at line \fB1797\fP of file \fBwayland\-client\-protocol\-unstable\&.hpp\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Wayland++ from the source code\&.