Skip to end of metadata
Go to start of metadata

This page contains the detailed design of Wayland IVI Extension with some details how to use it.



Releases

Date Document Version Changes Component Versions tag in repo of weston ivi-shell tag in repo of Wayland IVI Extension Link to snapshot
03.07.20151.0Initial version. Under construction--  
15.07.20151.4First alignment of DesignReleased for specification of ivi-shell in Weston 1.8.0, Wayland-ivi-extension 1.4.0Weston 1.8.0 [1]Wayland IVI Extension 1.4.0 [2][3]
 1.4.91start update for 1.5    
25.12.21051.5Stable version for interface re-alignmentReleased for specification of ivi-shell in Weston 1.9.0, Wayland-ivi-extension 1.9.0Weston 1.9.0 [4]Wayland IVI Extension 1.9.0 [5][6]
07.04.20161.9.1Bugfix releaseReleased Wayland-ivi-extension 1.9.1Weston 1.9.0 [4]Wayland IVI Extension 1.9.1 
09.11.20161.11.0
  • fixes several memory leaks
  • introduces touch support for subsurfaces
  • introduces two new comands to LayerManagerControl
  • compatible with Weston 1.11.0
Released Wayland-ivi-extension 1.11.0Weston 1.11.0 Wayland IVI Extension 1.11.0Source 1.11.0.tar.gz

References

Definitions

Name Definition
IVI SceneLogical container for multiple screens, layers and surfaces.
IVI ScreenLogical container for multiple layers usualy corresponds to concrete display
IVI LayerLogical container for multiple surfaces usually attached to one ivi screen
IVI SurfaceRepresents graphical content of an application. One application can provide several surfaces.
IVIIn Vehicle Infotainment
RenderOrderLogical arrangements of surfaces or layers, first element of the list is on bottom, last element is on top
IVI Applicationclient application for ivi. Predefined numeric ID shall be assigned to each ivi application to be identified by HMI Central Controller.
HMI Controller/Central ControllerWindow Manager which is responsible to controll the composition and input routing
HMIHuman-Machine Interface
--

Acronyms and Abbreviations

Name Definition
- 

Summary

In the automotive domain, most HMI systems use their own window manager implementation. Many applications (e.g. Car Navigation, Rear view camera) are implemented standalone and therefore one service is used to composite all applications to final image on screens by the own window manager. A Project: IVI Layer Management defines a common set of APIs and provide a proof-of-concept implementation for the IVI Layer Management Service. The service improves the existing vendor-specific layer management implementations. This "Wayland IVI Extension" is forked from IVI Layer Management to define a common set of APIs by wayland style protocol and provide reference implementation which can be loaded on Weston: http://wayland.freedesktop.org.

Overview

Wayland IVI Extension provides ivi-controller.so and ivi-input.so modules which are loaded by ivi-shell.so. This modules are used by Window Manager or HMI central controller to control input routing and applications

  • ivi-controller.so: manages properties of ivi surfaces, ivi layers and ivi screen
  • ivi-input.so: manages input focus and input routing from input devices to ivi surfaces

To be managed by ivi-controller.so and ivi-input.so, an ivi application (e.g. Car Navigation) needs to map its wayland surface with a numeric ID which shall be unique in the system. ivi-shell provides the ivi-application.xml protocol to map them, which is as a part of ivi-shell in the Weston project. When this mapping is done, the Window Manager can control position, visibility, transparency and other settings of the corresponding surface.

Wayland IVI Extension also provides libraries to wrap the ivi-application/controller/input protocols to be compatible with ILM APIs.

 

① HMI controller maps its own wl_surface to own numeric ID to be displayed in screen.

② IVI applications maps its own wl_surface to its numeric ID by using ivi-application protocol or ilmClient Library to be managed by HMI Central controller.

③ HMI controller receives notifications of mapping IVI application surfaces to numeric ID, which means IVI application is ready to be displayed. 

④ HMI controller sets properties of surfaces of IVI application to be laid out in UI by using ivi-controller protocol or ilmControl Library.

⑤ Weston collects requests from ivi-controller via ivi-shell: ivi-layout-interfaces and then re-composites wl_surface on the screen. Weston can then directly issue an ioctl to schedule a pageflip with KMS.

⑥ The evdev module of the Linux kernel gets an event and sends it to Weston.

⑦ Weston looks through its scenegraph, which is set by ivi-controll/ivi-input protocol from HMI controller, to determine which window should receive the event. The scenegraph corresponds to what's on screen and Weston understands the transformations that it may have applied to the elements in the scenegraph. Thus, Weston can pick the right window and transform the screen coordinates to window local coordinates, by applying the inverse transformations. The types of transformation that can be applied to a window are only restricted to what Weston can do, as long as it can compute the inverse transformation for the input events.

