wayland::server::surface_t(3)

📦
version 1.0.1 · 10 versions
, in ubuntu stonking

🦋 wayland::server::surface_t(3) — Wayland++ 🦋

Okay bestie, welcome to the wayland::server::surface_t page from the Wayland++ manual 💅 this is the whole vibe: an onscreen surface, its events, its role drama, and every inherited resource function that comes along for the ride.

🌸 NAME 🌸

wayland::server::surface_t — an onscreen surface

✨ SYNOPSIS ✨

#include <wayland-server-protocol.hpp>

💅 Public Member Functions 💅

  • std::function< void()> & on_destroy () — delete surface
  • std::function< void(buffer_t, int32_t, int32_t)> & on_attach () — set the surface contents
  • std::function< void(int32_t, int32_t, int32_t, int32_t)> & on_damage () — mark part of the surface damaged
  • std::function< void(callback_t)> & on_frame () — request a frame throttling hint
  • std::function< void(region_t)> & on_set_opaque_region () — set opaque region
  • std::function< void(region_t)> & on_set_input_region () — set input region
  • std::function< void()> & on_commit () — commit pending surface state
  • std::function< void(output_transform)> & on_set_buffer_transform () — sets the buffer transformation
  • std::function< void(int32_t)> & on_set_buffer_scale () — sets the buffer scaling factor
  • std::function< void(int32_t, int32_t, int32_t, int32_t)> & on_damage_buffer () — mark part of the surface damaged using buffer coordinates
  • std::function< void(int32_t, int32_t)> & on_offset () — set the surface contents offset
  • void enter (output_t const &output, bool post=true) — surface enters an output
  • void leave (output_t const &output, bool post=true) — surface leaves an output
  • void post_invalid_scale (std::string const &msg) — Post error: buffer scale value is invalid.
  • void post_invalid_transform (std::string const &msg) — Post error: buffer transform value is invalid.
  • void post_invalid_size (std::string const &msg) — Post error: buffer size is invalid.
  • void post_invalid_offset (std::string const &msg) — Post error: buffer offset is invalid.
  • bool proxy_has_object () const — Check whether this wrapper actually wraps an object.
  • void post_no_memory () const
  • uint32_t get_id () const
  • client_t get_client () const
  • unsigned int get_version () const
  • std::string get_class ()

🎀 Static Public Attributes 🎀

  • static constexpr std::uint32_t enter_since_version = 1 — Minimum protocol version required for the enter function.
  • static constexpr std::uint32_t leave_since_version = 1 — Minimum protocol version required for the leave function.

💖 Detailed Description 💖

an onscreen surface

Okay so picture a rectangle. That's a surface. It can be displayed on zero or more outputs, and the compositor can show it as many times as it wants. Surfaces can present wl_buffers, receive user input, and define a local coordinate system.

The size of a surface (and relative positions on it) is described in surface-local coordinates. Those may differ from the buffer coordinates of the pixel content when a buffer_transform or a buffer_scale is in play.

A surface without a "role" is fairly useless: the compositor does not know where, when, or how to present it. The role is the purpose of a wl_surface. Examples of roles are a cursor for a pointer (as set by wl_pointer.set_cursor), a drag icon (wl_data_device.start_drag), a sub-surface (wl_subcompositor.get_subsurface), and a window as defined by a shell protocol (e.g. wl_shell.get_shell_surface).

A surface can have only one role at a time. Initially a wl_surface does not have a role. Once a wl_surface is given a role, it is set permanently for the whole lifetime of the wl_surface object. Giving the current role again is allowed, unless explicitly forbidden by the relevant interface specification.

Surface roles are given by requests in other interfaces such as wl_pointer.set_cursor. The request should explicitly mention that this request gives a role to a wl_surface. Often, this request also creates a new protocol object that represents the role and adds additional functionality to wl_surface. When a client wants to destroy a wl_surface, they must destroy this 'role object' before the wl_surface.

Destroying the role object does not remove the role from the wl_surface, but it may stop the wl_surface from "playing the role". For instance, if a wl_subsurface object is destroyed, the wl_surface it was created for will be unmapped and forget its position and z-order. It is allowed to create a wl_subsurface for the same wl_surface again, but it is not allowed to use the wl_surface as a cursor (cursor is a different role than sub-surface, and role switching is not allowed).

