# Outputs

A `weston_output` determines what part of the global compositor coordinate space will be composited into an image and when. That image is presented on the attached heads (weston_head).

An output object is responsible for the framebuffer management, damage tracking, display timings, and the repaint state machine. Video mode, output scale and output transform are properties of an output.

In display hardware, a weston_output represents a CRTC, but only if it has been successfully enabled. The CRTC may be switched to another during an output’s lifetime.

The lifetime of a weston_output is controlled by the libweston user.

With at least a `weston_head` attached, you can construct a `weston_output` object which can be used by the compositor, by enabling the output using `weston_output_enable()`. The output must not be already enabled.

The reverse operation, `weston_output_disable()`, should be used when there’s a need to reconfigure the output or it will be destroyed.

enum weston_repaint_status

  State of the repaint loop.

  Values:

  enumerator REPAINT_NOT_SCHEDULED

    idle; no repaint will occur

  enumerator REPAINT_BEGIN_FROM_IDLE

    start_repaint_loop scheduled

  enumerator REPAINT_SCHEDULED

    repaint is scheduled to occur

  enumerator REPAINT_AWAITING_COMPLETION

    last repaint not yet finished

  enumerator REPAINT_DEFERRED

    Needs a repaint when the backend is ready.

    Backends must call weston_backend_clear_deferred() when ready.

void weston_output_copy_native_mode(struct weston_output *output, struct weston_mode *mode)

  Set up the native mode for an output.

  Our mode setting code does some ugly tricks, and will sometimes save pointers to ephemeral structures for comparison later.

  To work around this fragility, we copy the contents of the native mode at set time.

  This function will be removed when we fix the mode set code.

  Parameters:

    - output – The weston_output object

    - mode – The new native mode

int weston_output_mode_set_native(struct weston_output *output, struct weston_mode *mode, int32_t scale)

int weston_output_mode_switch_to_native(struct weston_output *output)

int weston_output_mode_switch_to_temporary(struct weston_output *output, struct weston_mode *mode, int32_t scale)

void weston_output_damage(struct weston_output *output)

void weston_output_finish_frame(struct weston_output *output, const struct timespec *stamp, uint32_t presented_flags)

void weston_output_schedule_repaint(struct weston_output *output)

static void weston_output_emit_heads_changed(struct weston_output *output)

  Send output heads changed signal.

  Notify that the enabled output gained and/or lost heads, or that the associated heads may have changed their connection status. This does not include cases where the output becomes enabled or disabled. The registered callbacks are called after the change has successfully happened.

  If connection status change causes the compositor to attach or detach a head to an enabled output, the registered callbacks may be called multiple times.

  Parameters:

    output – The output that changed.

