weston_compositor represents the core object of the library, which aggregates all the other objects and maintains their state. You can create it using weston_compositor_create(), while for releasing all the resources associated with it and then destroy it, you should use weston_compositor_destroy().

Compositor API

void weston_compositor_get_time(struct timespec *time)


struct weston_view *weston_compositor_pick_view(struct weston_compositor *compositor, struct weston_coord_global pos)


void weston_compositor_damage_all(struct weston_compositor *compositor)


void weston_compositor_schedule_repaint(struct weston_compositor *compositor)


void weston_compositor_wake(struct weston_compositor *compositor)

Restores the compositor to active status.

If the compositor was in a sleeping mode, all outputs are powered back on via DPMS. Otherwise if the compositor was inactive (idle/locked, offscreen, or sleeping) then the compositor’s wake signal will fire.

Restarts the idle timer.


compositor – The compositor instance

void weston_compositor_offscreen(struct weston_compositor *compositor)

Turns off rendering and frame events for the compositor.

This is used for example to prevent further rendering while the compositor is shutting down.

Stops the idle timer.


compositor – The compositor instance

void weston_compositor_sleep(struct weston_compositor *compositor)

Powers down all attached output devices.

Causes rendering to the outputs to cease, and no frame events to be sent. Only powers down the outputs if the compositor is not already in sleep mode.

Stops the idle timer.


compositor – The compositor instance

void weston_compositor_stack_plane(struct weston_compositor *ec, struct weston_plane *plane, struct weston_plane *above)


static void weston_compositor_schedule_heads_changed(struct weston_compositor *compositor)

Schedule a call on idle to heads_changed callback.


compositor – The Compositor.

void weston_compositor_add_head(struct weston_compositor *compositor, struct weston_head *head)

Register a new head.

This signals the core that a new head has become available, leading to heads_changed hook being called later.

  • compositor – The compositor.

  • head – The head to register, must not be already registered.

void weston_compositor_add_heads_changed_listener(struct weston_compositor *compositor, struct wl_listener *listener)

Adds a listener to be called when heads change.

The listener notify function argument is weston_compositor.

The listener function will be called after heads are added or their connection status has changed. Several changes may be accumulated into a single call. The user is expected to iterate over the existing heads and check their statuses to find out what changed.


weston_compositor_iterate_heads, weston_head_is_connected, weston_head_is_enabled

  • compositor – The compositor.

  • listener – The listener to add.

struct weston_head *weston_compositor_iterate_heads(struct weston_compositor *compositor, struct weston_head *iter)

Iterate over available heads.

Returns all available heads, regardless of being connected or enabled.

You can iterate over all heads as follows:

struct weston_head *head = NULL;

