# 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 also

  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 also

  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 also

    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
  int global_weston_surface_disambiguator
  uint32_t state
  struct wl_event_source *idle_source
  uint32_t idle_inhibit
  int idle_time
  int repaint_timer_fd
  struct wl_event_source *repaint_timer_source
  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 disable_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 weston_log_filtered *advertised_log_scopes
  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 output_capture

    Screenshooting global state, see output-capture.c.

  unsigned int frame_counter_interval

    interval which we divide the amount of frames

  struct wl_event_source *frame_counter_timer

    fires with frame_counter_interval rate

  struct weston_compositor perf_surface_stats
  uint32_t placeholder_color
  bool no_xwm_decorations
  bool latched

    When set the compositor has latched content updates for the upcoming repaint, and no more updates may be applied until after that repaint occurs.

  struct wl_list transaction_queue_list
  struct weston_commit_timing_target requested_repaint_fallback

    commit_timing_v1 - target repaint time for content updates for surfaces with no output