summaryrefslogtreecommitdiffstats
path: root/doc/ApplicationGuide.md
blob: b74dfddf27866fb209879f8a1e9efe51ca280dda (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
**Window Manager Application Guide**
====
<div align="right">Revision: 0.2Final</div>
<div align="right">TOYOTA MOTOR CORPORATION</div>
<div align="right">23rd/Oct/2017</div>

* * *
## **<div id="Table\ of\ content">Table of content</div>**
- [Introduction](#Introduction)
	- [Intended audience](#Intended\ audience)
	- [Scope of this Document](#Scope\ of\ this\ Document)
	- [Known Issues](#Known\ Issues)
	- [External libraries](#External\ libraries)
	- [Client Library](#Client\ Library)
- [Concepts](#Concepts)
	- [Layers](#Layers)
	- [Surfaces](#Surfaces)
- [Configuration](#Configuration)
	- [Configuration Items](#Configuration\ Items)
- [Building and Running](#Building\ and\ Running)
	- [Dependencies](#Dependencies)
	- [Build Configuration](#Build\ Configuration)
- [Implementation Notes](#Implementation\ Notes)
	- [Binding code generation](#Binding\ code\ generation)
	- [Structure](#Structure)
- [Sequence](#Sequence)
- [Binding API](#Binding\ API)
	- [LibWindowmanager](#LibWindowmanager)
	- [Methods](#Methods)
	- [Errors](#Errors)
	- [Usage](#Usage)
	- [Events](#Events)
- [Sample](#Sample)


<div id="Introduction">Introduction</div>
============

This WindowManager implements simple layout switching of applications on
multiple layers and with different layer layouts.

<div id="Intended\ audience">Intended audience</div>
-----------------

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.

<div id="Scope\ of\ this\ Document">Scope of this Document</div>
----------------------

This document covers the window manager that was implemented for TMC and
delivered to the Automotive Grade Linux (AGL) project. It includes its
implementation details, concepts of operation, configuration and usage.

It does not include

-   documentation of the underlying architecture, see
    [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).

-   documentation of the AGL application framework and its technologies,
    see [AGL Application
    Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).

It is highly recommended to have a good understanding of these documents
and projects before using the window manager.

<div id="Known\ Issues">Known Issues</div>
------------

Currently there is a one known issues:

-   Only single-surface Qt applications are support through the
    libwindowmanager library. This is a limitation of how Qt creates surface
    IDs for the ivi-application interface.

<div id="External\ libraries">External libraries</div>
------------------

This project includes a copy of version 2.1.1 the excellent [C++11 JSON
library by Niels Lohmann](https://github.com/nlohmann/json).

<div id="Client\ Library">Client Library</div>
--------------

A client library implementation that internally uses the *libafbwsc*, is
provided in the subdirectory `libwindowmanager/` with its own documentation
directory.

The client library is built together with the window manager itself.

<div id="Concepts">Concepts</div>
========

The window manager implements a couple of concepts in order to allow
efficient implementation.

<div id="Layers">Layers</div>
------

Layers are entities that are stacked on top of each other. Each layer
has an ID which is used for the ivi-controller interface, but this ID
also implicitly specifies its stacking order, from lowest to highest.

Layers are always full-screen. We do not use layer dimensions as a way
to setup the scene, rather - each layer has a layout attached to it,
which specifies an area that is used by surfaces to draw on.

Additionally, layers will generally leave surfaces on below layers
activated, and only disable surfaces on layers the are above the
currently used layer.

It is possible to deactivate these surfaces on lower layers explicitly
using the `DeactivateSurface` API call.

<div id="Surfaces">Surfaces</div>
--------

Surfaces are *placed* on layers according to their name. The surface
will then be resized to dimensions, according to the layer's layout
configuration.


<div id="Configuration">Configuration</div>
=============

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.

A sample configuration is provided with the window manager
implementation, this sample is installed to /etc/layers.json.

<div id="Configuration\ Items">Configuration Items</div>
-------------------

This section describes configuration items available through
`layers.json`. It will do this, by first providing an example, and then
going into its components.

### main\_surface

    "main_surface": {
       "surface_role": "HomeScreen",
    },

The `main_surface` object describes a surface that will internally be
treated as the main surface - usually this mean *HomeScreen*. The only
special handling this surface receives, is that it is not allowed to
deactivate it. Placement of this surface on an layer is done by the
other configuration described below.

-   `surface_role` this configuration item specifies the name of the
    main surface. Set this to e.g. `HomeScreen`.

### mappings

This configuration item is a list of surface-name to layer mappings.

#### surface to layer mapping

    "mappings": [
      {
         "role": "^HomeScreen$",
         "name": "HomeScreen",
         "layer_id": 1000,
         "area": { "type": "full" },
         "comment": "Single layer map for the HomeScreen, XXX: type is redundant, could also check existence of id/first_id+last_id"
      },
      {
         "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
         "name": "apps",
         "layer_id": 1001,
         "area": { "type": "rect", "rect": { "x": 0, "y": 218, "width": -1, "height": -433 } },
         "comment": "Range of IDs that will always be placed on layer 1001, negative rect values are interpreted as output_size.dimension - $value",

         "split_layouts": [
            {
               "name": "Navigation",
               "main_match": "Navigation",
               "sub_match": "HVAC|MediaPlayer",
               "priority": 1000
            }
         ]
      },
      {
         "role": "^OnScreen.*",
         "name": "popups",
         "layer_id": 9999,
         "area": { "type": "rect", "rect": { "x": 0, "y": 760, "width": -1, "height": 400 } },
         "comment": "Range of IDs that will always be placed on the popup layer, that gets a very high 'dummy' id of 9999"
      }
    ]

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,
    the surface will be visible on this layer.

-   `name` is just a name definition for this layer, it has no
    functional use apart from identifying a layer with a name.

-   `layer_id` specifies which ID this layer will use.

-   `area` is an object that defines the area assigned to surfaces.

-   `split_layouts` is an optional item, that - if present - defines a
    number of possible split-screen layouts for this layer.

#### Area

Areas can be either `full` or `rect`, whereas `full` means a full-screen
layer, this is mostly useful for the main\_surface or HomeScreen layer.
`rect` declares a layer drawing area specified as a rectangle with start
coordinates `x` and `y` as well as its dimensions `width` and `height`.

The dimensions can be specified relative to the screen dimensions. For
this negative values for width and height mus be used.

For example, a full-screen surface can have the following `rect`
definition:

    "rect": { "x": 0,
              "y": 0,
              "width": -1,
              "height": -1 }

A surface that leaves a 200pixel margin on the top and bottom can use
the following `rect` definition:

    "rect": { "x": 0,
              "y": 200,
              "width": -1,
              "height": -401 }

So the expression for the actual surface dimensions when using
screen-size-relative values will be:

    actual_width = screen_width + 1 + width
    actual_height = screen_height + 1 + height

Or in other words, to leave an `N` wide border around a surface, the
actual value in the dimension configuration needs to be `-N - 1`, and
appropriate offsets need to be set for `x` and `y`.

#### split\_layouts

This configuration item allows the specification of split-screen layouts
on layers for certain surfaces.

A split screen layout always has a *main* surface and a *sub* surface.
In order to enter a split screen layout, first the *main* surface of the
layout must be activated, and then the *sub* surface. In order to
disable the split layout, one of the two participating surface must be
deactivated (or a surface on a layer below the current one must be
activated).

    "split_layouts": [
       {
           "name": "Navigation",
           "main_match": "Navigation",
           "sub_match": "HVAC|MediaPlayer",
       }
    ]

A split layout object has the following attributes:

-   `name` defines its name, it has no actual function other then a way
    to identify this split layout.

-   `main_match` is a regular expression that matches for the *main*
    surface of this split layout.

-   `sub_match` is a regular expression that matches for the *sub*
    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
this layout.

The names must still match the layer’s role match!

<div id="Building\ and\ Running">Building and Running</div>
====================

<div id="Dependencies">Dependencies</div>
------------

This project is intended to be build with the 4.0 release of AGL.

Build dependencies are as follows:

-   afb-daemon &gt;= 1.0

-   libsystemd &gt;= 222

-   wayland-client &gt;= 1.11

-   cmake &gt;= 3.6.1

<div id="Build\ Configuration">Build Configuration</div>
-------------------

**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 sync
$ git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework

```

Then you can get the following recipe.
* `meta-hmi-framework/windowmanager`


**Bitbake**
```
$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
$ bitbake agl-service-windowmanager-2017
```


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.


<div id="Implementation\ Notes">Implementation Notes</div>
====================

The window manager is implemented as a app-framework-binder binding.
That means, the build produces one shared object that exports a binding
interface.

<div id="Binding\ code\ generation">Binding code generation</div>
-----------------------

The binding API is rather simple; functions receive a json object
describing arguments and return a json object describing the result or
an error. In order to simplify development, the
`generate-binding-glue.py` script was added, that contains a description
of the API as a python dictionary. This script generates the header
`afb_binding_api.hpp` and the afb binding functions as
`afb_binding_glue.inl`. Where the latter is included in `main.cpp`.

Each function for the AFB binding that is generated does the following:

-   Lock the binding mutex, so that we serialize all access to
    the binding.

-   Do some debug logging (if wanted).

-   Check the binding state, i.e. the compositor might have exited
    unexpectedly at which point it would not make sense to continue.

-   Extract the arguments from the json object that is provided (doing
    some primitive type checking).

-   Call the afb\_binding\_api method corresponding to this binding
    function

-   Check the afb\_binding\_api’s function return value, log an error
    state and return the result to the afb request.

The generated functions do also check for any "loose" exception that
comes out of the afb\_binding\_api call (which in turn might call the
actual non-trivial implementation in `App`). However, **IF** an
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).

<div id="Structure">Structure</div>
---------

The implementation is loosely split across the following source files:

-   `main.cpp`: The program entry point as used by the afb-daemon. This
    file defines the afbBindingV2 symbol tat is used by the afb-daemon
    in order to load a binding. It also defines the wayland fd event
    dispatcher and some globals to be used (as context for the afb calls
    we receive).

-   `afb_binding_api.cpp`: The implementation of the afb
    binding functions. The actual functions are generated by
    `generate-binding-glue.py` which generates a **.inl** file that is
    included by `main.cpp`.

-   `app.cpp` / `app.hpp`: This is the main application
    logic implementation.

-   `config.cpp` / `config.hpp`: Very simple configuration
    item interface.

-   `controller_hooks.hpp`: hook functions called by the wayland
    controller to call into the App instance. Only a very limited number
    of events are passed to the Application, which allowed the usage of
    such a simple interface.

-   `json_helper.cpp` / `json_helper.hpp`: Smaller json related
    helper functions.

-   `layers.cpp` / `layers.hpp`: Actually hold all the data from
    layers.json configuration, do some transformations and service the
    App implementation.

-   `layout.cpp` / `layout.hpp`: Very simple layout state for the
    implementation of split layouts and tracking of the
    surfaces involved.

-   `policy.hpp`: PolicyManager implementation stub. Gets passed the
    current and new layout on layout switch and can decide upon it being
    valid or not.

-   `result.hpp`: Simple result class around
    `std::experimental::optional` that additionally can hold a
    `char const *` to describe the error.

-   `util.cpp` / `util.hpp`: general utility functions and structs - and
    preprocessor definitions (e.g. `log*()` to AFB logging functions.

-   `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
    libwayland-client wrapper. It is instanced in `main.cpp` and handles
    all our wayland needs.

<div id="Sequence">Sequence</div>
===============

To understand the sequence between application and window manager, refer to the [spec documentation](https://wiki.automotivelinux.org/windowmanager).


<div id="Binding\ API">Binding API</div>
===============

Each function returns a reply containing at least a failed or successful
result of the call, additionally, when calls return something, it is
noted.

<div id="LibWindowmanager">LibWindowmanager</div>
------

This is the public interface of the class `LibWindowmanager`.

    class LibWindowmanager
    {
    public:
        LibWindowmanager();
        ~LibWindowmanager();

        enum EventType {
           Event_Active = 0,
           Event_Inactive,

           Event_Visible,
           Event_Invisible,

           Event_SyncDraw,
           Event_FlushDraw,
        };

        int init(int port, char const *token);

        // WM API
        int requestSurface(json_object *object);
        int activateSurface(json_object *object);
        int deactivateSurface(json_object *object);
        int endDraw(json_object *object);

        void set_event_handler(enum EventType et, handler_fun f);

    };

<div id="Methods">Methods</div>
-------

### init(int port, char const *token)

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,
i.e. this call will return `-EINVAL`.

The `port` parameter is the port the afb daemon is listening on, an
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
`-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'  }`**
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
*label*.

This method only is effective after the actual window or surface was
created by the application.

### deactivateSurface(json_object *object)

**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
surface also means to implicitly activate another (the last active or if
not available *main surface* or *HomeScreen*.)

This method only is effective after the actual window or surface was
created by the application.

### endDraw(json_object *object)

**args: `{ 'kKeyDrawingName': 'application name' }`**
This function is called from a client application when it is done
drawing its surface content.

It is not crucial to make this call at every time a drawing is finished
- it is mainly intended to allow the window manager to synchronize
drawing in case of layout switch. The exact semantics are explained in
the next [Events](#_events) Section.

### set\_event\_handler(enum EventType et, handler_fun f)

This method needs to be used to register event handlers for the WM
events described in the EventType enum. Only one hendler for each
EventType is possible, i.e. if it is called multiple times with the same
EventType the previous handler will be replaced.

The `func` handler functions will receive the label of the surface this
event is targeted at.

See Section [Events](#_events) for mor detailed information about event
delivery to client applications.

<div id="Errors">Errors</div>
------

Methods returning an `int` signal successful operation when returning
`0`. In case of an error, an error value is returned as a negative errno
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.

<div id="Usage">Usage</div>
-----

### Initialization of LibWindowmanager

Before usage of the LibWindowmanager, the method `init()` must be
called once, it will return `-errno` in case of en error and log
diagnostic messages to stderr.

### Request a surface

When creating a surface with *Qt* - it is necessary to request a surface
from the WM, internally this will communicate with the window manager
binding. Only after `requestSurface()` was successful, a surface should
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.

#### Workings of requestSurface()

`LibWindowmanager::requestSurface()` calls the AFB binding verb
`requestsurface` of the `windowmanager` API. This API call will return a
numeric ID to be used when creating the surface. This ID is never
explicitly returned to the client application, instead, it is set in the
application environment in order for *Qt* to then use it when creating
the surface.

With the current *Qt* implementation this means, that only one surface
will be available to client applications, as subsequent windows will
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.

<div id="Events">Events</div>
------

Events are a way for the *Window Manager* to propagate information to
client applications. It was vital for the project to implement a number
of events, that mirror functionality that is already present in the
wayland protocol.

All events have the surface label as argument - a way to enable future
multi-surface applications.

As already stated above, this is currently not possible with the way
*Qt* implements its surface ID setting.

### Active and Inactive Events

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' }
    Signal that the surface with the name
    `kKeyDrawingName` is now active.

-   `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
    (or sleeping).

### Visible and Invisible

These events signal an application that it was switched to be visible or
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' }
    Signal applications, that the
    surface with name `kKeyDrawingName` is now visible.

-   `Invisible(json_object *object)`
    args: { 'kKeyDrawingName': 'application name' }
    Signal applications that the
    surface with name `kKeyDrawingName` is now invisible.

### SyncDraw and FlushDraw

These events instruct applications that they should redraw their surface
contents - again, this is handled implicitly by the wayland protocol.

`SyncDraw` is sent to the application when it has to redraw its surface.

`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'  }
    Signal applications, that the
    surface with name `kKeyDrawingArea` needs to redraw its content - this
    usually is sent when the surface geometry changed.

-   `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).

<div id="Sample">Sample</div>
============

In order to enable application to use the `WM` surface registration
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`