⑧ Weston collects damage requests from its clients and then re-composites the surfaces on the screen.

Quick Start of Wayland IVI Extension

A Quick Start guide is provided in Wayland IVI Extension project page, http://projects.genivi.org/wayland-ivi-extension/quick-start. It can be easily followed if you have already installed Weston.

ivi application

Applications basically use the wayland core protocol defined by Wayland (e.g connection to display, wl_display and so on) to draw their contents. Weston also supports implementing our own shell which defines management of surfaces. For example, the positioning of a surface can be implemented in the shell. Without a shell, there is no composition of surface in screen. By default, the shell in Weston is "desktop-shell" which supports wl_shell. Wayland IVI Extension uses the ivi-shell to manage surfaces, whose shell protocol is ivi-application.xml. Applications must support the ivi-application protocol to be managed by the HMI central controller with an unique numeric ID.

ivi controller[edit]

ivi controller is a extension protocol defined in this project wayland-ivi-extension. It exports surface/layer/screen management protocol to make each product scene.

ivi input

ivi-input is enabled when ivi-input.so is added after ivi-controll.so in weston.ini. Without ivi-input, input handling is the same as normal desktop style; a top focused surface will be received when input event. Refer Wayland_IVI_Extension_Design_ivi_input

Requirements

Requirements are defined in wiki page for GENIVI member only.

Architecture

Use Cases

Layout of application surfaces

Graphic applications, e.g. Car Navigation, rear view Camera, draw own content on a Wayland surface, wl_surface. These surfaces shall be grouped in a layer/layers which shall belong to a screen or screens. The application surface shall be identified by Numeric ID for HMI to layout surfaces on layer/screens.

 

Input Handling

Controlling of the input routing from the device to the applications also taking into account multi display environment.

Component Diagram[edit]

This diagram shows internal components related to Wayland IVI Extension. This shows all related components but blue parts are provided by Wayland IVI Extension. Other parts are provided by Wayland/Wayland and Other Linux component correspondingly.

  • Layer Manager APIs: three shared libraries to be compatible with IVI Layer Management: http://projects.genivi.org/ivi-layer-management. These internally use ivi-application/ivi-controller protocol. This means developer also directly uses ivi-application/ivi-controller protocol to manage wayland surfaces without Layer Manager APIs.
  • ivi-controller: A shared library to export ivi-layout interfaces via ivi-controller protocol.
  • ivi-layout inteface: compatible with IVI Layer Management APIs. These internal APIs allow developers to develop an window manager in weston process with IVI Layer Management like APIs.
  • HMI Controller: provided as a module which shall be loaded on ivi-shell. This is a reference implementation how to use ivi-layout library. This shall be exclusively used with ivi-controller. In other words, developer shall decide how to implement own window manager with either using ivi-controller.so or ivi-layout interface inside of weston.
  • ivi-shell: realize ivi-application protocol and framework to load ivi-controller.so (or hmi-controller) as ivi-module to use ivi-layout interfaces.

 

ivi-input

ivi-input is enabled when ivi-input.so is added after ivi-controll.so in weston.ini. Without ivi-input, input handling is the same as normal desktop style; a top focused surface will be received when input event. 

[ivi-shell]

ivi-module=ivi-controller.so,ivi-input.so

description[edit]

Refer Wayland_IVI_Extension_Design_ivi_input

Sequence Diagram

Starting up Wayland IVI Extension with Weston

Wayland IVI Extension is loaded as ivi-module in ivi-shell + Weston. These modules are configured to be loaded by using weston.ini.

[core]

shell=ivi-shell.so

[ivi-shell]

ivi-module=ivi-controller.so



ivi input[edit]

Refer Wayland_IVI_Extension_Design_ivi_input

Sequence for ivi application and HMI central Controller

ivi application draw own content by using Wayland Core protocol and then map the wl_surface to Numeric ID by using ivi_application protocol to notify the application is ready to be managed by HMI Central Controller. HMI Centroller layout its Scene by using ivi-controller protocol/ilmControl library.

 

Component Interfaces

