[staging/windowmanager.git] / doc / WindowManagerTMC.txt

= WindowManagerTMC
:doctype: book
:toc:
:icons:
:data-uri:
:lang: en
:encoding: utf-8

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

=== Intended audience
This documentation is intended for developers and system integrators
that need to know how the window manager works and how it is to be used.

=== Scope of this Document
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.

=== Known Issues
Currently there are a couple of known issues:

* Weston seems not to redraw the screen correctly. When the window
  manager makes scene changes in quick succession, Weston seems not to
  redraw the screen correctly and also not send wl_surface::enter
  events, which in turn leaves applications "dead" - i.e. not rendering
  or showing up. We developed a simple secondary ivi-controller client
  application *redraw_fixer* (See <<_redraw_fixer,redraw_fixer>> for more)
  that listens for specific scene-change events and issues other commands
  that should prompt a correct redraw - however, this does not work in
  all instances.
* Only single-surface Qt applications are support through the AFBClient
  library. This is a limitation of how Qt creates surface IDs for the
  ivi-application interface.

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

=== Layers
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. That is, the screen render
order will be set according to the layer stacking which is determined by
the layer IDs.

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.

In order to deactivate surfaces on lower layer, it is possible to
deactivate these surfaces explicitly using the `deactivate_surface` API
call.

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

== Configuration
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.

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

Configuration items can contain `comment` objects, these are unused and
only for documentation purposes in the json, they can safely be removed
from the JSON file.

==== 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` if the main surface is called
  `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" },
   },
   {
      "role": "^App.*",
      "name": "apps",
      "layer_id": 1001,
      "area": { "type": "rect",
                "rect": { "x": 0,
                          "y": 100,
                          "width": -1,
                          "height": -201 } },
      "split_layouts": []
   }
]
------

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 fullscreen
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 fullscreen surface can have the following `rect`
definition:

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

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 configuration needs to be `-N - 1`.

===== 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 deactivate (or a surface on a layer
below the current one must be activated).

------
"split_layouts": [
   {
      "name": "Media Player",
      "main_match": "^App MPlayer Main$",
      "sub_match": "^App MPlayer Sub",
   }
]
------

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.

.Note
******
The names must still match the layer's role match!
******

== Binding API
The binding API consists of a couple of AFB _verbs_ - that is function
calls to the Window Manager.

=== Verbs (Functions)
* `RequestSurface(drawing_name: string): int`
  Request a surface ID for the given name. This name and ID association
  will live until the surface is destroyed (or e.g. the application
  exits). Each surface that is managed by the window manager needs to
  call this function first!
* `ActivateSurface(drawing_name: string)`
  This function requests the activation of a surface. It usually is not
  called by the application, but rather by the application framework or
  the HomeScreen.
* `DeactivateSurface(drawing_name: string)`
  Request deactivation of a surface. This function is not usually called
  by applications themselves, but rather by the application framework or
  the HomeScreen.
* `EndDraw(drawing_name: string)`
  Signals the window manager, that the surface is finished drawing. This
  is useful for consistent flicker-free layout switches, see the
  Architecture document for details.

There are a couple of non-essential (mostly for debugging and
development) API calls:

* `list_drawing_names(): json`
  List known surface _name_ to _ID_ associations.
* `ping()`
  Ping the window manager. Does also dispatch pending events if any.
* `debug_status(): json`
  Returns a json representation of the current layers and surfaces known
  to the window manager. This represents the wayland-ivi-extension
  object's properties.
* `debug_surfaces(): json`
  Returns a json representation of all surfaces known to the window
  manager. This represents the wayland-ivi-extension properties of the
  surfaces.
* `debug_layers(): json`
  Returns the current layer configuration, as configured through
  _layers.json_.
* `debug_terminate()`
  Terminates the afb-daemon running the window manager binding, if the
  environment variable `WINMAN_DEBUG_TERMINATE` is set.

=== Events
The window manager broadcasts certain events (to all applications) that
signal information on the state of the surface regarding the current
layout.

* `Active(drawing_name: string)`
  Signal that the surface with the name `drawing_name` is now active.
* `Inactive(drawing_name: string)`
  Signal that the surface with the name `drawing_name` is now inactive.
  This usually means, the layout got changed, and the surface is now
  considered inactive (or sleeping).
* `Visible(drawing_name: string)`
  Signal applications, that the surface with name `drawing_name` is now
  visible.
* `Invisible(drawing_name: string)`
  Signal applications that the surface with name `drawing_name` is now
  invisible.
* `SyncDraw(drawing_name: string)`
  Signal applications, that the surface with name `drawing_name` needs
  to redraw its content - this usually is sent when the surface geometry
  changed.
* `FlushDraw(drawing_name: string)`
  Signal to applications, that the surface with name `drawing_name` 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 geomtry).

=== Binding API Usage
For a detailed description on how the binding API is supposed to be
used, refer to the Architecture document.

== Building and Running

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

Build dependencies are as follows:

* afb-daemon >= 1.0
* libsystemd >= 2222
* wayland-client >= 1.11

=== Build Configuration
Use cmake to configure a build tree:

--------
mkdir build
cd build
cmake ..
make
[sudo] make install
--------

== Utilities
With the actual window manager implementation, two general utilities are
provided.

=== wm-request
A shell script, that wraps `afb-client-demo` and issues commands to the
window manager using the AFB exposed API. It will call synchronously to
the WM, and output any events that are happening in the meantime.
Replies are printed to stdout using an failed/success annotation and a
dump of the actual json reply from the AFB.

==== Commands
* `wm-request requestsurface $NAME`: request the surface with $NAME,
  this will succeed only if the surface name is not yet (or anymore)
  known. The actual call return is in the "response" json object of the
  reply.
* `wm-request activatesurface $NAME`: activate the surface with $NAME.
  This call will only succeed of the surface is available and not
  currently active. The reply just contains failure/success information,
  but no actual return value from the API.
* `wm-request deactivatesurface $NAME`: deactivate the surface with
  $NAME. This call will only succeed if the surface is currently active,
  no return value is provided by the API.
* `wm-request ping`: Just send a *ping* to the window manager, can be
  sued to check whether the WindowManager is alive or not.

=== redraw_fixer
This utility is intended to be ran alongside the compositor, it will
listen for certain events regarding surfaces, and issue a couple of
other commands, to hopefully trigger a redraw of the surface in the
compositor.

It will print messages for each acted-upon event, and exit when the
compositor exits.

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

=== Binding code generation
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).

=== Structure
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.

=== XXX
a

---------------------------
Some code
---------------------------

The `token` parameter is a string consisting of only alphanumeric
characters, and with a maximum length of 20 characters. If these
conditions are not met, the AFBClient instance will not initialize,
i.e. this call will return `-EINVAL`.

.Note
******************
The timeout should be small in order to not block too long, but also a
0 timeout will not dispatch anything and return immediately (see
https://linux.die.net/man/2/epoll_wait[epoll_wait(2)]).
******************

// vim:set ft=asciidoc tw=72 spell spelllang=en_US: