Crate wayland_server

Interface for interacting with the Wayland protocol, server-side.

General concepts

This crate is structured around four main objects: the Display and DisplayHandle structs, resources (objects implementing the Resource trait), and the Dispatch trait.

The 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 Resource 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 wayland-protocols crate.

Request dispatching and the Dispatch trait

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.

Globals

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 State to implement the GlobalDispatch trait for the interface associated with that global.

Logging

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 log crate.

Advanced use

Bypassing Dispatch

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 APIs from wayland-backend, allowing you to register callbacks for those objects by directly providing implementations of the backend ObjectData trait. See Client::create_resource_from_objdata() and DataInit::custom_init().

Interaction with FFI

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 wayland-backend, adding it to your dependencies and enabling its server_system feature.

Then, you’ll generally need:

• The *mut wl_display pointer, that you can retrieve by first retrieving the Backend using Display::backend(), and then invoke .handle()[.display_ptr()][backend::Handle::display_ptr()].
• The *mut wl_resource pointers for the objects you need to share, by first getting the ObjectId using the Resource::id() method, and then the [ObjectId::as_ptr()] method.

If you need to receive pointers from FFI, you can make ObjectIds from the *mut wl_resource pointers using [ObjectId::from_ptr()], and then make the resources using Resource::from_id().

Modules

backend

Backend reexports

protocol

Generated protocol definitions

Macros

delegate_dispatch

A helper macro which delegates a set of Dispatch implementations for a resource to some other type which provides a generic Dispatch implementation.

delegate_global_dispatch

A helper macro which delegates a set of GlobalDispatch implementations for a resource to some other type which provdes a generic GlobalDispatch implementation.

Structs

Client

A struct representing a Wayland client connected to your compositor.

DataInit

Helper to initialize client-created objects

Display

The Wayland display

DisplayHandle

A handle to the Wayland display

ListeningSocket

An utility representing a unix socket on which your compositor is listening for new clients

New

A newly created object that needs to be initialized. See DataInit.

ResourceData

The ObjectData implementation that is internally used by this crate

Weak

A weak handle to a Wayland object

Enums

BindError

Error that can occur when trying to bind a ListeningSocket

DispatchError

An error generated if an illegal request was received from a client

WEnum

An enum value in the protocol.

Traits

Dispatch

A trait which provides an implementation for handling a client’s requests from a resource with some type of associated user data.

GlobalDispatch

A trait which provides an implementation for handling advertisement of a global to clients with some type of associated user data.

Resource

Trait representing a Wayland interface