=== 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
provided in the subdirectory `client-lib/` with its own documentation
directory.
-The client library is build together with the window manager itself.
+The client library is built together with the window manager itself.
== Concepts
The window manager implements a couple of concepts in order to allow
=== 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 `DeactivateSurface` 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
------
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)
-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
- 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.
-
== Building and Running
=== Dependencies
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