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
The IVI-shell is able to also handle clients that use the
protocol, but in these cases the IVI-shell needs other means to identify client
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).
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
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
use the IVI-shell.
[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.
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
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
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
The controller must add the
ivi_layout_surface to an
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
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:
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
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.
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