Compositor¶

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

Compositor API¶

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

The following is from compositor.h

struct weston_point2d_device_normalized¶: 2D device coordinates normalized to [0, 1] range

struct weston_head¶

Represents a monitor

This object represents a monitor (hardware backends like DRM) or a window (windowed nested backends).

struct weston_compositor¶: owning compositor

struct wl_list compositor_link¶: in weston_compositor::head_list

struct wl_signal¶: destroy callbacks

struct weston_output * output¶: the output driving this head

struct wl_list output_link¶: in weston_output::head_list

struct wl_list resource_list¶: wl_output protocol objects

struct wl_global¶: wl_output global

int32_t mm_width¶: physical image width in mm

int32_t mm_height¶: physical image height in mm

char * make¶: monitor manufacturer (PNP ID)

char * model¶: monitor model

char * serial_number¶: monitor serial

uint32_t subpixel¶: enum wl_output_subpixel

int connection_internal¶: embedded monitor (e.g. laptop)

int device_changed¶: monitor information has changed

char * name¶: head name, e.g. connector name

int connected¶: is physically connected

int non_desktop¶: non-desktop display, e.g. HMD

struct weston_output¶

represents an output

struct wl_signal user_destroy_signal¶: Matches the lifetime from the user perspective

struct weston_matrix matrix¶: From global to output buffer coordinates.

struct weston_matrix inverse_matrix¶: From output buffer to global coordinates.

int region¶: Output area in global coordinates, simple rect

int repaint_needed¶

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

int repainted¶: Used only between repaint_begin and repaint_cancel.

enum weston_output::(anonymous at /home/mvlad/src/weston/libweston/doc-hawkmoth/../compositor.h:250:2)¶

State of the repaint loop

REPAINT_NOT_SCHEDULED¶: 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

struct timespec next_repaint¶: If repaint_status is REPAINT_SCHEDULED, contains the time the next repaint should be run

struct wl_event_source¶: For cancelling the idle_repaint callback on output destruction.

struct wl_signal destroy_signal¶: sent when disabled

struct timespec frame_time¶: presentation timestamp

uint64_t msc¶: media stream counter

struct wl_list head_list¶: List of driven weston_heads

int32_t backlight_current¶: backlight values are on 0-255 range, where higher is brighter

int enabled¶: is in the output_list, not pending list

int (*)(struct weston_output *) enable

enable the output

Parameters:	output – the output to enable

int (*)(struct weston_output *) disable: disable the output

int (*)(struct weston_output *, struct weston_head *) attach_head

Attach a head in the backend

Parameters:	output – The output to attach to. head – The head to attach.
Returns:	0 on success, -1 on failure.

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.

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

Detach a head in the backend

Parameters:	output – The output to detach from. head – The head to detach.

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

struct weston_pointer_grab_interface¶: pointer grab interface

struct weston_touch_device_matrix¶

libinput style calibration matrix

See https://wayland.freedesktop.org/libinput/doc/latest/absolute_axes.html and libinput_device_config_calibration_set_matrix().

struct weston_touch_device_ops¶

Operations for a calibratable touchscreen

struct weston_output *(*)(struct weston_touch_device *) get_output: Get the associated output if existing.

const char *(*)(struct weston_touch_device *) get_calibration_head_name: Get the name of the associated head if existing.

void (*)(struct weston_touch_device *, struct weston_touch_device_matrix *) get_calibration: Retrieve the current calibration matrix.

void (*)(struct weston_touch_device *, const struct weston_touch_device_matrix *) set_calibration: Set a new calibration matrix.

enum weston_touch_mode¶

the type of touch

WESTON_TOUCH_MODE_NORMAL¶: Normal touch event handling

WESTON_TOUCH_MODE_PREP_CALIB¶

Prepare moving to WESTON_TOUCH_MODE_CALIB.

Move to WESTON_TOUCH_MODE_CALIB as soon as no touches are down on any seat. Until then, all touch events are routed normally.

WESTON_TOUCH_MODE_CALIB¶

Calibration mode

Only a single weston_touch_device forwards events to the calibrator all other touch device cause a calibrator “wrong device” event to be sent.

WESTON_TOUCH_MODE_PREP_NORMAL¶

Prepare moving to WESTON_TOUCH_MODE_NORMAL.