Interfaces are classified into four libraries for type of application.

  • ilmCommon: common interfaces for both ivi application and HMI controller to initialize ilm library.
  • ilmClient: client interfaces for ivi application only to map numeric ID to client surface to be controlled by HMI controller. This client interfaces are defined as simple.
    • Client application has two choice to map numeric ID to own surface; 
      • One is wl_surface by using this ilmClient interfaces, ilm_surfaceCreate.
      • Second one directly uses ivi-application protocol which is wrapped in ilmClient interfaces. ivi-application protocol defined in Wayland/Weston project.
  • ilmControl: controller interfaces for HMI controller only to set properties to ivi applicaton's surfaces by identifying numeric ID. This interfaces allows HMI controller to control various properties of surfaces/layers and get notification when the properties are actually applied in Weston. 
    • HMI Controllerhas two choice to manage surface/layer;
      • One is ilmControl
      • Second one is directly uses ivi-controller protocol which is wrpped in ilmControl interfaces. ivi-controller protocl defined in this Wayland IVI Extension project as extension for IVI.
  • ilmInput: TBD

Interfaces

Common interfaces

This interface set consists of simple interfaces for init/destroy and get status of initialization of ilm library.

Name client/control Definition Parameters Description Remark
ilm_initBothilmErrorTypesvoid

\brief Initializes the Wayland IVI extension library

\ingroup ilmCommon
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if failure of initialization of ilmclient/control library.
This API shall be called once in an application/process to start using ilmclient/control library. wl_dispaly to the Weston is automatically established in this interface. If you want to use your established wl_display, use next interface.
ilm_initWithNativedisplayBothilmErrorTypest_ilm_nativedisplay nativedisplay

\brief Initializes the Wayland IVI extension library with wl_display

\ingroup ilmCommon
\\param[in] nativedisplay wl_dispaly to the Weston.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if failure of initialization of ilmclient/control library.
If you get wl_display directly, the wl_display can be reused in ilmclient/control library.
ilm_isInitializedBotht_ilm_boolvoid

\\brief Returns initialization state of ilmclient/control library

\ingroup ilmCommon
\return true if client library is initialized
\return false if client library is not initialized
 
ilm_commitChangesControlilmErrorTypesvoid

\\brief Commit all changes and execute all enqueued commands since last commit.

\ingroup ilmCommon
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
ilm_destroyBotchilmErrorTypesvoid

\\brief Destroys the context or memory related to ilmclient/control library. 

\ingroup ilmCommon
\return ILM_SUCCESS if the method call was successful and free memory related to ilmclient/control library. 
\return ILM_FAILED if the ilmclient/control library can not be closure.
This shall be called at destruction phase of an application.

Client interfaces

Client interfaces consists of two interfaces. Once application surface is mapped to numeric ID, the surface can be managed by ilmControl library. These interfaces are provided for legacy applications on GENIVI IVI layer manager so these are not mandatory to use but it can directly use ivi_application protocol http://cgit.freedesktop.org/wayland/weston/tree/protocol/ivi-application.xml as well.

Name Definition Parameters Description Remark
ilmClient_initilmErrorTypes
 t_ilm_nativedisplay nativedisplay

\brief Initializes the IVI LayerManagement Client APIs.

 \ingroup ilmControl
 \param[in] nativedisplay the wl_display of native application
 \return ILM_SUCCESS if the method call was successful
 \return ILM_FAILED if a connection can not be established to the service
A client needs to call this rather than ilm_init.
ilm_surfaceCreateilmErrorTypes
 t_ilm_nativehandle nativehandle,
 t_ilm_int width,
 t_ilm_int height,
 ilmPixelFormat pixelFormat,
 t_ilm_surface *pSurfaceId\

\brief Create a surface with wl_surface

 \ingroup ilmClient
 \param[in] nativehandle The native windowsystem's handle for the surface
 \param[in] width The original width of the surface
 \param[in] height The original height of the surface
 \param[in] pixelFormat The pixelformat to be used for the surface
 \param[in] pSurfaceId The value pSurfaceId points to is used as ID for new surface;
 \param[out] pSurfaceId The ID of the newly created surface is returned in this parameter
 \return ILM_SUCCESS if the method call was successful
 \return ILM_FAILED if the client can not call the method on the service.

 

ilm_surfaceRemoveilmErrorTypesconst t_ilm_surface surfaceId
\brief Remove a surface
\ingroup ilmClient
\param[in] surfaceId The id of the surface to be removed
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
ilmClient_destroyilmErrorTypesvoid
\brief Destroys the IVI LayerManagement Client APIs.
\ingroup ilmCommon
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not be closed or was not initialized.
A client needs to call this rather than ilm_destroy.

Control interfaces[edit]

Control interfaces provides six sets of interfaces, get operation, surface/layer/display oriented get/set operation, screenshot for debugging purpse, and notification. These interfaces are provided for legacy HMI central controller on GENIVI IVI layer manager so these are not mandatory to use but it can directly use ivi_controller protocol as well, http://git.projects.genivi.org/?p=wayland-ivi-extension.git;a=blob;f=protocol/ivi-controller.xml.

