doc: expand root documentation

src/backend/mod.rs

@@ -1,18 +1,67 @@
-//! Backend (rendering/input) creation helpers
+//! Backend (rendering/input) helpers
 //!
-//! Collection of common traits and implementation about
-//! rendering onto various targets and receiving input
-//! from various sources.
+//! This module provides helpers for interaction with the operating system.
 //!
-//! Supported graphics backends:
+//! ## Module structure
 //!
-//! - winit
-//! - drm
+//! The module is largely structured around three main aspects of interaction with the OS:
+//! session management, input handling, and graphics.
 //!
-//! Supported input backends:
+//! ### Session management
 //!
-//! - winit
-//! - libinput
+//! Session management relates to mechanisms allowing the compositor to access the ressources
+//! it needs to function. It contains interaction with the login manager if any ((e)logind or
+//! seatd), as well as releasing thoses ressources when TTY-switching. It is handled by the
+//! [`session`] module, gated by the `backend_session` cargo feature. You will generally need
+//! it to run your compositor directly on a TTY.
+//!
+//! This module is tightly coupled with the [`udev`] module (gated by the `backend_udev` cargo
+//! feature), which allows the discovery of usable graphics and input devices on the system, using
+//! the udev system daemon.
+//!
+//! ### Input handling
+//!
+//! Input handling consists in discovering the various available input devices, and receiving
+//! all inputs events from it. Smithay is build to support different possible sources for
+//! that input data, with a generic API provided by the traits and types defined in the
+//! [`input`] module. An input provider following this API based on `libinput` is given in the
+//! [`libinput`] module, gated by the `backend_libinput` cargo feature. The winit backend
+//! (see below) also provides an input provider.
+//!
+//! ### Graphics
+//!
+//! Combining content from the clients and displaying it on the screen is the central role of
+//! a wayland compositor, and also one of its most complex tasks; several backend modules are
+//! dedicated to this task.
+//!
+//! Smithay provides a rendering infrastructure built around graphics buffers: you retrieve buffers
+//! for your client, you composite them into a new buffer holding the contents of your desktop,
+//! that you will then submit to the hardware for display. The backbone of this infrastructure is
+//! structured around the [`allocator`] and [`renderer`] modules. The first one contains generic
+//! traits representing the capability to allocate and convert graphical buffers, as well as an
+//! implementation of this capability using GBM (see its module-level docs for details). The second
+//! provides traits representing the capability of graphics rendering using those buffers, as well
+//! as an implementation of this capability using GLes2 (see its module-level docs for details).
+//!
+//! Alongside this backbone capability, Smithay also provides the [`drm`] module, which handles
+//! direct interaction with the graphical physical devices to setup the display pipeline and
+//! submit rendered buffers to the monitors for display. This module is gated by the
+//! `backend_drm` cargo feature.
+//!
+//! The [`egl`] module provides the logic to setup an OpenGL context. It is used by the Gles2
+//! renderer (which is based on OpenGL), and also provides the capability for clients to use
+//! the `wl_drm`-based hardware-acceleration provided by Mesa, a precursor to the
+//! [`linux_dmabuf`](crate::wayland::dmabuf) Wayland protocol extension. Note that, at the
+//! moment, even clients using dma-buf still require that the `wl_drm` infrastructure is
+//! initialized to have hardware-acceleration.
+//!
+//! ## Winit backend
+//!
+//! Alongside this infrastructure, Smithay also provides an alternative backend based on
+//! [winit](https://crates.io/crates/winit), which makes it possible to run your compositor as
+//! a Wayland or X11 client. This is generally quite helpful for development and debugging.
+//! That backend is both a renderer and an input provider, and is accessible in the [`winit`]
+//! module, gated by the `backend_winit` cargo feature.
 
 pub mod allocator;
 pub mod input;

src/lib.rs

@@ -2,7 +2,44 @@
 // Allow acronyms like EGL
 #![allow(clippy::upper_case_acronyms)]
 
-//! **Smithay: the Wayland compositor smithy**
+//! # 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`](::wayland_server::DispatchData) for wayland-related callbacks). This structure provides
+//! an 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`](::slog::Logger) as argument
 //! that will be used as a drain for logging. If `None` is provided, the behavior depends on

src/wayland/mod.rs

@@ -3,6 +3,8 @@
 //! This module contains several handlers to manage the Wayland protocol
 //! and the clients.
 //!
+//! ## General structure
+//!
 //! Most utilities provided in this module work in the same way:
 //!
 //! - An `init` function or method will take the wayland display as argument and
@@ -16,6 +18,39 @@
 //! client requests that your logic needs to handle. In most cases these callback
 //! are given as input an enum specifying the event that occured, as well as the
 //! [`DispatchData`](wayland_server::DispatchData) from `wayland_server`.
+//!
+//! ## Provided helpers
+//!
+//! ### Core functionality
+//!
+//! The most fundamental module is the [`compositor`] module, which provides the necessary
+//! logic to handle the fundamental component by which clients build their windows: surfaces.
+//! Following this, the [`shell`] module contains the logic allowing clients to use their
+//! surface to build concrete windows with the usual interactions. Different kind of shells
+//! exist, but in general you will want to support at least the [`xdg`](shell::xdg) variant,
+//! which is the standart used by most applications.
+//!
+//! Then, the [`seat`] module contains logic related to input handling. These helpers are used
+//! to forward input (such as pointer action or keystrokes) to clients, and manage the input
+//! focus of clients. Tightly coupled with it is the [`data_device`] module, which handles
+//! cross-client interactions such as accessing the clipboard, or drag'n'drop actions.
+//!
+//! The [`shm`] module provides the necessary logic for client to provide buffers defining the
+//! contents of their windows using shared memory. This is the main mechanism used by clients
+//! that are not hardware accelerated. As a complement, the [`dmabuf`] module provides support
+//! hardware-accelerated clients; it is tighly linked to the
+//! [`backend::allocator`](crate::backend::allocator) module.
+//!
+//! The [`output`] module helps forwarding to clients information about the display monitors that
+//! are available. This notably plays a key role in HiDPI handling, and more generally notifying
+//! clients about whether they are currently visible or not (allowing them to stop drawing if they
+//! are not, for example).
+//!
+//! ### Experimental helpers
+//!
+//! The [`explicit_synchronization`] module provides helpers to give clients fine-grained control
+//! over the synchronization for accessing graphics buffer with the compositor, for low-latency
+//! rendering. It is however still experimental, and largely untested.
 
 use std::sync::atomic::{AtomicUsize, Ordering};