=== 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.
+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:
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. That is, the screen render
-order will be set according to the layer stacking which is determined by
-the layer IDs.
+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,
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.
+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
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.
-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": {
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`.
+ surface. Set this to e.g. `HomeScreen`.
==== mappings
This configuration item is a list of surface-name to layer mappings.
number of possible split-screen layouts for this layer.
===== Area
-Areas can be either `full` or `rect`, whereas `full` means a fullscreen
+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
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`
+For example, a full-screen surface can have the following `rect`
definition:
------
"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:
------
Or in other words, to leave an `N` wide border around a surface, the
-actual value in the configuration needs to be `-N - 1`.
+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 deactivate (or a surface on a layer
-below the current one must be activated).
+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": [
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
Build dependencies are as follows:
* afb-daemon >= 1.0
-* libsystemd >= 2222
+* libsystemd >= 222
* wayland-client >= 1.11
+* cmake >= 3.6.1
=== Build Configuration
Use cmake to configure a build tree:
[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.
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.
+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
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:
Code Review / staging / windowmanager.git / blobdiff