diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 8aa53b3e..a47bccb9 100644 --- a/doc/sphinx/index.rst +++ b/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 ------ diff --git a/doc/sphinx/toc/images/ivi-shell.png b/doc/sphinx/toc/images/ivi-shell.png new file mode 100644 index 00000000..87ff7a36 Binary files /dev/null and b/doc/sphinx/toc/images/ivi-shell.png differ diff --git a/doc/sphinx/toc/images/meson.build b/doc/sphinx/toc/images/meson.build new file mode 100644 index 00000000..c73a8c60 --- /dev/null +++ b/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 diff --git a/doc/sphinx/toc/ivi-shell.rst b/doc/sphinx/toc/ivi-shell.rst new file mode 100644 index 00000000..42eb5fe5 --- /dev/null +++ b/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 +``/ivi-shell/weston.ini``. diff --git a/doc/sphinx/toc/meson.build b/doc/sphinx/toc/meson.build index b7190f78..4c638411 100644 --- a/doc/sphinx/toc/meson.build +++ b/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') diff --git a/ivi-shell/README b/ivi-shell/README deleted file mode 100644 index 1d2212ea..00000000 --- a/ivi-shell/README +++ /dev/null @@ -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 /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