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.

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.

Parameters

  • output: The output that changed.

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.

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.

Return

The next attached head in the list.

Parameters

  • output: The output whose heads to iterate.

  • iter: The iterator, or NULL for start.

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.

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.

Return

0 on success, -1 on failure.

Parameters

  • output: The output to attach to.

  • head: The head that is not yet attached.

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.

void weston_output_move(struct weston_output *output, int x, int y)
void weston_output_transform_coordinate(struct weston_output *output, double device_x, double device_y, double *x, double *y)

Transform device coordinates into global coordinates.

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

  • output: the weston_output object

  • [in] device_x: X coordinate in device units.

  • [in] device_y: Y coordinate in device units.

  • [out] x: X coordinate in the global space.

  • [out] y: Y coordinate in the global space.

void weston_output_set_scale(struct weston_output *output, int32_t scale)

Sets the output scale for a given output.

It only supports setting scale for an output that is not enabled and it can only be ran once.

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_renderer_shadow_buffer(struct weston_output *output)

Make the output use renderer shadow buffer.

This can only be set on a disabled output object.

Return

True on success, false if unsupported.

Parameters

This is a temporary API to demonstrate WESTON_CAP_COLOR_OPS and allow testing related features. This will be superseded with color management API.

By default, a renderer is not using a shadow buffer of its own. Enabling a shadow buffer may enable other color related features.

Support depends on the chosen renderer and the graphics driver stack in use.

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.

Parameters

  • output: The weston_output object to initialize

  • compositor: The compositor instance.

  • name: Name for the output (the string is copied).

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

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.

Parameters

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

Sets up the transformation, zoom, 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.

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.

Parameters

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.

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

  • output: The output to watch.

  • listener: The listener to add. The notify member must be set.

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.

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().
Return

The listener, or NULL if not found.

Parameters

  • output: The output to query.

  • notify: The notify function used used for the added destroy listener.

See

wl_signal_get() weston_output_add_destroy_listener()

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.

Parameters

  • output: The output to destroy.

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

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.

Return

The first head in the output’s list.

Parameters

struct weston_output
#include <libweston.h>

Content producer for heads.

See Outputs.

Public Types

enum [anonymous]

State of the repaint loop.

Values:

REPAINT_NOT_SCHEDULED = 0

idle; no repaint will occur

REPAINT_BEGIN_FROM_IDLE

start_repaint_loop scheduled

REPAINT_SCHEDULED

repaint is scheduled to occur

REPAINT_AWAITING_COMPLETION

last repaint not yet finished

Public Members

uint32_t id
char *name
struct wl_signal user_destroy_signal

Matches the lifetime from the user perspective.

void *renderer_state
struct wl_list link
struct weston_compositor *compositor
struct wl_list paint_node_list
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
int32_t x
int32_t y
int32_t width
int32_t height
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 repainted

Used only between repaint_begin and repaint_cancel.

weston_output::[anonymous] 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 wl_event_source *idle_repaint_source

For cancelling the idle_repaint callback on output destruction.

struct weston_output_zoom zoom
int dirty
struct wl_signal frame_signal
struct wl_signal destroy_signal

sent when disabled

int move_x
int move_y
struct timespec frame_time
uint64_t msc
int disable_planes
int destroying
struct wl_list feedback_list
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
struct wl_list mode_list
struct wl_list head_list

List of driven weston_heads.

weston_hdcp_protection desired_protection
weston_hdcp_protection current_protection
bool allow_protection
int (*start_repaint_loop)(struct weston_output *output)
int (*repaint)(struct weston_output *output, pixman_region32_t *damage, void *repaint_data)
void (*destroy)(struct weston_output *output)
void (*assign_planes)(struct weston_output *output, void *repaint_data)
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)
uint16_t gamma_size
void (*set_gamma)(struct weston_output *output, uint16_t size, uint16_t *r, uint16_t *g, uint16_t *b)
bool enabled

is in the output_list, not pending list

int scale
bool use_renderer_shadow_buffer
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.

Return

0 on success, -1 on failure.

Parameters

  • output: The output to attach to.

  • head: The head to attach.

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

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.

Parameters

  • output: The output to detach from.

  • head: The head to detach.