tawasuyu/mirada

1#![cfg_attr(docsrs, feature(doc_auto_cfg))]
2#![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)]
3// Allow acronyms like EGL
4#![allow(clippy::upper_case_acronyms)]
5
6//! # Smithay: the Wayland compositor smithy
7//!
8//! This crate is a general framework for building wayland compositors. It currently focuses on low-level,
9//! helpers and abstractions, handling most of the system-level and wayland protocol interactions.
10//! The window management and drawing logic is however at this time not provided (but helpers for this
11//! are planned for future version).
12//!
13//! ## Structure of the crate
14//!
15//! The provided helpers are split into two main modules:
16//!
17//! - [`backend`] contains helpers for interacting with the operating
18//!   system, such as session management, interactions with the graphic stack
19//!   and input processing.
20//! - [`wayland`] contains helpers for interacting with wayland clients
21//!   according to the wayland protocol.
22//!
23//!  In addition, the [`xwayland`] module contains helpers for managing an
24//!  XWayland instance if you want to support it. See the documentation of
25//!  these respective modules for information about their usage.
26//!
27//! ## General principles for using Smithay
28//!
29//! ### The event loop and state handling
30//!
31//! Smithay is built around [`calloop`], a callback-oriented event loop, which fits naturally with the
32//! general behavior of a wayland compositor: waiting for events to occur and react to them (be it
33//! client requests, user input, or hardware events such as `vblank`).
34//!
35//! Using a callback-heavy structure however poses the question of state management: a lot of state needs
36//! to be accessed from many different callbacks. To avoid a heavy requirement on shared pointers such
37//! as `Rc` and `Arc` and the synchronization they require, [`calloop`] allows you to provide a mutable
38//! reference to a value that will be passed down to most callbacks. This structure provides
39//! easy access to a centralized mutable state without synchronization (as the callback invocation is
40//! *always* sequential), and is the recommended way of structuring your compositor.
41//! TODO: Add a section here how this links to wayland-server's `Dispatch` and link to the wayland-server
42//! docs, once they exist for 0.30.
43//!
44//! Several objects, in particular on the wayland clients side, can exist as multiple instances where each
45//! instance has its own associated state. For these situations, these objects provide an interface allowing
46//! you to associate an arbitrary value to them, that you can access at any time from the object itself
47//! (rather than having your own container in which you search for the appropriate value when you need it).
48//!
49//! ### Logging
50//!
51//! Smithay makes extensive use of [`tracing`] for its internal logging.
52//!
53//! For release builds it is recommended to limit the log level during compile time.
54//! This can be done by adding a dependency to [`tracing`] and enabling the corresponding features.
55//! For example to enable `trace` messages for debug builds, but limit release builds to `debug` add
56//! the following in your binary crate `Cargo.toml`:
57//!
58//! ```toml
59//! [dependencies]
60//! tracing = { version = "0.1", features = ["max_level_trace", "release_max_level_debug"] }
61//! ```
62//!
63//! If you do not want to use [`tracing`] for your compositor, refer to [`log compatibility`](tracing#log-compatibility)
64//! for how to forward smithays debug output to other `log` compatible frameworks.
65
66pub mod backend;
67#[cfg(feature = "desktop")]
68pub mod desktop;
69pub mod input;
70pub mod output;
71pub mod utils;
72#[cfg(feature = "wayland_frontend")]
73pub mod wayland;
74
75#[cfg(feature = "xwayland")]
76pub mod xwayland;
77
78pub mod reexports;