+++ /dev/null
-= 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
-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
- https://wiki.automotivelinux.org/hmiframework[HMI-Framework].
-* documentation of the AGL application framework and its technologies,
- see https://wiki.automotivelinux.org/agl-distro/app-framework[AGL
- Application 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
-https://github.com/nlohmann/json[C++11 JSON library by Niels Lohmann].
-
-=== 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.
-
-.Note
-******
-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.
-
-// vim:set ft=asciidoc tw=72 spell spelllang=en_US:
Code Review / staging / windowmanager.git / blobdiff