Crate smithay

Smithay: the Wayland compositor smithy

This crate is a general framework for building wayland compositors. It currently focuses on low-level, helpers and abstractions, handling most of the system-level and wayland protocol interactions. The window management and drawing logic is however at this time not provided (but helpers for this are planned for future version).

Structure of the crate

The provided helpers are split into two main modules:

• backend contains helpers for interacting with the operating system, such as session management, interactions with the graphic stack and input processing.
• wayland contains helpers for interacting with wayland clients according to the wayland protocol.

In addition, the xwayland module contains helpers for managing an XWayland instance if you want to support it. See the documentation of these respective modules for information about their usage.

General principles for using Smithay

The event loop and state handling

Smithay is built around calloop, a callback-oriented event loop, which fits naturally with the general behavior of a wayland compositor: waiting for events to occur and react to them (be it client requests, user input, or hardware events such as vblank).

Using a callback-heavy structure however poses the question of state management: a lot of state needs to be accessed from many different callbacks. To avoid a heavy requirement on shared pointers such as Rc and Arc and the synchronization they require, calloop allows you to provide a mutable reference to a value that will be passed down to most callbacks. This structure provides easy access to a centralized mutable state without synchronization (as the callback invocation is always sequential), and is the recommended way of structuring your compositor. TODO: Add a section here how this links to wayland-server’s Dispatch and link to the wayland-server docs, once they exist for 0.30.

Several objects, in particular on the wayland clients side, can exist as multiple instances where each instance has its own associated state. For these situations, these objects provide an interface allowing you to associate an arbitrary value to them, that you can access at any time from the object itself (rather than having your own container in which you search for the appropriate value when you need it).

Logging

Smithay makes extensive use of tracing for its internal logging.

For release builds it is recommended to limit the log level during compile time. This can be done by adding a dependency to tracing and enabling the corresponding features. For example to enable trace messages for debug builds, but limit release builds to debug add the following in your binary crate Cargo.toml:

[dependencies]
tracing = { version = "0.1", features = ["max_level_trace", "release_max_level_debug"] }

If you do not want to use tracing for your compositor, refer to log compatibility for how to forward smithays debug output to other log compatible frameworks.

Modules

backend

Backend (rendering/input) helpers

desktopdesktop

Desktop management helpers

input

Input abstractions

output

Output

reexports

Reexports of crates, that are part of the public api, for convenience

utils

Various utilities functions and types

waylandwayland_frontend

Protocol-related utilities

xwaylandxwayland

XWayland utilities

Macros

delegate_alpha_modifierwayland_frontend

Macro to delegate implementation of the alpha modifier protocol

delegate_commit_timingwayland_frontend

Macro used to delegate WpCommitTimingManagerV1 events

delegate_compositorwayland_frontend

delegate_content_typewayland_frontend

Macro to delegate implementation of the wp content type protocol

delegate_cursor_shapewayland_frontend

delegate_data_controlwayland_frontend

delegate_data_devicewayland_frontend

delegate_dmabufwayland_frontend

Macro to delegate implementation of the linux dmabuf to DmabufState.

delegate_drm_leasebackend_drm and wayland_frontend

Macro to delegate implementation of the drm-lease protocol to DrmLeaseState.

delegate_drm_syncobjbackend_drm and wayland_frontend

Macro to delegate implementation of the drm syncobj protocol to DrmSyncobjState.

delegate_ext_data_controlwayland_frontend

Macro to delegate implementation of the ext_data_control protocol

delegate_fifowayland_frontend

Macro used to delegate WpFifoManagerV1 events

delegate_foreign_toplevel_listwayland_frontend

Macro to delegate implementation of the xdg toplevel icon to ForeignToplevelListState.

delegate_fractional_scalewayland_frontend

delegate_idle_inhibitwayland_frontend

delegate_idle_notifywayland_frontend

Macro to delegate implementation of the ext idle notify protocol

delegate_input_method_managerwayland_frontend

delegate_kde_decorationwayland_frontend

delegate_keyboard_shortcuts_inhibitwayland_frontend

Macro to delegate implementation of the keyboard shortcuts inhibit protocol

delegate_layer_shellwayland_frontend

Macro to delegate implementation of wlr layer shell to WlrLayerShellState.

delegate_outputwayland_frontend

delegate_pointer_constraintswayland_frontend

delegate_pointer_gestureswayland_frontend

Macro to delegate implementation of the pointer gestures protocol

delegate_presentationwayland_frontend

delegate_primary_selectionwayland_frontend

delegate_relative_pointerwayland_frontend

Macro to delegate implementation of the relative pointer protocol

delegate_seatwayland_frontend

delegate_security_contextwayland_frontend

Macro to delegate implementation of the security context protocol

delegate_session_lockwayland_frontend

delegate_shmwayland_frontend

delegate_single_pixel_bufferwayland_frontend

Macro used to delegate WpSinglePixelBuffer events

delegate_tablet_managerwayland_frontend

delegate_text_input_managerwayland_frontend

delegate_viewporterwayland_frontend

delegate_virtual_keyboard_managerwayland_frontend

delegate_xdg_activationwayland_frontend

Macro to delegate implementation of the xdg activation to XdgActivationState.

delegate_xdg_decorationwayland_frontend

Macro to delegate implementation of the xdg decoration to XdgDecorationState.

delegate_xdg_dialogwayland_frontend

Macro to delegate implementation of the xdg dialog to XdgDialogState.

delegate_xdg_foreignwayland_frontend

Macro to delegate implementation of the xdg foreign to XdgForeignState.

delegate_xdg_shellwayland_frontend

delegate_xdg_system_bellwayland_frontend

Macro to delegate implementation of the xdg system bell to XdgSystemBellState.

delegate_xdg_toplevel_iconwayland_frontend

Macro to delegate implementation of the xdg toplevel icon to XdgToplevelIconManager.

delegate_xwayland_keyboard_grabxwayland and wayland_frontend

Macro to delegate implementation of the xwayland keyboard grab protocol

delegate_xwayland_shellxwayland and wayland_frontend

Macro to delegate implementation of the xwayland keyboard grab protocol

egl_platformbackend_egl

Create a EGLPlatform<'a> for the provided platform.

render_elements

Aggregate multiple types implementing RenderElement into a single enum type

space_elementsdesktop

Aggregate multiple types implementing SpaceElement into a single enum type to be used with a Space.