doc/WindowManagerTMC.txt

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