02_agl_compositor: Added gRPC proxy docs

Adds the proto buf protocol as well as pointing out to
agl-shell-activator or window-management-clieng-grpc.

Bug-AGL: SPEC-4833
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Change-Id: Ib683c09e81cfbb03c9fdbc290e475c6563de9025
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29722
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Reviewed-by: Lisandro Perez Meyer <lpmeyer@ics.com>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
(cherry picked from commit 690e21bcd0adb100d6a5d7c13421ac41c3fa8a13)
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29737

1 files changed, 153 insertions, 1 deletions

diff --git a/docs/06_Component_Documentation/02_agl_compositor.md b/docs/06_Component_Documentation/02_agl_compositor.md
index 9e62890..2029e60 100644
--- a/docs/06_Component_Documentation/02_agl_compositor.md
+++ b/docs/06_Component_Documentation/02_agl_compositor.md
@@ -191,7 +191,7 @@ handle any window management interaction on its own.
 Further more, with this protocol update we also includes some events already
 present in the agl-shell-desktop protocol like  deactivate and terminate.
 
-### agl-shell-desktop
+### agl-shell-desktop (deprecated, will be removed in future, see gRPC proxy)
 
 This extension is targeted at keeping some of the functionally already
 established in AGL as to a) allow applications display/activate other
@@ -241,6 +241,158 @@ present/running, it will attempt to make the surface backing that application
 the current activate one, with each output having independently active
 surfaces.
 
+## gRPC proxy for window management
+
+The gRPC proxy is an alternative to allow management of windows,
+without the need for clients to "speak" native Wayland C code.  Most major
+languages have RPC bindings, and in AGL clients do not touch Wayland code
+natively, using most of the time toolkits. It seemed reasonably to use gRPC
+as a way to interact with the compositor. The way this works is that
+there's proxy daemon started by the compositor which translates the gRPC
+calls to Wayland ones, using agl-shell protocol. Events coming from the
+compositor are handled by subscribing to RPC stream events, such that
+clients can act upon as well, so it is not just one way interaction.
+
+With respect to window management: placement, movement, and surface role
+changes all should, and can be done with RPC. Some of the calls, specifically
+background set-up or activation area, are still required to happen prior or
+require wayland primitives which can't be passed between processes, so those
+can't be used with RPC proxy.
+
+In terms of API, the following are available: activation/deactivation,
+role management, and events. All the message arguments are self-explanatory,
+requiring always an app_id, in form of string and possibly an output, in
+form a string as well. Toolkits can set/retrieve this information so refer
+to the respective toolkit. At the wayland level, the app_id is set/get
+with [xdg-shell](https://wayland.app/protocols/xdg-shell#xdg_toplevel:request:set_app_id)
+whereas output from [wl_output interface](https://wayland.app/protocols/wayland#wl_output:event:name)
+
+Activation and deactivation of applications:
+
+```
+rpc ActivateApp(ActivateRequest)         returns (ActivateResponse) {}
+rpc DeactivateApp(DeactivateRequest)     returns (DeactivateResponse) {}
+```
+With the following message arguments:
+
+```
+message ActivateRequest {
+       string app_id = 1;
+       string output_name = 2;
+}
+
+message ActivateResponse {
+};
+
+
+message DeactivateRequest {
+       string app_id = 1;
+};
+
+message DeactivateResponse {
+};
+```
+
+Management of surface roles can be done with these requests:
+
+
+```
+rpc SetAppSplit(SplitRequest)            returns  (SplitResponse) {}
+rpc SetAppFloat(FloatRequest)            returns  (FloatResponse) {}
+rpc SetAppFullscreen(FullscreenRequest)  returns  (FullscreenResponse) {}
+rpc AppStatusState(AppStateRequest)      returns  (stream AppStateResponse) {}
+rpc GetOutputs(OutputRequest)            returns  (ListOutputResponse) {}
+rpc SetAppNormal(NormalRequest)          returns  (NormalResponse) {}
+rpc SetAppOnOutput(AppOnOutputRequest)   returns  (AppOnOutputResponse) {}
+rpc SetAppPosition(AppPositionRequest)   returns  (AppPositionResponse) {}
+rpc SetAppScale(AppScaleRequest)         returns  (AppScaleResponse) {}
+```
+
+Message arguments are:
+
+```
+message SplitRequest {
+       string app_id = 1;
+       int32 tile_orientation = 2;
+       int32 width = 3;
+       int32 sticky = 4;
+       string output_name = 5;
+}
+
+message SplitResponse {
+};
+
+message FloatRequest {
+       string app_id = 1;
+       int32 x_pos = 2;
+       int32 y_pos = 3;
+};
+
+message FloatResponse {
+};
+
+message NormalRequest {
+        string app_id = 1;
+};
+
+message NormalResponse {
+};
+
+message FullscreenRequest {
+        string app_id = 1;
+};
+
+message FullscreenResponse {
+};
+
+message AppOnOutputRequest {
+        string app_id = 1;
+        string output = 2;
+};
+
+message AppOnOutputResponse {
+};
+
+message AppPositionRequest {
+       string app_id = 1;
+       int32 x = 2;
+       int32 y = 3;
+};
+
+message AppPositionResponse {
+};
+
+message AppScaleRequest {
+       string app_id = 1;
+       int32 width = 2;
+       int32 height = 3;
+};
+
+message AppScaleResponse {
+};
+```
+
+Events which clients can subscribe to:
+
+```
+rpc AppStatusState(AppStateRequest) returns (stream AppStateResponse) {}
+```
+
+With the message arguments:
+
+```
+message AppStateRequest {
+};
+
+message AppStateResponse {
+        int32 state = 1;
+        string app_id = 2;
+};
+```
+
+A C++ client implementation the gRPC API can be found in [agl-shell-activator](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-shell-activator.git;a=tree;h=refs/heads/master;hb=refs/heads/master)
+or in [window-management-client-grpc](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/window-management-client-grpc.git;a=tree;h=refs/heads/master;hb=refs/heads/master).
+
 ## Explicit output
 
 The activation and setting surface roles requires passing a Wayland output