Get Operation of Surface/Layer/Screen properties

No Name Definition Parameters Description Remark
1ilm_getPropertiesOfSurfaceilmErrorTypest_ilm_uint surfaceID, struct ilmSurfaceProperties* pSurfaceProperties

\brief Get the surface properties from the Layermanagement

\ingroup ilmClient
\param[in] surfaceID surface Indentifier as a Number from 0 .. MaxNumber of Surfaces
\param[out] pSurfaceProperties pointer where the surface properties should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not get the resolution.
 
2ilm_getPropertiesOfLayerilmErrorTypest_ilm_uint layerID, struct ilmLayerProperties* pLayerProperties

\brief Get the layer properties from the Layermanagement

\ingroup ilmControl
\param[in] layerID layer Indentifier as a Number from 0 .. MaxNumber of Layer
\param[out] pLayerProperties pointer where the layer properties should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not get the resolution.
 
3ilm_getPropertiesOfScreenilmErrorTypest_ilm_display screenID, struct ilmScreenProperties* pScreenProperties

\brief Get the screen properties from the Layermanagement

\ingroup ilmControl
\param[in] screenID screen Indentifier
\param[out] pScreenProperties pointer where the screen properties should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not get the resolution.
 
4ilm_getScreenIDsilmErrorTypest_ilm_uint* pNumberOfIDs, t_ilm_uint** ppIDs

\brief Get the screen Ids

\ingroup ilmControl
\param[out] pNumberOfIDs pointer where the number of Screen Ids should be returned
\param[out] ppIDs pointer to array where the IDs should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not get the resolution.
 
5ilm_getScreenResolutionilmErrorTypest_ilm_uint screenID, t_ilm_uint* pWidth, t_ilm_uint* pHeight

\brief Get the screen resolution of a specific screen from the Layermanagement

\ingroup ilmClient
\param[in] screenID Screen Indentifier as a Number from 0 .. MaxNumber of Screens
\param[out] pWidth pointer where width of screen should be stored
\param[out] pHeight pointer where height of screen should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not get the resolution.
 
6ilm_getLayerIDsilmErrorTypest_ilm_int* pLength, t_ilm_layer** ppArray

\brief Get all LayerIds which are currently registered and managed by the services

\ingroup ilmControl
\param[out] pLength Pointer where length of ids array should be stored
\param[out] ppArray Array where the ids should be stored,
                    the array will be allocated inside
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
7ilm_getLayerIDsOnScreenilmErrorTypest_ilm_uint screenID, t_ilm_int* pLength, t_ilm_layer** ppArray\brief Get all LayerIds of the given screen
* \ingroup ilmControl
* \param[in] screenID The id of the screen to get the layer IDs of
* \param[out] pLength Pointer where length of ids array should be stored
* \param[out] ppArray Array where the ids should be stored,
*                     the array will be allocated inside
* \return ILM_SUCCESS if the method call was successful
* \return ILM_FAILED if the client can not call the method on the service.
 
8ilm_getSurfaceIDsilmErrorTypest_ilm_int* pLength, t_ilm_surface** ppArray

\brief Get all SurfaceIDs which are currently registered and managed by the services

\ingroup ilmControl
\param[out] pLength Pointer where length of ids array should be stored
\param[out] ppArray Array where the ids should be stored,
                    the array will be allocated inside
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
9ilm_getSurfaceIDsOnLayerilmErrorTypest_ilm_layer layer, t_ilm_int* pLength, t_ilm_surface** ppArray

\brief Get all SurfaceIds which are currently registered to a given layer and are managed by the services

\ingroup ilmControl
\param[in] layer Id of the Layer whose surfaces are to be returned
\param[out] pLength Pointer where the array length of ids should be stored
\param[out] ppArray Array where the surface id should be stored,
                    the array will be allocated inside
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 

surface/layer/display oriented get/set operation

surface

No Name Definition Parameters Initial Value Description Remark
1ilm_surfaceSetVisibilityilmErrorTypest_ilm_surface surfaceId, t_ilm_bool newVisibilityFALSE

\brief Set the visibility of a surface. If a surface is not visible it will not be rendered.

\ingroup ilmControl
\param[in] surfaceId Id of the surface to set the visibility of
\param[in] newVisibility ILM_SUCCESS sets surface visible, ILM_FALSE disables the visibility.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
2ilm_surfaceGetVisibilityilmErrorTypest_ilm_surface surfaceId, t_ilm_bool *pVisibility-

