doc: shuffled around some sections, fixes.

Signed-off-by: Marcus Fritzsch <marcus_fritzsch@mentor.com>

diff --git a/doc/WindowManagerTMC.txt b/doc/WindowManagerTMC.txt
index c272299..6446396 100644 (file)
--- 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
 
 === 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
 
 === 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.
 
 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
 
 == 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
 === 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,
 
 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.
 
 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.
 
 
 === 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
 == 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
 ------
 
 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
 
 ===== 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": [
 
 ------
 "split_layouts": [


@@ -234,85 +319,6 @@ this layout.
 The names must still match the layer's role match!
 ******
 
 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
 == 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.
 
   wrapper. It is instanced in `main.cpp` and handles all our wayland
   needs.
 

-

 // vim:set ft=asciidoc tw=72 spell spelllang=en_US:
 // vim:set ft=asciidoc tw=72 spell spelllang=en_US: