[PATCH wayland v2] doc: Fill in high level description for Surfaces

[Bryce Harrington]

Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
---
 doc/publican/sources/Protocol.xml |   34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index b79b6be..9c6cb3b 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -282,13 +282,39 @@
   <section id="sect-Protocol-Surface">
     <title>Surfaces</title>
     <para>
-      Surfaces are created by the client.
-      Clients don't know the global position of their surfaces, and
+      A surface manages rectangular grids of pixels that clients create
+      for displaying their content to the screen.  The surface keeps
+      track of its location and size relative to whatever contains it
+      (which might be just a parent surface), thus clients don't know
+      the global position of their surfaces.  Importantly, clients
       cannot access other clients surfaces.
     </para>
     <para>
-      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
-      description.
+      The data for the grid of pixels is stored in a wl_buffer object.
+      A displayable surface has one or more of these content buffers
+      containing the content for the screen.  For example, a typical
+      surface maintains a pair of these buffers that are swapped between
+      the client and the compositor.  Once the client has finished
+      writing pixels, it 'commits' the buffer; this permits the
+      compositor to access the buffer and read the pixels.  When the
+      compositor is finished with a buffer, it releases it back to the
+      client.  This way, the client can begin writing the next buffer
+      while the compositor is processing the current one.
+    </para>
+    <para>
+      The actual processing behavior in practice can vary from one
+      backend to the next, and really is a renderer implementation
+      detail.  In particular, the display of the pixels on the screen
+      can happen after an unpredictable amount of time.  For example,
+      GL/RPi renderers with SHM-based buffers copy into a shadow buffer
+      and so will display instantly, whereas GL buffers on the GL
+      renderer do a blit for final presentation on the next
+      attach/commit, and DRM/atomic backends do it sometime later since
+      they promote the buffer directly to scanout.
+    </para>
+    <para>
+      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
+      protocol description.
     </para>
   </section>
   <section id="sect-Protocol-Input">
-- 
1.7.9.5