Move to WESTON_TOUCH_MODE_NORMAL as soon as no touches are down on any seat. Until then, touch events are routed as in WESTON_TOUCH_MODE_CALIB except “wrong device” events are not sent.

struct weston_touch_device¶

Represents a physical touchscreen input device

char * syspath¶: unique name

struct weston_touch * aggregate¶: weston_touch this is part of

struct wl_list link¶: in weston_touch::device_list

struct wl_signal destroy_signal¶: destroy notifier

void * backend_data¶: backend-specific private

const struct weston_touch_device_ops * ops¶: weston_touch_device ops

struct weston_touch_device_matrix saved_calibration¶: matrix calib

struct weston_touch¶

Represents a set of touchscreen devices aggregated under a seat

struct wl_list device_list¶: struct weston_touch_device::link

enum weston_layer_position¶

Higher value means higher in the stack.

These values are based on well-known concepts in a classic desktop environment. Third-party modules based on libweston are encouraged to use them to integrate better with other projects.

A fully integrated environment can use any value, based on these or not, at their discretion.

See weston_compositor_import_dmabuf()

weston_touch_calibration_save_func¶

Callback for saving calibration

param compositor The compositor. param device The physical touch device to save for. param calibration The new calibration from a client. return -1 on failure, 0 on success.

Failure will prevent taking the new calibration into use.

void notify_touch(struct weston_touch_device * device, const struct timespec * time, int touch_id, double x, double y, int touch_type)¶

Feed in touch down, motion, and up events, non-calibratable device.

@sa notify_touch_cal

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

The following is from compositor.c

void weston_mode_switch_send_events(struct weston_head * head, int mode_changed, int scale_changed)¶

Send wl_output events for mode and scale changes

Parameters:	head – Send on all resources bound to this head. mode_changed – If true, send the current mode. scale_changed – If true, send the current scale.

void weston_matrix_transform_region(int * dest, struct weston_matrix * matrix, int * src)¶

Transform a region by a matrix, restricted to axis-aligned transformations

Warning: This function does not work for projective, affine, or matrices that encode arbitrary rotations. Only 90-degree step rotations are supported.

int weston_surface_to_buffer_rect()¶

Transform a rectangle from surface coordinates to buffer coordinates

Parameters:	surface – The surface to fetch wp_viewport and buffer transformation from. rect – The rectangle to transform.
Returns:	The transformed rectangle.

Viewport and buffer transformations can only do translation, scaling, and rotations in 90-degree steps. Therefore the only loss in the conversion is coordinate rounding.

However, some coordinate rounding takes place as an intermediate step before the buffer scale factor is applied, so the rectangle boundary may not be exactly as expected.

This is OK for damage tracking since a little extra coverage is not a problem.

void weston_surface_to_buffer_region(struct weston_surface * surface, int * surface_region, int * buffer_region)¶

Transform a region from surface coordinates to buffer coordinates

Parameters:	surface_region – The region in surface coordinates. buffer_region – The region converted to buffer coordinates.

Buffer_region must be init’d, but will be completely overwritten.

Viewport and buffer transformations can only do translation, scaling, and rotations in 90-degree steps. Therefore the only loss in the conversion is from the coordinate rounding that takes place in weston_surface_to_buffer_rect().

void weston_view_damage_below(struct weston_view * view)¶

Inflict damage on the plane where the view is visible.

Parameters:	view – The view that causes the damage.

If the view is currently on a plane (including the primary plane), take the view’s boundingbox, subtract all the opaque views that cover it, and add the remaining region as damage to the plane. This corresponds to the damage inflicted to the plane if this view disappeared.

A repaint is scheduled for this view.

The region of all opaque views covering this view is stored in weston_view::clip and updated by view_accumulate_damage() during weston_output_repaint(). Specifically, that region matches the scenegraph as it was last painted.

void weston_surface_send_enter_leave(struct weston_surface * surface, struct weston_head * head, int enter, int leave)¶

Send wl_surface.enter/leave events

Parameters:	surface – The surface. head – A head of the entered/left output. enter – True if entered. left – True if left.

Send the enter/leave events for all protocol objects bound to the given output by the client owning the surface.

void weston_surface_update_output_mask(struct weston_surface * es, int mask)¶

param es The surface param mask The new set of outputs for the surface

Sets the surface’s set of outputs to the ones specified by the new output mask provided. Identifies the outputs that have changed, the posts enter and leave events for these outputs as appropriate.

