Module smithay::wayland::compositor

source ·
Available on crate feature wayland_frontend only.
Expand description

Utilities for handling surfaces, subsurfaces and regions

This module provides automatic handling of surfaces, subsurfaces and region Wayland objects, by registering an implementation for for the wl_compositor and wl_subcompositor globals.

§Why use this implementation

This implementation does a simple job: it stores in a coherent way the state of surface trees with subsurfaces, to provide you direct access to the tree structure and all surface attributes, and handles the application of double-buffered state.

As such, you can, given a root surface with a role requiring it to be displayed, you can iterate over the whole tree of subsurfaces to recover all the metadata you need to display the subsurface tree.

This implementation will not do anything more than present you the metadata specified by the client in a coherent and practical way. All the logic regarding drawing itself, and the positioning of windows (surface trees) one relative to another is out of its scope.

§How to use it

§Initialization

To initialize this implementation create the CompositorState, store it inside your State struct and implement the CompositorHandler, as shown in this example:

use smithay::delegate_compositor;
use smithay::wayland::compositor::{CompositorState, CompositorClientState, CompositorHandler};

// Create the compositor state
let compositor_state = CompositorState::new::<State>(
    &display.handle(),
);

// insert the CompositorState into your state
// ..

// implement the necessary traits
impl CompositorHandler for State {
   fn compositor_state(&mut self) -> &mut CompositorState {
       &mut self.compositor_state
   }

   fn client_compositor_state<'a>(&self, client: &'a wayland_server::Client) -> &'a CompositorClientState {
       &client.get_data::<ClientState>().unwrap().compositor_state    
   }

   fn commit(&mut self, surface: &wayland_server::protocol::wl_surface::WlSurface) {
       // called on every buffer commit.
       // .. your implementation ..
   }
}
delegate_compositor!(State);

// You're now ready to go!

§Use the surface states

The main access to surface states is done through the with_states function, which gives you access to the SurfaceData instance associated with this surface. It acts as a general purpose container for associating state to a surface, double-buffered or not. See its documentation for more details.

§State application and hooks

On commit of a surface several steps are taken to update the state of the surface. Actions are taken by smithay in the following order:

  1. Pre Commit hooks registered to this surface are invoked. Such hooks can be registered using the add_pre_commit_hook function. They are typically used by protocol extensions that add state to a surface and need to check on commit that client did not request an illegal state before it is applied on commit.
  2. The pending state is either applied and made current, or cached for later application is the surface is a synchronize subsurface. If the current state is applied, state of the synchronized children subsurface are applied as well at this point.
  3. Post Commit hooks registered to this surface are invoked. Such hooks can be registered using the add_post_commit_hook function. They are typically used by abstractions that further process the state.
  4. Your implementation of CompositorHandler::commit is invoked, so that you can access the new current state of the surface. The state of sync children subsurfaces of your surface may have changed as well, so this is the place to check it, using functions like with_surface_tree_upward or with_surface_tree_downward. On the other hand, if the surface is a sync subsurface, its current state will note have changed as the result of that commit. You can check if it is using is_sync_subsurface.
  5. If the surface is destroyed, destruction hooks are invoked. Such hooks can be registered using the add_destruction_hook function. They are typically used to cleanup associated state.

§Surface roles

The wayland protocol specifies that a surface needs to be assigned a role before it can be displayed. Furthermore, a surface can only have a single role during its whole lifetime. Smithay represents this role as a &'static str identifier, that can only be set once on a surface. See give_role and get_role for details. This module manages the subsurface role, which is identified by the string "subsurface".

Structs§

Enums§

Constants§

Traits§

  • Blocker
    Types potentially blocking state changes
  • Cacheable
    Trait representing a value that can be used in double-buffered storage
  • CompositorHandler
    Handler trait for compositor

Functions§