\brief Get the visibility of a surface. If a surface is not visible, the surface will not be rendered.

\ingroup ilmClient
\param[in] surfaceId Id of the surface to get the visibility of.
\param[out] pVisibility pointer where the visibility of a surface should be stored
                        ILM_SUCCESS if the surface is visible,
                        ILM_FALSE if the visibility is disabled.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
3ilm_surfaceSetOpacityilmErrorTypesconst t_ilm_surface surfaceId, t_ilm_float opacity1.0

\brief Set the opacity of a surface.

\ingroup ilmControl
\param surfaceId Id of the surface to set the opacity of.
\param opacity 0.0 means the surface is fully transparent,
               1.0 means the surface is fully opaque
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
4ilm_surfaceGetOpacityilmErrorTypesconst t_ilm_surface surfaceId, t_ilm_float *pOpacity-

\brief Get the opacity of a surface.

\ingroup ilmControl
\param[in] surfaceId Id of the surface to get the opacity of.
\param[out] pOpacity pointer where the surface opacity should be stored.
                     0.0 means the surface is fully transparent,
                     1.0 means the surface is fully opaque
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
5ilm_surfaceSetSourceRectangleilmErrorTypest_ilm_surface surfaceId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height0,0,0,0

\brief Set the area of a surface which should be used for the rendering.

\ingroup ilmClient
\param[in] surfaceId Id of surface.
\param[in] x horizontal start position of the used area
\param[in] y vertical start position of the used area
\param[in] width width of the area
\param[in] height height of the area
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
A behavior of this API is difficult to understand. Refer following link,

https://at.projects.genivi.org/wiki/display/WIE/02.+Summary+of+Layer+manager+APIs

6ilm_surfaceSetDestinationRectangleilmErrorTypest_ilm_surface surfaceId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height0,0,0,0

\brief Set the destination area of a surface within a layer for rendering. The surface will be scaled to this rectangle for rendering.

\ingroup ilmControl
\param[in] surfaceId Id of surface.
\param[in] x horizontal start position of the used area
\param[in] y vertical start position of the used area
\param[in] width width of the area
\param[in] height height of the area
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
A behavior of this API is difficult to understand. Refer following link,

https://at.projects.genivi.org/wiki/display/WIE/02.+Summary+of+Layer+manager+APIs

7ilm_surfaceSetOrientationilmErrorTypest_ilm_surface surfaceId, ilmOrientation orientation0

\brief Sets the orientation of a surface.

\ingroup ilmControl
\param[in] surfaceId Id of surface.
\param[in] orientation Orientation of the surface.
\note ilmOrientation for information about orientation values
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
A behavior of this API is difficult to understand. Refer following link,

https://at.projects.genivi.org/wiki/display/WIE/02.+Summary+of+Layer+manager+APIs

8ilm_surfaceGetOrientationilmErrorTypest_ilm_surface surfaceId, ilmOrientation *pOrientation-

\brief Gets the orientation of a surface.

\ingroup ilmControl
\param[in]  surfaceId Id of surface.
\param[out] pOrientation Address where orientation of the surface should be stored.
\note ilmOrientation for information about orientation values
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
9ilm_surfaceGetPixelformatilmErrorTypest_ilm_layer surfaceId, ilmPixelFormat *pPixelformat-

\brief Gets the pixelformat of a surface.

\ingroup ilmControl
\param[in] surfaceId Id of surface.
\param[out] pPixelformat Pointer where the pixelformat of the surface should be stored
\note ilmPixelFormat for information about pixel format values
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 

Layer

No Name Definition Parameters Initial Value Description Remark
1ilm_layerCreateWithDimensionilmErrorTypest_ilm_layer* pLayerId, t_ilm_uint width, t_ilm_uint height-

\brief Create a layer which should be managed by the service

\ingroup ilmControl
\param[out] pLayerId pointer where the id should be/is stored. It is possible
                     to set a id from outside, 0 will create a new id.
\param[in] width     horizontal dimension of the layer
\param[in] height    vertical dimension of the layer
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
2ilm_layerRemoveilmErrorTypest_ilm_layer layerId-

\brief Removes a layer which is currently managed by the service

\ingroup ilmControl
\param[in] layerId Layer to be removed
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
3ilm_layerAddSurfaceilmErrorTypest_ilm_layer layerId, t_ilm_surface surfaceIdnone

\brief Add a surface to a layer which is currently managed by the service

\ingroup ilmClient
\param[in] layerId Id of layer which should host the surface.
\param[in] surfaceId Id of surface which should be added to the layer.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.

 

