doc: convert asciidoc to md

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

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 who
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.

It does not include

-   documentation of the underlying architecture, see
    [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).

-   documentation of the AGL application framework and its technologies,
    see [AGL Application
    Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).

It is highly recommended to have a good understanding of these documents
and projects before using the window manager.

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.

External libraries
------------------

This project includes a copy of version 2.1.1 the excellent [C++11 JSON
library by Niels Lohmann](https://github.com/nlohmann/json).

Client Library
--------------

A client library implementation that internally uses the *libafbwsc*, is
provided in the subdirectory `client-lib/` with its own documentation
directory.

The client library is built together with the window manager itself.

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, from lowest to highest.

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.

It is possible to deactivate these surfaces on lower layers explicitly
using the `DeactivateSurface` 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.

Binding API
===========

The binding API consists of a couple of AFB *verbs* - that is; function
calls to the Window Manager.

Verbs (Functions)
-----------------

Each function returns a reply containing at least a failed or successful
result of the call, additionally, when calls return something, it is
noted. The notation used has the following meaning:

    FunctionName(argument_name: argument_type)[: function_return_type]

Where the return type may be omitted if it is void.

-   `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 geometry).

Binding API Usage
-----------------

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

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.

A sample configuration is provided with the window manager
implementation, this sample is installed to /etc/layers.json.

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.

### 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`.

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

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

A surface that leaves a 200pixel margin on the top and bottom can use
the following `rect` definition:

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

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 dimension configuration needs to be `-N - 1`, and
appropriate offsets need to be set for `x` and `y`.

#### 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
deactivated (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.

The names must still match the layer’s role match!

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 >= 222

-   wayland-client >= 1.11

-   cmake >= 3.6.1

Build Configuration
-------------------

Use cmake to configure a build tree:

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

A couple of build options to configure the build are available:

-   `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
    output from the window manager, use --verbose three times on an
    afb-daemon instance to see the debug messages.

-   `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
    used for a rather small portion of the window manager code. However,
    it is used quite extensively in the AFBClient implementation.

By default these options will be disabled.

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. When found on the system, it
will use `pygmentize` to apply syntax highlighting to the returned JSON.

### Examples

    $ wm-request list_drawing_names
    ON-REPLY 1:winman/list_drawing_names: OK
    {
      "response":{
        "App1":1,
        "App2":2,
        "HomeScreen":3,
        "OnScreen":4
      },
      "jtype":"afb-reply",
      "request":{
        "status":"success",
        "info":"success"
      }
    }
    $ wm-request activatesurface App1
    ON-REPLY 1:winman/activatesurface: OK
    {
      "response":{
      },
      "jtype":"afb-reply",
      "request":{
        "status":"success",
        "info":"success"
      }
    }
    $ wm-request activatesurface AppThatDoesNotExist
    ON-REPLY 1:winman/activatesurface: ERROR
    {
      "jtype":"afb-reply",
      "request":{
        "status":"failed",
        "info":"Surface does not exist"
      }
    }

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.