[mutter/gbsneto/cleanup-x11-from-window-actor: 9/10] Add documentation about window and surface actors

[Georges Basile Stavracas Neto <gbsneto src gnome org>]

commit 44c990864a8c5a905ddd81caeb715a23faa23158
Author: Georges Basile Stavracas Neto <georges stavracas gmail com>
Date:   Sat Dec 22 12:17:32 2018 -0200

    Add documentation about window and surface actors
    
    Document the roles of MetaSurfaceActor and MetaWindowActor,
    and when their subclasses are used.
    
    (And this is actually the first real documentation under
    src/compositor/README!)
    
    https://gitlab.gnome.org/GNOME/mutter/merge_requests/368

 src/compositor/README | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)
---
diff --git a/src/compositor/README b/src/compositor/README
index b6308f69f..57239813c 100644
--- a/src/compositor/README
+++ b/src/compositor/README
@@ -1,7 +1,38 @@
 Intro
 =====
 
-Fix me.
+In general, the compositor splits the window from the contents of
+the window from the shape of the window. In other words, a window
+has contents, and the contents of the window have a shape. This is
+represented by the actor hierarchy:
+
+ +--------------------------------------+
+ | MetaWindowActor                      |
+ | +----------------------------------+ |
+ | | MetaSurfaceActor                 | |
+ | | +------------------------------+ | |
+ | | | MetaShapedTexture            | | |
+ | | |                              | | |
+ | | |                              | | |
+ | | |                              | | |
+ | | |                              | | |
+ | | +------------------------------+ | |
+ | +----------------------------------+ |
+ +--------------------------------------+
+
+## Client and compositor
+
+MetaWindowActor and its subclasses represent the client window's
+type. A X11 client will have a MetaWindowActorX11 representing it,
+and a Wayland client will have a MetaWindowActorWayland.
+
+On the compositor side, the surface where the contents of the window
+are drawn into are represented by MetaSurfaceActor subclasses. On a
+Wayland session, windows are backed by a MetaSurfaceActorWayland
+surface, whereas on X11 sessions, by MetaSurfaceActorX11.
+
+XWayland windows are X11 client windows (MetaWindowActorX11) backed
+by Wayland surfaces (MetaWindowActorWayland).
 
 
 Env Vars