void weston_view_set_output(struct weston_view * view, struct weston_output * output)¶

Set the primary output of the view

Parameters:	view – The view whose primary output to set output – The new primary output for the view

Set a output to be the primary output of the a view.

Notice that the assignment may be temporary; the primary output could be automatically changed. Hence, one cannot rely on the value persisting.

Passing NULL as /a output will set the primary output to NULL.

void weston_surface_assign_output(struct weston_surface * es)¶

Recalculate which output(s) the surface has views displayed on

param es The surface to remap to outputs

Finds the output that is showing the largest amount of one of the surface’s various views. This output becomes the surface’s primary output for vsync and frame callback purposes.

Also notes all outputs of all of the surface’s views in the output_mask for the surface.

void weston_view_assign_output(struct weston_view * ev)¶

Recalculate which output(s) the view is displayed on

param ev The view to remap to outputs

Identifies the set of outputs that the view is visible on, noting them into the output_mask. The output that the view is most visible on is set as the view’s primary output.

Also does the same for the view’s surface. See weston_surface_assign_output().

void weston_surface_schedule_repaint(struct weston_surface * surface)¶

schedule a surface repaint

Parameters:	surface – The surface to be repainted

Marks the output(s) that the surface is shown on as needing to be repainted. See weston_output_schedule_repaint().

void weston_view_schedule_repaint(struct weston_view * view)¶

schedule a view repaint

Parameters:	view – The view to be repainted

Marks the output(s) that the view is shown on as needing to be repainted. See weston_output_schedule_repaint().

void weston_surface_damage(struct weston_surface * surface)¶

This function does it the wrong way.

surface->damage is the damage from the client, and causes surface_flush_damage() to copy pixels. No window management action can cause damage to the client-provided content, warranting re-upload!

Instead of surface->damage, this function should record the damage with all the views for this surface to avoid extraneous texture uploads.

void weston_view_set_mask(struct weston_view * view, int x, int y, int width, int height)¶

Set a clip mask rectangle on a view

Parameters:	view – The view to set the clip mask on. x – Top-left corner X coordinate of the clip rectangle. y – Top-left corner Y coordinate of the clip rectangle. width – Width of the clip rectangle, non-negative. height – Height of the clip rectangle, non-negative.

A shell may set a clip mask rectangle on a view. Everything outside the rectangle is cut away for input and output purposes: it is not drawn and cannot be hit by hit-test based input like pointer motion or touch-downs. Everything inside the rectangle will behave normally. Clients are unaware of clipping.

The rectangle is set in surface-local coordinates. Setting a clip mask rectangle does not affect the view position, the view is positioned as it would be without a clip. The clip also does not change weston_surface::width,height.

The clip mask rectangle is part of transformation inheritance (weston_view_set_transform_parent()). A clip set in the root of the transformation inheritance tree will affect all views in the tree. A clip can be set only on the root view. Attempting to set a clip on view that has a transformation parent will fail. Assigning a parent to a view that has a clip set will cause the clip to be forgotten.

Because the clip mask is an axis-aligned rectangle, it poses restrictions on the additional transformations in the child views. These transformations may not rotate the coordinate axes, i.e., only translation and scaling are allowed. Violating this restriction causes the clipping to malfunction. Furthermore, using scaling may cause rounding errors in child clipping.

The clip mask rectangle is not automatically adjusted based on wl_surface.attach dx and dy arguments.

A clip mask rectangle can be set only if the compositor capability WESTON_CAP_VIEW_CLIP_MASK is present.

This function sets the clip mask rectangle and schedules a repaint for the view.

void weston_view_set_mask_infinite(struct weston_view * view)¶

Remove the clip mask from a view

Parameters:	view – The view to remove the clip mask from.

Removed the clip mask rectangle and schedules a repaint.

@sa weston_view_set_mask

int weston_view_is_mapped()¶

Check if view should be displayed

The indicator is set manually when assigning a view to a surface.

This needs reworking. See the thread starting at:

https://lists.freedesktop.org/archives/wayland-devel/2016-June/029656.html

int weston_view_is_opaque()¶

Check if view is opaque in specified region

Parameters:	view – The view to check for opacity. region – The region to check for opacity, in view coordinates.

Returns true if the view is opaque in the specified region, because view alpha is 1.0 and either the opaque region set by the client contains the specified region, or the buffer pixel format or solid color is opaque.

