doc: update and move IVI-shell README to doc

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
Michael Tretter 2 years ago committed by Daniel Stone
parent 7d16485efd
commit a2684005b6
  1. 1
      doc/sphinx/index.rst
  2. BIN
      doc/sphinx/toc/images/ivi-shell.png
  3. 9
      doc/sphinx/toc/images/meson.build
  4. 111
      doc/sphinx/toc/ivi-shell.rst
  5. 2
      doc/sphinx/toc/meson.build
  6. 78
      ivi-shell/README

@ -9,6 +9,7 @@ Welcome to Weston documentation!
toc/libweston.rst
toc/test-suite.rst
toc/kiosk-shell.rst
toc/ivi-shell.rst
Weston
------

Binary file not shown.

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,6 +1,7 @@
# you need to add here any files you add to the toc directory as well
files = [
'kiosk-shell.rst',
'ivi-shell.rst',
'running-weston.rst',
'libweston.rst',
'test-suite.rst',
@ -11,4 +12,5 @@ foreach file : files
configure_file(input: file, output: file, copy: true)
endforeach
subdir('images')
subdir('libweston')

@ -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…
Cancel
Save