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