Definition at line 2138 of file wayland-server-protocol.hpp.

👑 Member Function Documentation 👑

🫶 void surface_t::enter (output_t const & output, bool post = true)

surface enters an output

Parameters

  • output — output entered by the surface

This is emitted whenever a surface's creation, movement, or resizing results in some part of it being within the scanout region of an output.

Note that a surface may be overlapping with zero or more outputs.

Definition at line 2475 of file wayland-server-protocol.cpp.

🎀 std::string wayland::server::resource_t::get_class () [inherited]

Retrieve the interface name (class) of a resource object.

Returns: Interface name of the resource object.

🌸 client_t wayland::server::resource_t::get_client () const [inherited]

Get the associated client

Returns: the client that owns the resource.

🦋 uint32_t wayland::server::resource_t::get_id () const [inherited]

Get the internal ID of the resource

Returns: the internal ID of the resource

⭐ unsigned int wayland::server::resource_t::get_version () const [inherited]

Get interface version

Returns: Interface version this resource has been constructed with.

💜 void surface_t::leave (output_t const & output, bool post = true)

surface leaves an output

Parameters

  • output — output left by the surface

This is emitted whenever a surface's creation, movement, or resizing results in it no longer having any part of it within the scanout region of an output.

Clients should not use the number of outputs the surface is on for frame throttling purposes. The surface might be hidden even if no leave event has been sent, and the compositor might expect new surface content updates even if no enter event has been sent. The frame event should be used instead.

Definition at line 2480 of file wayland-server-protocol.cpp.

🔥 std::function< void(buffer_t, int32_t, int32_t)> & surface_t::on_attach ()

set the surface contents

Parameters

  • buffer — buffer of surface contents
  • x — surface-local x coordinate
  • y — surface-local y coordinate

Set a buffer as the content of this surface.

The new size of the surface is calculated based on the buffer size transformed by the inverse buffer_transform and the inverse buffer_scale. This means that at commit time the supplied buffer size must be an integer multiple of the buffer_scale. If that's not the case, an invalid_size error is sent.

The x and y arguments specify the location of the new pending buffer's upper left corner, relative to the current buffer's upper left corner, in surface-local coordinates. In other words, the x and y, combined with the new surface size, define in which directions the surface's size changes. Setting anything other than 0 as x and y arguments is discouraged, and should instead be replaced with using the separate wl_surface.offset request.

When the bound wl_surface version is 5 or higher, passing any non-zero x or y is a protocol violation, and will result in an 'invalid_offset' error being raised. To achieve equivalent semantics, use wl_surface.offset.

Surface contents are double-buffered state, see wl_surface.commit.

The initial surface contents are void; there is no content. wl_surface.attach assigns the given wl_buffer as the pending wl_buffer. wl_surface.commit makes the pending wl_buffer the new surface contents, and the size of the surface becomes the size calculated from the wl_buffer, as described above. After commit, there is no pending buffer until the next attach.

Committing a pending wl_buffer allows the compositor to read the pixels in the wl_buffer. The compositor may access the pixels at any time after the wl_surface.commit request. When the compositor will not access the pixels anymore, it will send the wl_buffer.release event. Only after receiving wl_buffer.release, the client may reuse the wl_buffer. A wl_buffer that has been attached and then replaced by another attach instead of committed will not receive a release event, and is not used by the compositor.

If a pending wl_buffer has been committed to more than one wl_surface, the delivery of wl_buffer.release events becomes undefined. A well behaved client should not rely on wl_buffer.release events in this case. Alternatively, a client could create multiple wl_buffer objects from the same backing storage or use wp_linux_buffer_release.

Destroying the wl_buffer after wl_buffer.release does not change the surface contents. Destroying the wl_buffer before wl_buffer.release is allowed as long as the underlying buffer storage isn't re-used (this can happen e.g. on client process termination). However, if the client destroys the wl_buffer before receiving the wl_buffer.release event and mutates the underlying buffer storage, the surface contents become undefined immediately.

If wl_surface.attach is sent with a NULL wl_buffer, the following wl_surface.commit will remove the surface content.

Definition at line 2415 of file wayland-server-protocol.cpp.

🌈 std::function< void()> & surface_t::on_commit ()

