The README for the IVI-shell is completely outdated. Update the documentation, add some more information on the IVI-shell use cases and explain how to use and customize the IVI-shell. Also convert the file to rst and move it to doc directory next to the kiosk-shell documentation. Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>dev
parent
7d16485efd
commit
a2684005b6
After Width: | Height: | Size: 108 KiB |
@ -0,0 +1,9 @@ |
|||||||
|
# Sphinx does not know look for these files in the source directory, so |
||||||
|
# they must be copied to the build directory. |
||||||
|
files = [ |
||||||
|
'ivi-shell.png', |
||||||
|
] |
||||||
|
|
||||||
|
foreach file : files |
||||||
|
configure_file(input: file, output: file, copy: true) |
||||||
|
endforeach |
@ -0,0 +1,111 @@ |
|||||||
|
Weston IVI-shell |
||||||
|
================ |
||||||
|
|
||||||
|
Weston's IVI-shell is a highly customizable shell targeted at use cases which |
||||||
|
need custom control over the shell's window layout with one or more applications |
||||||
|
without interactive configuration of the layout by the user. |
||||||
|
|
||||||
|
Example use cases for the IVI-shell are IVI applications or industrial human |
||||||
|
machine interfaces. In general, whenever the user interface requires the exact |
||||||
|
positioning of multiple application surfaces on one or more screens. |
||||||
|
|
||||||
|
The IVI-shell also provides a means for applications to identify themselves to |
||||||
|
the shell by application IDs via the ivi_application Wayland protocol. |
||||||
|
|
||||||
|
IVI-shell client protocol |
||||||
|
------------------------- |
||||||
|
|
||||||
|
Wayland clients can implement the ``ivi_application`` Wayland protocol, which |
||||||
|
allows them to specify an ``ivi_id`` to allow the IVI controller to identify the |
||||||
|
application. This allows the controller to implement special behavior for |
||||||
|
well-known applications. |
||||||
|
|
||||||
|
The IVI-shell is able to also handle clients that use the ``xdg-shell`` |
||||||
|
protocol, but in these cases the IVI-shell needs other means to identify client |
||||||
|
applications. |
||||||
|
|
||||||
|
See ``ivi-application.xml`` for the protocol specification. |
||||||
|
|
||||||
|
IVI-shell Weston modules |
||||||
|
------------------------ |
||||||
|
|
||||||
|
The IVI-shell consists of two main components: The ``ivi-shell.so`` and custom |
||||||
|
IVI controller (with the ``hmi-controller.so`` example implementation). |
||||||
|
|
||||||
|
The ``ivi-shell.so`` is responsible for handling the application IDs and for |
||||||
|
providing abstractions to configure the window layout via the |
||||||
|
``ivi_layout_interface``. This interface is discussed in `IVI-shell compositor |
||||||
|
implementation`. |
||||||
|
|
||||||
|
The IVI controller uses the ``ivi_layout_interface`` to implement a window |
||||||
|
manager and is responsible for configuring the window layout, i.e. the position |
||||||
|
of the applications on the screens. |
||||||
|
|
||||||
|
Due to this separation, both modules must be loaded in your ``weston.ini`` to |
||||||
|
use the IVI-shell. |
||||||
|
|
||||||
|
.. code-block:: ini |
||||||
|
|
||||||
|
[core] |
||||||
|
shell=ivi-shell.so |
||||||
|
modules=hmi-controller.so |
||||||
|
|
||||||
|
If you are using your custom controller, replace ``hmi-controller.so`` with the |
||||||
|
name of your own controller module. |
||||||
|
|
||||||
|
.. figure:: images/ivi-shell.png |
||||||
|
:alt: IVI-shell architecture overview |
||||||
|
|
||||||
|
Controlling the IVI-shell |
||||||
|
------------------------- |
||||||
|
|
||||||
|
The IVI-shell provides the ``ivi_layout_interface`` API that a controller must |
||||||
|
use to control the window layout of the IVI-shell. See |
||||||
|
``ivi-shell/ivi-layout-export.h`` for the definition of this API. |
||||||
|
|
||||||
|
For the initial configuration, the controller has to create at least one |
||||||
|
``ivi_layout_layer`` and add the ``ivi_layout_layer`` to a ``weston_output``. |
||||||
|
The layers allow to group multiple applications surfaces and control them |
||||||
|
together and are the main mechanism to group and organize surfaces. These are |
||||||
|
always necessary to show something using the IVI-shell. The IVI-shell will |
||||||
|
internally create an ``ivi_layout_screen``, but a controller always uses the |
||||||
|
``weston_output`` directly. |
||||||
|
|
||||||
|
To get control over the client surfaces, the controller must use notifiers that |
||||||
|
trigger whenever there are changes to the client surfaces. The client surfaces |
||||||
|
then show up as ``ivi_layout_surface``. These have an ID, which allows the |
||||||
|
controller to identify the surface and reconfigure the window layout |
||||||
|
accordingly. |
||||||
|
|
||||||
|
The controller must add the ``ivi_layout_surface`` to an ``ivi_layout_layer`` |
||||||
|
and configure it's position and z-order wrt. the other surfaces in the layer. |
||||||
|
Otherwise, the newly added surface will not show up on the screen. |
||||||
|
|
||||||
|
The IVI-shell will internally create an ``ivi_layout_view`` for each layer that |
||||||
|
the surface was added to. However, the views are not provided to the IVI |
||||||
|
controller. |
||||||
|
|
||||||
|
After configuring all expected changes, the controller must call the |
||||||
|
``commit_changes`` to atomically update the display layout. |
||||||
|
|
||||||
|
IVI-shell example implementation |
||||||
|
-------------------------------- |
||||||
|
|
||||||
|
The IVI-shell comes with an example implementation of an IVI controller -- the |
||||||
|
`hmi-controller`. The hmi-controller will usually replaced by a custom |
||||||
|
implementation that implements the use-case-specific behavior. |
||||||
|
|
||||||
|
The hmi-controller is split into two parts: |
||||||
|
|
||||||
|
The ``hmi-controller.so`` is a Weston Plugin that uses the |
||||||
|
``ivi_layout_interface`` to perform the window manager tasks. It allows some |
||||||
|
reconfiguration of the window layout via the ``ivi_hmi_controller`` protocol. |
||||||
|
Other implementations may keep all window management inside the module or may |
||||||
|
expose even more window management via a custom protocol to an external process. |
||||||
|
|
||||||
|
The ``weston-ivi-shell-user-interface`` is an example hmi-controller helper |
||||||
|
client that serves as a user interface for controlling the hmi-controller. |
||||||
|
|
||||||
|
The hmi-controller can be customized using the ``[ivi-shell]`` section in the |
||||||
|
``weston.ini``. An example configuration will be generated in |
||||||
|
``<build_dir>/ivi-shell/weston.ini``. |
@ -1,78 +0,0 @@ |
|||||||
In-vehicle infotainment (information and entertainment) |
|
||||||
graphical environment support modules for Weston |
|
||||||
|
|
||||||
|
|
||||||
IVI-shell is an alternative shell for Weston, a Wayland display server. |
|
||||||
Window management and application interaction with the display server |
|
||||||
are very different to that of a normal desktop, which is why this is |
|
||||||
a separate shell and not an extension to the desktop-shell suite with |
|
||||||
xdg_shell. As such, applications need to be specifically written to use |
|
||||||
IVI-shell. |
|
||||||
|
|
||||||
IVI-shell contains two main features: |
|
||||||
- Common layout library for surface, which allow ivi-shell developer |
|
||||||
to develop own shell, linking Common layout library. |
|
||||||
For the time being, the library refers Genivi ilm interface. |
|
||||||
|
|
||||||
https://at.projects.genivi.org/wiki/display/WIE/Wayland+IVI+Extension+Home |
|
||||||
|
|
||||||
- Extension protocol; ivi-application to tie wl_surface and a given ID. |
|
||||||
With this ID, shell can identify which wl_surface is drawn by which |
|
||||||
application. In in-vehicle infortainment system, a shell has to update |
|
||||||
a property of a wl_surface. E.g. there may be a use case when vehicle |
|
||||||
starts to move, the wl_surface drawn by Car navigation is expected to |
|
||||||
move top of surfaces. |
|
||||||
|
|
||||||
The actual software components delivered with Weston are: |
|
||||||
|
|
||||||
- ivi-application.xml: |
|
||||||
Wayland protocol extension for IVI-applications; the public |
|
||||||
shell protocol (the same concept as xdg_shell). |
|
||||||
Implemented by ivi-shell.so. |
|
||||||
|
|
||||||
- ivi-shell.so: |
|
||||||
A Weston shell module that implements ivi-application.xml interfaces. |
|
||||||
Loads ivi-layout.so. |
|
||||||
|
|
||||||
- ivi-layout.so: |
|
||||||
Implements the IVI window management concepts: Screen, Layer, |
|
||||||
Surface, groups of Layers, groups of Surfaces, see: |
|
||||||
https://at.projects.genivi.org/wiki/display/WIE/Summary+of+Layer+manager+APIs |
|
||||||
Offers a stable API for writing IVI-controller modules like |
|
||||||
hmi-controller.so against the IVI concepts. In other words, |
|
||||||
it offers an API to write IVI window manager modules. |
|
||||||
|
|
||||||
- hmi-controller.so: |
|
||||||
A sample implementation of an IVI-controller module, usually |
|
||||||
replaced by IVI system vendors. |
|
||||||
Uses ivi-layout.so to perform essentially window manager tasks. |
|
||||||
This implementation keeps all window management inside the module, |
|
||||||
while IVI-systems may use another module that exposes all window |
|
||||||
management via Wayland or other protocol for an external process |
|
||||||
to control. |
|
||||||
|
|
||||||
- ivi-hmi-controller.xml: |
|
||||||
Wayland protocol extension for IVI display control; the private |
|
||||||
shell protocol for weston-ivi-shell-user-interface client |
|
||||||
(the same concept as desktop-shell.xml). |
|
||||||
Implemented by hmi-controller.so, and usually replaced by IVI |
|
||||||
system vendors. |
|
||||||
|
|
||||||
- weston-ivi-shell-user-interface: |
|
||||||
A sample implementation of an IVI shell helper client, usually |
|
||||||
replaced by IVI system vendors. |
|
||||||
A helper client for basic display content, similar to |
|
||||||
weston-desktop-shell. |
|
||||||
|
|
||||||
|
|
||||||
How to compile: |
|
||||||
same as weston. To disable, use option: --disable-ivi-shell for configure. |
|
||||||
|
|
||||||
How to configure weston.ini: |
|
||||||
reference ini file will be generated in <build_dir>/ivi-shell. |
|
||||||
|
|
||||||
How to run: |
|
||||||
same as weston. exec weston. |
|
||||||
|
|
||||||
How to use UI: |
|
||||||
http://lists.freedesktop.org/archives/wayland-devel/attachments/20140625/abbfc064/attachment-0001.png |
|
Loading…
Reference in new issue