diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/WindowManagerTMC.txt | 197 |
1 files changed, 101 insertions, 96 deletions
diff --git a/doc/WindowManagerTMC.txt b/doc/WindowManagerTMC.txt index c272299..6446396 100644 --- a/doc/WindowManagerTMC.txt +++ b/doc/WindowManagerTMC.txt @@ -12,7 +12,7 @@ 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. +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 @@ -55,7 +55,7 @@ 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. +The client library is built together with the window manager itself. == Concepts The window manager implements a couple of concepts in order to allow @@ -64,9 +64,7 @@ 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, @@ -76,15 +74,99 @@ Additionally, layers will generally leave surfaces on below layers 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 @@ -194,16 +276,19 @@ actual_height = screen_height + 1 + height ------ 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": [ @@ -234,85 +319,6 @@ this layout. 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 @@ -479,5 +485,4 @@ The implementation is loosely split across the following source files: wrapper. It is instanced in `main.cpp` and handles all our wayland needs. - // vim:set ft=asciidoc tw=72 spell spelllang=en_US: |