10 This WindowManager implements simple layout switching of applications on
11 multiple layers and with different layer layouts.
14 This documentation is intended for developers and system integrators
15 that need to know, how the window manager works and how it is to be used.
17 === Scope of this Document
18 This document covers the window manager that was implemented for TMC and
19 delivered to the Automotive Grade Linux (AGL) project. It includes its
20 implementation details, concepts of operation, configuration and usage.
24 * documentation of the underlying architecture, see
25 https://wiki.automotivelinux.org/hmiframework[HMI-Framework].
26 * documentation of the AGL application framework and its technologies,
27 see https://wiki.automotivelinux.org/agl-distro/app-framework[AGL
28 Application Framework].
30 It is highly recommended to have a good understanding of these documents
31 and projects before using the window manager.
34 Currently there are a couple of known issues:
36 * Weston seems not to redraw the screen correctly. When the window
37 manager makes scene changes in quick succession, Weston seems not to
38 redraw the screen correctly and also not send wl_surface::enter
39 events, which in turn leaves applications "dead" - i.e. not rendering
40 or showing up. We developed a simple secondary ivi-controller client
41 application *redraw_fixer* (See <<_redraw_fixer,redraw_fixer>> for more)
42 that listens for specific scene-change events and issues other commands
43 that should prompt a correct redraw - however, this does not work in
45 * Only single-surface Qt applications are support through the AFBClient
46 library. This is a limitation of how Qt creates surface IDs for the
47 ivi-application interface.
49 === External libraries
50 This project includes a copy of version 2.1.1 the excellent
51 https://github.com/nlohmann/json[C++11 JSON library by Niels Lohmann].
54 A client library implementation that internally uses the _libafbwsc_, is
55 provided in the subdirectory `client-lib/` with its own documentation
58 The client library is build together with the window manager itself.
61 The window manager implements a couple of concepts in order to allow
62 efficient implementation.
65 Layers are entities that are stacked on top of each other. Each layer
66 has an ID which is used for the ivi-controller interface, but this ID
67 also implicitly specifies its stacking order. That is, the screen render
68 order will be set according to the layer stacking which is determined by
71 Layers are always full-screen. We do not use layer dimensions as a way
72 to setup the scene, rather - each layer has a layout attached to it,
73 which specifies an area that is used by surfaces to draw on.
75 Additionally, layers will generally leave surfaces on below layers
76 activated, and only disable surfaces on layers the are above the
79 In order to deactivate surfaces on lower layer, it is possible to
80 deactivate these surfaces explicitly using the `DeactivateSurface` API
84 Surfaces are _placed_ on layers according to their name. The surface
85 will then be resized to dimensions, according to the layer's layout
89 The window manager is configured with the _layers.json_ configuration
90 file, by default it is searched in `/etc/layers.json` but through the
91 use of the environment variable `LAYERS_JSON` the WM can be instructed
92 to use different file. Note, that the WM will not run unless this
93 configuration is found and valid.
95 A sample configuration is provided with the window manager
96 implementation, this sample is installed to /etc/layers.json.
98 === Configuration Items
99 This section describes configuration items available through
100 `layers.json`. It will do this, by first providing an example, and then
101 going into its components.
106 "surface_role": "HomeScreen",
110 The `main_surface` object describes a surface that will internally be
111 treated as the main surface - usually this mean _HomeScreen_. The only
112 special handling this surface receives, is that it is not allowed to
113 deactivate it. Placement of this surface on an layer is done by the
114 other configuration described below.
116 * `surface_role` this configuration item specifies the name of the main
117 surface. Set this to e.g. `HomeScreen`.
120 This configuration item is a list of surface-name to layer mappings.
122 ===== surface to layer mapping
126 "role": "^HomeScreen$",
127 "name": "HomeScreen",
129 "area": { "type": "full" },
135 "area": { "type": "rect",
145 Each mapping defines the following items to map corresponding surfaces
148 * `role` defines a regular expression that application drawing names are
149 matched against. If applications match tis regular expression, the
150 surface will be visible on this layer.
151 * `name` is just a name definition for this layer, it has no functional use
152 apart from identifying a layer with a name.
153 * `layer_id` specifies which ID this layer will use.
154 * `area` is an object that defines the area assigned to surfaces.
155 * `split_layouts` is an optional item, that - if present - defines a
156 number of possible split-screen layouts for this layer.
159 Areas can be either `full` or `rect`, whereas `full` means a full-screen
160 layer, this is mostly useful for the main_surface or HomeScreen layer.
161 `rect` declares a layer drawing area specified as a rectangle with
162 start coordinates `x` and `y` as well as its dimensions `width` and
165 The dimensions can be specified relative to the screen dimensions. For
166 this negative values for width and height mus be used.
168 For example, a full-screen surface can have the following `rect`
178 A surface that leaves a 200pixel margin on the top and bottom can use
179 the following `rect` definition:
188 So the expression for the actual surface dimensions when using
189 screen-size-relative values will be:
192 actual_width = screen_width + 1 + width
193 actual_height = screen_height + 1 + height
196 Or in other words, to leave an `N` wide border around a surface, the
197 actual value in the configuration needs to be `-N - 1`.
200 this configuration item allows the specification of split-screen layouts
201 on layers for certain surfaces. A split screen layout always has a
202 _main_ surface and a _sub_ surface. In order to enter a split screen
203 layout, first the _main_ surface of the layout must be activated, and
204 then the _sub_ surface. In order to disable the split layout, one of the
205 two participating surface must be deactivate (or a surface on a layer
206 below the current one must be activated).
211 "name": "Media Player",
212 "main_match": "^App MPlayer Main$",
213 "sub_match": "^App MPlayer Sub",
218 A split layout object has the following attributes:
220 * `name` defines its name, it has no actual function other then a way to
221 identify this split layout.
222 * `main_match` is a regular expression that matches for the _main_
223 surface of this split layout.
224 * `sub_match` is a regular expression that matches for the _sub_ surface
227 In the above example only the surface with drawing name
228 `App MPlayer Main` will be used as the _main_ surface, but all surfaces
229 that begin with `App MPlayer Sub` can be used as a _sub_ surface for
234 The names must still match the layer's role match!
238 The binding API consists of a couple of AFB _verbs_ - that is; function
239 calls to the Window Manager.
241 === Verbs (Functions)
242 Each function returns a reply containing at least a failed or successful
243 result of the call, additionally, when calls return something, it is
246 * `RequestSurface(drawing_name: string): int`
247 Request a surface ID for the given name. This name and ID association
248 will live until the surface is destroyed (or e.g. the application
249 exits). Each surface that is managed by the window manager needs to
250 call this function first!
251 * `ActivateSurface(drawing_name: string)`
252 This function requests the activation of a surface. It usually is not
253 called by the application, but rather by the application framework or
255 * `DeactivateSurface(drawing_name: string)`
256 Request deactivation of a surface. This function is not usually called
257 by applications themselves, but rather by the application framework or
259 * `EndDraw(drawing_name: string)`
260 Signals the window manager, that the surface is finished drawing. This
261 is useful for consistent flicker-free layout switches, see the
262 Architecture document for details.
264 There are a couple of non-essential (mostly for debugging and
265 development) API calls:
267 * `list_drawing_names(): json`
268 List known surface _name_ to _ID_ associations.
270 Ping the window manager. Does also dispatch pending events if any.
271 * `debug_status(): json`
272 Returns a json representation of the current layers and surfaces known
273 to the window manager. This represents the wayland-ivi-extension
275 * `debug_surfaces(): json`
276 Returns a json representation of all surfaces known to the window
277 manager. This represents the wayland-ivi-extension properties of the
279 * `debug_layers(): json`
280 Returns the current layer configuration, as configured through
282 * `debug_terminate()`
283 Terminates the afb-daemon running the window manager binding, if the
284 environment variable `WINMAN_DEBUG_TERMINATE` is set.
287 The window manager broadcasts certain events (to all applications) that
288 signal information on the state of the surface regarding the current
291 * `Active(drawing_name: string)`
292 Signal that the surface with the name `drawing_name` is now active.
293 * `Inactive(drawing_name: string)`
294 Signal that the surface with the name `drawing_name` is now inactive.
295 This usually means, the layout got changed, and the surface is now
296 considered inactive (or sleeping).
297 * `Visible(drawing_name: string)`
298 Signal applications, that the surface with name `drawing_name` is now
300 * `Invisible(drawing_name: string)`
301 Signal applications that the surface with name `drawing_name` is now
303 * `SyncDraw(drawing_name: string)`
304 Signal applications, that the surface with name `drawing_name` needs
305 to redraw its content - this usually is sent when the surface geometry
307 * `FlushDraw(drawing_name: string)`
308 Signal to applications, that the surface with name `drawing_name` can
309 now be swapped to its newly drawn content as the window manager is
310 ready to activate a new layout (i.e. a new surface geometry).
312 === Binding API Usage
313 For a detailed description on how the binding API is supposed to be
314 used, refer to the Architecture document.
316 == Building and Running
319 This project is intended to be build with the 4.0 release of AGL.
321 Build dependencies are as follows:
325 * wayland-client >= 1.11
328 === Build Configuration
329 Use cmake to configure a build tree:
339 A couple of build options to configure the build are available:
341 * `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
342 output from the window manager, use --verbose three times on an
343 afb-daemon instance to see the debug messages.
344 * `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
345 used for a rather small portion of the window manager code. However,
346 it is used quite extensively in the AFBClient implementation.
348 By default these options will be disabled.
351 With the actual window manager implementation, two general utilities are
355 A shell script, that wraps `afb-client-demo` and issues commands to the
356 window manager using the AFB exposed API. It will call synchronously to
357 the WM, and output any events that are happening in the meantime.
358 Replies are printed to stdout using an failed/success annotation and a
359 dump of the actual json reply from the AFB. When found on the system, it
360 will use `pygmentize` to apply syntax highlighting to the returned JSON.
365 $ wm-request list_drawing_names
366 ON-REPLY 1:winman/list_drawing_names: OK
380 $ wm-request activatesurface App1
381 ON-REPLY 1:winman/activatesurface: OK
391 $ wm-request activatesurface AppThatDoesNotExist
392 ON-REPLY 1:winman/activatesurface: ERROR
397 "info":"Surface does not exist"
403 This utility is intended to be ran alongside the compositor, it will
404 listen for certain events regarding surfaces, and issue a couple of
405 other commands, to hopefully trigger a redraw of the surface in the
408 It will print messages for each acted-upon event, and exit when the
411 == Implementation Notes
412 The window manager is implemented as a app-framework-binder binding. That
413 means, the build produces one shared object that exports a binding
416 === Binding code generation
417 The binding API is rather simple; functions receive a json object
418 describing arguments and return a json object describing the result or
419 an error. In order to simplify development, the
420 `generate-binding-glue.py` script was added, that contains a description
421 of the API as a python dictionary. This script generates the header
422 `afb_binding_api.hpp` and the afb binding functions as
423 `afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
425 Each function for the AFB binding that is generated does the following:
427 * Lock the binding mutex, so that we serialize all access to the
429 * Do some debug logging (if wanted).
430 * Check the binding state, i.e. the compositor might have exited
431 unexpectedly at which point it would not make sense to continue.
432 * Extract the arguments from the json object that is provided (doing
433 some primitive type checking).
434 * Call the afb_binding_api method corresponding to this binding function
435 * Check the afb_binding_api's function return value, log an error state
436 and return the result to the afb request.
438 The generated functions do also check for any "loose" exception that
439 comes out of the afb_binding_api call (which in turn might call the
440 actual non-trivial implementation in `App`). However, *IF* an exception
441 is thrown and not handled inside the afb_binding_call, that internal
442 state of the window manager might be broken at this time (hence the
443 talkative error log).
446 The implementation is loosely split across the following source files:
448 * `main.cpp`: The program entry point as used by the afb-daemon. This
449 file defines the afbBindingV2 symbol tat is used by the afb-daemon in
450 order to load a binding. It also defines the wayland fd event
451 dispatcher and some globals to be used (as context for the afb calls
453 * `afb_binding_api.cpp`: The implementation of the afb binding
454 functions. The actual functions are generated by
455 `generate-binding-glue.py` which generates a *.inl* file that is
456 included by `main.cpp`.
457 * `app.cpp` / `app.hpp`: This is the main application logic
459 * `config.cpp` / `config.hpp`: Very simple configuration item interface.
460 * `controller_hooks.hpp`: hook functions called by the wayland
461 controller to call into the App instance. Only a very limited number
462 of events are passed to the Application, which allowed the usage of
463 such a simple interface.
464 * `json_helper.cpp` / `json_helper.hpp`: Smaller json related helper
466 * `layers.cpp` / `layers.hpp`: Actually hold all the data from
467 layers.json configuration, do some transformations and service the App
469 * `layout.cpp` / `layout.hpp`: Very simple layout state for the
470 implementation of split layouts and tracking of the surfaces involved.
471 * `policy.hpp`: PolicyManager implementation stub. Gets passed the
472 current and new layout on layout switch and can decide upon it being
474 * `result.hpp`: Simple result class around `std::experimental::optional`
475 that additionally can hold a `char const *` to describe the error.
476 * `util.cpp` / `util.hpp`: general utility functions and structs - and
477 preprocessor definitions (e.g. `log*()` to AFB logging functions.
478 * `wayland.cpp` / `wayland.hpp`: A C++ object-oriented libwayland-client
479 wrapper. It is instanced in `main.cpp` and handles all our wayland
483 // vim:set ft=asciidoc tw=72 spell spelllang=en_US: