Interface for interacting with the Wayland protocol, server-side.
Display is the heart of this crate, it represents the protocol state of your Wayland server, and
takes care of processing messages from clients. You’ll need to integrate it in your event loop (see its
documentation for details). From it you can retrieve the
DisplayHandle, which is a clonable handle to
the Wayland state and is the type used to actually interact with the protocol.
Each of the Wayland object you can manipulate is represented by a struct implementing the
trait. Thos structs are automatically generated from the wayland XML protocol specification. This crate
provides the types generated from the core protocol in the
protocol module. For other standard
protocols, see the
The request dispatching logic provided by this crate is build around the
Dispatch trait. During the
dispatching process (in
Display::dispatch_clients()), all requests sent by clients are read from
their respective process and delivered to your processing logic, by invoking methods on the various
Dispatch implementations of your
State struct. In this paradigm, your
State needs to implement
Dispatch<O, _> for every Wayland object
O it needs to process events for.
However, implementing all those traits on your own is a lot of (often uninteresting) work. To make this
easier a composition mechanism is provided using the
delegate_dispatch! macro. This way, another
library (such as Smithay) can provide generic
Dispatch implementations that you can reuse on your
own app by delegating those objects to that provided implementation. See the documentation of those
traits and macro for details.
The entry point of the protocol for clients goes through the protocol globals. Each global represents a
capability of your compositor, a peripheral it has access to, or a protocol extension it supports.
Globals are created by you using
DisplayHandle::create_global(), and require your
GlobalDispatch trait for the interface associated with that global.
This crate can generate some runtime error message (notably when a protocol error occurs). By default
those messages are printed to stderr. If you activate the
log cargo feature, they will instead be
piped through the
It may be that for some of your objects, handling them via the
Dispatch trait is impractical. In
those contexts, this crate also provides some escape-hatches to directly interface with the low-level
wayland-backend, allowing you to register callbacks for those objects by directly providing
implementations of the backend
It can happen that you’ll need to interact with Wayland states accross FFI, such as for example when interfacing with the graphics stack for enabling hardware acceleration for clients.
In this case, you’ll need to do it in two steps, by explicitly working with
it to your dependencies and enabling its
Then, you’ll generally need:
*mut wl_displaypointer, that you can retrieve by first retrieving the
Display::backend(), and then invoke `Backend::display_ptr().
*mut wl_resourcepointers for the objects you need to share, by first getting the
Resource::id()method, and then the
A struct representing a Wayland client connected to your compositor.
Helper to initialize client-created objects
The Wayland display
A handle to the Wayland display
An utility representing a unix socket on which your compositor is listening for new clients
A weak handle to a Wayland object
An error generated if an illegal request was received from a client
An enum value in the protocol.
A trait which provides an implementation for handling a client’s requests from a resource with some type of associated user data.
A trait which provides an implementation for handling advertisement of a global to clients with some type of associated user data.
Trait representing a Wayland interface