--- /dev/null
+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.
+
+
Code Review / staging / windowmanager.git / blobdiff