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).
type 'v t = ([ `Wl_surface ], 'v, [ `Server ]) Proxy.tVersion 1
val leave :
[< `V1 | `V2 | `V3 | `V4 | `V5 ] t ->
output:([ `Wl_output ], 'a, [ `Server ]) Proxy.t ->
unitSurface 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.
val enter :
[< `V1 | `V2 | `V3 | `V4 | `V5 ] t ->
output:([ `Wl_output ], 'a, [ `Server ]) Proxy.t ->
unitSurface 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.
Version 2
Version 3
Version 4
Version 5
Handlers
Note: Servers will always want to use v1.
class virtual +'a v1 : object ... endHandler for a proxy with version >= 1.
class virtual +'a v2 : object ... endHandler for a proxy with version >= 2.
class virtual +'a v3 : object ... endHandler for a proxy with version >= 3.
class virtual +'a v4 : object ... endHandler for a proxy with version >= 4.
class virtual +'a v5 : object ... endHandler for a proxy with version >= 5.