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

  Parameters:

    resource – A wl_output protocol object.

  Returns:

    The backing object (user data) of a wl_resource representing 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.

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

  Parameters:

    - head – The head to initialize.

    - name – The head name, e.g. the connector name or equivalent.

void weston_head_detach(struct weston_head *head)

  Detach a head from its output.

  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.

  See also

  weston_output_disable

  Parameters:

    head – The head to detach.

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_device_changed(struct weston_head *head)

  Propagate device information changes.

  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.

  Normally this is handled automatically by the generic setters, but if a backend has specific head properties it may have to call this directly.

  See also

  weston_head_reset_device_changed, weston_compositor_set_heads_changed_cb, weston_head_is_device_changed

  Parameters:

    head – The head that changed.

bool 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 “unknown”.

    - model – The monitor model or name, or a made-up string, or NULL for “unknown”.

    - serialno – The monitor serial number, a made-up string, or NULL for none.

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

bool weston_head_set_transform(struct weston_head *head, uint32_t transform)

  Store display transformation.

  This may set the device_changed flag.

  Parameters:

    - head – The head to modify.

    - transform – The transformation to apply for this head

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

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

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

  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 also

  weston_compositor_set_heads_changed_cb

  Parameters:

    - head – The head to modify.

    - connected – Whether the head is connected.

void weston_head_set_supported_eotf_mask(struct weston_head *head, uint32_t eotf_mask)

  Store the set of supported EOTF modes.

  This may set the device_changed flag.

  Parameters:

    - head – The head to modify.

    - eotf_mask – A bit mask with the possible bits or’ed together from enum weston_eotf_mode.

void weston_head_set_supported_colorimetry_mask(struct weston_head *head, uint32_t colorimetry_mask)

  Store the set of supported colorimetry modes.

  This may set the device_changed flag.

  Parameters:

    - head – The head to modify.

    - colorimetry_mask – A bit mask with the possible bits or’ed together from enum weston_colorimetry_mode.

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.

  This is independent from the head being enabled.

  See also

  weston_head_is_enabled

  Parameters:

    head – The head to query.

  Returns:

    Connection status.

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.

  This is independent of the head being connected.

  See also

  weston_head_is_connected

  Parameters:

    head – The head to query.

  Returns:

    Video status.

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.

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

  See also

  weston_head_reset_device_changed, weston_compositor_set_heads_changed_cb

  Parameters:

    head – The head to query.

  Returns:

    True if the device information has changed since last reset.

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.

  Parameters:

    head – The head to query.

  Returns:

    True if the device is a non-desktop display.

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.

  See also

  weston_head_is_device_changed

  Parameters:

    head – The head to acknowledge.

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.

  Parameters:

    head – The head to query.

  Returns:

    The head’s name, not NULL.

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.

uint32_t weston_head_get_transform(struct weston_head *head)

  Get the head’s native transformation.

  A weston_head may have a ‘native’ transform provided by the backend. Examples include panels which are physically rotated, where the rotation is recorded and described as part of the system configuration. This call will return any known native transform for the head.

  Parameters:

    head – The head to query.

  Returns:

    The head’s native transform, as a WL_OUTPUT_TRANSFORM_* value

const struct di_info *weston_head_get_display_info(const struct weston_head *head)

  Get display information (EDID, DisplayID).

  Hardware heads (monitors, TVs, etc.) driven directly by this compositor may provide EDID or DisplayID information. If a backend has that information, it may expose it as a libdisplay-info structure. The caller needs to use libdisplay-info to extract information from the returned pointer.

  Parameters:

    head – The head to query.

  Returns:

    libdisplay-info structure, or NULL.

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.

  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.

  Parameters:

    - head – The head to watch for.

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

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

  See also

  wl_signal_get()

  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.

struct weston_head
  #include <libweston.h>

  Represents a head, usually a display connector.

  See Heads.

  Public Members

  struct weston_compositor *compositor

    owning compositor

  struct weston_backend *backend

    owning backend

  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

  uint32_t transform

    WL_OUTPUT_TRANSFORM enum to apply to match native orientation.

  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

  uint32_t supported_eotf_mask

    supported weston_eotf_mode bits

  uint32_t supported_colorimetry_mask

    supported weston_colorimetry_mode bits

  struct di_info *display_info

    libdisplay-info, from DRM

  enum weston_hdcp_protection current_protection

    Current content protection status.

  struct wl_list cm_output_resource_list
  uint32_t supported_vrr_mode_mask
  uint32_t supported_color_format_mask