1 **Window Manager Application Guide**
3 <div align="right">Revision: 0.5</div>
4 <div align="right">TOYOTA MOTOR CORPORATION</div>
5 <div align="right">20th/Mar/2018</div>
8 <div id="Table\ of\ content"></div>
12 - [Introduction](#Introduction)
13 - [Intended audience](#Intended\ audience)
14 - [Scope of this Document](#Scope\ of\ this\ Document)
15 - [Known Issues](#Known\ Issues)
16 - [External libraries](#External\ libraries)
17 - [Client Library](#Client\ Library)
18 - [Concepts](#Concepts)
20 - [Surfaces](#Surfaces)
21 - [Configuration](#Configuration)
22 - [Configuration Items](#Configuration\ Items)
23 - [Building and Running](#Building\ and\ Running)
24 - [Dependencies](#Dependencies)
25 - [Build Configuration](#Build\ Configuration)
26 - [Implementation Notes](#Implementation\ Notes)
27 - [Structure](#Structure)
28 - [Sequence](#Sequence)
29 - [Binding API](#Binding\ API)
30 - [LibWindowmanager](#LibWindowmanager)
38 <div id="Introduction"></div>
43 This window manager implements simple layout switching of applications on
44 multiple layers and with different layer layouts.
46 <div id="Intended\ audience"></div>
51 This document is intended for developers and system integrators who
52 need to know, how the window manager works and how it is to be used.
54 <div id="Scope\ of\ this\ Document"></div>
56 Scope of this Document
57 ----------------------
59 This document covers the window manager that was implemented for TMC and
60 delivered to the Automotive Grade Linux (AGL) project. It includes its
61 implementation details, concepts of operation, configuration and usage.
65 - document of the underlying architecture, see
66 [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
68 - document of the AGL application framework and its technologies,
70 Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
72 It is highly recommended to have a good understanding of these documents
73 and projects before using the window manager.
75 <div id="Known\ Issues"></div>
80 Currently there is a one known issues:
82 - Only single-surface Qt applications are support through the
83 libwindowmanager library. This is a limitation of how Qt creates surface
84 IDs for the ivi-application interface.
86 <div id="External\ libraries"></div>
91 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
92 library by Niels Lohmann](https://github.com/nlohmann/json).
94 <div id="Client\ Library"></div>
99 A client library implementation that internally uses the *libafbwsc*, is
100 provided in the `libwindowmanager`.
102 <div id="Concepts"></div>
107 The window manager implements a couple of concepts in order to allow
108 efficient implementation.
110 <div id="Layers"></div>
115 Layers are entities that are stacked on top of each other. Each layer
116 has an ID which is used for the ivi-controller interface, but this ID
117 also implicitly specifies its stacking order, from lowest to highest.
119 Layers are always full-screen. We do not use layer dimensions as a way
120 to setup the scene, rather - each layer has a layout attached to it,
121 which specifies an area that is used by surfaces to draw on.
123 Additionally, layers will generally leave surfaces on below layers
124 activated, and only disable surfaces on layers the are above the
125 currently used layer.
127 It is possible to deactivate these surfaces on lower layers explicitly
128 using the `DeactivateSurface` API call.
130 <div id="Surfaces"></div>
135 Surfaces are *placed* on layers according to their name. The surface
136 will then be resized to dimensions, according to the layer's layout
140 <div id="Configuration"></div>
145 The window manager is configured with the *layers.json* configuration
146 file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`.
147 However, if /etc/xdg/windowmanager/layers.json exists, it will be used instead.
148 The window manager will use a default configuration unless a configuration file
149 is found in one of these locations.
151 A sample configuration is provided with the window manager
152 implementation, this sample is installed to ${AFM_APP_INSTALL_DIR}/etc/layers.json.
155 Currently, window manager doesn't block the application displaying because "Fallback" is set by default. If the "Fallback" is not set in layers.json, window manager blocks the application displaying. In such a situation, you have to add your role(application name) at "role" in layers.json.
157 <div id="Configuration\ Items"></div>
162 This section describes configuration items available through
163 `layers.json`. It will do this, by first providing an example, and then
164 going into its components.
169 "surface_role": "HomeScreen",
172 The `main_surface` object describes a surface that will internally be
173 treated as the main surface - usually this mean *HomeScreen*. The only
174 special handling this surface receives, is that it is not allowed to
175 deactivate it. Placement of this surface on an layer is done by the
176 other configuration described below.
178 - `surface_role` this configuration item specifies the name of the
179 main surface. Set this to e.g. `HomeScreen`.
183 This configuration item is a list of surface-name to layer mappings.
185 #### surface to layer mapping
189 "role": "^HomeScreen$",
190 "name": "HomeScreen",
192 "area": { "type": "full" },
193 "comment": "Single layer map for the HomeScreen"
196 "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
199 "area": { "type": "rect", "rect": { "x": 0, "y": 218, "width": -1, "height": -433 } },
200 "comment": "Range of IDs that will always be placed on layer 1001, negative rect values are interpreted as output_size.dimension - $value",
204 "name": "Navigation",
205 "main_match": "Navigation",
206 "sub_match": "HVAC|MediaPlayer",
212 "role": "^OnScreen.*",
215 "area": { "type": "rect", "rect": { "x": 0, "y": 760, "width": -1, "height": 400 } },
216 "comment": "Range of IDs that will always be placed on the popup layer, that gets a very high 'dummy' id of 9999"
220 Each mapping defines the following items to map corresponding surfaces
223 - `role` defines a regular expression that application drawing names
224 are matched against. If applications match this regular expression,
225 the surface will be visible on this layer.
227 - `name` is just a name definition for this layer, it has no
228 functional use apart from identifying a layer with a name.
230 - `layer_id` specifies which ID this layer will use.
232 - `area` is an object that defines the area assigned to surfaces.
234 - `split_layouts` is an optional item, that - if present - defines a
235 number of possible split-screen layouts for this layer.
239 Areas can be either `full` or `rect`, whereas `full` means a full-screen
240 layer, this is mostly useful for the main\_surface or HomeScreen layer.
241 `rect` declares a layer drawing area specified as a rectangle with start
242 coordinates `x` and `y` as well as its dimensions `width` and `height`.
244 The dimensions can be specified relative to the screen dimensions. For
245 this negative values for width and height must be used.
247 For example, a full-screen surface can have the following `rect`
255 A surface that leaves a 200pixel margin on the top and bottom can use
256 the following `rect` definition:
263 So the expression for the actual surface dimensions when using
264 screen-size-relative values will be:
266 actual_width = screen_width + 1 + width
267 actual_height = screen_height + 1 + height
269 Or in other words, to leave an `N` wide border around a surface, the
270 actual value in the dimension configuration needs to be `-N - 1`, and
271 appropriate offsets need to be set for `x` and `y`.
275 This configuration item allows the specification of split-screen layouts
276 on layers for certain surfaces.
278 A split screen layout always has a *main* surface and a *sub* surface.
279 In order to enter a split screen layout, first the *main* surface of the
280 layout must be activated, and then the *sub* surface. In order to
281 disable the split layout, one of the two participating surface must be
282 deactivated (or a surface on a layer below the current one must be
287 "name": "Navigation",
288 "main_match": "Navigation",
289 "sub_match": "HVAC|MediaPlayer",
293 A split layout object has the following attributes:
295 - `name` defines its name, it has no actual function other then a way
296 to identify this split layout.
298 - `main_match` is a regular expression that matches for the *main*
299 surface of this split layout.
301 - `sub_match` is a regular expression that matches for the *sub*
302 surface of this layout.
304 In the above example only the surface with drawing name
305 `Navigation` will be used as the *main* surface, and the surfaces
306 with drawing name `HVAC` or `MediaPlayer` can be used as a *sub* surface for
309 The names must still match the layer's role match!
311 <div id="Building\ and\ Running"></div>
316 <div id="Dependencies"></div>
321 Build dependencies are as follows:
323 - afb-daemon >= 1.0
325 - libsystemd >= 222
327 - wayland-client >= 1.11
329 - wayland-ivi-extension >= 2.0.2 (until eel, wayland-ivi-extension >= 1.13)
333 <div id="Supported environment"></div>
335 Supported environment
338 | Item | Description |
339 |:------------|:----------------------------------|
340 | AGL version | Electric Eel |
341 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
344 <div id="Build\ Configuration"></div>
350 If repo is already done, please start with git clone
355 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
360 Then you can get the following recipe.
362 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/agl-service-windowmanager-2017`
364 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/libwindowmanager`
369 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo
370 $ bitbake agl-demo-platform
373 <div id="Implementation\ Notes"></div>
378 The window manager is implemented as a app-framework-binder binding.
379 That means, the build produces one shared object that exports a binding
382 <div id="Structure"></div>
387 The implementation is loosely split across the following source files:
389 - `main.cpp`: The program entry point as used by the afb-daemon. This
390 file defines the afbBindingV2 symbol that is used by the afb-daemon
391 in order to load a binding. It also defines the wayland fd event
392 dispatcher and some globals to be used (as context for the afb calls
395 - `app.cpp` / `app.hpp`: This is the main window manager
396 logic implementation.
398 - `config.cpp` / `config.hpp`: Very simple configuration
401 - `controller_hooks.hpp`: hook functions called by the wayland
402 controller to call into the window manager instance. Only a very limited number
403 of events are passed to the window manager, which allowed the usage of
404 such a simple interface.
406 - `json_helper.cpp` / `json_helper.hpp`: Smaller json related
409 - `layers.cpp` / `layers.hpp`: Actually hold all the data from
410 layers.json configuration, do some transformations and service the
411 window manager implementation.
413 - `layout.cpp` / `layout.hpp`: Very simple layout state for the
414 implementation of split layouts and tracking of the
417 - `policy.hpp`: PolicyManager implementation stub. Gets passed the
418 current and new layout on layout switch and can decide upon it being
421 - `result.hpp`: Simple result class around
422 `std::experimental::optional` that additionally can hold a
423 `char const *` to describe the error.
425 - `util.cpp` / `util.hpp`: general utility functions and structs - and
426 preprocessor definitions (e.g. `log*()` to AFB logging functions.
428 - `wayland_ivi_wm.cpp` / `wayland_ivi_wm.hpp`: A C++ object-oriented
429 libwayland-client wrapper. It is instanced in `main.cpp` and handles
430 all our wayland needs. These files are in master. In eel, the name
431 of these files are `wayland.cpp` / `wayland.hpp`
433 <div id="Sequence"></div>
438 To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/windowmanager).
441 <div id="Binding\ API"></div>
446 Each function returns a reply containing at least a failed or successful
447 result of the call, additionally, when calls return something, it is
450 <div id="LibWindowmanager"></div>
455 This is the public interface of the class `LibWindowmanager`.
457 class LibWindowmanager
474 int init(int port, char const *token);
476 // Window manager API
477 int requestSurface(json_object *object);
478 int requestSurfaceXDG(json_object *object);
479 int activateSurface(json_object *object);
480 int deactivateSurface(json_object *object);
481 int endDraw(json_object *object);
482 int getDisplayInfo(json_object *object);
483 int getAreaInfo(json_object *in_obj, json_object *out_obj);
485 int getAreaInfo(const char *label, json_object *out_obj);
487 void set_event_handler(enum EventType et, handler_fun f);
491 <div id="Methods"></div>
496 ### init(int port, char const *token)
498 Initialize the Binding communication.
500 The `token` parameter is a string consisting of only alphanumeric characters.
501 If these conditions are not met, the LibWindowmanager instance will not initialize,
502 i.e. this call will return `-EINVAL`.
504 The `port` parameter is the port the afb daemon is listening on, an
505 invalid port will lead to a failure of the call and return `-EINVAL`.
507 ### requestSurface(json_object *object)
509 **args: `{ 'kKeyDrawingName': 'application name' }`**
510 This method requests a surface with the label given from the *Window Manager*.
511 It will return `surface id` a client application can use, and
512 `-errno` on failure. Additionally, on the standard error, messages are
513 logged to help debugging the issue.
515 ### requestSurfaceXDG(json_object *object)
517 **args: `{ 'kKeyDrawingName': 'application name', 'kKeyIviId': 'ivi id' }`**
518 This method is mainly intended for *xdglauncher* that controls xdg application such as chromium.
519 It will return `surface id` xdglauncher uses, and
520 `-errno` on failure. Additionally, on the standard error, messages are
521 logged to help debugging the issue.
523 ### activateSurface(json_object *object)
525 **args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }`**
526 This method is mainly intended for *manager* applications that control
527 other applications (think an application manager or the *HomeScreen*).
528 It instructs the window manager to activate the surface with the given
531 This method only is effective after the actual window or surface was
532 created by the application.
534 ### deactivateSurface(json_object *object)
536 **args: `{ 'kKeyDrawingName': 'application name' }`**
537 This method is mainly intended for *manager* applications that control other applications.
538 In adition, this is for applications that overrides other applications such like popup message.
539 In this case, popup surface requests to be hidden. It instructs the window manager to deactivate the surface associated with the given label. Note, that deactivating a surface also means to implicitly activate another (the last active or if not available *main surface* or *HomeScreen*.)
541 This method only is effective after the actual window or surface was
542 created by the application.
544 ### endDraw(json_object *object)
546 **args: `{ 'kKeyDrawingName': 'application name' }`**
547 This function is called from a client application when it is done
548 drawing its surface content.
550 It is not crucial to make this call at every time a drawing is finished
551 - it is mainly intended to allow the window manager to synchronize
552 drawing in case of layout switch. The exact semantics are explained in
553 the next [Events](#_events) Section.
555 ### getDisplayInfo(json_object *object)
558 This function gets the display information as follows:
564 It outputs the display information for json_object in the argument as follows:
565 `{"width_pixel": int value of width[pixel], "height_pixel": int value of height[pixel],
566 "width_mm": int value of width[mm], "height_mm": int value of height[mm]}`
568 It should be called after calling init().
569 It should not be called in the event handler because it occurs hang-up.
572 It uses wl_output::geometry() for getting physical width[mm] and height[mm] of the display,
573 but the value is different with measured value.
575 - value from wl_output::geometry(): width:320 height:520
576 - measured value : width:193 height:343
578 ### getAreaInfo(json_object *in_obj, json_object *out_obj)
580 **args1: `{ 'kKeyDrawingName': 'application name' }`**
582 This function gets the information of area drawn by the application as follows:
588 It outputs the area information for json_object in the 2nd argument as follows:
589 `{"x": int value of x-coordinate, "y": int value of y-coordinate,
590 "width": int value of width, "height": int value of height}`
592 It should be called after calling activateSurface().
593 It should not be called in the event handler because it occurs hang-up.
596 The same information can given by SyncDraw event.
598 ### getAreaInfo(const char *label, json_object *out_obj)
600 **args1: String of application name**
602 This function is same with `getAreaInfo(json_object *in_obj, json_object *out_obj)`,
603 but only has difference of 1st argument.
605 ### set\_event\_handler(enum EventType et, handler_fun f)
607 This method needs to be used to register event handlers for the WM
608 events described in the EventType enum. Only one hendler for each
609 EventType is possible, i.e. if it is called multiple times with the same
610 EventType the previous handler will be replaced.
612 The `func` handler functions will receive the label of the surface this
613 event is targeted at.
615 See Section [Events](#_events) for more detailed information about event
616 delivery to client applications.
618 <div id="Errors"></div>
623 Methods returning an `int` signal successful operation when returning
624 `0`. In case of an error, an error value is returned as a negative errno
625 value. E.g. `-EINVAL` to signal that some input value was invalid.
627 Additionally, logging of error messages is done on the standard error
628 file descriptor to help debugging the issue.
630 <div id="Usage"></div>
635 ### Initialization of LibWindowmanager
637 Before usage of the LibWindowmanager, the method `init()` must be
638 called once, it will return `-errno` in case of an error and log
639 diagnostic messages to stderr.
641 ### Request a surface
643 When creating a surface with *Qt* - it is necessary to request a surface
644 from the WM, internally this will communicate with the window manager
645 binding. Only after `requestSurface()` was successful, a surface should
648 This is also true for *QML* applications, where only after the
649 `requestSurface()` should the load of the resource be done. The method
650 returns `surface id` a client application can use
651 after the surface was requested successfully.
653 #### Workings of requestSurface()
655 `LibWindowmanager::requestSurface()` calls the AFB binding verb
656 `requestsurface` of the `windowmanager` API. This API call will return a
657 numeric ID to be used when creating the surface. This ID is never
658 explicitly returned to the client application, instead, it is set in the
659 application environment in order for *Qt* to then use it when creating
662 With the current *Qt* implementation this means, that only one surface
663 will be available to client applications, as subsequent windows will
664 increment this numeric ID internally - which then will lead to IDs that
665 cannot be known by the window manager as there is no direct
666 communication from *Qt* to the WM.
668 <div id="Events"></div>
673 Events are a way for the *Window Manager* to propagate information to
674 client applications. It was vital for the project to implement a number
675 of events, that mirror functionality that is already present in the
678 All events have the surface label as argument - a way to enable future
679 multi-surface applications.
681 As already stated above, this is currently not possible with the way
682 *Qt* implements its surface ID setting.
684 ### Active and Inactive Events
686 These events signal an application that it was activated or deactivated
687 respectively. Usually this means it was switched visible - which means
688 the surface will now be on the screen and therefor continue to render.
690 - `Active(json_object *object)`
691 args: { 'kKeyDrawingName': 'application name' }
692 Signal that the surface with the name
693 `kKeyDrawingName` is now active.
695 - `Inactive(json_object *object)`
696 args: { 'kKeyDrawingName': 'application name' }
697 Signal that the surface with the
698 name `kKeyDrawingName` is now inactive. This usually means, the layout
699 got changed, and the surface is now considered inactive
702 ### Visible and Invisible
704 These events signal an application that it was switched to be visible or
705 invisible respectively. These events also are handled implicitly through
706 the wayland protocol by means of `wl_surface::enter` and
707 `wl_surface::leave` events to the client.
709 - `Visible(json_object *object)`
710 args: { 'kKeyDrawingName': 'application name' }
711 Signal applications, that the
712 surface with name `kKeyDrawingName` is now visible.
714 - `Invisible(json_object *object)`
715 args: { 'kKeyDrawingName': 'application name' }
716 Signal applications that the
717 surface with name `kKeyDrawingName` is now invisible.
719 ### SyncDraw and FlushDraw
721 These events instruct applications that they should redraw their surface
722 contents - again, this is handled implicitly by the wayland protocol.
724 `SyncDraw` is sent to the application when it has to redraw its surface.
726 `FlushDraw` is sent to the application when it should swap its buffers,
727 that is *signal* the compositor that its surface contains new content.
729 - `SyncDraw(json_object *object)`
730 args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout',
731 'kKeyDrawingRect': { "x": int value of x-coordinate, "y": int value of y-coordinate,
732 "width": int value of width, "height": int value of height } }
733 Signal applications, that the
734 surface with name `kKeyDrawingArea` needs to redraw its content
735 in the layout with name `kKeyDrawingArea` - this
736 usually is sent when the surface geometry changed.
737 And the area position and size are included with name `kKeyDrawingRect`.
739 - `FlushDraw(json_object *object)`
740 args: { 'kKeyDrawingName': 'application name' }
741 Signal applications, that the
742 surface with name `kKeyDrawingArea` can now be swapped to its newly
743 drawn content as the window manager is ready to activate a new
744 layout (i.e. a new surface geometry).
746 <div id="Sample"></div>
751 In order to enable application to use the `WM` surface registration
752 function the above described steps need to be implemented.
754 As a minimal example the usage and initialization can look like the
757 Repo: `apps/agl-service-homescreen-2017`
758 Path: `sample/template/main.c`