Module smithay::wayland::compositor[−][src]

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, use the compositor_init method provided by this module. It’ll require you to first define as few things, as shown in this example:

use smithay::wayland::compositor::compositor_init;

// Call the init function:
compositor_init(
    &mut display,
    |surface, dispatch_data| {
        /*
          Your handling of surface commits
         */
    },
    None // put a logger here
);

// 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:

Commit hooks registered to this surface are invoked. Such hooks can be registered using the add_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.
Your user callback provided to compositor_init 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.

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