Struct wayland_server::protocol::wl_surface::WlSurface

pub struct WlSurface { /* private fields */ }

an onscreen surface

A surface is a rectangular area that may be displayed on zero or more outputs, and shown any number of times at the compositor’s discretion. They 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, which may differ from the buffer coordinates of the pixel content, in case a buffer_transform or a buffer_scale is used.

A surface without a “role” is fairly useless: a 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).

See also the Request enum for this interface.

Implementations

impl WlSurface

pub fn enter(&self, output: &WlOutput)

surface enters an output

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.

pub fn leave(&self, output: &WlOutput)

surface leaves an output

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.

Trait Implementations

impl Clone for WlSurface

fn clone(&self) -> WlSurface

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WlSurface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<WlSurface> for WlSurface

fn eq(&self, other: &WlSurface) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Resource for WlSurface

type Request = Request

type Event = Event

fn interface() -> &'static Interface

fn id(&self) -> ObjectId

fn version(&self) -> u32

fn data<U: 'static>(&self) -> Option<&U>

fn object_data(&self) -> Option<&Arc<dyn Any + Send + Sync>>

fn handle(&self) -> &WeakHandle

fn from_id(conn: &DisplayHandle, id: ObjectId) -> Result<Self, InvalidId>

fn send_event(&self, evt: Self::Event) -> Result<(), InvalidId>

fn parse_request(
    conn: &DisplayHandle,
    msg: Message<ObjectId>
) -> Result<(Self, Self::Request), DispatchError>

fn write_event(
    &self,
    conn: &DisplayHandle,
    msg: Self::Event
) -> Result<Message<ObjectId>, InvalidId>

fn post_error(
    &self,
    dh: &DisplayHandle,
    code: impl Into<u32>,
    error: impl Into<String>
)

impl Eq for WlSurface