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, wl_fixed_t x, wl_fixed_t y, wl_fixed_t *vx, wl_fixed_t *vy)¶: 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.

Parameters

compositor: The compositor instance

Restarts the idle timer.

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.

Parameters

compositor: The compositor instance

Stops the idle timer.

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.

Parameters

compositor: The compositor instance

Stops the idle timer.

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.

Parameters

compositor: The compositor.
listener: The listener to add.

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

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.

Return

The next available head in the list.

Parameters

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

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.

static void weston_compositor_remove_output(struct weston_output *output)¶

Removes output from compositor’s list of enabled outputs.

The following happens:

Parameters

output: The weston_output object that is being removed.

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.

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.

Return

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

Parameters

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

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

Create a named output.

This creates a new

weston_output that starts with no heads attached.

Return

A new weston_output, or NULL on failure.

Parameters

compositor: The compositor.
name: The name for the output.

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

struct weston_output *weston_compositor_create_output_with_head(struct weston_compositor *compositor, struct weston_head *head)¶

Create an output for an unused head.

This creates a new

weston_output that starts with the given head attached. The output inherits the name of the head. The head must not be already attached to another output.

Return

A new weston_output, or NULL on failure.

Parameters

compositor: The compositor.
head: The head to attach to the output.

An output must be configured before it can be enabled.

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.

Return

The testsuite data.

See

weston_compositor_test_data_init

Parameters

ec: The weston compositor.

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.

Return

The compositor instance on success or NULL on failure.

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.

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_set_presentation_clock(struct weston_compositor *compositor, clockid_t clk_id)¶: weston_compositor_set_presentation_clock

int weston_compositor_set_presentation_clock_software(struct weston_compositor *compositor)¶: For choosing the software clock, when the display hardware or API does not expose a compatible presentation timestamp.

void weston_compositor_read_presentation_clock(const 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:
[out] ts: 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.

Return

true on usable buffers, false otherwise

Parameters

compositor:
buffer: the dmabuf buffer to import

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

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.

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

Return

0 on success, or -1 on error.

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.

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.

Return

A valid pointer on success, NULL on failure.

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.

See: weston_log_ctx_add_log_scope

Public Members

struct wl_signal destroy_signal¶

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 axis_binding_list¶

struct wl_list debug_binding_list¶

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¶

struct weston_plane primary_plane¶

uint32_t capabilities¶

struct weston_color_manager *color_manager¶

struct weston_renderer *renderer¶

pixman_format_code_t read_format¶

struct weston_backend *backend¶

struct weston_launcher *launcher¶

struct wl_list plugin_api_list¶

uint32_t output_id_pool¶

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)¶

bool require_input¶

struct weston_testsuite_data test_data¶

struct wl_signal heads_changed_signal¶

struct wl_event_source *heads_changed_source¶

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 content_protection *content_protection¶