• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. _libweston-head:
2
3Heads
4=====
5
6A head is represented by a :type:`weston_head` object.
7
8A head refers to a monitor when driving hardware, but it can also be a window
9in another window system, or a virtual concept. Essentially a head is a place
10where you could present an image. The image will be produced by a weston_output
11where the head is attached to.
12
13In display hardware, a head represents a display connector in a computer
14system, not the actual monitor connected to the connector. A head carries
15monitor information, if present, like make and model, EDID and possible video
16modes. Other properties are DPMS mode and backlight control.
17
18In terms of Wayland protocol, a head corresponds to a wl_output. If one
19:type:`weston_output` has several heads, meaning that the heads are cloned,
20each head is represented as a separate wl_output global in wl_registry. Only
21the heads of an enabled output are exposed as wl_outputs.
22
23Heads can appear and disappear dynamically, mainly because of DisplayPort
24Multi-Stream Transport where connecting a new monitor may expose new
25connectors. Window and virtual outputs are often dynamic as well.
26
27Heads are always owned by libweston which dictates their lifetimes. Some
28backends may offer specific API to create and destroy heads, but hardware
29backends like DRM-backend create and destroy heads on their own.
30
31.. note::
32
33   :func:`weston_head_init` and :func:`weston_head_release` belong to the
34   private/internal backend API and should be moved accordingly once that
35   section has been created. There are many other functions as well that are
36   intended only for backends.
37
38A :type:`weston_head` must be attached/detached from a :type:`weston_output`.
39To that purpose you can use :func:`weston_output_attach_head`, respectively
40:func:`weston_head_detach`.
41
42
43.. doxygengroup:: head
44   :content-only:
45