while ((head = weston_compositor_iterate_heads(compositor, head))) {

If you cause iter to be removed from the list, you cannot use it to continue iterating. Removing any other item is safe.

  • compositor – The compositor.

  • iter – The iterator, or NULL for start.


The next available head in the list.

static void weston_compositor_remove_output(struct weston_output *output)

Removes output from compositor’s list of enabled outputs.

The following happens:

  • Destroys all paint nodes related to the output.

  • The output assignments of all views in the current scenegraph are recomputed.

  • Destroys output’s color transforms.

  • Presentation feedback is discarded.

  • Compositor is notified that outputs were changed and applies the necessary changes to re-layout outputs.

  • The output is put back in the pending outputs list.

  • Signal is emitted to notify all users of the weston_output object that the output is being destroyed.

  • wl_output protocol objects referencing this weston_output are made inert, and the wl_output global is removed.

  • The output’s internal ID is released.


output – The weston_output object that is being removed.

void weston_compositor_add_pending_output(struct weston_output *output, struct weston_compositor *compositor)

Adds weston_output object to pending output list.

The opposite of this operation is built into weston_output_release().

  • output – The weston_output object to add

  • compositor – The compositor instance.

void weston_compositor_flush_heads_changed(struct weston_compositor *compositor)

Forces a synchronous call to heads_changed hook.

If there are new or changed heads, calls the heads_changed hook and returns after the hook returns.


compositor – The compositor instance

struct weston_output *weston_compositor_find_output_by_name(struct weston_compositor *compositor, const char *name)

Find an output by its given name.

  • compositor – The compositor to search in.

  • name – The output name to search for.


An existing output with the given name, or NULL if not found.

struct weston_output *weston_compositor_create_output(struct weston_compositor *compositor, struct weston_head *head, const char *name)

Create a named output for an unused head.

This creates a new weston_output that starts with the given head attached. The head must not be already attached to another output.

An output must be configured and it must have at least one head before it can be enabled.

  • compositor – The compositor.

  • head – The head to attach to the output.

  • name – The name for the output.


A new weston_output, or NULL on failure.

char *weston_compositor_print_scene_graph(struct weston_compositor *ec)

Output information on how libweston is currently composing the scene graph.

void *weston_compositor_get_test_data(struct weston_compositor *ec)

Retrieve testsuite data from compositor.

The testsuite data can be defined by the test suite of projects that uses libweston and given to the compositor at the moment of its creation. This function should be used when we need to retrieve the testsuite private data from the compositor.




ec – The weston compositor.


The testsuite data.

struct weston_compositor *weston_compositor_create(struct wl_display *display, struct weston_log_context *log_ctx, void *user_data, const struct weston_testsuite_data *test_data)

Create the compositor.

This functions creates and initializes a compositor instance.

  • display – The Wayland display to be used.

  • user_data – A pointer to an object that can later be retrieved

  • log_ctx – A pointer to weston_debug_compositor

  • test_data – Optional testsuite data, or NULL. using the weston_compositor_get_user_data function.


The compositor instance on success or NULL on failure.

static void weston_compositor_shutdown(struct weston_compositor *ec)


void weston_compositor_exit_with_code(struct weston_compositor *compositor, int exit_code)


void weston_compositor_set_default_pointer_grab(struct weston_compositor *ec, const struct weston_pointer_grab_interface *interface)


int weston_compositor_backends_loaded(struct weston_compositor *compositor)

To be called by the compositor after the last backend is loaded.


compositor – A compositor that has all backends loaded.


0 on success, or -1 on error.

void weston_compositor_read_presentation_clock(struct weston_compositor *compositor, struct timespec *ts)

Read the current time from the Presentation clock.

This function is never meant to fail. If reading the clock does fail, an error message is logged and a zero time is returned. Callers are not supposed to detect or react to failures.


Reading the current time in user space is always imprecise to some degree.

  • compositor

  • ts[out] The current time.

bool weston_compositor_import_dmabuf(struct weston_compositor *compositor, struct linux_dmabuf_buffer *buffer)

Import dmabuf buffer into current renderer.

This function tests that the linux_dmabuf_buffer is usable for the current renderer. Returns false on unusable buffers. Usually usability is tested by importing the dmabufs for composition.

This hook is also used for detecting if the renderer supports dmabufs at all. If the renderer hook is NULL, dmabufs are not supported.

  • compositor

  • buffer – the dmabuf buffer to import


true on usable buffers, false otherwise

void weston_compositor_destroy(struct weston_compositor *compositor)

Destroys the compositor.

This function cleans up the compositor state and then destroys it.


compositor – The compositor to be destroyed.

void weston_compositor_exit(struct weston_compositor *compositor)

Instruct the compositor to exit.

This functions does not directly destroy the compositor object, it merely command it to start the tear down process. It is not guaranteed that the tear down will happen immediately.


compositor – The compositor to tear down.

void *weston_compositor_get_user_data(struct weston_compositor *compositor)

Return the user data stored in the compositor.

This function returns the user data pointer set with user_data parameter to the weston_compositor_create function.

struct weston_backend *weston_compositor_load_backend(struct weston_compositor *compositor, enum weston_compositor_backend backend, struct weston_backend_config *config_base)

Load a backend into a weston_compositor.

A backend must be loaded to make a weston_compositor work. A backend provides input and output capabilities, and determines the renderer to use.

  • compositor – A compositor that has not had a backend loaded yet.

  • backend – Name of the backend file.

  • config_base – A pointer to a backend-specific configuration structure’s ‘base’ member.


A new weston_backend on success, or NULL on error.

int weston_compositor_load_xwayland(struct weston_compositor *compositor)


int weston_compositor_load_color_manager(struct weston_compositor *compositor)

Load Little CMS color manager plugin.

Calling this function before loading any backend sets Little CMS as the active color matching module (CMM) instead of the default no-op color manager.

struct weston_compositor
#include <libweston.h>

Main object, container-like structure which aggregates all other objects.

Public Functions

struct weston_log_scope *weston_compositor_add_log_scope(struct weston_compositor *compositor, const char *name, const char *description, weston_log_scope_cb new_subscription, weston_log_scope_cb destroy_subscription, void *user_data)

Register a new stream name, creating a log scope.

This function works like weston_log_ctx_add_log_scope(), but the log scope created is linked to the log context of compositor.



  • compositor – The compositor that contains the log context where the log scope will be linked.

  • name – The debug stream/scope name; must not be NULL.

  • description – The log scope description for humans; must not be NULL.

  • new_subscription – Optional callback when a client subscribes to this scope.

  • destroy_subscription – Optional callback when a client destroys the subscription.

  • user_data – Optional user data pointer for the callback.


A valid pointer on success, NULL on failure.

Public Members

struct wl_signal destroy_signal
bool shutting_down
struct wl_display *wl_display
struct weston_desktop_xwayland *xwayland
const struct weston_desktop_xwayland_interface *xwayland_interface
struct wl_signal create_surface_signal
struct wl_signal activate_signal
struct wl_signal transform_signal
struct wl_signal kill_signal
struct wl_signal idle_signal
struct wl_signal wake_signal
struct wl_signal show_input_panel_signal
struct wl_signal hide_input_panel_signal
struct wl_signal update_input_panel_signal
struct wl_signal seat_created_signal
struct wl_signal output_created_signal
struct wl_signal output_destroyed_signal
struct wl_signal output_moved_signal
struct wl_signal output_resized_signal
struct wl_signal output_heads_changed_signal
struct wl_signal session_signal
bool session_active
struct weston_layer fade_layer
struct weston_layer cursor_layer
struct wl_list pending_output_list
struct wl_list output_list
struct wl_list head_list
struct wl_list seat_list
struct wl_list layer_list
struct wl_list view_list
struct wl_list plane_list
struct wl_list key_binding_list
struct wl_list modifier_binding_list
struct wl_list button_binding_list
struct wl_list touch_binding_list
struct wl_list tablet_tool_binding_list
struct wl_list axis_binding_list
struct wl_list debug_binding_list
bool view_list_needs_rebuild
uint32_t state
struct wl_event_source *idle_source
uint32_t idle_inhibit
int idle_time
struct wl_event_source *repaint_timer
const struct weston_pointer_grab_interface *default_pointer_grab
uint32_t capabilities
struct weston_color_manager *color_manager
struct weston_idalloc *color_profile_id_generator
struct weston_idalloc *color_transform_id_generator
struct weston_renderer *renderer
const struct pixel_format_info *read_format
struct weston_backend *primary_backend
struct wl_list backend_list
struct weston_launcher *launcher
struct weston_dmabuf_feedback *default_dmabuf_feedback
struct weston_dmabuf_feedback_format_table *dmabuf_feedback_format_table
struct wl_list plugin_api_list
uint32_t output_id_pool
bool output_flow_dirty
struct xkb_rule_names xkb_names
struct xkb_context *xkb_context
struct weston_xkb_info *xkb_info
int32_t kb_repeat_rate
int32_t kb_repeat_delay
bool vt_switching
clockid_t presentation_clock
int32_t repaint_msec
struct timespec last_repaint_start
unsigned int activate_serial
struct wl_global *pointer_constraints
int exit_code
void *user_data
void (*exit)(struct weston_compositor *c)
struct wl_global *tablet_manager
struct wl_list tablet_manager_resource_list
bool require_input
bool multi_backend
struct weston_testsuite_data test_data
struct wl_signal heads_changed_signal
struct wl_event_source *heads_changed_source
enum weston_touch_mode touch_mode
struct wl_global *touch_calibration
weston_touch_calibration_save_func touch_calibration_save
struct weston_layer calibrator_layer
struct weston_touch_calibrator *touch_calibrator
struct weston_log_context *weston_log_ctx
struct weston_log_scope *debug_scene
struct weston_log_scope *timeline
struct weston_log_scope *libseat_debug
struct content_protection *content_protection
struct weston_log_pacer unmapped_surface_or_view_pacer
struct weston_log_pacer presentation_clock_failure_pacer
struct wl_global *weston_capture_v1
struct wl_signal ask_auth
struct weston_compositor::[anonymous] output_capture

Screenshooting global state, see output-capture.c.