Crate smithay[−][src]
Expand description
Smithay: the Wayland compositor smithy
This crate is a general framework for build 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 the 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. On the other hand, 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 an 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 (possibly under the form of a
DispatchData for wayland-related 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 to of structuring your compositor.
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
Most entry points in the modules can take an optional slog::Logger as argument
that will be used as a drain for logging. If None is provided, the behavior depends on
whether the slog-stdlog is enabled. If yes, the module will log to the global logger of the
log crate. If not, the logs will discarded. This cargo feature is part of the default set of
features of Smithay.
Modules
Backend (rendering/input) helpers
Reexports of crates, that are part of the public api, for convenience
Various utilities functions and types
Protocol-related utilities
XWayland utilities
Macros
Create a EGLPlatform<'a> for the provided platform.