You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
104 lines
4.2 KiB
104 lines
4.2 KiB
Output management
|
|
=================
|
|
|
|
Libweston output API revolves around two main concepts: :type:`weston_head` and
|
|
:type:`weston_output`. A head represents a connector or a monitor (a sink)
|
|
while an output represents the compositing state machine that produces content
|
|
(a source) to be presented on a head. If a backend allows it, it is possible to
|
|
attach more than one head to an output, in which case all those heads will have
|
|
identical timings and contents (they share framebuffers if applicable).
|
|
|
|
Heads are created and destroyed automatically by libweston according to e.g.
|
|
hardware features like the existence of physical connectors. Creation, hotplug
|
|
events and other changes to heads are notified with
|
|
:func:`weston_compositor_add_heads_changed_listener`. Head destruction is
|
|
communicated via :func:`weston_head_add_destroy_listener`. Note that
|
|
disconnecting a connector does not mean the head is destroyed. A head is
|
|
destroyed when the connector itself disappears.
|
|
|
|
Some backends, mainly virtual and nested ones, may offer backend-specific API
|
|
to create and destroy heads at will. In these cases a head does not represent
|
|
anything physical but can be e.g. a window in another window system.
|
|
|
|
Outputs are explicitly created and destroyed by the libweston user at will. To
|
|
make a new output or to light up a head, you create an output, attach the
|
|
head(s) to it, configure it, and finally :func:`weston_output_enable` it to
|
|
make it live.
|
|
|
|
An enabled output cannot be reconfigured, but this is intended to change in the
|
|
future. You can use :func:`weston_output_disable` to disable an output and then
|
|
reconfigure it, but this will cause visible glitches.
|
|
|
|
.. toctree::
|
|
:caption: API
|
|
|
|
head.rst
|
|
output.rst
|
|
|
|
The following sequence diagrams show the function calls for various actions.
|
|
:numref:`libweston-initial-heads` shows how DRM-backend creates and configures
|
|
heads on compositor start-up.
|
|
:numref:`libweston-react-to-heads-changed` shows the principle of a compositor
|
|
reacting to initial heads discovered and hotplug events.
|
|
|
|
When a compositor wants to light up a monitor, it creates an output as in
|
|
:numref:`libweston-create-output`. Attaching more than one head to an output
|
|
requires specific hardware support in the case of DRM-backend. Other backends
|
|
are unlikely to support multiple heads per output.
|
|
|
|
A connector becoming disconnected is a common reason to destroy an output.
|
|
This happens in :numref:`libweston-destroy-output`.
|
|
|
|
Heads can also disappear. This is not due to normal monitor unplug but refers
|
|
to the connector itself disappearing. This is particularly possible with
|
|
DisplayPort Multi-Stream Transport, where unplugging a monitor will literally
|
|
remove a connector from the system as that connector was provided by the
|
|
monitor for daisy-chaining. One scenario of handling that is presented in
|
|
:numref:`libweston-head-destroyed`.
|
|
|
|
|
|
.. _libweston-initial-heads:
|
|
|
|
.. figure:: images/initial-heads.png
|
|
:alt: Sequence diagram of creating heads initially.
|
|
|
|
Heads are being created on compositor start-up with a backend that manages
|
|
head lifetimes completely on its own, e.g. DRM-backend.
|
|
|
|
|
|
.. _libweston-react-to-heads-changed:
|
|
|
|
.. figure:: images/react-to-heads-changed.png
|
|
:alt: Sequence diagram of reacting to head changes.
|
|
|
|
A compositor handles libweston notification of something with heads having
|
|
changed. This happens on both compositor start-up and later due to hotplug.
|
|
|
|
|
|
.. _libweston-create-output:
|
|
|
|
.. figure:: images/create_output.png
|
|
:alt: Sequence diagram for creating an output.
|
|
|
|
A compositor creates and configures an output for a head or heads it wants
|
|
to light up.
|
|
|
|
|
|
.. _libweston-destroy-output:
|
|
|
|
.. figure:: images/destroy-output.png
|
|
:alt: Sequence diagram of compositor destroying an output.
|
|
|
|
A compositor finds out a head has been disconnected and proceeds to
|
|
destroy the corresponding output.
|
|
|
|
|
|
.. _libweston-head-destroyed:
|
|
|
|
.. figure:: images/head-destroyed.png
|
|
:alt: Sequence diagram of a head being destroyed.
|
|
|
|
The backend realises that a piece of hardware has disappeared and needs to
|
|
destroy the corresponding head. The head is released, and even when the
|
|
compositor is not listening for head destroy signal, the output gets
|
|
automatically disabled, though not destroyed.
|
|
|