Initialize the weston_layer struct.

param compositor The compositor instance param layer The layer to initialize

Sets the position of the layer in the layer list. The layer will be placed below any layer with the same position value, if any. This function is safe to call if the layer is already on the list, but the layer may be moved below other layers at the same position, if any.

param layer The layer to modify param position The position the layer will be placed at

Hide a layer by taking it off the layer list. This function is safe to call if the layer is not on the list.

param layer The layer to hide

Compute a + b > c while being safe to overflows.

void weston_surface_get_content_size(struct weston_surface * surface, int * width, int * height)¶

Get the size of surface contents

Parameters:	surface – The surface to query. width – Returns the width of raw contents. height – Returns the height of raw contents.

Retrieves the raw surface content size in pixels for the given surface. This is the whole content size in buffer pixels. If the surface has no content or the renderer does not implement this feature, zeroes are returned.

This function is used to determine the buffer size needed for a weston_surface_copy_content() call.

struct weston_geometry weston_surface_get_bounding_box(struct weston_surface * surface)¶

Get the bounding box of a surface and its subsurfaces

Parameters:	surface – The surface to query.
Returns:	The bounding box relative to the surface origin.

int weston_surface_copy_content(struct weston_surface * surface, void * target, int size, int src_x, int src_y, int width, int height)¶

Copy surface contents to system memory.

Parameters:	surface – The surface to copy from. target – Pointer to the target memory buffer. size – Size of the target buffer in bytes. src_x – X location on contents to copy from. src_y – Y location on contents to copy from. width – Width in pixels of the area to copy. height – Height in pixels of the area to copy.
Returns:	0 for success, -1 for failure.

Surface contents are maintained by the renderer. They can be in a reserved weston_buffer or as a copy, e.g. a GL texture, or something else.

Surface contents are copied into memory pointed to by target, which has size bytes of space available. The target memory may be larger than needed, but being smaller returns an error. The extra bytes in target may or may not be written; their content is unspecified. Size must be large enough to hold the image.

The image in the target memory will be arranged in rows from top to bottom, and pixels on a row from left to right. The pixel format is PIXMAN_a8b8g8r8, 4 bytes per pixel, and stride is exactly width * 4.

Parameters src_x and src_y define the upper-left corner in buffer coordinates (pixels) to copy from. Parameters width and height define the size of the area to copy in pixels.

The rectangle defined by src_x, src_y, width, height must fit in the surface contents. Otherwise an error is returned.

Use weston_surface_get_content_size to determine the content size; the needed target buffer size and rectangle limits.

CURRENT IMPLEMENTATION RESTRICTIONS: - the machine must be little-endian due to Pixman formats.

NOTE: Pixman formats are premultiplied.

void weston_compositor_dpms(struct weston_compositor * compositor, enum dpms_enum state)¶

Set a DPMS mode on all of the compositor’s outputs

param compositor The compositor instance param state The DPMS state the outputs will be set to

Restores the compositor to active status

param compositor The compositor instance

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.

Turns off rendering and frame events for the compositor.

param compositor The compositor instance

This is used for example to prevent further rendering while the compositor is shutting down.

Stops the idle timer.

Powers down all attached output devices

param compositor The compositor instance

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.

int idle_handler(void * data)¶

Sets compositor to idle mode

param data The compositor instance

This is called when the idle timer fires. Once the compositor is in idle mode it requires a wake action (e.g. via weston_compositor_wake()) to restore it. The compositor’s idle_signal will be triggered when the idle event occurs.

Idleness can be inhibited by setting the compositor’s idle_inhibit property.

void weston_head_remove_global(struct weston_head * head)¶

Remove the global wl_output protocol object

param head The head whose global to remove.

Also orphans the wl_resources for this head (wl_output).

Get the backing object of wl_output

param resource A wl_output protocol object. return The backing object (user data) of a wl_resource representing a wl_output protocol object.

Initialize a pre-allocated weston_head

param head The head to initialize. param name The head name, e.g. the connector name or equivalent.

The head will be safe to attach, detach and release.

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

memberof weston_head internal

void weston_output_emit_heads_changed(struct weston_output * output)¶

Send output heads changed signal

param output The output that changed.

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.

void weston_compositor_call_heads_changed(void * data)¶: Idle task for emitting heads_changed_signal

