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

[Giulio Camuffo]

2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce at osg.samsung.com>:
>
> Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
>  doc/publican/sources/Protocol.xml |   20 +++++++++++++++-----
>  1 file changed, 15 insertions(+), 5 deletions(-)
>
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index b79b6be..2e48a7c 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -282,13 +282,23 @@
>    <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>
> -      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
> -      description.
> +      A surface has a pair of content buffers that are swapped between

Uhm, a surface can actually use more than two buffers, that depends on
the client only. For shm buffers, if the compositor supports it, a
surface can even be single buffered without creating artifacts.

> +      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>
> +      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
> +      protocol description.
>      </para>
>    </section>
>    <section id="sect-Protocol-Input">
> --
> 1.7.9.5
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel