the current activate one, with each output having independently active
surfaces.
-#### Explicit output
+## Explicit output
The activation and setting surface roles requires passing a Wayland output
(wl_output). The output is the wayland interface representation of an output
is the one recommended way and provides a mapping between a human
representation of the output and the wayland one.
+One can also choose the output where the application can start, by configuring
+directly the AGL compositor. Under the `[output]` section one can use
+`agl-shell-app-id=appid` restart the AGL compositor unitd systemd service and
+start the application. Currently this *only* applies to regular applications, the
+client shell having to handle it in the code.
+
## Available toolkits, application conversions and available eco-systems
Users and OEM vendors alike have the possibility, depending on their use-cases,
weston, the AGL compositor loads up the remoting-plugin to achieve the same
thing.
+The remoting-plugin uses the DRM virtual output API from libweston together
+with gstreamer pipeline to capture, using DMA buffers, the DRM output and to
+stream it, remotely to another machine. They can be over the network, or
+locally.
+
Further more, to cope with situations where the output is just a
panel/display, without some kind of compositor driving it, the necessity of
handling input events is an important feature to have, giving the user to
* `hide-cursor=[false]` - do not advertise pointer/cursor to clients. Present
in the `[core]` section.
-### Running with software rendering
+## Running with software rendering
By default the compositor will attempt to use the GL-renderer, and implicitly
the GPU. One could instead use the CPU, by making use of the Pixman library. To
actually use the GL library and perform the operations in software, while the
former does not use any GL whatsover. All back-ends support disabling the
GL-render to make sure it does not interfere with the composing process.
+
+## Multiple output set-up and touch input devices
+
+There's no deterministic way in which the compositor enables the outputs and
+depending on the input devices, specifically touch input devices, and the way
+the connectors are wired, a touch input device might be associated with a
+different output than the one intended.
+
+A consistent way, that survives a reboot, is to use
+[udev rules](https://man7.org/linux/man-pages/man7/udev.7.html), which
+libweston would be able to use such that a particular output is tied/associated
+to a particular touch input device.
+
+For instance, assuming that you have a set-up consisting of 4 outputs, a 4
+touch input devices, when the outputs are being enabled the compositor
+front-end will associate all 4 touch input device -- if they haven't been
+previously being associated to a particular output, to the first enabled
+output.
+
+In order to avoid that, and associate each touch input device to
+their respective output an udev rule can be installed, for the default
+seat (named `seat0`).
+
+Example of a udev rule:
+
+```
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004a", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-1"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004b", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-2"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004c", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-3"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-4"
+```
+
+Add the following under `/etc/udev/rules.d/91-output.rules` and reload udev
+rules for these changes to take effect:
+
+ $ udevadm control --reload-rules && udevadm trigger
+
+Note that in the above example, we use physical seat, named `seat0` which is
+the default physical seat. You can verify that these changes have been applied by
+checking the compositor logs (under `/run/platform/display/compositor.log` file)
+You should be seeing `CONNECTOR-NO by udev` message like the following:
+
+```
+associating input device event0 with output HDMI-A-1 (HDMI-A-1 by udev)
+```
+
+vs
+
+```
+associating input device event0 with output HDMI-A-2 (none by udev)
+```
+
+where the rules are either incorrect or badly written.
+
+Retrieving device attributes could be done archaically using `lsusb` or `lspci`
+or using `udevadm info -a /dev/input/event*` which can provide with a multitude
+of attributes to use. In our above example we only relied `idVendor` and
+`idProduct` but potentially other attributes might be used.
Code Review / AGL / documentation.git / blobdiff