From 468a3bb8dc6dbb5dbc915fea43fc423d25af9a04 Mon Sep 17 00:00:00 2001 From: Victor Berger Date: Fri, 2 Jul 2021 12:54:54 +0200 Subject: [PATCH] doc: expand root documentation --- src/backend/mod.rs | 69 +++++++++++++++++++++++++++++++++++++++------- src/lib.rs | 39 +++++++++++++++++++++++++- src/wayland/mod.rs | 35 +++++++++++++++++++++++ 3 files changed, 132 insertions(+), 11 deletions(-) diff --git a/src/backend/mod.rs b/src/backend/mod.rs index c98f0d5..86ae532 100644 --- a/src/backend/mod.rs +++ b/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; diff --git a/src/lib.rs b/src/lib.rs index 0a94ee1..9bec057 100644 --- a/src/lib.rs +++ b/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 diff --git a/src/wayland/mod.rs b/src/wayland/mod.rs index 2c613e7..3cd7b0e 100644 --- a/src/wayland/mod.rs +++ b/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};