commit pending surface state

Surface state (input, opaque, and damage regions, attached buffers, etc.) is double-buffered. Protocol requests modify the pending state, as opposed to the current state in use by the compositor. A commit request atomically applies all pending state, replacing the current state. After commit, the new pending state is as documented for each related request.

On commit, a pending wl_buffer is applied first, and all other state second. This means that all coordinates in double-buffered state are relative to the new wl_buffer coming into use, except for wl_surface.attach itself. If there is no pending wl_buffer, the coordinates are relative to the current surface contents.

All requests that need a commit to become effective are documented to affect double-buffered state.

Other interfaces may add further double-buffered surface state.

Definition at line 2445 of file wayland-server-protocol.cpp.

💫 std::function< void(int32_t, int32_t, int32_t, int32_t)> & surface_t::on_damage ()

mark part of the surface damaged

Parameters

  • x — surface-local x coordinate
  • y — surface-local y coordinate
  • width — width of damage rectangle
  • height — height of damage rectangle

Okay so picture the pending buffer and the current surface contents beefing 💀 — this request is literally how you point at exactly where they differ. Those regions are the ones the surface needs to repaint, periodt. Anything in your damage rectangle that hangs off the edge of the surface? The compositor just ignores it, no cap.

Damage is double-buffered state, see wl_surface.commit. 📌

The damage rectangle is in surface-local coordinates, where x and y specify the upper-left corner of the damage rectangle.

The initial value of pending damage is empty — no damage, nothing, zero, a clean slate ✨. wl_surface.damage adds pending damage: the new pending damage is the union of the old pending damage and the rectangle you just gave it.

wl_surface.commit assigns pending damage as the current damage and clears pending damage. Then the server clears the current damage as it repaints the surface. 🎨

Note! New clients should not use this request 🙅‍♀️. Instead, damage can be posted with wl_surface.damage_buffer, which uses buffer coordinates instead of surface coordinates. iykyk.

Definition at line 2421 of file wayland-server-protocol.cpp.

std::function< void(int32_t, int32_t, int32_t, int32_t)> & surface_t::on_damage_buffer ()

Mark part of the surface damaged — but using buffer coordinates this time 🦋.

Parameters, bestie:

  • x — buffer-local x coordinate
  • y — buffer-local y coordinate
  • width — width of damage rectangle
  • height — height of damage rectangle

This request describes the regions where the pending buffer differs from the current surface contents, and where the surface therefore needs to be repainted. The compositor ignores the parts of the damage that fall outside of the surface.

Damage is double-buffered state, see wl_surface.commit.

The damage rectangle is specified in buffer coordinates, where x and y specify the upper left corner of the damage rectangle.

The initial value for pending damage is empty — no damage, bestie. wl_surface.damage_buffer adds pending damage: the new pending damage is the union of old pending damage and the given rectangle.

wl_surface.commit assigns pending damage as the current damage, and clears pending damage. The server will clear the current damage as it repaints the surface.

Here's the one (1) difference from wl_surface.damage — it takes damage in buffer coordinates instead of surface-local coordinates 👑. That's basically more intuitive than surface coordinates anyway, but it's especially desirable when you're using wp_viewport, or when a drawing library (like EGL) is blissfully unaware of buffer scale and buffer transform. 🙈

Note: Because buffer transformation changes and damage requests may be interleaved in the protocol stream, it is impossible to determine the actual mapping between surface and buffer damage until wl_surface.commit time 😭. So compositors wishing to take both kinds of damage into account will have to accumulate damage from the two requests separately, and only transform from one to the other after receiving the wl_surface.commit. Fr fr, no shortcuts.

Definition at line 2463 of file wayland-server-protocol.cpp.

std::function< void()> & surface_t::on_destroy ()

Delete surface. Deletes the surface and invalidates its object ID. 💀 That's it, that's the whole vibe — the object ID is gone, don't come looking for it.

Definition at line 2409 of file wayland-server-protocol.cpp.

std::function< void(callback_t)> & surface_t::on_frame ()

Request a frame throttling hint 🎀 — the actual glow-up request for anyone doing animations.

Parameters:

  • callback — callback object for the frame request

Request a notification when it's a good time to start drawing a new frame, by creating a frame callback. This is the moment for throttling redrawing operations and driving animations. 🌀

