Head¶

A head usually refers to a monitor, but it can also refer to an output window in case of a nested compositor. A weston_output is responsible for driving a weston_head. weston_head should be initialized using weston_head_init(), and shall be released using weston_head_release().

Note

weston_head_init() and weston_head_release() belong to the private/internal backend API and should be moved accordingly once that section has been created.

A weston_head must be attached/detached from a weston_output. To that purpose you can use weston_output_attach_head(), respectively weston_head_detach().

Head API¶

struct weston_head *weston_head_from_resource(struct wl_resource *resource)¶

Get the backing object of wl_output.

Return

The backing object (user data) of a wl_resource representing a wl_output protocol object.

Parameters

resource: A wl_output protocol object.

void weston_head_init(struct weston_head *head, const char *name)¶

Initialize a pre-allocated weston_head.

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

Parameters

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

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

void weston_head_detach(struct weston_head *head)¶

Detach a head from its output.

It is safe to detach a non-attached head.

Parameters

head: The head to detach.

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

See: weston_output_disable

void weston_head_release(struct weston_head *head)¶

Destroy a head.

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

head.

Parameters

head: The head to be released.

void weston_head_set_monitor_strings(struct weston_head *head, const char *make, const char *model, const char *serialno)¶

Store monitor make, model and serial number.

This may set the device_changed flag.

Parameters

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

void weston_head_set_non_desktop(struct weston_head *head, bool non_desktop)¶

Store display non-desktop status.

Parameters

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

void weston_head_set_physical_size(struct weston_head *head, int32_t mm_width, int32_t mm_height)¶

Store physical image size.

This may set the device_changed flag.

Parameters

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

void weston_head_set_subpixel(struct weston_head *head, enum wl_output_subpixel sp)¶

Store monitor sub-pixel layout.

This may set the device_changed flag.

Parameters

head: The head to modify.
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

void weston_head_set_internal(struct weston_head *head)¶

Mark the monitor as internal.

This is used for embedded screens, like laptop panels.

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

Parameters

head: The head to mark as internal.

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

Store connector status.

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

Parameters

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

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.

See: weston_compositor_set_heads_changed_cb

bool weston_head_is_connected(struct weston_head *head)¶

Is the head currently connected?

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.

Return

Connection status.

Parameters

head: The head to query.

This is independent from the head being enabled.

See: weston_head_is_enabled

bool weston_head_is_enabled(struct weston_head *head)¶

Is the head currently enabled?

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

Return

Video status.

Parameters

head: The head to query.

This is independent of the head being connected.

See: weston_head_is_connected

bool weston_head_is_device_changed(struct weston_head *head)¶

Has the device information changed?

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.

Return

True if the device information has changed since last reset.

Parameters

head: The head to query.

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

See: weston_head_reset_device_changed, weston_compositor_set_heads_changed_cb

bool weston_head_is_non_desktop(struct weston_head *head)¶

Does the head represent 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.

Return

True if the device is a non-desktop display.

Parameters

head: The head to query.

void weston_head_reset_device_changed(struct weston_head *head)¶

Acknowledge device information change.

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.

Parameters

head: The head to acknowledge.

See: weston_head_is_device_changed

const char *weston_head_get_name(struct weston_head *head)¶

Get the name of a head.

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

Return

The head’s name, not NULL.

Parameters

head: The head to query.

struct weston_output *weston_head_get_output(struct weston_head *head)¶

Get the output the head is attached to.

Return

The output the head is attached to, or NULL if detached.

Parameters

head: The head to query.

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

Add destroy callback for a head.

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.

Parameters

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

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 data argument to the notify callback is the weston_head being destroyed.

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

Look up destroy listener for a head.

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

head: The head to query.
notify: The notify function used used for the added destroy listener.

See: wl_signal_get()

struct weston_head¶

#include <libweston.h>

Represents a monitor.

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

Public Members

struct weston_compositor *compositor¶: owning compositor

struct wl_list compositor_link¶: in weston_compositor::head_list

struct wl_signal destroy_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 *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

bool connection_internal¶

embedded monitor (e.g.

laptop)

bool device_changed¶: monitor information has changed

char *name¶

head name, e.g.

connector name

bool connected¶: is physically connected

bool non_desktop¶

non-desktop display, e.g.

HMD