4ilm_layerRemoveSurfaceilmErrorTypest_ilm_layer layerId, t_ilm_surface surfaceId-

\brief Removes a surface from a layer which is currently managed by the service

\ingroup ilmClient
\param[in] layerId Id of the layer which contains the surface.
\param[in] surfaceId Id of the surface which should be removed from the layer.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
5ilm_layerSetVisibilityilmErrorTypest_ilm_layer layerId, t_ilm_bool newVisibilityFALSE

\brief Set the visibility of a layer. If a layer is not visible, the layer and its surfaces will not be rendered.

\ingroup ilmControl
\param[in] layerId Id of the layer.
\param[in] newVisibility ILM_SUCCESS sets layer visible, ILM_FALSE disables the visibility.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
6ilm_layerGetVisibilityilmErrorTypest_ilm_layer layerId, t_ilm_bool *pVisibility-

\brief Get the visibility of a layer. If a layer is not visible, the layer and its surfaces will not be rendered.

\ingroup ilmControl
\param[in] layerId Id of layer.
\param[out] pVisibility pointer where the visibility of the layer should be stored
                        ILM_SUCCESS if the Layer is visible,
                        ILM_FALSE if the visibility is disabled.
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
7ilm_layerSetOpacityilmErrorTypest_ilm_layer layerId, t_ilm_float opacity1.0

\brief Set the opacity of a layer.

\ingroup ilmControl
\param[in] layerId Id of the layer.
\param[in] opacity 0.0 means the layer is fully transparent,
                   1.0 means the layer is fully opaque
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
8ilm_layerGetOpacityilmErrorTypest_ilm_layer layerId, t_ilm_float *pOpacity-

\brief Get the opacity of a layer.

\ingroup ilmControl
\param[in] layerId Id of the layer to obtain the opacity of.
\param[out] pOpacity pointer where the layer opacity should be stored.
                     0.0 means the layer is fully transparent,
                     1.0 means the layer is fully opaque
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
9ilm_layerSetSourceRectangleilmErrorTypest_ilm_layer layerId, t_ilm_uint x, t_ilm_uint y, t_ilm_uint width, t_ilm_uint height0,0,0,0

\brief Set the area of a layer which should be used for the rendering. Only this part will be visible.

\ingroup ilmControl
\param[in] layerId Id of the layer.
\param[in] x horizontal start position of the used area
\param[in] y vertical start position of the used area
\param[in] width width of the area
\param[in] height height of the area
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
A behavior of this API is difficult to understand. Refer following link,

http://projects.genivi.org/wayland-ivi-extension/layer-manager-apis

10ilm_layerSetDestinationRectangleilmErrorTypest_ilm_layer layerId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height0,0,0,0

\brief Set the destination area on the display for a layer. The layer will be scaled and positioned to this rectangle for rendering

\ingroup ilmControl
\param[in] layerId Id of the layer.
\param[in] x horizontal start position of the used area
\param[in] y vertical start position of the used area
\param[in] width width of the area
\param[in] height height of the area
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
A behavior of this API is difficult to understand. Refer following link,

http://projects.genivi.org/wayland-ivi-extension/layer-manager-apis

11ilm_layerGetDimensionilmErrorTypest_ilm_layer layerId, t_ilm_uint *pDimension-

\brief Get the horizontal and vertical dimension of the layer.

\ingroup ilmControl
\param[in] layerId Id of layer.
\param[out] pDimension pointer to an array where the dimension should be stored.
                      dimension[0]=width, dimension[1]=height
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
12ilm_layerSetOrientationilmErrorTypest_ilm_layer layerId, ilmOrientation orientation0

\brief Sets the orientation of a layer.

\ingroup ilmControl
\param[in] layerId Id of layer.
\param[in] orientation Orientation of the layer.
\note ilmOrientation for more information on orientation values
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
13ilm_layerGetOrientationilmErrorTypest_ilm_layer layerId, ilmOrientation *pOrientation-A behavior of this API is difficult to understand. Refer following link,

http://projects.genivi.org/wayland-ivi-extension/layer-manager-apis \brief Gets the orientation of a layer.

\ingroup ilmControl
\param[in] layerId Id of layer.
\param[out] pOrientation Address where orientation of the layer should be stored.
\note ilmOrientation for more information on orientation values
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
14ilm_layerSetRenderOrderilmErrorTypest_ilm_layer layerId, t_ilm_layer *pSurfaceId, t_ilm_int numbernone

\brief Sets render order of surfaces within one layer