void weston_compositor_schedule_heads_changed(struct weston_compositor * compositor)¶

Schedule a call on idle to heads_changed callback

Parameters:	compositor – The Compositor.

@memberof weston_compositor @internal

Register a new head

param compositor:
	The compositor.
param head:	The head to register, must not be already registered.

This signals the core that a new head has become available, leading to heads_changed hook being called later.

@memberof weston_compositor @internal

Adds a listener to be called when heads change

param compositor The compositor. param listener The listener to add.

The listener notify function argument is the var 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.

sa weston_compositor_iterate_heads, weston_head_is_connected, weston_head_is_enabled memberof weston_compositor

Iterate over available heads

param compositor:
	The compositor.
param item:	The iterator, or NULL for start.
return:	The next available head in the list.

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 @c iter to be removed from the list, you cannot use it to

continue iterating. Removing any other item is safe.

@memberof weston_compositor

Iterate over attached heads

param output The output whose heads to iterate. param item The iterator, or NULL for start. return The next attached head in the list.

Returns all heads currently attached to the output.

You can iterate over all heads as follows: code struct weston_head *head = NULL;

while ((head = weston_output_iterate_heads(output, head))) {: …

} endcode

If you cause c iter to be removed from the list, you cannot use it to

continue iterating. Removing any other item is safe.

memberof weston_compositor

Attach a head to an output

param output The output to attach to. param head The head that is not yet attached. return 0 on success, -1 on failure.

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.

memberof weston_output

Detach a head from its output

param head The head to detach.

It is safe to detach a non-attached head.

If the head is attached to an enabled output and the output will be left with no heads, the output will be disabled.

memberof weston_head sa weston_output_disable

void weston_head_set_device_changed(struct weston_head * head)¶

Destroy a head

param head The head to be released.

Destroys the head. The caller is responsible for freeing the memory pointed to by c head.

memberof weston_head internal

int str_null_eq()¶: String equal comparison with NULLs being equal

Store monitor make, model and serial number

param head The head to modify. param make The monitor make. If EDID is available, the PNP ID. Otherwise any string, or NULL for none. param model The monitor model or name, or a made-up string, or NULL for none. param serialno The monitor serial number, a made-up string, or NULL for none.

This may set the device_changed flag.

memberof weston_head internal

Store display non-desktop status

param head The head to modify. param non_desktop Whether the head connects to a non-desktop display.

memberof weston_head internal

Store physical image size

param head The head to modify. param mm_width Image area width in millimeters. param mm_height Image area height in millimeters.

This may set the device_changed flag.

memberof weston_head internal

Store monitor sub-pixel layout

param head The head to modify. param sp Sub-pixel layout. The possible values are: - WL_OUTPUT_SUBPIXEL_UNKNOWN, - WL_OUTPUT_SUBPIXEL_NONE, - WL_OUTPUT_SUBPIXEL_HORIZONTAL_RGB, - WL_OUTPUT_SUBPIXEL_HORIZONTAL_BGR, - WL_OUTPUT_SUBPIXEL_VERTICAL_RGB, - WL_OUTPUT_SUBPIXEL_VERTICAL_BGR

This may set the device_changed flag.

memberof weston_head internal

Mark the monitor as internal

This is used for embedded screens, like laptop panels.

param head The head to mark as internal.

By default a head is external. The type is often inferred from the physical connector type.

memberof weston_head internal

void weston_head_set_connection_status(struct weston_head * head, int connected)¶

Store connector status

Parameters:	head – The head to modify. connected – Whether the head is connected.

Connectors are created as disconnected. This function can be used to set the connector status.

The status should be set to true when a physical connector is connected to a video sink device like a monitor and to false when the connector is disconnected. For nested backends, the connection status should reflect the connection to the parent display server.

When the connection status changes, it schedules a call to the heads_changed hook and sets the device_changed flag.

@sa weston_compositor_set_heads_changed_cb @memberof weston_head @internal

int weston_head_is_connected()¶

Is the head currently connected?

Parameters:	head – The head to query.
Returns:	Connection status.

Returns true if the head is physically connected to a monitor, or in case of a nested backend returns true when there is a connection to the parent display server.

This is independent from the head being enabled.

sa weston_head_is_enabled memberof weston_head

int weston_head_is_enabled()¶

Is the head currently enabled?

Parameters:	head – The head to query.
Returns:	Video status.

