====== Weston IVI-Shell ======

**Weston IVI-Shell** provides a shell plugin for the [[https://en.wikipedia.org/wiki/Wayland_  %28display_server_protocol%29#Weston|Weston]] compositor, implementing the [[http://www.genivi.org|GENIVI]] API for [[https://en.wikipedia.org/wiki/In_car_entertainment|In-Vehicle Infotainment]].

Project site : [[http://cgit.freedesktop.org/wayland/weston/tree/ivi-shell/|http://cgit.freedesktop.org/wayland/weston/tree/ivi-shell]]

----

===== AGL Demonstration Platform =====

IVI-Shell is always built when [[https://git.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl-demo.git;a=blob;f=README.md;h=0722d30898c16e6aad27d1b25725210865c19478;hb=HEAD#l102|creating an "agl-demo-platform" image]], but will only start automatically if you add the following lines to your "//conf/local.conf//" file :

<code>IMAGE_INSTALL_append = " \
    weston-ivi-shell-config \
    "</code>

or, in case the image has already been built, if you overwrite its "///etc/xdg/weston/weston.ini//" file with **[[https://git.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=meta-ivi-common/recipes-graphics/wayland/weston-ivi-shell/weston.ini.ivi-shell|this one]]**. Or:

<code>
[core]
shell=ivi-shell.so
backend=drm-backend.so

[ivi-shell]
ivi-module=ivi-controller.so
</code>

If everything went fine, you should see a display similar to [[http://iot.bzh/images/images/weston-ivi-shell.png|this one]].

Note also that you might have to turn the screen adding the following lines to "///etc/xdg/weston/weston.ini//"

<code>
[output]
name=HDMI-A-1
transform=270
</code>

----

===== General architecture =====

IVI-Shell provides 2 protocols :

* **ivi-application** : client-side protocol, needed for client applications to be actually shown. Some toolkits/frameworks supporting it currently :
  * **//Qt//** : [[https://git.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl-demo.git;a=blob;f=recipes-  qt/qt5/qtwayland/0021-Implement-initial-IVI-Shell-  support.patch;h=8723def26c3e093580265410389c087d84326a48;hb=HEAD|ad-hoc patch]]
  * **//EFL//** : [[https://git.enlightenment.org/core/efl.git/commit/?id=50287ab731d4d87170238b365203e830edc038d5|Git commit]]
  * **//Chromium/Crosswalk//** : [[https://github.com/01org/ozone-wayland/commit/a034a018b6ec317ec5559dcce6efec916ec40512|Git commit]]

* **ivi-hmi-controller** : server-side protocol, allowing customization of shell behavior and look and feel.

----

===== Implementation examples =====

If we wanted to use //wl_shell//, we would create a //wl_shell_surface// on top of a //wl_surface// : 
<code>struct wl_shell_surface *shell_surface;
shell_surface = wl_shell_get_shell_surface (wl_shell, wl_surface);</code>

Similarly, to use //xdg_shell//, we would create a //xdg_surface// on top of a //wl_surface// : 
<code>struct xdg_surface *xdg_surface;
xdg_surface = xdg_shell_get_xdg_surface (xdg_shell, wl_surface);</code>

IVI-Shell supports creating an //ivi_surface// on top of a //wl_surface//, along with a //unique ID// : 
<code>struct ivi_surface *ivi_surface;
uint32_t id;   // Global numeral ID identifying a managed surface
ivi_surface = ivi_application_surface_create(id, wl_surface);</code>

----

===== Extension features =====

The **[[http://git.projects.genivi.org/?p=wayland-ivi-extension.git|wayland-ivi-extension]]** project brings additional features to IVI-Shell, including :

  * **ivi-controller** plugin : adds support for getting pointers to //native_handle// and //wl_surface// objects managed by //wl_shell// :
<code>get_native_handle()
native_handle</code>

  * **IVISurfaceCreator** command-line tool : associates a Global ID to a //wl_surface// manually. The surface can then be controlled by using the ivi-controller plugin or ivi layout APIs.

<code>$ IVISurfaceCreator --help
Usage: IVISurfaceCreator <Process ID> <Window Title> <IVI-Surface ID></code>

  * **EGLWLMockNavigation** demonstration : uses ivi layout APIs to show an accelerated EGL window with a sample animated scene.

Screeshot [[http://iot.bzh/images/images/renesas_agl_wayland-ivi-extension-1.jpg|here]].

==== Additional information ====

Additional information regarding wayland-ivi-extension, most notably detailed design and HOWTO, can be found on the **GENIVI wiki** :
[[https://at.projects.genivi.org/wiki/display/PROJ/Wayland+IVI+Extension+Design]]