4 This WindowManager implements simple layout switching of applications on
5 multiple layers and with different layer layouts.
10 This documentation is intended for developers and system integrators who
11 need to know, how the window manager works and how it is to be used.
13 Scope of this Document
14 ----------------------
16 This document covers the window manager that was implemented for TMC and
17 delivered to the Automotive Grade Linux (AGL) project. It includes its
18 implementation details, concepts of operation, configuration and usage.
22 - documentation of the underlying architecture, see
23 [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
25 - documentation of the AGL application framework and its technologies,
27 Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
29 It is highly recommended to have a good understanding of these documents
30 and projects before using the window manager.
35 Currently there are a couple of known issues:
37 - Weston seems not to redraw the screen correctly. When the window
38 manager makes scene changes in quick succession, Weston seems not to
39 redraw the screen correctly and also not send wl\_surface::enter
40 events, which in turn leaves applications "dead" - i.e. not
41 rendering or showing up. We developed a simple secondary
42 ivi-controller client application **redraw\_fixer** (See
43 [redraw\_fixer](#_redraw_fixer) for more) that listens for specific
44 scene-change events and issues other commands that should prompt a
45 correct redraw - however, this does not work in all instances.
47 - Only single-surface Qt applications are support through the
48 AFBClient library. This is a limitation of how Qt creates surface
49 IDs for the ivi-application interface.
54 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
55 library by Niels Lohmann](https://github.com/nlohmann/json).
60 A client library implementation that internally uses the *libafbwsc*, is
61 provided in the subdirectory `client-lib/` with its own documentation
64 The client library is built together with the window manager itself.
69 The window manager implements a couple of concepts in order to allow
70 efficient implementation.
75 Layers are entities that are stacked on top of each other. Each layer
76 has an ID which is used for the ivi-controller interface, but this ID
77 also implicitly specifies its stacking order, from lowest to highest.
79 Layers are always full-screen. We do not use layer dimensions as a way
80 to setup the scene, rather - each layer has a layout attached to it,
81 which specifies an area that is used by surfaces to draw on.
83 Additionally, layers will generally leave surfaces on below layers
84 activated, and only disable surfaces on layers the are above the
87 It is possible to deactivate these surfaces on lower layers explicitly
88 using the `DeactivateSurface` API call.
93 Surfaces are *placed* on layers according to their name. The surface
94 will then be resized to dimensions, according to the layer’s layout
100 The binding API consists of a couple of AFB *verbs* - that is; function
101 calls to the Window Manager.
106 Each function returns a reply containing at least a failed or successful
107 result of the call, additionally, when calls return something, it is
108 noted. The notation used has the following meaning:
110 FunctionName(argument_name: argument_type)[: function_return_type]
112 Where the return type may be omitted if it is void.
114 - `RequestSurface(drawing_name: string): int` Request a surface ID for
115 the given name. This name and ID association will live until the
116 surface is destroyed (or e.g. the application exits). Each surface
117 that is managed by the window manager needs to call this function
120 - `ActivateSurface(drawing_name: string)` This function requests the
121 activation of a surface. It usually is not called by the
122 application, but rather by the application framework or
125 - `DeactivateSurface(drawing_name: string)` Request deactivation of
126 a surface. This function is not usually called by applications
127 themselves, but rather by the application framework or
130 - `EndDraw(drawing_name: string)` Signals the window manager, that the
131 surface is finished drawing. This is useful for consistent
132 flicker-free layout switches, see the Architecture document
135 There are a couple of non-essential (mostly for debugging and
136 development) API calls:
138 - `list_drawing_names(): json` List known surface *name* to
141 - `ping()` Ping the window manager. Does also dispatch pending events
144 - `debug_status(): json` Returns a json representation of the current
145 layers and surfaces known to the window manager. This represents the
146 wayland-ivi-extension object’s properties.
148 - `debug_surfaces(): json` Returns a json representation of all
149 surfaces known to the window manager. This represents the
150 wayland-ivi-extension properties of the surfaces.
152 - `debug_layers(): json` Returns the current layer configuration, as
153 configured through *layers.json*.
155 - `debug_terminate()` Terminates the afb-daemon running the window
156 manager binding, if the environment variable
157 `WINMAN_DEBUG_TERMINATE` is set.
162 The window manager broadcasts certain events (to all applications) that
163 signal information on the state of the surface regarding the current
166 - `Active(drawing_name: string)` Signal that the surface with the name
167 `drawing_name` is now active.
169 - `Inactive(drawing_name: string)` Signal that the surface with the
170 name `drawing_name` is now inactive. This usually means, the layout
171 got changed, and the surface is now considered inactive
174 - `Visible(drawing_name: string)` Signal applications, that the
175 surface with name `drawing_name` is now visible.
177 - `Invisible(drawing_name: string)` Signal applications that the
178 surface with name `drawing_name` is now invisible.
180 - `SyncDraw(drawing_name: string)` Signal applications, that the
181 surface with name `drawing_name` needs to redraw its content - this
182 usually is sent when the surface geometry changed.
184 - `FlushDraw(drawing_name: string)` Signal to applications, that the
185 surface with name `drawing_name` can now be swapped to its newly
186 drawn content as the window manager is ready to activate a new
187 layout (i.e. a new surface geometry).
192 For a detailed description on how the binding API is supposed to be
193 used, refer to the Architecture document.
198 The window manager is configured with the *layers.json* configuration
199 file, by default it is searched in `/etc/layers.json` but through the
200 use of the environment variable `LAYERS_JSON` the WM can be instructed
201 to use different file. Note, that the WM will not run unless this
202 configuration is found and valid.
204 A sample configuration is provided with the window manager
205 implementation, this sample is installed to /etc/layers.json.
210 This section describes configuration items available through
211 `layers.json`. It will do this, by first providing an example, and then
212 going into its components.
217 "surface_role": "HomeScreen",
220 The `main_surface` object describes a surface that will internally be
221 treated as the main surface - usually this mean *HomeScreen*. The only
222 special handling this surface receives, is that it is not allowed to
223 deactivate it. Placement of this surface on an layer is done by the
224 other configuration described below.
226 - `surface_role` this configuration item specifies the name of the
227 main surface. Set this to e.g. `HomeScreen`.
231 This configuration item is a list of surface-name to layer mappings.
233 #### surface to layer mapping
237 "role": "^HomeScreen$",
238 "name": "HomeScreen",
240 "area": { "type": "full" },
246 "area": { "type": "rect",
255 Each mapping defines the following items to map corresponding surfaces
258 - `role` defines a regular expression that application drawing names
259 are matched against. If applications match tis regular expression,
260 the surface will be visible on this layer.
262 - `name` is just a name definition for this layer, it has no
263 functional use apart from identifying a layer with a name.
265 - `layer_id` specifies which ID this layer will use.
267 - `area` is an object that defines the area assigned to surfaces.
269 - `split_layouts` is an optional item, that - if present - defines a
270 number of possible split-screen layouts for this layer.
274 Areas can be either `full` or `rect`, whereas `full` means a full-screen
275 layer, this is mostly useful for the main\_surface or HomeScreen layer.
276 `rect` declares a layer drawing area specified as a rectangle with start
277 coordinates `x` and `y` as well as its dimensions `width` and `height`.
279 The dimensions can be specified relative to the screen dimensions. For
280 this negative values for width and height mus be used.
282 For example, a full-screen surface can have the following `rect`
290 A surface that leaves a 200pixel margin on the top and bottom can use
291 the following `rect` definition:
298 So the expression for the actual surface dimensions when using
299 screen-size-relative values will be:
301 actual_width = screen_width + 1 + width
302 actual_height = screen_height + 1 + height
304 Or in other words, to leave an `N` wide border around a surface, the
305 actual value in the dimension configuration needs to be `-N - 1`, and
306 appropriate offsets need to be set for `x` and `y`.
310 This configuration item allows the specification of split-screen layouts
311 on layers for certain surfaces.
313 A split screen layout always has a *main* surface and a *sub* surface.
314 In order to enter a split screen layout, first the *main* surface of the
315 layout must be activated, and then the *sub* surface. In order to
316 disable the split layout, one of the two participating surface must be
317 deactivated (or a surface on a layer below the current one must be
322 "name": "Media Player",
323 "main_match": "^App MPlayer Main$",
324 "sub_match": "^App MPlayer Sub",
328 A split layout object has the following attributes:
330 - `name` defines its name, it has no actual function other then a way
331 to identify this split layout.
333 - `main_match` is a regular expression that matches for the *main*
334 surface of this split layout.
336 - `sub_match` is a regular expression that matches for the *sub*
337 surface of this layout.
339 In the above example only the surface with drawing name
340 `App MPlayer Main` will be used as the *main* surface, but all surfaces
341 that begin with `App MPlayer Sub` can be used as a *sub* surface for
344 The names must still match the layer’s role match!
352 This project is intended to be build with the 4.0 release of AGL.
354 Build dependencies are as follows:
356 - afb-daemon >= 1.0
358 - libsystemd >= 222
360 - wayland-client >= 1.11
367 Use cmake to configure a build tree:
375 A couple of build options to configure the build are available:
377 - `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
378 output from the window manager, use --verbose three times on an
379 afb-daemon instance to see the debug messages.
381 - `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
382 used for a rather small portion of the window manager code. However,
383 it is used quite extensively in the AFBClient implementation.
385 By default these options will be disabled.
390 With the actual window manager implementation, two general utilities are
396 A shell script, that wraps `afb-client-demo` and issues commands to the
397 window manager using the AFB exposed API. It will call synchronously to
398 the WM, and output any events that are happening in the meantime.
399 Replies are printed to stdout using an failed/success annotation and a
400 dump of the actual json reply from the AFB. When found on the system, it
401 will use `pygmentize` to apply syntax highlighting to the returned JSON.
405 $ wm-request list_drawing_names
406 ON-REPLY 1:winman/list_drawing_names: OK
420 $ wm-request activatesurface App1
421 ON-REPLY 1:winman/activatesurface: OK
431 $ wm-request activatesurface AppThatDoesNotExist
432 ON-REPLY 1:winman/activatesurface: ERROR
437 "info":"Surface does not exist"
444 This utility is intended to be ran alongside the compositor, it will
445 listen for certain events regarding surfaces, and issue a couple of
446 other commands, to hopefully trigger a redraw of the surface in the
449 It will print messages for each acted-upon event, and exit when the
455 The window manager is implemented as a app-framework-binder binding.
456 That means, the build produces one shared object that exports a binding
459 Binding code generation
460 -----------------------
462 The binding API is rather simple; functions receive a json object
463 describing arguments and return a json object describing the result or
464 an error. In order to simplify development, the
465 `generate-binding-glue.py` script was added, that contains a description
466 of the API as a python dictionary. This script generates the header
467 `afb_binding_api.hpp` and the afb binding functions as
468 `afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
470 Each function for the AFB binding that is generated does the following:
472 - Lock the binding mutex, so that we serialize all access to
475 - Do some debug logging (if wanted).
477 - Check the binding state, i.e. the compositor might have exited
478 unexpectedly at which point it would not make sense to continue.
480 - Extract the arguments from the json object that is provided (doing
481 some primitive type checking).
483 - Call the afb\_binding\_api method corresponding to this binding
486 - Check the afb\_binding\_api’s function return value, log an error
487 state and return the result to the afb request.
489 The generated functions do also check for any "loose" exception that
490 comes out of the afb\_binding\_api call (which in turn might call the
491 actual non-trivial implementation in `App`). However, **IF** an
492 exception is thrown and not handled inside the afb\_binding\_call, that
493 internal state of the window manager might be broken at this time (hence
494 the talkative error log).
499 The implementation is loosely split across the following source files:
501 - `main.cpp`: The program entry point as used by the afb-daemon. This
502 file defines the afbBindingV2 symbol tat is used by the afb-daemon
503 in order to load a binding. It also defines the wayland fd event
504 dispatcher and some globals to be used (as context for the afb calls
507 - `afb_binding_api.cpp`: The implementation of the afb
508 binding functions. The actual functions are generated by
509 `generate-binding-glue.py` which generates a **.inl** file that is
510 included by `main.cpp`.
512 - `app.cpp` / `app.hpp`: This is the main application
513 logic implementation.
515 - `config.cpp` / `config.hpp`: Very simple configuration
518 - `controller_hooks.hpp`: hook functions called by the wayland
519 controller to call into the App instance. Only a very limited number
520 of events are passed to the Application, which allowed the usage of
521 such a simple interface.
523 - `json_helper.cpp` / `json_helper.hpp`: Smaller json related
526 - `layers.cpp` / `layers.hpp`: Actually hold all the data from
527 layers.json configuration, do some transformations and service the
530 - `layout.cpp` / `layout.hpp`: Very simple layout state for the
531 implementation of split layouts and tracking of the
534 - `policy.hpp`: PolicyManager implementation stub. Gets passed the
535 current and new layout on layout switch and can decide upon it being
538 - `result.hpp`: Simple result class around
539 `std::experimental::optional` that additionally can hold a
540 `char const *` to describe the error.
542 - `util.cpp` / `util.hpp`: general utility functions and structs - and
543 preprocessor definitions (e.g. `log*()` to AFB logging functions.
545 - `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
546 libwayland-client wrapper. It is instanced in `main.cpp` and handles
547 all our wayland needs.