1Output management 2================= 3 4Libweston output API revolves around two main concepts: :type:`weston_head` and 5:type:`weston_output`. A head represents a connector or a monitor (a sink) 6while an output represents the compositing state machine that produces content 7(a source) to be presented on a head. If a backend allows it, it is possible to 8attach more than one head to an output, in which case all those heads will have 9identical timings and contents (they share framebuffers if applicable). 10 11Heads are created and destroyed automatically by libweston according to e.g. 12hardware features like the existence of physical connectors. Creation, hotplug 13events and other changes to heads are notified with 14:func:`weston_compositor_add_heads_changed_listener`. Head destruction is 15communicated via :func:`weston_head_add_destroy_listener`. Note that 16disconnecting a connector does not mean the head is destroyed. A head is 17destroyed when the connector itself disappears. 18 19Some backends, mainly virtual and nested ones, may offer backend-specific API 20to create and destroy heads at will. In these cases a head does not represent 21anything physical but can be e.g. a window in another window system. 22 23Outputs are explicitly created and destroyed by the libweston user at will. To 24make a new output or to light up a head, you create an output, attach the 25head(s) to it, configure it, and finally :func:`weston_output_enable` it to 26make it live. 27 28An enabled output cannot be reconfigured, but this is intended to change in the 29future. You can use :func:`weston_output_disable` to disable an output and then 30reconfigure it, but this will cause visible glitches. 31 32.. toctree:: 33 :caption: API 34 35 head.rst 36 output.rst 37 38The following sequence diagrams show the function calls for various actions. 39:numref:`libweston-initial-heads` shows how DRM-backend creates and configures 40heads on compositor start-up. 41:numref:`libweston-react-to-heads-changed` shows the principle of a compositor 42reacting to initial heads discovered and hotplug events. 43 44When a compositor wants to light up a monitor, it creates an output as in 45:numref:`libweston-create-output`. Attaching more than one head to an output 46requires specific hardware support in the case of DRM-backend. Other backends 47are unlikely to support multiple heads per output. 48 49A connector becoming disconnected is a common reason to destroy an output. 50This happens in :numref:`libweston-destroy-output`. 51 52Heads can also disappear. This is not due to normal monitor unplug but refers 53to the connector itself disappearing. This is particularly possible with 54DisplayPort Multi-Stream Transport, where unplugging a monitor will literally 55remove a connector from the system as that connector was provided by the 56monitor for daisy-chaining. One scenario of handling that is presented in 57:numref:`libweston-head-destroyed`. 58 59 60.. _libweston-initial-heads: 61 62.. figure:: images/initial-heads.png 63 :alt: Sequence diagram of creating heads initially. 64 65 Heads are being created on compositor start-up with a backend that manages 66 head lifetimes completely on its own, e.g. DRM-backend. 67 68 69.. _libweston-react-to-heads-changed: 70 71.. figure:: images/react-to-heads-changed.png 72 :alt: Sequence diagram of reacting to head changes. 73 74 A compositor handles libweston notification of something with heads having 75 changed. This happens on both compositor start-up and later due to hotplug. 76 77 78.. _libweston-create-output: 79 80.. figure:: images/create_output.png 81 :alt: Sequence diagram for creating an output. 82 83 A compositor creates and configures an output for a head or heads it wants 84 to light up. 85 86 87.. _libweston-destroy-output: 88 89.. figure:: images/destroy-output.png 90 :alt: Sequence diagram of compositor destroying an output. 91 92 A compositor finds out a head has been disconnected and proceeds to 93 destroy the corresponding output. 94 95 96.. _libweston-head-destroyed: 97 98.. figure:: images/head-destroyed.png 99 :alt: Sequence diagram of a head being destroyed. 100 101 The backend realises that a piece of hardware has disappeared and needs to 102 destroy the corresponding head. The head is released, and even when the 103 compositor is not listening for head destroy signal, the output gets 104 automatically disabled, though not destroyed. 105
