Heads

A head is represented by a weston_head object.

A head refers to a monitor when driving hardware, but it can also be a window in another window system, or a virtual concept. Essentially a head is a place where you could present an image. The image will be produced by a weston_output where the head is attached to.

In display hardware, a head represents a display connector in a computer system, not the actual monitor connected to the connector. A head carries monitor information, if present, like make and model, EDID and possible video modes. Other properties are DPMS mode and backlight control.

In terms of Wayland protocol, a head corresponds to a wl_output. If one weston_output has several heads, meaning that the heads are cloned, each head is represented as a separate wl_output global in wl_registry. Only the heads of an enabled output are exposed as wl_outputs.

Heads can appear and disappear dynamically, mainly because of DisplayPort Multi-Stream Transport where connecting a new monitor may expose new connectors. Window and virtual outputs are often dynamic as well.

Heads are always owned by libweston which dictates their lifetimes. Some backends may offer specific API to create and destroy heads, but hardware backends like DRM-backend create and destroy heads on their own.

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. There are many other functions as well that are intended only for backends.

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

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 head, usually a display connector.

See Heads.

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

struct wl_list xdg_output_resource_list

xdg_output protocol objects

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

weston_hdcp_protection current_protection

Current content protection status.