+== 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.
+