\ingroup ilmControl
\param[in] layerId Id of layer.
\param[in] pSurfaceId array of surface ids
\param[in] number Number of elements in the given array of ids
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.

This can set several surfaces with order by one request.

 

Display (screen)

No Name Definition Parameters Initial Value Description Remark
1ilm_displaySetRenderOrderilmErrorTypest_ilm_display display, t_ilm_layer *pLayerId, const t_ilm_uint numbernone

\brief Sets render order of layers on a display

\ingroup ilmControl
\param[in] display Id of display to set the given order of layers.
\param[in] pLayerId array of layer ids
\param[in] number number of layerids in the given array
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.

 

Screenshot (debug)[edit]

No Name Definition Parameters Initial Value Description Remark
1ilm_takeScreenshotilmErrorTypest_ilm_uint screen, t_ilm_const_string filename-

\brief Take a screenshot from the current displayed layer scene. The screenshot is saved as bmp file with the corresponding filename.

\ingroup ilmControl
\param[in] screen Id of screen where screenshot should be taken
\param[in] filename Location where the screenshot should be stored
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
2ilm_takeLayerScreenshotilmErrorTypest_ilm_const_string filename, t_ilm_layer layerid-

\brief Take a screenshot of a certain layer. The screenshot is saved as bmp file with the corresponding filename.

\ingroup ilmControl
\param[in] filename Location where the screenshot should be stored
\param[in] layerid Identifier of the layer to take the screenshot of
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 
3ilm_takeSurfaceScreenshotilmErrorTypest_ilm_const_string filename, t_ilm_surface surfaceid-

\brief Take a screenshot of a certain surface. The screenshot is saved as bmp file with the corresponding filename.

\ingroup ilmControl
\param[in] filename Location where the screenshot should be stored
\param[in] surfaceid Identifier of the surface to take the screenshot of
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
 

Notification

No Name Definition Parameters Initial Value Description Remark
1ilm_layerAddNotificationilmErrorTypest_ilm_layer layer, layerNotificationFunc callback-

\brief register for notification on property changes of layer

\ingroup ilmControl
\param[in] layer id of layer to register for notification
\param[in] callback pointer to function to be called for notification
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
\return ILM_ERROR_INVALID_ARGUMENT if the given layer already has notification callback registered
 
2ilm_layerRemoveNotificationilmErrorTypest_ilm_layer layer-

\brief remove notification on property changes of layer

\ingroup ilmControl
\param[in] layer id of layer to remove notification
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
\return ILM_ERROR_INVALID_ARGUMENT if the given layer has no notification callback registered
 
3ilm_surfaceAddNotificationilmErrorTypest_ilm_surface surface, surfaceNotificationFunc callback-

\brief register for notification on property changes of surface

\ingroup ilmClient
\param[in] surface id of surface to register for notification
\param[in] callback pointer to function to be called for notification
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
\return ILM_ERROR_INVALID_ARGUMENT if the given surface already has notification callback registered
HOWTO: refer HMI central controller example, layer-add-surfaces.
4ilm_surfaceRemoveNotificationilmErrorTypest_ilm_surface surface-

\brief remove notification on property changes of surface

\ingroup ilmClient
\param[in] surface id of surface to remove notification
\return ILM_SUCCESS if the method call was successful
\return ILM_FAILED if the client can not call the method on the service.
\return ILM_ERROR_INVALID_ARGUMENT if the given surface has no notification callback registered
 
5ilm_registerNotificationilmErrorTypesnotificationFunc callback, void *user_data-

\brief register notification callback for creation/deletion of ilm surfaces/layers

 \ingroup ilmControl
 \param[in] callback pointer to function to be called for notification
callback function is defined as:
void
cb(ilmObjectType o, t_ilm_uint id, t_ilm_bool created, void *user_data)

 \param[in] user_data pointer to data which will be passed to a notification callback
\return ILM_SUCCESS if the method call was successful \return ILM_FAILED if the client can not call the method on the service.
HOWTO: refer HMI central controller example, layer-add-surfaces.
6ilm_unregisterNotificationilmErrorTypesvoid-

\brief unregister notification for creation/deletion events of ilm surfaces/layers

 \ingroup ilmControl
 \return ILM_SUCCESS if the method call was successful
 \return ILM_FAILED if the client can not call the method on the service.
 

Input handling interfaces

Refer Wayland_IVI_Extension_Design_ivi_input

Examples

There are several reference implementation when you implement your own ivi-application or HMI Central controller.

ivi application

The following examples show reference implementation how to draw content on a surface and map the surface to Numeric ID to be controlled by HMI Central Controller. 

