Add agl-service-windowmanager-2017
[apps/agl-service-windowmanager-2017.git] / doc / ApplicationGuide.md
1 **Window Manager Application Guide**
2 ====
3 <div align="right">Revision: 0.2Beta</div>
4 <div align="right">TOYOTA MOTOR CORPORATION</div>
5 <div align="right">30th/Sep/2017</div>
6
7 * * *
8
9 Introduction
10 ============
11
12 This WindowManager implements simple layout switching of applications on
13 multiple layers and with different layer layouts.
14
15 Intended audience
16 -----------------
17
18 This documentation is intended for developers and system integrators who
19 need to know, how the window manager works and how it is to be used.
20
21 Scope of this Document
22 ----------------------
23
24 This document covers the window manager that was implemented for TMC and
25 delivered to the Automotive Grade Linux (AGL) project. It includes its
26 implementation details, concepts of operation, configuration and usage.
27
28 It does not include
29
30 -   documentation of the underlying architecture, see
31     [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
32
33 -   documentation of the AGL application framework and its technologies,
34     see [AGL Application
35     Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
36
37 It is highly recommended to have a good understanding of these documents
38 and projects before using the window manager.
39
40 Known Issues
41 ------------
42
43 Currently there is a one known issues:
44
45 -   Only single-surface Qt applications are support through the
46     libwindowmanager library. This is a limitation of how Qt creates surface
47     IDs for the ivi-application interface.
48
49 External libraries
50 ------------------
51
52 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
53 library by Niels Lohmann](https://github.com/nlohmann/json).
54
55 Client Library
56 --------------
57
58 A client library implementation that internally uses the *libafbwsc*, is
59 provided in the subdirectory `libwindowmanager/` with its own documentation
60 directory.
61
62 The client library is built together with the window manager itself.
63
64 Concepts
65 ========
66
67 The window manager implements a couple of concepts in order to allow
68 efficient implementation.
69
70 Layers
71 ------
72
73 Layers are entities that are stacked on top of each other. Each layer
74 has an ID which is used for the ivi-controller interface, but this ID
75 also implicitly specifies its stacking order, from lowest to highest.
76
77 Layers are always full-screen. We do not use layer dimensions as a way
78 to setup the scene, rather - each layer has a layout attached to it,
79 which specifies an area that is used by surfaces to draw on.
80
81 Additionally, layers will generally leave surfaces on below layers
82 activated, and only disable surfaces on layers the are above the
83 currently used layer.
84
85 It is possible to deactivate these surfaces on lower layers explicitly
86 using the `DeactivateSurface` API call.
87
88 Surfaces
89 --------
90
91 Surfaces are *placed* on layers according to their name. The surface
92 will then be resized to dimensions, according to the layer’s layout
93 configuration.
94
95 Binding API
96 ===========
97
98 The binding API consists of a couple of AFB *verbs* - that is; function
99 calls to the Window Manager.
100
101 Verbs (Functions)
102 -----------------
103
104 Each function returns a reply containing at least a failed or successful
105 result of the call, additionally, when calls return something, it is
106 noted. The notation used has the following meaning:
107
108     FunctionName(argument_name: argument_type)[: function_return_type]
109
110 Where the return type may be omitted if it is void.
111
112 -   `RequestSurface(drawing_name: string): int` Request a surface ID for
113     the given name. This name and ID association will live until the
114     surface is destroyed (or e.g. the application exits). Each surface
115     that is managed by the window manager needs to call this function
116     first!
117
118 -   `ActivateSurface(drawing_name: string)` This function requests the
119     activation of a surface. It usually is not called by the
120     application, but rather by the application framework or
121     the HomeScreen.
122
123 -   `DeactivateSurface(drawing_name: string)` Request deactivation of
124     a surface. This function is not usually called by applications
125     themselves, but rather by the application framework or
126     the HomeScreen.
127
128 -   `EndDraw(drawing_name: string)` Signals the window manager, that the
129     surface is finished drawing. This is useful for consistent
130     flicker-free layout switches, see the Architecture document
131     for details.
132
133 There are a couple of non-essential (mostly for debugging and
134 development) API calls:
135
136 -   `list_drawing_names(): json` List known surface *name* to
137     *ID* associations.
138
139 -   `ping()` Ping the window manager. Does also dispatch pending events
140     if any.
141
142 -   `debug_status(): json` Returns a json representation of the current
143     layers and surfaces known to the window manager. This represents the
144     wayland-ivi-extension object’s properties.
145
146 -   `debug_surfaces(): json` Returns a json representation of all
147     surfaces known to the window manager. This represents the
148     wayland-ivi-extension properties of the surfaces.
149
150 -   `debug_layers(): json` Returns the current layer configuration, as
151     configured through *layers.json*.
152
153 -   `debug_terminate()` Terminates the afb-daemon running the window
154     manager binding, if the environment variable
155     `WINMAN_DEBUG_TERMINATE` is set.
156
157 Events
158 ------
159
160 The window manager broadcasts certain events (to all applications) that
161 signal information on the state of the surface regarding the current
162 layout.
163
164 -   `Active(drawing_name: string)` Signal that the surface with the name
165     `drawing_name` is now active.
166
167 -   `Inactive(drawing_name: string)` Signal that the surface with the
168     name `drawing_name` is now inactive. This usually means, the layout
169     got changed, and the surface is now considered inactive
170     (or sleeping).
171
172 -   `Visible(drawing_name: string)` Signal applications, that the
173     surface with name `drawing_name` is now visible.
174
175 -   `Invisible(drawing_name: string)` Signal applications that the
176     surface with name `drawing_name` is now invisible.
177
178 -   `SyncDraw(drawing_name: string)` Signal applications, that the
179     surface with name `drawing_name` needs to redraw its content - this
180     usually is sent when the surface geometry changed.
181
182 -   `FlushDraw(drawing_name: string)` Signal to applications, that the
183     surface with name `drawing_name` can now be swapped to its newly
184     drawn content as the window manager is ready to activate a new
185     layout (i.e. a new surface geometry).
186
187 Binding API Usage
188 -----------------
189
190 For a detailed description on how the binding API is supposed to be
191 used, refer to the Architecture document.
192
193 Configuration
194 =============
195
196 The window manager is configured with the *layers.json* configuration
197 file, by default it is searched in `/etc/layers.json` but through the
198 use of the environment variable `LAYERS_JSON` the WM can be instructed
199 to use different file. Note, that the WM will not run unless this
200 configuration is found and valid.
201
202 A sample configuration is provided with the window manager
203 implementation, this sample is installed to /etc/layers.json.
204
205 Configuration Items
206 -------------------
207
208 This section describes configuration items available through
209 `layers.json`. It will do this, by first providing an example, and then
210 going into its components.
211
212 ### main\_surface
213
214     "main_surface": {
215        "surface_role": "HomeScreen",
216     },
217
218 The `main_surface` object describes a surface that will internally be
219 treated as the main surface - usually this mean *HomeScreen*. The only
220 special handling this surface receives, is that it is not allowed to
221 deactivate it. Placement of this surface on an layer is done by the
222 other configuration described below.
223
224 -   `surface_role` this configuration item specifies the name of the
225     main surface. Set this to e.g. `HomeScreen`.
226
227 ### mappings
228
229 This configuration item is a list of surface-name to layer mappings.
230
231 #### surface to layer mapping
232
233     "mappings": [
234        {
235           "role": "^HomeScreen$",
236           "name": "HomeScreen",
237           "layer_id": 1000,
238           "area": { "type": "full" },
239        },
240        {
241           "role": "MediaPlayer|Radio|Phone",
242           "name": "apps",
243           "layer_id": 1001,
244           "area": { "type": "rect",
245                     "rect": { "x": 0,
246                               "y": 100,
247                               "width": -1,
248                               "height": -201 } },
249           "split_layouts": []
250        }
251     ]
252
253 Each mapping defines the following items to map corresponding surfaces
254 to a layer.
255
256 -   `role` defines a regular expression that application drawing names
257     are matched against. If applications match tis regular expression,
258     the surface will be visible on this layer.
259
260 -   `name` is just a name definition for this layer, it has no
261     functional use apart from identifying a layer with a name.
262
263 -   `layer_id` specifies which ID this layer will use.
264
265 -   `area` is an object that defines the area assigned to surfaces.
266
267 -   `split_layouts` is an optional item, that - if present - defines a
268     number of possible split-screen layouts for this layer.
269
270 #### Area
271
272 Areas can be either `full` or `rect`, whereas `full` means a full-screen
273 layer, this is mostly useful for the main\_surface or HomeScreen layer.
274 `rect` declares a layer drawing area specified as a rectangle with start
275 coordinates `x` and `y` as well as its dimensions `width` and `height`.
276
277 The dimensions can be specified relative to the screen dimensions. For
278 this negative values for width and height mus be used.
279
280 For example, a full-screen surface can have the following `rect`
281 definition:
282
283     "rect": { "x": 0,
284               "y": 0,
285               "width": -1,
286               "height": -1 }
287
288 A surface that leaves a 200pixel margin on the top and bottom can use
289 the following `rect` definition:
290
291     "rect": { "x": 0,
292               "y": 200,
293               "width": -1,
294               "height": -401 }
295
296 So the expression for the actual surface dimensions when using
297 screen-size-relative values will be:
298
299     actual_width = screen_width + 1 + width
300     actual_height = screen_height + 1 + height
301
302 Or in other words, to leave an `N` wide border around a surface, the
303 actual value in the dimension configuration needs to be `-N - 1`, and
304 appropriate offsets need to be set for `x` and `y`.
305
306 #### split\_layouts
307
308 This configuration item allows the specification of split-screen layouts
309 on layers for certain surfaces.
310
311 A split screen layout always has a *main* surface and a *sub* surface.
312 In order to enter a split screen layout, first the *main* surface of the
313 layout must be activated, and then the *sub* surface. In order to
314 disable the split layout, one of the two participating surface must be
315 deactivated (or a surface on a layer below the current one must be
316 activated).
317
318     "split_layouts": [
319        {
320           "name": "Media Player",
321           "main_match": "^App MPlayer Main$",
322           "sub_match": "^App MPlayer Sub",
323        }
324     ]
325
326 A split layout object has the following attributes:
327
328 -   `name` defines its name, it has no actual function other then a way
329     to identify this split layout.
330
331 -   `main_match` is a regular expression that matches for the *main*
332     surface of this split layout.
333
334 -   `sub_match` is a regular expression that matches for the *sub*
335     surface of this layout.
336
337 In the above example only the surface with drawing name
338 `App MPlayer Main` will be used as the *main* surface, but all surfaces
339 that begin with `App MPlayer Sub` can be used as a *sub* surface for
340 this layout.
341
342 The names must still match the layer’s role match!
343
344 Building and Running
345 ====================
346
347 Dependencies
348 ------------
349
350 This project is intended to be build with the 4.0 release of AGL.
351
352 Build dependencies are as follows:
353
354 -   afb-daemon &gt;= 1.0
355
356 -   libsystemd &gt;= 222
357
358 -   wayland-client &gt;= 1.11
359
360 -   cmake &gt;= 3.6.1
361
362 Build Configuration
363 -------------------
364
365 **Download recipe**
366 If repo is already done, please start with git clone
367 ```
368 $ mkdir WORK
369 $ cd WORK
370 $ repo init -b dab -m dab_4.0.0_xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
371 $ repo sync
372 $ git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework
373
374 ```
375
376 Then you can get the following recipe.
377 * `meta-hmi-framework/windowmanager`
378
379
380 **Bitbake**
381 ```
382 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
383 $ bitbake agl-service-windowmanager-2017
384 ```
385
386
387 A couple of build options to configure the build are available:
388
389 -   `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
390     output from the window manager, use --verbose three times on an
391     afb-daemon instance to see the debug messages.
392
393 -   `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
394     used for a rather small portion of the window manager code. However,
395     it is used quite extensively in the libwindowmanager implementation.
396
397 By default these options will be disabled.
398
399
400 Implementation Notes
401 ====================
402
403 The window manager is implemented as a app-framework-binder binding.
404 That means, the build produces one shared object that exports a binding
405 interface.
406
407 Binding code generation
408 -----------------------
409
410 The binding API is rather simple; functions receive a json object
411 describing arguments and return a json object describing the result or
412 an error. In order to simplify development, the
413 `generate-binding-glue.py` script was added, that contains a description
414 of the API as a python dictionary. This script generates the header
415 `afb_binding_api.hpp` and the afb binding functions as
416 `afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
417
418 Each function for the AFB binding that is generated does the following:
419
420 -   Lock the binding mutex, so that we serialize all access to
421     the binding.
422
423 -   Do some debug logging (if wanted).
424
425 -   Check the binding state, i.e. the compositor might have exited
426     unexpectedly at which point it would not make sense to continue.
427
428 -   Extract the arguments from the json object that is provided (doing
429     some primitive type checking).
430
431 -   Call the afb\_binding\_api method corresponding to this binding
432     function
433
434 -   Check the afb\_binding\_api’s function return value, log an error
435     state and return the result to the afb request.
436
437 The generated functions do also check for any "loose" exception that
438 comes out of the afb\_binding\_api call (which in turn might call the
439 actual non-trivial implementation in `App`). However, **IF** an
440 exception is thrown and not handled inside the afb\_binding\_call, that
441 internal state of the window manager might be broken at this time (hence
442 the talkative error log).
443
444 Structure
445 ---------
446
447 The implementation is loosely split across the following source files:
448
449 -   `main.cpp`: The program entry point as used by the afb-daemon. This
450     file defines the afbBindingV2 symbol tat is used by the afb-daemon
451     in order to load a binding. It also defines the wayland fd event
452     dispatcher and some globals to be used (as context for the afb calls
453     we receive).
454
455 -   `afb_binding_api.cpp`: The implementation of the afb
456     binding functions. The actual functions are generated by
457     `generate-binding-glue.py` which generates a **.inl** file that is
458     included by `main.cpp`.
459
460 -   `app.cpp` / `app.hpp`: This is the main application
461     logic implementation.
462
463 -   `config.cpp` / `config.hpp`: Very simple configuration
464     item interface.
465
466 -   `controller_hooks.hpp`: hook functions called by the wayland
467     controller to call into the App instance. Only a very limited number
468     of events are passed to the Application, which allowed the usage of
469     such a simple interface.
470
471 -   `json_helper.cpp` / `json_helper.hpp`: Smaller json related
472     helper functions.
473
474 -   `layers.cpp` / `layers.hpp`: Actually hold all the data from
475     layers.json configuration, do some transformations and service the
476     App implementation.
477
478 -   `layout.cpp` / `layout.hpp`: Very simple layout state for the
479     implementation of split layouts and tracking of the
480     surfaces involved.
481
482 -   `policy.hpp`: PolicyManager implementation stub. Gets passed the
483     current and new layout on layout switch and can decide upon it being
484     valid or not.
485
486 -   `result.hpp`: Simple result class around
487     `std::experimental::optional` that additionally can hold a
488     `char const *` to describe the error.
489
490 -   `util.cpp` / `util.hpp`: general utility functions and structs - and
491     preprocessor definitions (e.g. `log*()` to AFB logging functions.
492
493 -   `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
494     libwayland-client wrapper. It is instanced in `main.cpp` and handles
495     all our wayland needs.
496
497