Crate wayland_server [] [src]

Server-side Wayland connector

Overview

Setting up the listening socket is done by the create_display function, providing you a Display object and an EventLoop.

On the event loop, you'll be able to register the globals you want to advertize, as well as handlers for all ressources created by the clients.

You then integrate the wayland event loop in your main event loop to run your compositor.

Implementation and event loop

This crate mirrors the callback-oriented design of the Wayland C library by using implementation structs: each wayland type defines an Implementation struct in its module, with one function field for each possible event this object can receive.

When registering an object on an event loop, you need to provide an implementation for this object. You can also provide some "implementation data": a value that will be provided as second argument to all the callback methods of your implementation.

A typical use of implementation data is to store here one or more state tokens to access some part of the shared state from your callback.

Example of implementation

You can register your wayland objects to an event queue:

Be careful when using this code, it's not being tested!
event_loop.register(&my_object, implementation, impl_data);

A given wayland object can only be registered to an event loop at a given time, re-registering it will overwrite the previous configuration.

Objects can be registered to event loop using the &EventLoopHandle argument, available from withing an event callback.

Globals definition

Some wayland objects are special and can be directly created by the clients from their registry. To handle them your must declare which globals you want to make available to your clients, like this:

Be careful when using this code, it's not being tested!
event_loop.register_global(version, callback, idata);

Where callback is a function or non-capturing closure, provided as an implementation for when this global is instanciated by a client. See the method documentation for details.

Event loop integration

Once the setup phase is done, you can integrate the event loop in the main event loop of your program.

Either all you need is for it to run indefinitely (external events are checked in an other thread?):

Be careful when using this code, it's not being tested!
event_loop.run();

Or you can integrate it with more control:

Be careful when using this code, it's not being tested!
loop {
    // flush events to client sockets
    display.flush_clients();
    // receive request from clients and dispatch them
    // blocking if no request is pending for at most
    // 10ms
    event_loop.dispatch(Some(10)).unwrap();
    // then you can check events from other sources if
    // you need to
}

Protocols integration

This crate provides the basic primitives as well as the core wayland protocol (in the protocol module), but other protocols can be integrated from XML descriptions.

The the crate wayland_scanner and its documentation for details about how to do so.

Modules

protocol

The wayland core protocol

protocol_interfaces

Interfaces for the core protocol

sources

Secondary event sources

sys

Reexports of types and objects from wayland-sys

Structs

Client

A wayland client connected to your server

Display

A wayland socket

EventLoop
EventLoopHandle

Handle to an event loop

Global

A handle to a global object

State

A state store

StateToken

A token for accessing the state store contents

Enums

EventResult

Possible outcome of the call of a event on a resource

Liveness

Represents the state of liveness of a wayland object

RegisterStatus

Status of a registration attempt of a resource.

Traits

Implementable

Common trait for wayland objects that can be registered to an EventQueue

Resource

Common routines for wayland resource objects.

Functions

create_display

Create a new display

resource_is_registered

Checks if a resource is registered with a given implementation on an event loop

Type Definitions

GlobalCallback

Callback function called when a global is instanciated by a client