X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=doc%2FApplicationGuide.md;h=d4587e15007ae4195ec8e953b063e6e16c85d710;hb=7879eaa87df698098b4ac250d36dbc41f63627d2;hp=b74dfddf27866fb209879f8a1e9efe51ca280dda;hpb=02eef0a7cff4ede60d1434e860cd4bc9e163af56;p=apps%2Fagl-service-windowmanager.git diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md index b74dfdd..d4587e1 100644 --- a/doc/ApplicationGuide.md +++ b/doc/ApplicationGuide.md @@ -5,7 +5,10 @@
23rd/Oct/2017
* * * -## **
Table of content
** +
+ +Table of content +============ - [Introduction](#Introduction) - [Intended audience](#Intended\ audience) - [Scope of this Document](#Scope\ of\ this\ Document) @@ -33,19 +36,25 @@ - [Sample](#Sample) -
Introduction
+
+ +Introduction ============ This WindowManager implements simple layout switching of applications on multiple layers and with different layer layouts. -
Intended audience
+
+ +Intended audience ----------------- This documentation is intended for developers and system integrators who need to know, how the window manager works and how it is to be used. -
Scope of this Document
+
+ +Scope of this Document ---------------------- This document covers the window manager that was implemented for TMC and @@ -64,7 +73,9 @@ It does not include It is highly recommended to have a good understanding of these documents and projects before using the window manager. -
Known Issues
+
+ +Known Issues ------------ Currently there is a one known issues: @@ -73,28 +84,33 @@ Currently there is a one known issues: libwindowmanager library. This is a limitation of how Qt creates surface IDs for the ivi-application interface. -
External libraries
+
+ +External libraries ------------------ This project includes a copy of version 2.1.1 the excellent [C++11 JSON library by Niels Lohmann](https://github.com/nlohmann/json). -
Client Library
+
+ +Client Library -------------- A client library implementation that internally uses the *libafbwsc*, is -provided in the subdirectory `libwindowmanager/` with its own documentation -directory. +provided in the `libwindowmanager`. -The client library is built together with the window manager itself. +
-
Concepts
+Concepts ======== The window manager implements a couple of concepts in order to allow efficient implementation. -
Layers
+
+ +Layers ------ Layers are entities that are stacked on top of each other. Each layer @@ -112,7 +128,9 @@ currently used layer. It is possible to deactivate these surfaces on lower layers explicitly using the `DeactivateSurface` API call. -
Surfaces
+
+ +Surfaces -------- Surfaces are *placed* on layers according to their name. The surface @@ -120,19 +138,21 @@ will then be resized to dimensions, according to the layer's layout configuration. -
Configuration
+
+ +Configuration ============= The window manager is configured with the *layers.json* configuration -file, by default it is searched in `/etc/layers.json` but through the -use of the environment variable `LAYERS_JSON` the WM can be instructed -to use different file. Note, that the WM will not run unless this -configuration is found and valid. +file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`. +Note, that the WM will not run unless this configuration is found and valid. A sample configuration is provided with the window manager -implementation, this sample is installed to /etc/layers.json. +implementation, this sample is installed to ${AFM_APP_INSTALL_DIR}/etc/layers.json. + +
-
Configuration Items
+Configuration Items ------------------- This section describes configuration items available through @@ -197,7 +217,7 @@ Each mapping defines the following items to map corresponding surfaces to a layer. - `role` defines a regular expression that application drawing names - are matched against. If applications match tis regular expression, + are matched against. If applications match this regular expression, the surface will be visible on this layer. - `name` is just a name definition for this layer, it has no @@ -278,16 +298,20 @@ A split layout object has the following attributes: surface of this layout. In the above example only the surface with drawing name -`App MPlayer Main` will be used as the *main* surface, but all surfaces -that begin with `App MPlayer Sub` can be used as a *sub* surface for +`Navigation` will be used as the *main* surface, and the surfaces +with drawing name `HVAC` or `MediaPlayer` can be used as a *sub* surface for this layout. -The names must still match the layer’s role match! +The names must still match the layer's role match! + +
-
Building and Running
+Building and Running ==================== -
Dependencies
+
+ +Dependencies ------------ This project is intended to be build with the 4.0 release of AGL. @@ -302,52 +326,58 @@ Build dependencies are as follows: - cmake >= 3.6.1 -
Build Configuration
+
+ +Supported environment +------------------- + +| Item | Description | +|:------------|:----------------------------------| +| AGL version | Electric Eel | +| Hardware | Renesas R-Car Starter Kit Pro(M3) | + + +
+ +Build Configuration ------------------- **Download recipe** If repo is already done, please start with git clone + ``` $ mkdir WORK $ cd WORK -$ repo init -b dab -m dab_4.0.0_xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo $ repo sync -$ git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework ``` Then you can get the following recipe. -* `meta-hmi-framework/windowmanager` +* `meta-agl-devel/meta-hmi-framework/recipes-graphics/agl-service-windowmanager-2017` + +* `meta-agl-devel/meta-hmi-framework/recipes-graphics/libwindowmanager` **Bitbake** + ``` $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework -$ bitbake agl-service-windowmanager-2017 +$ bitbake agl-demo-platform ``` +
-A couple of build options to configure the build are available: - -- `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug - output from the window manager, use --verbose three times on an - afb-daemon instance to see the debug messages. - -- `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism - used for a rather small portion of the window manager code. However, - it is used quite extensively in the libwindowmanager implementation. - -By default these options will be disabled. - - -
Implementation Notes
+Implementation Notes ==================== The window manager is implemented as a app-framework-binder binding. That means, the build produces one shared object that exports a binding interface. -
Binding code generation
+
+ +Binding code generation ----------------------- The binding API is rather simple; functions receive a json object @@ -384,7 +414,9 @@ exception is thrown and not handled inside the afb\_binding\_call, that internal state of the window manager might be broken at this time (hence the talkative error log). -
Structure
+
+ +Structure --------- The implementation is loosely split across the following source files: @@ -437,20 +469,26 @@ The implementation is loosely split across the following source files: libwayland-client wrapper. It is instanced in `main.cpp` and handles all our wayland needs. -
Sequence
+
+ +Sequence =============== To understand the sequence between application and window manager, refer to the [spec documentation](https://wiki.automotivelinux.org/windowmanager). -
Binding API
+
+ +Binding API =============== Each function returns a reply containing at least a failed or successful result of the call, additionally, when calls return something, it is noted. -
LibWindowmanager
+
+ +LibWindowmanager ------ This is the public interface of the class `LibWindowmanager`. @@ -484,7 +522,9 @@ This is the public interface of the class `LibWindowmanager`. }; -
Methods
+
+ +Methods ------- ### init(int port, char const *token) @@ -492,7 +532,7 @@ This is the public interface of the class `LibWindowmanager`. Initialize the Binding communication. The `token` parameter is a string consisting of only alphanumeric characters. -If these conditions are not met, the LibWindowmanager instance will not initialize, +If these conditions are not met, the LibWindowmanager instance will not initialize, i.e. this call will return `-EINVAL`. The `port` parameter is the port the afb daemon is listening on, an @@ -500,15 +540,15 @@ invalid port will lead to a failure of the call and return `-EINVAL`. ### requestSurface(json_object *object) -**args: `{ 'kKeyDrawingName': 'application name' }`** -This method requests a surface with the label given from the *Window -Manager*. It will return `0` for a successful surface request, and +**args: `{ 'kKeyDrawingName': 'application name' }`** +This method requests a surface with the label given from the *Window Manager*. +It will return `surface id` a client application can use, and `-errno` on failure. Additionally, on the standard error, messages are logged to help debgging the issue. ### activateSurface(json_object *object) -**args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }`** +**args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }`** This method is mainly intended for *manager* applications that control other applications (think an application manager or the *HomeScreen*). It instructs the window manager to activate the surface with the given @@ -519,7 +559,7 @@ created by the application. ### deactivateSurface(json_object *object) -**args: `{ 'kKeyDrawingName': 'application name' }`** +**args: `{ 'kKeyDrawingName': 'application name' }`** This method is mainly intended for *manager* applications that control other applications. It instructs the window manager to deactivate the surface associated with the given label. Note, that deactivating a @@ -531,7 +571,7 @@ created by the application. ### endDraw(json_object *object) -**args: `{ 'kKeyDrawingName': 'application name' }`** +**args: `{ 'kKeyDrawingName': 'application name' }`** This function is called from a client application when it is done drawing its surface content. @@ -553,7 +593,9 @@ event is targeted at. See Section [Events](#_events) for mor detailed information about event delivery to client applications. -
Errors
+
+ +Errors ------ Methods returning an `int` signal successful operation when returning @@ -563,7 +605,9 @@ value. E.g. `-EINVAL` to signal that some input value was invalid. Additionally, logging of error messages is done on the standard error file descriptor to help debugging the issue. -
Usage
+
+ +Usage ----- ### Initialization of LibWindowmanager @@ -581,7 +625,8 @@ be created. This is also true for *QML* applications, where only after the `requestSurface()` should the load of the resource be done. The method -returns `0` after the surface was requested successfully. +returns `surface id` a client application can use +after the surface was requested successfully. #### Workings of requestSurface() @@ -598,7 +643,9 @@ increment this numeric ID internally - which then will lead to IDs that cannot be known by the window manager as there is no direct communication from *Qt* to the WM. -
Events
+
+ +Events ------ Events are a way for the *Window Manager* to propagate information to @@ -618,13 +665,13 @@ These events signal an application that it was activated or deactivated respectively. Usually this means it was switched visible - which means the surface will now be on the screen and therefor continue to render. -- `Active(json_object *object)` - args: { 'kKeyDrawingName': 'application name' } +- `Active(json_object *object)` + args: { 'kKeyDrawingName': 'application name' } Signal that the surface with the name `kKeyDrawingName` is now active. -- `Inactive(json_object *object)` - args: { 'kKeyDrawingName': 'application name' } +- `Inactive(json_object *object)` + args: { 'kKeyDrawingName': 'application name' } Signal that the surface with the name `kKeyDrawingName` is now inactive. This usually means, the layout got changed, and the surface is now considered inactive @@ -637,13 +684,13 @@ invisible respectively. These events also are handled implicitly through the wayland protocol by means of `wl_surface::enter` and `wl_surface::leave` events to the client. -- `Visible(json_object *object)` - args: { 'kKeyDrawingName': 'application name' } +- `Visible(json_object *object)` + args: { 'kKeyDrawingName': 'application name' } Signal applications, that the surface with name `kKeyDrawingName` is now visible. -- `Invisible(json_object *object)` - args: { 'kKeyDrawingName': 'application name' } +- `Invisible(json_object *object)` + args: { 'kKeyDrawingName': 'application name' } Signal applications that the surface with name `kKeyDrawingName` is now invisible. @@ -657,20 +704,23 @@ contents - again, this is handled implicitly by the wayland protocol. `FlushDraw` is sent to the application when it should swap its buffers, that is *signal* the compositor that its surface contains new content. -- `SyncDraw(json_object *object)` - args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' } +- `SyncDraw(json_object *object)` + args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' } Signal applications, that the - surface with name `kKeyDrawingArea` needs to redraw its content - this + surface with name `kKeyDrawingArea` needs to redraw its content + in the layout with name `kKeyDrawingArea` - this usually is sent when the surface geometry changed. -- `FlushDraw(json_object *object)` - args: { 'kKeyDrawingName': 'application name' } +- `FlushDraw(json_object *object)` + args: { 'kKeyDrawingName': 'application name' } Signal applications, that the surface with name `kKeyDrawingArea` can now be swapped to its newly drawn content as the window manager is ready to activate a new layout (i.e. a new surface geometry). -
Sample
+
+ +Sample ============ In order to enable application to use the `WM` surface registration @@ -679,6 +729,6 @@ function the above described steps need to be implemented. As a minimal example the usage and initialization can look like the following. -Repo: `apps/agl-service-homescreen-2017` -Path: `sample/template/main.c` +Repo: `apps/agl-service-homescreen-2017` +Path: `sample/template/main.c`