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

[Bryce Harrington]

Sorry, sorry, sorry for the misfire!  Please ignore this patch.

(and thanks for patchwork!)

On Fri, Dec 12, 2014 at 11:38:58AM -0800, Bryce Harrington wrote:
> 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