Returns true if the head is currently transmitting a video stream.

This is independent of the head being connected.

sa weston_head_is_connected memberof weston_head

int weston_head_is_device_changed()¶

Has the device information changed?

Parameters:	head – The head to query.
Returns:	True if the device information has changed since last reset.

The information about the connected display device, e.g. a monitor, may change without being disconnected in between. Changing information causes a call to the heads_changed hook.

The information includes make, model, serial number, physical size, and sub-pixel type. The connection status is also included.

sa weston_head_reset_device_changed, weston_compositor_set_heads_changed_cb memberof weston_head

int weston_head_is_non_desktop()¶

Does the head represent a non-desktop display?

Parameters:	head – The head to query.
Returns:	True if the device is a non-desktop display.

Non-desktop heads are not attached to outputs by default. This stops weston from extending the desktop onto head mounted displays.

@memberof weston_head

void weston_head_reset_device_changed(struct weston_head * head)¶

Acknowledge device information change

Parameters:	head – The head to acknowledge.

Clears the device changed flag on this head. When a compositor has processed device information, it should call this to be able to notice further changes.

@sa weston_head_is_device_changed @memberof weston_head

const char * weston_head_get_name(struct weston_head * head)¶

Get the name of a head

Parameters:	head – The head to query.
Returns:	The head’s name, not NULL.

The name depends on the backend. The DRM backend uses connector names, other backends may use hardcoded names or user-given names.

struct weston_output * weston_head_get_output(struct weston_head * head)¶

Get the output the head is attached to

Parameters:	head – The head to query.
Returns:	The output the head is attached to, or NULL if detached.

void weston_head_add_destroy_listener(struct weston_head * head, struct wl_listener * listener)¶

Add destroy callback for a head

Parameters:	head – The head to watch for. listener – The listener to add. The c notify member must be set.

Heads may get destroyed for various reasons by the backends. If a head is attached to an output, the compositor should listen for head destruction and reconfigure or destroy the output if necessary.

The destroy callbacks will be called on weston_head destruction before any automatic detaching from an associated weston_output and before any weston_head information is lost.

The c data argument to the notify callback is the weston_head being destroyed.

struct wl_listener * weston_head_get_destroy_listener(struct weston_head * head, int notify)¶

Look up destroy listener for a head

Parameters:	head – The head to query. notify – The notify function used used for the added destroy listener.
Returns:	The listener, or NULL if not found.

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 c container_of().

@sa wl_signal_get()

void weston_compositor_reflow_outputs(struct weston_compositor * compositor, struct weston_output * resized_output, int delta_width)¶: Move other outputs when one is resized so the space remains contiguous.

void weston_compositor_add_output(struct weston_compositor * compositor, struct weston_output * output)¶

Signal that a pending output is taken into use.

Removes the output from the pending list and adds it to the compositor’s list of enabled outputs. The output created signal is emitted.

The output gets an internal ID assigned, and the wl_output global is created.

param compositor The compositor instance. param output The output to be added.

internal

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

@param device_x[in] X coordinate in device units. @param device_y[in] Y coordinate in device units. @param x[out] X coordinate in the global space. @param y[out] Y coordinate in the global space.

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.

@memberof weston_output @internal

void weston_compositor_remove_output(struct weston_output * output)¶

Removes output from compositor’s list of enabled outputs

Parameters:	output – The weston_output object that is being removed.

The following happens:

The output assignments of all views in the current scenegraph are recomputed.
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.

@memberof weston_output @internal

