mirror of
https://gitlab.freedesktop.org/wayland/weston
synced 2024-09-06 18:05:39 +00:00
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>
This commit is contained in:
parent
7d16485efd
commit
a2684005b6
|
@ -9,6 +9,7 @@ Welcome to Weston documentation!
|
|||
toc/libweston.rst
|
||||
toc/test-suite.rst
|
||||
toc/kiosk-shell.rst
|
||||
toc/ivi-shell.rst
|
||||
|
||||
Weston
|
||||
------
|
||||
|
|
BIN
doc/sphinx/toc/images/ivi-shell.png
Normal file
BIN
doc/sphinx/toc/images/ivi-shell.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 108 KiB |
9
doc/sphinx/toc/images/meson.build
Normal file
9
doc/sphinx/toc/images/meson.build
Normal file
|
@ -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
|
111
doc/sphinx/toc/ivi-shell.rst
Normal file
111
doc/sphinx/toc/ivi-shell.rst
Normal file
|
@ -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…
Reference in a new issue