Product SiteDocumentation Site

4.4. Interfaces

The protocol includes several interfaces which are used for interacting with the server. Each interface provides requests, events, and errors (which are really just special events) as described above. Specific compositor implementations may have their own interfaces provided as extensions, but there are several which are always expected to be present.
Core interfaces:
wl_display - core global object
The core global object. This is a special singleton object. It is used for internal Wayland protocol features.
wl_registry - global registry object
The global registry object. The server has a number of global objects that are available to all clients. These objects typically represent an actual object in the server (for example, an input device) or they are singleton objects that provide extension functionality. When a client creates a registry object, the registry object will emit a global event for each global currently in the registry. Globals come and go as a result of device or monitor hotplugs, reconfiguration or other events, and the registry will send out global and global_remove events to keep the client up to date with the changes. To mark the end of the initial burst of events, the client can use the wl_display.sync request immediately after calling wl_display.get_registry. A client can bind to a global object by using the bind request. This creates a client-side handle that lets the object emit events to the client and lets the client invoke requests on the object.
wl_callback - callback object
Clients can handle the 'done' event to get notified when the related request is done.
wl_compositor - the compositor singleton
A compositor. This object is a singleton global. The compositor is in charge of combining the contents of multiple surfaces into one displayable output.
wl_shm_pool - a shared memory pool
The wl_shm_pool object encapsulates a piece of memory shared between the compositor and client. Through the wl_shm_pool object, the client can allocate shared memory wl_buffer objects. All objects created through the same pool share the same underlying mapped memory. Reusing the mapped memory avoids the setup/teardown overhead and is useful when interactively resizing a surface or for many small buffers.
wl_shm - shared memory support
A global singleton object that provides support for shared memory. Clients can create wl_shm_pool objects using the create_pool request. At connection setup time, the wl_shm object emits one or more format events to inform clients about the valid pixel formats that can be used for buffers.
wl_buffer - content for a wl_surface
A buffer provides the content for a wl_surface. Buffers are created through factory interfaces such as wl_drm, wl_shm or similar. It has a width and a height and can be attached to a wl_surface, but the mechanism by which a client provides and updates the contents is defined by the buffer factory interface.
wl_data_offer - offer to transfer data
A wl_data_offer represents a piece of data offered for transfer by another client (the source client). It is used by the copy-and-paste and drag-and-drop mechanisms. The offer describes the different mime types that the data can be converted to and provides the mechanism for transferring the data directly from the source client.
wl_data_source - offer to transfer data
The wl_data_source object is the source side of a wl_data_offer. It is created by the source client in a data transfer and provides a way to describe the offered data and a way to respond to requests to transfer the data.
wl_data_device - data transfer device
There is one wl_data_device per seat which can be obtained from the global wl_data_device_manager singleton. A wl_data_device provides access to inter-client data transfer mechanisms such as copy-and-paste and drag-and-drop.
wl_data_device_manager - data transfer interface
The wl_data_device_manager is a singleton global object that provides access to inter-client data transfer mechanisms such as copy-and-paste and drag-and-drop. These mechanisms are tied to a wl_seat and this interface lets a client get a wl_data_device corresponding to a wl_seat.
wl_shell - create desktop-style surfaces
This interface is implemented by servers that provide desktop-style user interfaces. It allows clients to associate a wl_shell_surface with a basic surface.
wl_shell_surface - desktop-style metadata interface
An interface that may be implemented by a wl_surface, for implementations that provide a desktop-style user interface. It provides requests to treat surfaces like toplevel, fullscreen or popup windows, move, resize or maximize them, associate metadata like title and class, etc. On the server side the object is automatically destroyed when the related wl_surface is destroyed. On client side, wl_shell_surface_destroy() must be called before destroying the wl_surface object.
wl_surface - an onscreen surface
A surface is a rectangular area that is displayed on the screen. It has a location, size and pixel contents. The size of a surface (and relative positions on it) is described in surface local coordinates, which may differ from the buffer local coordinates of the pixel content, in case a buffer_transform or a buffer_scale is used. Surfaces are also used for some special purposes, e.g. as cursor images for pointers, drag icons, etc.
wl_seat - group of input devices
A seat is a group of keyboards, pointer and touch devices. This object is published as a global during start up, or when such a device is hot plugged. A seat typically has a pointer and maintains a keyboard focus and a pointer focus.
wl_pointer - pointer input device
The wl_pointer interface represents one or more input devices, such as mice, which control the pointer location and pointer_focus of a seat. The wl_pointer interface generates motion, enter and leave events for the surfaces that the pointer is located over, and button and axis events for button presses, button releases and scrolling.
wl_keyboard - keyboard input device
The wl_keyboard interface represents one or more keyboards associated with a seat.
wl_touch - touchscreen input device
The wl_touch interface represents a touchscreen associated with a seat. Touch interactions can consist of one or more contacts. For each contact, a series of events is generated, starting with a down event, followed by zero or more motion events, and ending with an up event. Events relating to the same contact point can be identified by the ID of the sequence.
wl_output - compositor output region
An output describes part of the compositor geometry. The compositor works in the 'compositor coordinate system' and an output corresponds to rectangular area in that space that is actually visible. This typically corresponds to a monitor that displays part of the compositor space. This object is published as global during start up, or when a monitor is hotplugged.
wl_region - region interface
A region object describes an area. Region objects are used to describe the opaque and input regions of a surface.