summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarcus Fritzsch <marcus_fritzsch@mentor.com>2017-09-13 15:56:53 +0200
committerMarcus Fritzsch <marcus_fritzsch@mentor.com>2017-09-14 14:04:51 +0200
commitf6c2b28453ac64da299ea67de6d715d28973daf4 (patch)
tree13567b1720f37fa8164af739dcaaae97804c21f6
parent8ec32940e425c028d7669b1dc9a81d8d72859e71 (diff)
doc: documentation update, more examples, some external links
Signed-off-by: Marcus Fritzsch <marcus_fritzsch@mentor.com>
-rw-r--r--doc/WindowManagerTMC.txt148
1 files changed, 101 insertions, 47 deletions
diff --git a/doc/WindowManagerTMC.txt b/doc/WindowManagerTMC.txt
index 69182fd..c272299 100644
--- a/doc/WindowManagerTMC.txt
+++ b/doc/WindowManagerTMC.txt
@@ -12,13 +12,24 @@ 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.
+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.
+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:
@@ -35,6 +46,17 @@ 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 build together with the window manager itself.
+
== Concepts
The window manager implements a couple of concepts in order to allow
efficient implementation.
@@ -55,7 +77,7 @@ 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
+deactivate these surfaces explicitly using the `DeactivateSurface` API
call.
=== Surfaces
@@ -70,15 +92,14 @@ 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.
-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": {
@@ -93,8 +114,7 @@ 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`.
+ surface. Set this to e.g. `HomeScreen`.
==== mappings
This configuration item is a list of surface-name to layer mappings.
@@ -136,7 +156,7 @@ to a layer.
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
@@ -145,7 +165,7 @@ 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:
------
@@ -155,6 +175,16 @@ 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:
@@ -205,10 +235,14 @@ 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
+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.
+
* `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
@@ -273,7 +307,7 @@ layout.
* `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).
+ 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
@@ -287,8 +321,9 @@ 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
+* libsystemd >= 222
* wayland-client >= 1.11
+* cmake >= 3.6.1
=== Build Configuration
Use cmake to configure a build tree:
@@ -301,6 +336,17 @@ 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.
@@ -310,22 +356,48 @@ 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.
+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
@@ -407,23 +479,5 @@ The implementation is loosely split across the following source files:
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: