wayland::subcompositor_t(3)

📦
version 1.0.1 · 10 versions
, in ubuntu stonking

💅 NAME 💅

okay so this is the wayland::subcompositor_t(3) page from the Wayland++ manual, and it’s all about sub-surface compositing. bestie, it’s giving “nested surfaces have main character energy” and we’re here for it. 💖

✨ SYNOPSIS ✨

#include <wayland-client-protocol.hpp>

Inherits wayland::proxy_t. lowkey iconic inheritance moment. 🫶

🎀 Public Types 🎀

  • enum class wrapper_type { standard, display, foreign, proxy_wrapper } — the wrapper-type enum, fr fr. it tells you what kind of underlying proxy vibe we’re dealing with.

🌸 Public Member Functions 🌸

  • subsurface_t get_subsurface (surface_t const &surface, surface_t const &parent) — give a surface the role sub-surface ✨
  • uint32_t get_id () const [inherited] — Get the id of a proxy object.
  • std::string get_class () const [inherited] — Get the interface name (class) of a proxy object.
  • uint32_t get_version () const [inherited] — Get the protocol object version of a proxy object.
  • wrapper_type get_wrapper_type () const [inherited] — Get the type of a proxy object.
  • void set_queue (event_queue_t queue) [inherited] — Assign a proxy to an event queue.
  • wl_proxy * c_ptr () const [inherited] — Get a pointer to the underlying C struct.
  • bool proxy_has_object () const [inherited] — Check whether this wrapper actually wraps an object.
  • operator bool () const [inherited] — Check whether this wrapper actually wraps an object.
  • bool operator== (const proxy_t &right) const [inherited] — Check whether two wrappers refer to the same object.
  • bool operator!= (const proxy_t &right) const [inherited] — Check whether two wrappers refer to different objects.
  • void proxy_release () [inherited] — Release the wrapped object (if any), making this an empty wrapper.

🦋 Static Public Attributes 🦋

  • static constexpr std::uint32_t get_subsurface_since_version = 1 — Minimum protocol version required for the get_subsurface function. yes bestie, version gate. 💅

💖 Detailed Description 💖

sub-surface compositing

The global interface exposing sub-surface compositing capabilities. A wl_surface, that has sub-surfaces associated, is called the parent surface. Sub-surfaces can be arbitrarily nested and create a tree of sub-surfaces. 🌈

The root surface in a tree of sub-surfaces is the main surface. The main surface cannot be a sub-surface, because sub-surfaces must always have a parent. no cap, the hierarchy is strict. 👑

A main surface with its sub-surfaces forms a (compound) window. For window management purposes, this set of wl_surface objects is to be considered as a single window, and it should also behave as such. it’s literally one window with lore. 🪟✨

The aim of sub-surfaces is to offload some of the compositing work within a window from clients to the compositor. A prime example is a video player with decorations and video in separate wl_surface objects. This should allow the compositor to pass YUV video buffer processing to dedicated overlay hardware when possible. ate. 🔥

Definition at line 3864 of file wayland-client-protocol.hpp.

🧚 Member Enumeration Documentation 🧚

enum class wayland::proxy_t::wrapper_type [strong], [inherited]

Underlying wl_proxy type and properties of a proxy_t that affect construction, destruction, and event handling. this enum is basically the vibe check for how a proxy gets treated. 🫶

Enumerator

  • standard — C pointer is a standard type compatible with wl_proxy*. Events are dispatched and it is destructed when the proxy_t is destructed. User data is set.
  • display — C pointer is a wl_display*. No events are dispatched, wl_display_disconnect is called when the proxy_t is destructed. User data is set.
  • foreign — 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 proxy_t is destructed, user data is not touched. Consequently, there is no reference counting for the proxy_t. Lifetime of such wrappers should preferably be short to minimize the chance that the owning library decides to destroy the wl_proxy.
  • proxy_wrapper — 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 proxy_t is destroyed. Reference counting is active. A reference to the proxy_t creating this proxy wrapper is held to extend its lifetime until after the proxy wrapper is destroyed.

