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>

doc/sphinx/index.rst

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

doc/sphinx/toc/images/meson.build

@@ -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

doc/sphinx/toc/ivi-shell.rst

@@ -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``.

doc/sphinx/toc/meson.build

@@ -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')

ivi-shell/README

@@ -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