1 **Window Manager Application Guide**
3 <div align="right">Revision: 0.2Final</div>
4 <div align="right">TOYOTA MOTOR CORPORATION</div>
5 <div align="right">23rd/Oct/2017</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 - [Binding code generation](#Binding\ code\ generation)
28 - [Structure](#Structure)
29 - [Sequence](#Sequence)
30 - [Binding API](#Binding\ API)
31 - [LibWindowmanager](#LibWindowmanager)
39 <div id="Introduction"></div>
44 This WindowManager implements simple layout switching of applications on
45 multiple layers and with different layer layouts.
47 <div id="Intended\ audience"></div>
52 This documentation is intended for developers and system integrators who
53 need to know, how the window manager works and how it is to be used.
55 <div id="Scope\ of\ this\ Document"></div>
57 Scope of this Document
58 ----------------------
60 This document covers the window manager that was implemented for TMC and
61 delivered to the Automotive Grade Linux (AGL) project. It includes its
62 implementation details, concepts of operation, configuration and usage.
66 - documentation of the underlying architecture, see
67 [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
69 - documentation of the AGL application framework and its technologies,
71 Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
73 It is highly recommended to have a good understanding of these documents
74 and projects before using the window manager.
76 <div id="Known\ Issues"></div>
81 Currently there is a one known issues:
83 - Only single-surface Qt applications are support through the
84 libwindowmanager library. This is a limitation of how Qt creates surface
85 IDs for the ivi-application interface.
87 <div id="External\ libraries"></div>
92 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
93 library by Niels Lohmann](https://github.com/nlohmann/json).
95 <div id="Client\ Library"></div>
100 A client library implementation that internally uses the *libafbwsc*, is
101 provided in the `libwindowmanager`.
103 <div id="Concepts"></div>
108 The window manager implements a couple of concepts in order to allow
109 efficient implementation.
111 <div id="Layers"></div>
116 Layers are entities that are stacked on top of each other. Each layer
117 has an ID which is used for the ivi-controller interface, but this ID
118 also implicitly specifies its stacking order, from lowest to highest.
120 Layers are always full-screen. We do not use layer dimensions as a way
121 to setup the scene, rather - each layer has a layout attached to it,
122 which specifies an area that is used by surfaces to draw on.
124 Additionally, layers will generally leave surfaces on below layers
125 activated, and only disable surfaces on layers the are above the
126 currently used layer.
128 It is possible to deactivate these surfaces on lower layers explicitly
129 using the `DeactivateSurface` API call.
131 <div id="Surfaces"></div>
136 Surfaces are *placed* on layers according to their name. The surface
137 will then be resized to dimensions, according to the layer's layout
141 <div id="Configuration"></div>
146 The window manager is configured with the *layers.json* configuration
147 file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`.
148 Note, that the WM will not run unless this configuration is found and valid.
150 A sample configuration is provided with the window manager
151 implementation, this sample is installed to ${AFM_APP_INSTALL_DIR}/etc/layers.json.
153 <div id="Configuration\ Items"></div>
158 This section describes configuration items available through
159 `layers.json`. It will do this, by first providing an example, and then
160 going into its components.
165 "surface_role": "HomeScreen",
168 The `main_surface` object describes a surface that will internally be
169 treated as the main surface - usually this mean *HomeScreen*. The only
170 special handling this surface receives, is that it is not allowed to
171 deactivate it. Placement of this surface on an layer is done by the
172 other configuration described below.
174 - `surface_role` this configuration item specifies the name of the
175 main surface. Set this to e.g. `HomeScreen`.
179 This configuration item is a list of surface-name to layer mappings.
181 #### surface to layer mapping
185 "role": "^HomeScreen$",
186 "name": "HomeScreen",
188 "area": { "type": "full" },
189 "comment": "Single layer map for the HomeScreen"
192 "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
195 "area": { "type": "rect", "rect": { "x": 0, "y": 218, "width": -1, "height": -433 } },
196 "comment": "Range of IDs that will always be placed on layer 1001, negative rect values are interpreted as output_size.dimension - $value",
200 "name": "Navigation",
201 "main_match": "Navigation",
202 "sub_match": "HVAC|MediaPlayer",
208 "role": "^OnScreen.*",
211 "area": { "type": "rect", "rect": { "x": 0, "y": 760, "width": -1, "height": 400 } },
212 "comment": "Range of IDs that will always be placed on the popup layer, that gets a very high 'dummy' id of 9999"
216 Each mapping defines the following items to map corresponding surfaces
219 - `role` defines a regular expression that application drawing names
220 are matched against. If applications match this regular expression,
221 the surface will be visible on this layer.
223 - `name` is just a name definition for this layer, it has no
224 functional use apart from identifying a layer with a name.
226 - `layer_id` specifies which ID this layer will use.
228 - `area` is an object that defines the area assigned to surfaces.
230 - `split_layouts` is an optional item, that - if present - defines a
231 number of possible split-screen layouts for this layer.
235 Areas can be either `full` or `rect`, whereas `full` means a full-screen
236 layer, this is mostly useful for the main\_surface or HomeScreen layer.
237 `rect` declares a layer drawing area specified as a rectangle with start
238 coordinates `x` and `y` as well as its dimensions `width` and `height`.
240 The dimensions can be specified relative to the screen dimensions. For
241 this negative values for width and height mus be used.
243 For example, a full-screen surface can have the following `rect`
251 A surface that leaves a 200pixel margin on the top and bottom can use
252 the following `rect` definition:
259 So the expression for the actual surface dimensions when using
260 screen-size-relative values will be:
262 actual_width = screen_width + 1 + width
263 actual_height = screen_height + 1 + height
265 Or in other words, to leave an `N` wide border around a surface, the
266 actual value in the dimension configuration needs to be `-N - 1`, and
267 appropriate offsets need to be set for `x` and `y`.
271 This configuration item allows the specification of split-screen layouts
272 on layers for certain surfaces.
274 A split screen layout always has a *main* surface and a *sub* surface.
275 In order to enter a split screen layout, first the *main* surface of the
276 layout must be activated, and then the *sub* surface. In order to
277 disable the split layout, one of the two participating surface must be
278 deactivated (or a surface on a layer below the current one must be
283 "name": "Navigation",
284 "main_match": "Navigation",
285 "sub_match": "HVAC|MediaPlayer",
289 A split layout object has the following attributes:
291 - `name` defines its name, it has no actual function other then a way
292 to identify this split layout.
294 - `main_match` is a regular expression that matches for the *main*
295 surface of this split layout.
297 - `sub_match` is a regular expression that matches for the *sub*
298 surface of this layout.
300 In the above example only the surface with drawing name
301 `Navigation` will be used as the *main* surface, and the surfaces
302 with drawing name `HVAC` or `MediaPlayer` can be used as a *sub* surface for
305 The names must still match the layer's role match!
307 <div id="Building\ and\ Running"></div>
312 <div id="Dependencies"></div>
317 This project is intended to be build with the 4.0 release of AGL.
319 Build dependencies are as follows:
321 - afb-daemon >= 1.0
323 - libsystemd >= 222
325 - wayland-client >= 1.11
329 <div id="Supported environment"></div>
331 Supported environment
334 | Item | Description |
335 |:------------|:----------------------------------|
336 | AGL version | Electric Eel |
337 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
340 <div id="Build\ Configuration"></div>
346 If repo is already done, please start with git clone
351 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
356 Then you can get the following recipe.
358 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/agl-service-windowmanager-2017`
360 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/libwindowmanager`
365 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
366 $ bitbake agl-demo-platform
369 <div id="Implementation\ Notes"></div>
374 The window manager is implemented as a app-framework-binder binding.
375 That means, the build produces one shared object that exports a binding
378 <div id="Binding\ code\ generation"></div>
380 Binding code generation
381 -----------------------
383 The binding API is rather simple; functions receive a json object
384 describing arguments and return a json object describing the result or
385 an error. In order to simplify development, the
386 `generate-binding-glue.py` script was added, that contains a description
387 of the API as a python dictionary. This script generates the header
388 `afb_binding_api.hpp` and the afb binding functions as
389 `afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
391 Each function for the AFB binding that is generated does the following:
393 - Lock the binding mutex, so that we serialize all access to
396 - Do some debug logging (if wanted).
398 - Check the binding state, i.e. the compositor might have exited
399 unexpectedly at which point it would not make sense to continue.
401 - Extract the arguments from the json object that is provided (doing
402 some primitive type checking).
404 - Call the afb\_binding\_api method corresponding to this binding
407 - Check the afb\_binding\_api’s function return value, log an error
408 state and return the result to the afb request.
410 The generated functions do also check for any "loose" exception that
411 comes out of the afb\_binding\_api call (which in turn might call the
412 actual non-trivial implementation in `App`). However, **IF** an
413 exception is thrown and not handled inside the afb\_binding\_call, that
414 internal state of the window manager might be broken at this time (hence
415 the talkative error log).
417 <div id="Structure"></div>
422 The implementation is loosely split across the following source files:
424 - `main.cpp`: The program entry point as used by the afb-daemon. This
425 file defines the afbBindingV2 symbol tat is used by the afb-daemon
426 in order to load a binding. It also defines the wayland fd event
427 dispatcher and some globals to be used (as context for the afb calls
430 - `afb_binding_api.cpp`: The implementation of the afb
431 binding functions. The actual functions are generated by
432 `generate-binding-glue.py` which generates a **.inl** file that is
433 included by `main.cpp`.
435 - `app.cpp` / `app.hpp`: This is the main application
436 logic implementation.
438 - `config.cpp` / `config.hpp`: Very simple configuration
441 - `controller_hooks.hpp`: hook functions called by the wayland
442 controller to call into the App instance. Only a very limited number
443 of events are passed to the Application, which allowed the usage of
444 such a simple interface.
446 - `json_helper.cpp` / `json_helper.hpp`: Smaller json related
449 - `layers.cpp` / `layers.hpp`: Actually hold all the data from
450 layers.json configuration, do some transformations and service the
453 - `layout.cpp` / `layout.hpp`: Very simple layout state for the
454 implementation of split layouts and tracking of the
457 - `policy.hpp`: PolicyManager implementation stub. Gets passed the
458 current and new layout on layout switch and can decide upon it being
461 - `result.hpp`: Simple result class around
462 `std::experimental::optional` that additionally can hold a
463 `char const *` to describe the error.
465 - `util.cpp` / `util.hpp`: general utility functions and structs - and
466 preprocessor definitions (e.g. `log*()` to AFB logging functions.
468 - `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
469 libwayland-client wrapper. It is instanced in `main.cpp` and handles
470 all our wayland needs.
472 <div id="Sequence"></div>
477 To understand the sequence between application and window manager, refer to the [spec documentation](https://wiki.automotivelinux.org/windowmanager).
480 <div id="Binding\ API"></div>
485 Each function returns a reply containing at least a failed or successful
486 result of the call, additionally, when calls return something, it is
489 <div id="LibWindowmanager"></div>
494 This is the public interface of the class `LibWindowmanager`.
496 class LibWindowmanager
513 int init(int port, char const *token);
516 int requestSurface(json_object *object);
517 int activateSurface(json_object *object);
518 int deactivateSurface(json_object *object);
519 int endDraw(json_object *object);
521 void set_event_handler(enum EventType et, handler_fun f);
525 <div id="Methods"></div>
530 ### init(int port, char const *token)
532 Initialize the Binding communication.
534 The `token` parameter is a string consisting of only alphanumeric characters.
535 If these conditions are not met, the LibWindowmanager instance will not initialize,
536 i.e. this call will return `-EINVAL`.
538 The `port` parameter is the port the afb daemon is listening on, an
539 invalid port will lead to a failure of the call and return `-EINVAL`.
541 ### requestSurface(json_object *object)
543 **args: `{ 'kKeyDrawingName': 'application name' }`**
544 This method requests a surface with the label given from the *Window Manager*.
545 It will return `surface id` a client application can use, and
546 `-errno` on failure. Additionally, on the standard error, messages are
547 logged to help debgging the issue.
549 ### activateSurface(json_object *object)
551 **args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }`**
552 This method is mainly intended for *manager* applications that control
553 other applications (think an application manager or the *HomeScreen*).
554 It instructs the window manager to activate the surface with the given
557 This method only is effective after the actual window or surface was
558 created by the application.
560 ### deactivateSurface(json_object *object)
562 **args: `{ 'kKeyDrawingName': 'application name' }`**
563 This method is mainly intended for *manager* applications that control
564 other applications. It instructs the window manager to deactivate the
565 surface associated with the given label. Note, that deactivating a
566 surface also means to implicitly activate another (the last active or if
567 not available *main surface* or *HomeScreen*.)
569 This method only is effective after the actual window or surface was
570 created by the application.
572 ### endDraw(json_object *object)
574 **args: `{ 'kKeyDrawingName': 'application name' }`**
575 This function is called from a client application when it is done
576 drawing its surface content.
578 It is not crucial to make this call at every time a drawing is finished
579 - it is mainly intended to allow the window manager to synchronize
580 drawing in case of layout switch. The exact semantics are explained in
581 the next [Events](#_events) Section.
583 ### set\_event\_handler(enum EventType et, handler_fun f)
585 This method needs to be used to register event handlers for the WM
586 events described in the EventType enum. Only one hendler for each
587 EventType is possible, i.e. if it is called multiple times with the same
588 EventType the previous handler will be replaced.
590 The `func` handler functions will receive the label of the surface this
591 event is targeted at.
593 See Section [Events](#_events) for mor detailed information about event
594 delivery to client applications.
596 <div id="Errors"></div>
601 Methods returning an `int` signal successful operation when returning
602 `0`. In case of an error, an error value is returned as a negative errno
603 value. E.g. `-EINVAL` to signal that some input value was invalid.
605 Additionally, logging of error messages is done on the standard error
606 file descriptor to help debugging the issue.
608 <div id="Usage"></div>
613 ### Initialization of LibWindowmanager
615 Before usage of the LibWindowmanager, the method `init()` must be
616 called once, it will return `-errno` in case of en error and log
617 diagnostic messages to stderr.
619 ### Request a surface
621 When creating a surface with *Qt* - it is necessary to request a surface
622 from the WM, internally this will communicate with the window manager
623 binding. Only after `requestSurface()` was successful, a surface should
626 This is also true for *QML* applications, where only after the
627 `requestSurface()` should the load of the resource be done. The method
628 returns `surface id` a client application can use
629 after the surface was requested successfully.
631 #### Workings of requestSurface()
633 `LibWindowmanager::requestSurface()` calls the AFB binding verb
634 `requestsurface` of the `windowmanager` API. This API call will return a
635 numeric ID to be used when creating the surface. This ID is never
636 explicitly returned to the client application, instead, it is set in the
637 application environment in order for *Qt* to then use it when creating
640 With the current *Qt* implementation this means, that only one surface
641 will be available to client applications, as subsequent windows will
642 increment this numeric ID internally - which then will lead to IDs that
643 cannot be known by the window manager as there is no direct
644 communication from *Qt* to the WM.
646 <div id="Events"></div>
651 Events are a way for the *Window Manager* to propagate information to
652 client applications. It was vital for the project to implement a number
653 of events, that mirror functionality that is already present in the
656 All events have the surface label as argument - a way to enable future
657 multi-surface applications.
659 As already stated above, this is currently not possible with the way
660 *Qt* implements its surface ID setting.
662 ### Active and Inactive Events
664 These events signal an application that it was activated or deactivated
665 respectively. Usually this means it was switched visible - which means
666 the surface will now be on the screen and therefor continue to render.
668 - `Active(json_object *object)`
669 args: { 'kKeyDrawingName': 'application name' }
670 Signal that the surface with the name
671 `kKeyDrawingName` is now active.
673 - `Inactive(json_object *object)`
674 args: { 'kKeyDrawingName': 'application name' }
675 Signal that the surface with the
676 name `kKeyDrawingName` is now inactive. This usually means, the layout
677 got changed, and the surface is now considered inactive
680 ### Visible and Invisible
682 These events signal an application that it was switched to be visible or
683 invisible respectively. These events also are handled implicitly through
684 the wayland protocol by means of `wl_surface::enter` and
685 `wl_surface::leave` events to the client.
687 - `Visible(json_object *object)`
688 args: { 'kKeyDrawingName': 'application name' }
689 Signal applications, that the
690 surface with name `kKeyDrawingName` is now visible.
692 - `Invisible(json_object *object)`
693 args: { 'kKeyDrawingName': 'application name' }
694 Signal applications that the
695 surface with name `kKeyDrawingName` is now invisible.
697 ### SyncDraw and FlushDraw
699 These events instruct applications that they should redraw their surface
700 contents - again, this is handled implicitly by the wayland protocol.
702 `SyncDraw` is sent to the application when it has to redraw its surface.
704 `FlushDraw` is sent to the application when it should swap its buffers,
705 that is *signal* the compositor that its surface contains new content.
707 - `SyncDraw(json_object *object)`
708 args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }
709 Signal applications, that the
710 surface with name `kKeyDrawingArea` needs to redraw its content
711 in the layout with name `kKeyDrawingArea` - this
712 usually is sent when the surface geometry changed.
714 - `FlushDraw(json_object *object)`
715 args: { 'kKeyDrawingName': 'application name' }
716 Signal applications, that the
717 surface with name `kKeyDrawingArea` can now be swapped to its newly
718 drawn content as the window manager is ready to activate a new
719 layout (i.e. a new surface geometry).
721 <div id="Sample"></div>
726 In order to enable application to use the `WM` surface registration
727 function the above described steps need to be implemented.
729 As a minimal example the usage and initialization can look like the
732 Repo: `apps/agl-service-homescreen-2017`
733 Path: `sample/template/main.c`