struct weston_head *weston_output_iterate_heads(struct weston_output *output, struct weston_head *iter)

  Iterate over attached heads.

  Returns all heads currently attached to the output.

  You can iterate over all heads as follows:

      struct weston_head *head = NULL;

      while ((head = weston_output_iterate_heads(output, 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:

    - output – The output whose heads to iterate.

    - iter – The iterator, or NULL for start.

  Returns:

    The next attached head in the list.

int weston_output_attach_head(struct weston_output *output, struct weston_head *head)

  Attach a head to an output.

  Attaches the given head to the output. All heads of an output are clones and share the resolution and timings.

  Cloning heads this way uses less resources than creating an output for each head, but is not always possible due to environment, driver and hardware limitations.

  On failure, the head remains unattached. Success of this function does not guarantee the output configuration is actually valid. The final checks are made on weston_output_enable() unless the output was already enabled.

  Parameters:

    - output – The output to attach to.

    - head – The head that is not yet attached.

  Returns:

    0 on success, -1 on failure.

void weston_output_set_position(struct weston_output *output, struct weston_coord_global pos)

void weston_output_move(struct weston_output *output, struct weston_coord_global pos)

struct weston_coord_global weston_coord_global_from_output_point(double x, double y, const struct weston_output *output)

  Create a weston_coord_global from a point and a weston_output.

  Transforms coordinates from the device coordinate space (physical pixel units) to the global coordinate space (logical pixel units). This takes into account output transform and scale.

  Parameters:

    - x – x coordinate on the output

    - y – y coordinate on the output

    - output – the weston_output object

  Returns:

    coordinate in global space corresponding to x, y on the output

void weston_output_color_effect_inversion(struct weston_output *output)

  Set output’s color effect as color inversion.

  The color effect is an effect applied to the whole scenegraph. Note that in some cases this may force all the surfaces to be composed on the primary plane, i.e. offloading to overlay planes won’t be possible.

  Parameters:

    output – The output to set the effect.

void weston_output_color_effect_cvd_correction(struct weston_output *output, enum weston_cvd_correction_type type)

  Set output’s color effect as CVD correction.

  The color effect is an effect applied to the whole scenegraph. Note that in some cases this may force all the surfaces to be composed on the primary plane, i.e. offloading to overlay planes won’t be possible.

  Parameters:

    - output – The output to set the effect.

    - type – The color blidness correction type.

void weston_output_set_scale(struct weston_output *output, int32_t scale)

  Sets the output scale for a given output.

  Parameters:

    - output – The weston_output object that the scale is set for.

    - scale – Scale factor for the given output.

void weston_output_set_transform(struct weston_output *output, uint32_t transform)

  Sets the output transform for a given output.

  Refer to wl_output::transform section located at https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_output for list of values that can be passed to this function.

  Parameters:

    - output – The weston_output object that the transform is set for.

    - transform – Transform value for the given output.

bool weston_output_set_color_profile(struct weston_output *output, struct weston_color_profile *cprof)

  Set output’s color profile.

  Calling this function changes the color profile of the output. This causes all existing weston_color_transform objects related to this output via paint nodes to be unreferenced and later re-created on demand.

  This function may not be called from within weston_output_repaint().

  On failure, nothing is changed.

  Parameters:

    - output – The output to change.

    - cprof – The color profile to set. Can be NULL for default sRGB profile.

  Returns:

    True on success, or false on failure.

void weston_output_set_eotf_mode(struct weston_output *output, enum weston_eotf_mode eotf_mode)

  Set EOTF mode on an output.

  Setting the output EOTF mode is used for turning HDR on/off. There are multiple modes for HDR on, see enum weston_eotf_mode. This is the high level choice on how to drive a video sink (monitor), either in the traditional SDR mode or in one of the HDR modes.

  After attaching heads to an output, you can find out the possibly supported EOTF modes with weston_output_get_supported_eotf_modes().

  This function does not check whether the given eotf_mode is actually supported on the output. Enabling an output with an unsupported EOTF mode has undefined visual results.

  TODO: Enforce mode validity.

  The initial EOTF mode is SDR.

  Parameters:

    - output – The output to modify, must be in disabled state.

    - eotf_mode – The EOTF mode to set.

enum weston_eotf_mode weston_output_get_eotf_mode(const struct weston_output *output)

  Get EOTF mode of an output.

  See also

  weston_output_set_eotf_mode

  Parameters:

    output – The output to query.

  Returns:

    The EOTF mode.

void weston_output_set_colorimetry_mode(struct weston_output *output, enum weston_colorimetry_mode colorimetry_mode)

  Set colorimetry mode on an output.

  Setting the output colorimetry mode is used for choosing the video signal encoding colorimetry. This is purely metadata to be sent to the video sink, intended to allow the video sink to decode the sent pixels correctly. This may be used to enable wide color gamut modes. ST2084 and HLG EOTF modes for HDR tend to use BT.2020 colorimetry mode.

  Only backends that directly drive a video sink might use this information (DRM-backend).

  After attaching heads to an output, you can find out the possibly supported colorimetry modes with weston_output_get_supported_colorimetry_modes().

  This function does not check whether the given colorimetry_mode is actually supported on the output. Enabling an output with an unsupported colorimetry mode has undefined visual results.

  TODO: Enforce mode validity.

  The initial colorimetry mode is DEFAULT.

  Parameters:

    - output – The output to modify, must be in disabled state.

    - colorimetry_mode – The colorimetry mode to set.

enum weston_colorimetry_mode weston_output_get_colorimetry_mode(const struct weston_output *output)

  Get colorimetry mode of an output.

  See also

  weston_output_set_colorimetry_mode

  Parameters:

    output – The output to query.

  Returns:

    The colorimetry mode.

const struct weston_hdr_metadata_type1 *weston_output_get_hdr_metadata_type1(const struct weston_output *output)

  Get HDR static metadata type 1.

  This function is meant to be used by libweston backends.

  Parameters:

    output – The output to query.

  Returns:

    Pointer to the metadata stored in weston_output.

void weston_output_set_color_characteristics(struct weston_output *output, const struct weston_color_characteristics *cc)

  Set display or monitor basic color characteristics.

  This sets the metadata that describes the color characteristics of the output in a very simple manner. If a non-NULL color profile is set for the output, that will always take precedence.

  The initial value has everything unset.

  This function is meant to be used by compositor frontends.

  See also

  weston_output_set_color_profile

  Parameters:

    - output – The output to modify, must be in disabled state.

    - cc – The new characteristics to set, or NULL to unset everything.

const struct weston_color_characteristics *weston_output_get_color_characteristics(struct weston_output *output)

  Get display or monitor basic color characteristics.

  This function is meant to be used by color manager modules.

  See also

  weston_output_set_color_characteristics

  Parameters:

    output – The output to query.

  Returns:

    Pointer to the metadata stored in weston_output.

void weston_output_init(struct weston_output *output, struct weston_compositor *compositor, const char *name)

  Initializes a weston_output object with enough data so an output can be configured.

  Sets initial values for fields that are expected to be configured either by compositors or backends.

  The name is used in logs, and can be used by compositors as a configuration identifier.

  Parameters:

    - output – The weston_output object to initialize

    - compositor – The compositor instance.

    - name – Name for the output (the string is copied).

static char *weston_output_create_heads_string(struct weston_output *output)

  Create a string with the attached heads’ names.

  The string must be free()’d.

int weston_output_enable(struct weston_output *output)

  Constructs a weston_output object that can be used by the compositor.

  Output coordinates are calculated and each new output is by default assigned to the right of previous one.

  Sets up the transformation, and geometry of the output using the properties that need to be configured by the compositor.

  Establishes a repaint timer for the output with the relevant display object’s event loop. See output_repaint_timer_handler().

  The output is assigned an ID. Weston can support up to 32 distinct outputs, with IDs numbered from 0-31; the compositor’s output_id_pool is referred to and used to find the first available ID number, and then this ID is marked as used in output_id_pool.

  The output is also assigned a Wayland global with the wl_output external interface.

  Backend specific function is called to set up the output output.

  Output is added to the compositor’s output list

  If the backend specific function fails, the weston_output object is returned to a state it was before calling this function and is added to the compositor’s pending_output_list in case it needs to be reconfigured or just so it can be destroyed at shutdown.

  0 is returned on success, -1 on failure.

  Parameters:

    output – The weston_output object that needs to be enabled. Must not be enabled already. Must have at least one head attached.

void weston_output_disable(struct weston_output *output)

  Converts a weston_output object to a pending output state, so it can be configured again or destroyed.

  Calls a backend specific function to disable an output, in case such function exists.

  The backend specific disable function may choose to postpone the disabling by returning a negative value, in which case this function returns early. In that case the backend will guarantee the output will be disabled soon by the backend calling this function again. One must not attempt to re-enable the output until that happens.

  Otherwise, if the output is being used by the compositor, it is removed from weston’s output_list (see weston_compositor_remove_output()) and is returned to a state it was before weston_output_enable() was ran (see weston_output_enable_undo()).

  See weston_output_init() for more information on the state output is returned to.

  If the output has never been enabled yet, this function can still be called to ensure that the output is actually turned off rather than left in the state it was discovered in.

  Parameters:

    output – The weston_output object that needs to be disabled.

void weston_output_add_destroy_listener(struct weston_output *output, struct wl_listener *listener)

  Add destroy callback for an output.

  The listener callback will be called when user destroys an output. This may be delayed by a backend in some cases. The main purpose of the listener is to allow hooking up custom data to the output. The custom data can be fetched via weston_output_get_destroy_listener() followed by container_of().

  The `data` argument to the notify callback is the weston_output being destroyed.

  Note

  This is for the final destruction of an output, not when it gets disabled. If you want to keep track of enabled outputs, this is not it.

  Parameters:

    - output – The output to watch.

    - listener – The listener to add. The `notify` member must be set.

struct wl_listener *weston_output_get_destroy_listener(struct weston_output *output, wl_notify_func_t notify)

  Look up destroy listener for an output.

  This looks up the previously added destroy listener struct based on the notify function it has. The listener can be used to access user data through `container_of()`.

  See also

  wl_signal_get() weston_output_add_destroy_listener()

  Parameters:

    - output – The output to query.

    - notify – The notify function used used for the added destroy listener.

  Returns:

    The listener, or NULL if not found.

void weston_output_release(struct weston_output *output)

  Uninitialize an output.

  Removes the output from the list of enabled outputs if necessary, but does not call the backend’s output disable function. The output will no longer be in the list of pending outputs either.

  All fields of weston_output become uninitialized, i.e. should not be used anymore. The caller can free the memory after this.

void weston_output_destroy(struct weston_output *output)

  Destroy an output.

  The heads attached to the given output are detached and become unused again.

  It is not necessary to explicitly destroy all outputs at compositor exit. weston_compositor_destroy() will automatically destroy any remaining outputs.

  Parameters:

    output – The output to destroy.

struct weston_head *weston_output_get_first_head(struct weston_output *output)

  When you need a head…

  This function is a hack, used until all code has been converted to become multi-head aware.

  Parameters:

    output – The weston_output whose head to get.

  Returns:

    The first head in the output’s list.

uint32_t weston_output_get_supported_eotf_modes(struct weston_output *output)

  Get supported EOTF modes as a bit mask.

  Returns the bit mask of the EOTF modes that all the currently attached heads claim to support. Adding or removing heads may change the result. An output can be queried regrdless of whether it is enabled or disabled.

  If no heads are attached, no EOTF modes are deemed supported.

  Parameters:

    output – The output to query.

  Returns:

    A bit mask with values from enum weston_eotf_mode or’ed together.

uint32_t weston_output_get_supported_colorimetry_modes(struct weston_output *output)

  Get supported colorimetry modes as a bit mask.

  Returns the intersection of the colorimetry modes supported by the currently attached heads as a bit mask. Adding or removing heads may change the result. An output can be queried regardless of whether it is enabled or disabled.

  If no heads are attached, no colorimetry modes are deemed supported.

  Parameters:

    output – The output to query.

  Returns:

    A bit mask with values from enum weston_colorimetry_mode or’ed together.

void weston_output_set_ready(struct weston_output *output)

  Inform the compositor that an output is ready for its first repaint.

  When a new output is added, it may not have any content to be displayed. This could lead to strange flickers or hangs at startup if uninitialized buffers become attached for scanout. To prevent this, we assert that the output has content to display.

  The shell must inform the compositor when content such as a background is in the scene graph and this output can safely be repainted.

  Only needs to be called once per output, and an output can never become unready.

  Parameters:

    output – the output that has become ready

struct weston_output_color_outcome
  #include <color.h>

  Output properties derived from its color characteristics and profile.

  These are constructed by a color manager.

  A weston_output_color_outcome owns (a reference to) everything it contains.

  Public Members

  struct weston_color_transform *from_sRGB_to_output

    sRGB to output color space transformation

  struct weston_color_transform *from_sRGB_to_blend

    sRGB to blending color space transformation

  struct weston_color_transform *from_blend_to_output

    Blending to output color space transformation.

  struct weston_hdr_metadata_type1 hdr_meta

    HDR Static Metadata Type 1 for WESTON_EOTF_MODE_ST2084.

struct weston_mode
  #include <libweston.h>

  Possible mode of an output.

  Public Members

  uint32_t flags
  enum weston_mode_aspect_ratio aspect_ratio

    Picture aspect ratio.

  int32_t width

    Width in pixels.

  int32_t height

    Height in pixels.

  uint32_t refresh

    Refresh rate in mHz.

  struct wl_list link

    in weston_output::mode_list

struct weston_output
  #include <libweston.h>

  Content producer for heads.

  See Outputs.

  Public Members

  uint32_t id
  char *name
  void *shell_private
  struct weston_backend *backend
  struct wl_signal user_destroy_signal

    Matches the lifetime from the user perspective.

  void *renderer_state
  struct weston_plane primary_plane
  struct wl_list link
  struct weston_compositor *compositor
  struct wl_list paint_node_list
  enum weston_paint_node_status paint_node_changes

    Only valid during repaint: changes for this repaint.

  struct weston_matrix matrix

    From global to output buffer coordinates.

  struct weston_matrix inverse_matrix

    From output buffer to global coordinates.

  struct wl_list animation_list
  struct weston_coord_global pos
  int32_t width
  int32_t height
  uint64_t gpu_track_id
  uint64_t paint_track_id
  uint64_t presentation_track_id
  struct wl_list paint_node_z_order_list

    List of paint nodes in z-order, from top to bottom, maybe pruned.

    struct weston_paint_node::z_order_link

  pixman_region32_t region

    Output area in global coordinates, simple rect.

  bool repaint_needed

    True if damage has occurred since the last repaint for this output; if set, a repaint will eventually occur.

  bool full_repaint_needed

    True if the entire contents of the output should be redrawn.

  bool will_repaint

    True if the output will be repainted in the currently active repaint handler.

  bool repainted

    Used only between repaint_begin and repaint_cancel.

  bool repaint_only_on_capture

    Repaints are triggered only on capture requests, not on damages.

  enum weston_repaint_status repaint_status

    State of the repaint loop.

  struct timespec next_repaint

    If repaint_status is REPAINT_SCHEDULED, contains the time the next repaint should be run.

  struct timespec next_present

    If repaint_statue is REPAINT_SCHEDULED, contains the time the next repaint should be displayed.

  struct weston_commit_timing_target requested_present

    commit-timing protocol will set this for the closest requested presentation time from a surface on this output.

    It’s only valid during weston_repaint_timer_arm.

  struct weston_commit_timing_target forced_present

    commit-timing protocol will set this when state containing a target time is applied.

    Weston will try to hit this time if VRR is in use.

  struct wl_event_source *idle_repaint_source

    For cancelling the idle_repaint callback on output destruction.

  struct wl_signal frame_signal
  struct wl_signal post_latch_signal
  struct wl_signal destroy_signal

    sent when disabled

  struct weston_coord_global move
  struct timespec frame_time
  uint32_t frame_flags
  uint64_t msc
  int disable_planes
  int destroying
  struct wl_list feedback_list
  struct weston_output_capture_info *capture_info
  uint32_t transform
  int32_t native_scale
  int32_t current_scale
  int32_t original_scale
  struct weston_mode *native_mode
  struct weston_mode *current_mode
  struct weston_mode *original_mode
  uint32_t flags
  enum weston_mode_aspect_ratio aspect_ratio
  uint32_t refresh
  struct weston_output native_mode_copy
  struct wl_list mode_list
  struct wl_list head_list

    List of driven weston_heads.

  enum weston_hdcp_protection desired_protection
  enum weston_hdcp_protection current_protection
  bool allow_protection
  enum weston_output_power_state power_state
  struct weston_log_pacer repaint_delay_pacer
  struct weston_log_pacer pixman_overdraw_pacer
  int (*start_repaint_loop)(struct weston_output *output)
  void (*prepare_repaint)(struct weston_output *output)
  int (*repaint)(struct weston_output *output)
  void (*destroy)(struct weston_output *output)
  void (*assign_planes)(struct weston_output *output)
  int (*switch_mode)(struct weston_output *output, struct weston_mode *mode)
  int32_t backlight_current
  void (*set_backlight)(struct weston_output *output, uint32_t value)
  void (*set_dpms)(struct weston_output *output, enum dpms_enum level)
  bool enabled

    is in the output_list, not pending list

  struct weston_color_profile *color_profile
  bool from_blend_to_output_by_backend
  enum weston_eotf_mode eotf_mode
  enum weston_colorimetry_mode colorimetry_mode
  struct weston_color_characteristics color_characteristics
  struct weston_output_color_outcome *color_outcome
  uint64_t color_outcome_serial
  struct weston_output_color_effect *color_effect
  int (*enable)(struct weston_output *output)
  int (*disable)(struct weston_output *output)
  int (*attach_head)(struct weston_output *output, struct weston_head *head)

    Attach a head in the backend.

    Do anything necessary to account for a new head being attached to the output, and check any conditions possible. On failure, both the head and the output must be left as before the call.

    Libweston core will add the head to the head_list after a successful call.

    Param output:

      The output to attach to.

    Param head:

      The head to attach.

    Return:

      0 on success, -1 on failure.

  void (*detach_head)(struct weston_output *output, struct weston_head *head)

    Detach a head in the backend.

    Do any clean-up necessary to detach this head from the output. The head has already been removed from the output’s head_list.

    Param output:

      The output to detach from.

    Param head:

      The head to detach.

  const struct weston_drm_format_array *(*get_writeback_formats)(struct weston_output *output)

    Get the DRM formats supported by a compatible writeback connector.

  struct weston_output *mirror_of

    When set, this output is a mirror-of another output.

    See mirror-of key in [output] section.

  enum weston_vrr_mode vrr_mode
  enum weston_color_format color_format
  bool ready

    Set by the shell to indicate there’s some content for this output to display.

  bool paint_node_list_needs_rebuild

    Needs to rebuild the paint node z ordered list.

  struct wl_list fifo_barrier_surfaces

    fifo_v1 - list of surfaces to clear next repaint