void weston_output_set_scale(struct weston_output * output, int 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.

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

@memberof weston_output

void weston_output_set_transform(struct weston_output * output, int transform)¶

Sets the output transform for a given output.

Parameters:	output – The weston_output object that the transform is set for. transform – Transform value for the 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.

@memberof 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.

Parameters:	output – The weston_output object to initialize compositor – The compositor instance. name – Name for the output (the string is copied).

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.

@memberof weston_output @internal

Adds weston_output object to pending output list.

param output The weston_output object to add param compositor The compositor instance.

The opposite of this operation is built into weston_output_release().

memberof weston_output internal

char * weston_output_create_heads_string(struct weston_output * output)¶

Create a string with the attached heads’ names.

The string must be free()’d.

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

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

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

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.

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

param output The weston_output object that needs to be disabled.

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.

Forces a synchronous call to heads_changed hook

param compositor The compositor instance

If there are new or changed heads, calls the heads_changed hook and returns after the hook returns.

Add destroy callback for an output

param output The output to watch. param listener The listener to add. The c notify member must be set.

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

Look up destroy listener for an output

param output The output to query. param notify The notify function used used for the added destroy listener. return The listener, or NULL if not found.

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 c container_of().

sa wl_signal_get() weston_output_add_destroy_listener()

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.

memberof weston_output internal

Find an output by its given name

param compositor The compositor to search in. param name The output name to search for. return An existing output with the given name, or NULL if not found.

memberof weston_compositor

Create a named output

param compositor The compositor. param name The name for the output. return A new c weston_output, or NULL on failure.

This creates a new weston_output that starts with no heads attached.

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

memberof weston_compositor

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

Create an output for an unused head

Parameters:	compositor – The compositor. head – The head to attach to the output.
Returns:	A new `weston_output`, or NULL on failure.

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.

An output must be configured before it can be enabled.

@memberof weston_compositor

Destroy an output

param output The output to destroy.

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.

memberof weston_output

void destroy_viewport(struct wl_resource * resource)¶

When you need a head…

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

param output The weston_output whose head to get. return The first head in the output’s list.

Output information on how libweston is currently composing the scene graph.

void debug_scene_graph_cb(struct weston_debug_stream * stream, void * data)¶: Called when the ‘scene-graph’ debug scope is bound by a client. This one-shot weston-debug scope prints the current scene graph when bound, and then terminates the stream.

struct weston_compositor * weston_compositor_create(struct wl_display * display, void * user_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

using the weston_compositor_get_user_data() function.

Returns:	The compositor instance on success or NULL on failure.

Read the current time from the Presentation clock

param compositor param ts[out] The current time.

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

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.

int weston_compositor_import_dmabuf()¶

Import dmabuf buffer into current renderer

@param compositor

Parameters:	buffer – the dmabuf buffer to import
Returns:	true on usable buffers, false otherwise

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.

int weston_module_path_from_env()¶

Attempts to find a module path from the module map specified in the environment. If found, writes the full path into the path variable.

The module map is a string in environment variable WESTON_MODULE_MAP, where each entry is of the form “name=path” and entries are separated by semicolons. Whitespace is significant.

Parameters:	name – The name to search for. path – Where the path is written to if found. path_len – Allocated bytes at c path .
Returns:	The length of the string written to path on success, or 0 if the

module was not specified in the environment map or path_len was too small.

Destroys the compositor.

This function cleans up the compositor state and destroys it.

param compositor The compositor to be destroyed.

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.

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

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:	0 on success, or -1 on error.

void weston_buffer_send_server_error(struct weston_buffer * buffer, const char * msg)¶

Resolve an internal compositor error by disconnecting the client.

This function is used in cases when the wl_buffer turns out unusable and there is no fallback path.

It is possible the fault is caused by a compositor bug, the underlying graphics stack bug or normal behaviour, or perhaps a client mistake. In any case, the options are to either composite garbage or nothing, or disconnect the client. This is a helper function for the latter.

The error is sent as an INVALID_OBJECT error on the client’s wl_display.

Parameters:	buffer – The weston buffer that is unusable. msg – A custom error message attached to the protocol error.

Windowed API¶

This is from windowed-output-api.h

struct weston_windowed_output_api¶

window output api

int (*)(struct weston_output *, int, int) output_set_size

Assign a given width and height to an output.

param output An output to be configured. param width Desired width of the output. param height Desired height of the output.

Returns 0 on success, -1 on failure.

This assigns a desired width and height to a windowed output. The backend decides what should be done and applies the desired configuration. After using this function and generic weston_output_set_*, a windowed output should be in a state where weston_output_enable() can be run.

int (*)(struct weston_compositor *, const char *) create_head

Create a new windowed head.

param compositor The compositor instance. param name Desired name for a new head, not NULL.

Returns 0 on success, -1 on failure.

This creates a new head in the backend. The new head will be advertised in the compositor’s head list and triggers a head_changed callback.

A new output can be created for the head. The output must be configured with output_set_size() and weston_output_set_{scale,transform}() before enabling it.

weston_compositor_set_heads_changed_cb(), weston_compositor_create_output_with_head().

Cross-Reference¶

Some example for cross-ref if… weston_touch_create_touch_device()