Definition at line 117 of file wayland-client.hpp.

🔥 Member Function Documentation 🔥

wl_proxy * wayland::proxy_t::c_ptr () const [inherited]

Get a pointer to the underlying C struct.

Returns: The underlying wl_proxy wrapped by this proxy_t if it exists, otherwise an exception is thrown. so yeah, bestie, it can absolutely throw. 😭

std::string wayland::proxy_t::get_class () const [inherited]

Get the interface name (class) of a proxy object.

Returns: The interface name of the object associated with the proxy.

uint32_t wayland::proxy_t::get_id () const [inherited]

Get the id of a proxy object.

Returns: The id the object associated with the proxy.

subsurface_t subcompositor_t::get_subsurface (surface_t const & surface, surface_t const & parent)

give a surface the role sub-surface

Returns: the new sub-surface object ID

Parameters:

  • surface — the surface to be turned into a sub-surface
  • parent — the parent surface

Create a sub-surface interface for the given surface, and associate it with the given parent surface. This turns a plain wl_surface into a sub-surface. ✨

The to-be sub-surface must not already have another role, and it must not have an existing wl_subsurface object. Otherwise a protocol error is raised. periodt, that’s a protocol error, not a cute little warning. 💀

Adding sub-surfaces to a parent is a double-buffered operation on the parent (see wl_surface.commit). The effect of adding a sub-surface becomes visible on the next time the state of the parent surface is applied. 👑

This request modifies the behaviour of wl_surface.commit request on the sub-surface, see the documentation on wl_subsurface interface.

Definition at line 3563 of file wayland-client-protocol.cpp.

uint32_t wayland::proxy_t::get_version () const [inherited]

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.

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. bestie, do not guess wildly. 🙈

display_t will always return version 0.

Returns: The protocol object version of the proxy or 0.

wrapper_type wayland::proxy_t::get_wrapper_type () const [inline], [inherited]

Get the type of a proxy object.

Definition at line 303 of file wayland-client.hpp.

wayland::proxy_t::operator bool () const [inherited]

Check whether this wrapper actually wraps an object.

Returns: true if there is an underlying object, false if this wrapper is empty.

bool wayland::proxy_t::operator!= (const proxy_t & right) const [inherited]

Check whether two wrappers refer to different objects.

bool wayland::proxy_t::operator== (const proxy_t & right) const [inherited]

Check whether two wrappers refer to the same object.

bool wayland::proxy_t::proxy_has_object () const [inherited]

Check whether this wrapper actually wraps an object.

Returns: true if there is an underlying object, false if this wrapper is empty.

void wayland::proxy_t::proxy_release () [inherited]

Release the wrapped object (if any), making this an empty wrapper. Note that display_t instances cannot be released this way. Attempts to do so are ignored. not me trying to release a display and getting politely ignored 😭

Examples: foreign_display.cpp.

void wayland::proxy_t::set_queue (event_queue_t queue) [inherited]

Parameters: queue — The event queue that will handle this proxy

Assign proxy to event queue. Events coming from proxy will be queued in queue instead of the display's main queue.

See also: display_t::dispatch_queue().

Examples: proxy_wrapper.cpp.

🍓 Member Data Documentation 🍓

std::uint32_t wayland::subcompositor_t::get_subsurface_since_version = 1 [static], [constexpr]

Minimum protocol version required for the get_subsurface function.

Definition at line 3912 of file wayland-client-protocol.hpp.

👑 Author 👑

Generated automatically by Doxygen for Wayland++ from the source code.

okay bestie, that’s the whole page! 💖 this was Wayland++ version 1.0.1, dated Fri Mar 27 2026 13:15:00 — and yes, the header vibe is wayland::subcompositor_t(3). slay, you made it to the end. ✨🎀

📦 where this page comes from