Module wayland_client::protocol::wl_surface [−][src]
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).
Structs
| WlSurface |
Enums
| Error | wl_surface error values |
| Event | |
| Request |
Constants
| EVT_ENTER_SINCE | The minimal object version supporting this event |
| EVT_LEAVE_SINCE | The minimal object version supporting this event |
| REQ_ATTACH_SINCE | The minimal object version supporting this request |
| REQ_COMMIT_SINCE | The minimal object version supporting this request |
| REQ_DAMAGE_BUFFER_SINCE | The minimal object version supporting this request |
| REQ_DAMAGE_SINCE | The minimal object version supporting this request |
| REQ_DESTROY_SINCE | The minimal object version supporting this request |
| REQ_FRAME_SINCE | The minimal object version supporting this request |
| REQ_SET_BUFFER_SCALE_SINCE | The minimal object version supporting this request |
| REQ_SET_BUFFER_TRANSFORM_SINCE | The minimal object version supporting this request |
| REQ_SET_INPUT_REGION_SINCE | The minimal object version supporting this request |
| REQ_SET_OPAQUE_REGION_SINCE | The minimal object version supporting this request |
Statics
| wl_surface_events | C-representation of the messages of this interface, for interop |
| wl_surface_interface | C representation of this interface, for interop |
| wl_surface_requests | C-representation of the messages of this interface, for interop |