(*) These examples are expected to use only a surface. If you want to use multiple surfaces in your application, wl_subsurface is one of better choice. if you want to use multiple wl_surfaces, your application needs to communicate HMI Central Controller to set properties of these surfaces. It would be dependent on business logic of a HMI Central controller and it will loose compatibility with other controller(Not recommenced).

Example 1: Simple egl

This is a simple example to draw graphics contents and map its surface to numeric ID. This example is maintained by Wayland/Weston. So it supports multiple shells; xdg_shell and ivi_shell with this one example. http://cgit.freedesktop.org/wayland/weston/tree/clients/simple-egl.c

There are several key topics to be address for ivi application developer. This example uses Wayland core protocol as well, refer http://wayland.freedesktop.org/docs/html. Some key protocol is highlighted here.

  • A method "registry_listener" added to listener to know when a protocol is bound/unbound to the Weston. For example, if ivi-shell binds ivi_application, this application can get ivi_application interfaces in this listener. And then this application can know which shell is loaded on Weston, ivi-shell or xdg-shell. 
  • For Wayland IVI Extension, ivi application doesn't have to support xdg-shell. For example, this application identifies which shell is loaded and executes corresponding code like following condition. But ivi application can refer only part related to ivi_application. 
    if (display->shell) {
    	create_xdg_surface(window, display);
    } else if (display->ivi_application ) {
    	create_ivi_surface(window, display);
    } else {
    	assert(0);
    }
  • A method "create_surface" provides several key topics to start to draw graphics contents and map numeric ID to wl_surface.
    • create wl_surface by wl_compositor_create_surface
    • get egl_surface by weston_platform_create_egl_surface
    • In create_ivi_surface, 
      • wl_surface is mapped to numeric ID by ivi_application_surface_create. The ID is generated based on process ID as just a reference. It should be unique in a product to be identified by HMI central Controller.
      • set listener to get event from Weston. For example, "handle_ivi_surface_configure" is set as listener. When the size of ivi_surface mapped to application's wl_surface is changed by HMI Central controller, the size is notified and application is suggested to change its content. Refer <event name="configure"> at http://cgit.freedesktop.org/wayland/weston/tree/protocol/ivi-application.xml.
    • And then attach an EGL rendering context to EGL surfaces by eglMakeCurrent
    • Finally, it calls eglSwapInterval. This is also important keyword for applications. If it doesn't call this, the eglSwapbuffers is synchronized at redraw, composition of Weston. For example, if the weston composes surfaces at Vsync per 60fps, the application get return of eglSwapbuffers at the same pace. If an application keep own pace, it shall use eglSwapInterval with 0, not synchronizing composition of surfaces by Weston.
    • (*) wl_display_roundtrip: http://wayland.freedesktop.org/docs/html/apb.html#Client-classwl__display, as usual, an ivi application doesn't have to wait for server side processing. This is because application can draw its content asynchronously which is composed to final screen by Weston per Vsync according to those properties set by ilmControl. Additionally, ivi_application can get event by protocol so it shall be implemented as event driven per an event, not waiting for for whole processing of side server.

Example 2: EGLMockNavigation

This example calls ilm_surfaceCreate in OpenGLES2App::setupLayerMangement at OpenGLES2App.cpp alternatively for ivi_application protocol. This example is also referred for HMI Central Control how to use ilmControl library.

http://git.projects.genivi.org/?p=wayland-ivi-extension.git;a=tree;f=ivi-layermanagement-examples/EGLWLMockNavigation

Example 3: multi-touch-viewer

This example provides us how to receive multi touch and handle them for own application. This shows multi touch as points with differenctcolor.

http://git.projects.genivi.org/?p=wayland-ivi-extension.git;a=tree;f=ivi-layermanagement-examples/multi-touch-viewer

HMI Central Controller

HMI Central Controller layouts ivi-applications to fit them in its HMI by using ilmControl library.

Example 1: layer-add-surfaces

http://git.projects.genivi.org/?p=wayland-ivi-extension.git;a=tree;f=ivi-layermanagement-examples/layer-add-surfaces This example provides simple examples how to use ilmControl apis.

  • create layer according to parameter
  • set properties to the layer
  • set callback to get notification of surfaces.
  • wait for event of surfaces
  • When a surface is created, it receives notification via registered callback.
  • set properties to a surface to be visible in layer and then add it to the layer.

Testing

Wayland ivi extension provides conformance test to verify IVI layer manager APIs

$ export XDG_RUNTIME_DIR=/var/run/user/1000

$ cd $(BUILD_DIR)/ivi-layermanagement-api/test

$ ./ivi-layermanagement-api-test


  • No labels