From 310fea467cf714d3ed7d66747c463790246f9be1 Mon Sep 17 00:00:00 2001
From: Bryce Harrington <bryce@osg.samsung.com>
Date: Tue, 27 Jan 2015 16:32:16 -0800
Subject: [PATCH] doc: Fill in high level description for Surfaces

Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Jon A. Cruz <jonc@osg.samsung.com>
---
 doc/publican/sources/Protocol.xml | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 5f3e8526..477063be 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -282,9 +282,16 @@
   <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
-      cannot access other clients surfaces.
+      A surface manages a rectangular grid of pixels that clients create
+      for displaying their content to the screen.  Clients don't know
+      the global position of their surfaces, and cannot access other
+      clients' surfaces.
+    </para>
+    <para>
+      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, it releases the
+      buffer back to the client.
     </para>
     <para>
       See <xref linkend="protocol-spec-wl_surface"/> for the protocol