When a client is animating on a wl_surface, it can use the frame request to get notified when it's a good time to draw and commit the next frame of animation. If the client commits an update earlier than that, it's likely that some updates will not make it to the display — and the client is out here wasting resources by drawing too often. Not the move. 🙅

The frame request takes effect on the next wl_surface.commit. The notification will only be posted for one frame unless requested again. For a wl_surface, the notifications are posted in the order the frame requests were committed.

The server must send the notifications so that a client won't send excessive updates, while still allowing the highest possible update rate for clients that wait for the reply before drawing again. The server should give some time for the client to draw and commit after sending the frame callback events, so it can hit the next output refresh. ✨

A server should avoid signaling the frame callbacks if the surface isn't visible in any way — like, the surface is off-screen, or completely obscured by other opaque surfaces. Why ping someone who isn't even on screen, right?

Heads up: the object returned by this request will be destroyed by the compositor after the callback is fired, and as such the client must not attempt to use it after that point. Use-after-free is not the main character energy we're going for 😭.

The callback_data passed in the callback is the current time, in milliseconds, with an undefined base. Yeah, undefined base, we don't know from when, don't ask.

Definition at line 2427 of file wayland-server-protocol.cpp.

std::function< void(int32_t, int32_t)> & surface_t::on_offset ()

Set the surface contents offset 🌸.

Parameters:

  • x — surface-local x coordinate
  • y — surface-local y coordinate

The x and y arguments specify the location of the new pending buffer's upper left corner, relative to the current buffer's upper left corner, in surface-local coordinates. In other words: x and y, combined with the new surface size, define in which directions the surface's size changes. 🧭

Surface location offset is double-buffered state, see wl_surface.commit.

This request is semantically equivalent to — and replaces — the x and y arguments in the wl_surface.attach request in wl_surface versions prior to 5. See wl_surface.attach for details.

Definition at line 2469 of file wayland-server-protocol.cpp.

std::function< void(int32_t)> & surface_t::on_set_buffer_scale ()

Sets the buffer scaling factor 💅.

Parameters:

  • scale — positive scale for interpreting buffer contents

This request sets an optional scaling factor on how the compositor interprets the contents of the buffer attached to the window.

Buffer scale is double-buffered state, see wl_surface.commit.

A newly created surface has its buffer scale set to 1. ✨

wl_surface.set_buffer_scale changes the pending buffer scale. wl_surface.commit copies the pending buffer scale to the current one. Otherwise, the pending and current values are never changed. Ever. That's the whole deal.

The purpose here is to let clients supply higher resolution buffer data for use on high resolution outputs. The vibe is: pick the same buffer scale as the scale of the output the surface is displayed on. That way the compositor can avoid scaling when rendering the surface on that output. Big brain. 🧠

Careful tho: if the scale is larger than 1, then you have to attach a buffer that is larger (by a factor of scale in each dimension) than the desired surface size.

If scale is not positive, the invalid_scale protocol error is raised. 🚨

Definition at line 2457 of file wayland-server-protocol.cpp.

std::function< void(output_transform)> & surface_t::on_set_buffer_transform ()

Sets the buffer transformation 🦋.

Parameters:

  • transform — transform for interpreting buffer contents

This request sets an optional transformation on how the compositor interprets the contents of the buffer attached to the surface. The accepted values for the transform parameter are the values for wl_output.transform. No inventing your own, bestie.

Buffer transform is double-buffered state, see wl_surface.commit.

A newly created surface has its buffer transformation set to normal.

wl_surface.set_buffer_transform changes the pending buffer transformation. wl_surface.commit copies the pending buffer transformation to the current one. Otherwise, the pending and current values are never changed.

The purpose of this request is to allow clients to render content according to the output transform, which lets the compositor use certain optimizations even if the display is rotated. 💫 Using hardware overlays and scanning out a client buffer for fullscreen surfaces are examples of such optimizations. Those optimizations are highly dependent on the compositor implementation, so the use of this request should be considered on a case-by-case basis. Don't just assume it'll pop off.

Note: if the transform value includes 90 or 270 degree rotation, the width of the buffer will become the surface height and the height of the buffer will become the surface width. Flip-flop, iconic.

If transform is not one of the values from the wl_output.transform enum, the invalid_transform protocol error is raised. 🚨

