Compositor

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): weston_compositor_get_time

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

void weston_compositor_damage_all(struct weston_compositor *compositor): weston_compositor_damage_all

void weston_compositor_schedule_repaint(struct weston_compositor *compositor): weston_compositor_schedule_repaint

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.

Parameters: 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.

Parameters: 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.

Parameters: compositor – The compositor instance

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

static void weston_compositor_schedule_heads_changed(struct weston_compositor *compositor)

Schedule a call on idle to heads_changed callback.

Parameters: 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.

Parameters

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.

See: weston_compositor_iterate_heads, weston_head_is_connected, weston_head_is_enabled

Parameters

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.

Parameters

compositor – The compositor.
iter – The iterator, or NULL for start.

Returns

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.

Parameters: 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().

Parameters

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.

Parameters: 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.

Parameters

compositor – The compositor to search in.
name – The output name to search for.

Returns

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.

Parameters

compositor – The compositor.
head – The head to attach to the output.
name – The name for the output.

Returns

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.

See: weston_compositor_test_data_init

Parameters: ec – The weston compositor.
Returns: 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.

Parameters

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.

Returns

The compositor instance on success or NULL on failure.

static void weston_compositor_shutdown(struct weston_compositor *ec): weston_compositor_shutdown

void weston_compositor_exit_with_code(struct weston_compositor *compositor, int exit_code): weston_compositor_exit_with_code

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

int weston_compositor_backends_loaded(struct weston_compositor *compositor)

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

Parameters: compositor – A compositor that has all backends loaded.
Returns: 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.

Note

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

Parameters

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.

Parameters

compositor –
buffer – the dmabuf buffer to import

Returns

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.

Parameters: 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.

Parameters: 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.

Parameters

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.

Returns

A new weston_backend on success, or NULL on error.

int weston_compositor_load_xwayland(struct weston_compositor *compositor): weston_compositor_load_xwayland

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.

See: weston_log_ctx_add_log_scope

Parameters

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.

Returns

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.