.TH "wayland::subsurface_t" 3 "Wed May 3 2023" "Version 1.0.0" "Wayland++" \" -*- nroff -*- .ad l .nh .SH NAME wayland::subsurface_t \- sub-surface interface to a wl_surface .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 \fBset_position\fP (int32_t x, int32_t y)" .br .RI "reposition the sub-surface " .ti -1c .RI "void \fBplace_above\fP (\fBsurface_t\fP const &sibling)" .br .RI "restack the sub-surface " .ti -1c .RI "void \fBplace_below\fP (\fBsurface_t\fP const &sibling)" .br .RI "restack the sub-surface " .ti -1c .RI "void \fBset_sync\fP ()" .br .RI "set sub-surface to synchronized mode " .ti -1c .RI "void \fBset_desync\fP ()" .br .RI "set sub-surface to desynchronized mode " .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 \fBset_position_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBset_position\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBplace_above_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBplace_above\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBplace_below_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBplace_below\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBset_sync_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBset_sync\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBset_desync_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBset_desync\fP function\&. " .in -1c .SH "Detailed Description" .PP sub-surface interface to a wl_surface An additional interface to a wl_surface object, which has been made a sub-surface\&. A sub-surface has one parent surface\&. A sub-surface's size and position are not limited to that of the parent\&. Particularly, a sub-surface is not automatically clipped to its parent's area\&. .PP A sub-surface becomes mapped, when a non-NULL wl_buffer is applied and the parent surface is mapped\&. The order of which one happens first is irrelevant\&. A sub-surface is hidden if the parent becomes hidden, or if a NULL wl_buffer is applied\&. These rules apply recursively through the tree of surfaces\&. .PP The behaviour of a wl_surface\&.commit request on a sub-surface depends on the sub-surface's mode\&. The possible modes are synchronized and desynchronized, see methods wl_subsurface\&.set_sync and wl_subsurface\&.set_desync\&. Synchronized mode caches the wl_surface state to be applied when the parent's state gets applied, and desynchronized mode applies the pending wl_surface state directly\&. A sub-surface is initially in the synchronized mode\&. .PP Sub-surfaces also have another kind of state, which is managed by wl_subsurface requests, as opposed to wl_surface requests\&. This state includes the sub-surface position relative to the parent surface (wl_subsurface\&.set_position), and the stacking order of the parent and its sub-surfaces (wl_subsurface\&.place_above and \&.place_below)\&. This state is applied when the parent surface's wl_surface state is applied, regardless of the sub-surface's mode\&. As the exception, set_sync and set_desync are effective immediately\&. .PP The main surface can be thought to be always in desynchronized mode, since it does not have a parent in the sub-surfaces sense\&. .PP Even if a sub-surface is in desynchronized mode, it will behave as in synchronized mode, if its parent surface behaves as in synchronized mode\&. This rule is applied recursively throughout the tree of surfaces\&. This means, that one can set a sub-surface into synchronized mode, and then assume that all its child and grand-child sub-surfaces are synchronized, too, without explicitly setting them\&. .PP If the wl_surface associated with the wl_subsurface is destroyed, the wl_subsurface object becomes inert\&. Note, that destroying either object takes effect immediately\&. If you need to synchronize the removal of a sub-surface to the parent surface update, unmap the sub-surface first by attaching a NULL wl_buffer, update parent, and then destroy the sub-surface\&. .PP If the parent wl_surface object is destroyed, the sub-surface is unmapped\&. .PP Definition at line \fB3978\fP of file \fBwayland\-client\-protocol\&.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 "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 "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 "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 "void subsurface_t::place_above (\fBsurface_t\fP const & sibling)" .PP restack the sub-surface .PP \fBParameters\fP .RS 4 \fIsibling\fP the reference surface .RE .PP This sub-surface is taken from the stack, and put back just above the reference surface, changing the z-order of the sub-surfaces\&. The reference surface must be one of the sibling surfaces, or the parent surface\&. Using any other surface, including this sub-surface, will cause a protocol error\&. .PP The z-order is double-buffered\&. Requests are handled in order and applied immediately to a pending state\&. The final pending state is copied to the active state the next time the state of the parent surface is applied\&. When this happens depends on whether the parent surface is in synchronized mode or not\&. See wl_subsurface\&.set_sync and wl_subsurface\&.set_desync for details\&. .PP A new sub-surface is initially added as the top-most in the stack of its siblings and parent\&. .PP Definition at line \fB3633\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "void subsurface_t::place_below (\fBsurface_t\fP const & sibling)" .PP restack the sub-surface .PP \fBParameters\fP .RS 4 \fIsibling\fP the reference surface .RE .PP The sub-surface is placed just below the reference surface\&. See wl_subsurface\&.place_above\&. .PP Definition at line \fB3639\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .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 subsurface_t::set_desync ()" .PP set sub-surface to desynchronized mode Change the commit behaviour of the sub-surface to desynchronized mode, also described as independent or freely running mode\&. .PP In desynchronized mode, wl_surface\&.commit on a sub-surface will apply the pending state directly, without caching, as happens normally with a wl_surface\&. Calling wl_surface\&.commit on the parent surface has no effect on the sub-surface's wl_surface state\&. This mode allows a sub-surface to be updated on its own\&. .PP If cached state exists when wl_surface\&.commit is called in desynchronized mode, the pending state is added to the cached state, and applied as a whole\&. This invalidates the cache\&. .PP Note: even if a sub-surface is set to desynchronized, a parent sub-surface may override it to behave as synchronized\&. For details, see wl_subsurface\&. .PP If a surface's parent surface behaves as desynchronized, then the cached state is applied on set_desync\&. .PP Definition at line \fB3651\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "void subsurface_t::set_position (int32_t x, int32_t y)" .PP reposition the sub-surface .PP \fBParameters\fP .RS 4 \fIx\fP x coordinate in the parent surface .br \fIy\fP y coordinate in the parent surface .RE .PP This schedules a sub-surface position change\&. The sub-surface will be moved so that its origin (top left corner pixel) will be at the location x, y of the parent surface coordinate system\&. The coordinates are not restricted to the parent surface area\&. Negative values are allowed\&. .PP The scheduled coordinates will take effect whenever the state of the parent surface is applied\&. When this happens depends on whether the parent surface is in synchronized mode or not\&. See wl_subsurface\&.set_sync and wl_subsurface\&.set_desync for details\&. .PP If more than one set_position request is invoked by the client before the commit of the parent surface, the position of a new request always replaces the scheduled position from any previous request\&. .PP The initial position is 0, 0\&. .PP Definition at line \fB3627\fP of file \fBwayland\-client\-protocol\&.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\&. .SS "void subsurface_t::set_sync ()" .PP set sub-surface to synchronized mode Change the commit behaviour of the sub-surface to synchronized mode, also described as the parent dependent mode\&. .PP In synchronized mode, wl_surface\&.commit on a sub-surface will accumulate the committed state in a cache, but the state will not be applied and hence will not change the compositor output\&. The cached state is applied to the sub-surface immediately after the parent surface's state is applied\&. This ensures atomic updates of the parent and all its synchronized sub-surfaces\&. Applying the cached state will invalidate the cache, so further parent surface commits do not (re-)apply old state\&. .PP See wl_subsurface for the recursive effect of this mode\&. .PP Definition at line \fB3645\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SH "Member Data Documentation" .PP .SS "constexpr std::uint32_t wayland::subsurface_t::place_above_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBplace_above\fP function\&. .PP Definition at line \fB4052\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::subsurface_t::place_below_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBplace_below\fP function\&. .PP Definition at line \fB4065\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::subsurface_t::set_desync_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBset_desync\fP function\&. .PP Definition at line \fB4117\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::subsurface_t::set_position_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBset_position\fP function\&. .PP Definition at line \fB4026\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::subsurface_t::set_sync_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBset_sync\fP function\&. .PP Definition at line \fB4088\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Wayland++ from the source code\&.