Definition at line 2451 of file wayland-server-protocol.cpp.

std::function< void(region_t)> & surface_t::on_set_input_region ()

Set input region 🫶.

Parameters:

  • region — input region of the surface

This request sets the region of the surface that can receive pointer and touch events. So like, where the taps actually land. 👆

Input events happening outside of this region will try the next surface in the server surface stack. The compositor ignores the parts of the input region that fall outside of the surface.

The input region is specified in surface-local coordinates.

Input region is double-buffered state, see wl_surface.commit.

wl_surface.set_input_region changes the pending input region. wl_surface.commit copies the pending region to the current region. Otherwise the pending and current regions are never changed — except cursor and icon surfaces are special cases, see wl_pointer.set_cursor and wl_data_device.start_drag. 😌

The initial value for an input region is infinite. That means the whole surface will accept input. Setting the pending input region has copy semantics, and the wl_region object can be destroyed immediately. A NULL wl_region causes the input region to be set to infinite. Yes, NULL = infinite, it's giving chaos but it's correct 💅.

Definition at line 2439 of file wayland-server-protocol.cpp.

std::function< void(region_t)> & surface_t::on_set_opaque_region ()

Set opaque region 👑

Parameters:

  • region — opaque region of the surface

This request sets the region of the surface that contains opaque content.

The opaque region is an optimization hint for the compositor that lets it optimize the redrawing of content behind opaque regions. Setting an opaque region is not required for correct behaviour, but marking transparent content as opaque will result in repaint artifacts. So like... don't lie to the compositor, it'll show. 💀

The opaque region is specified in surface-local coordinates.

The compositor ignores the parts of the opaque region that fall outside of the surface.

Opaque region is double-buffered state, see wl_surface.commit.

wl_surface.set_opaque_region changes the pending opaque region. wl_surface.commit copies the pending region to the current region. Otherwise, the pending and current regions are never changed.

The initial value for an opaque region is empty. Setting the pending opaque region has copy semantics, and the wl_region object can be destroyed immediately. A NULL wl_region causes the pending opaque region to be set to empty.

literally just know that this is the tail of set_opaque_region — Definition at line 2433 of file wayland-server-protocol.cpp.

void surface_t::post_invalid_offset (std::string const & msg)

Posts the error: buffer offset is invalid. 💀

Definition at line 2500 of file wayland-server-protocol.cpp.

void surface_t::post_invalid_scale (std::string const & msg)

Posts the error: buffer scale value is invalid.

Definition at line 2485 of file wayland-server-protocol.cpp.

void surface_t::post_invalid_size (std::string const & msg)

Posts the error: buffer size is invalid.

Definition at line 2495 of file wayland-server-protocol.cpp.

void surface_t::post_invalid_transform (std::string const & msg)

Posts the error: buffer transform value is invalid.

Definition at line 2490 of file wayland-server-protocol.cpp.

void wayland::server::resource_t::post_no_memory () const [inherited]

Posts the "not enough memory" error to the client. 🫠

So like — if the compositor doesn't have enough memory to fulfill a request the client made, you call this function to let the client know that's what's going on. No cap, that's the whole vibe.

bool wayland::server::resource_t::proxy_has_object () const [inherited]

Checks whether this wrapper actually wraps an object. 👀

Returns

  • true if there's genuinely an underlying object chillin' in there
  • false if this wrapper is empty

🌸 Member Data Documentation 🌸

std::uint32_t wayland::server::surface_t::enter_since_version = 1 [static], [constexpr]

The minimum protocol version required for the enter function. ⭐

Definition at line 2541 of file wayland-server-protocol.hpp.

std::uint32_t wayland::server::surface_t::leave_since_version = 1 [static], [constexpr]

The minimum protocol version required for the leave function. 🦋

Definition at line 2561 of file wayland-server-protocol.hpp.

🫶 Author 🫶

Generated automatically by Doxygen for Wayland++ from the source code. Not a human bestie, just a very industrious little robot. 🤖💖

ok that's the whole page!! tysm for reading to the end, you ate that fr fr. this was Version 1.0.1, dated Fri Mar 27 2026 13:15 — go forth and slay your surfaces, ily, mwah 💅✨🎀
📦 where this page comes from