Module compositor

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:

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.
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.
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.
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.
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§

AlreadyHasRole: An error type signifying that the surface already has a role and cannot be assigned an other
Barrier: A simple Blocker barrier
CachedState: Double buffered cached state of type T
CompositorClientState: Per-client state of a compositor
CompositorState: State of a compositor
HookId: Unique hook identifier used to unregister commit/descruction hooks
MultiCache: A typemap-like container for double-buffered values
RegionAttributes: Description of the contents of a region
RegionUserData: User data of WlRegion
SubsurfaceCachedState: The cached state associated with a subsurface
SubsurfaceUserData: User data of WlSubsurface
SurfaceAttributes: General state associated with a surface
SurfaceData: The state container associated with a surface
SurfaceUserData: User data for WlSurface

Enums§

BlockerState: States of a Blocker
BufferAssignment: New buffer assignation for a surface
Damage: Description of a part of a surface that should be considered damaged and needs to be redrawn
RectangleKind: Kind of a rectangle part of a region
TraversalAction: Possible actions to do after handling a node during tree traversal

Constants§

SUBSURFACE_ROLE: The role of a subsurface surface.

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§

add_blocker: Adds a blocker for the currently queued up state changes of the given surface.
add_destruction_hook: Register a destruction hook to be invoked on surface destruction
add_post_commit_hook: Register a post-commit hook to be invoked on surface commit
add_pre_commit_hook: Register a pre-commit hook to be invoked on surface commit
get_children: Retrieve the children of this surface
get_parent: Retrieve the parent of this surface
get_region_attributes: Retrieve the metadata associated with a wl_region
get_role: Get the current role of this surface
give_role: Register that this surface has given role
is_sync_subsurface: Check if this subsurface is a synchronized subsurface
remove_destruction_hook: Unregister a destruction hook
remove_post_commit_hook: Unregister a post-commit hook
remove_pre_commit_hook: Unregister a pre-commit hook
send_surface_state: Send the scale and transform preferences for the given surface when it supports them.
with_states: Access the states associated to this surface
with_surface_tree_downward: Access the data of a surface tree from top to bottom
with_surface_tree_upward: Access the data of a surface tree from bottom to top

Module compositorCopy item path