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

[Bryce Harrington]

On Thu, Dec 11, 2014 at 10:28:25AM +0200, Giulio Camuffo wrote:
> 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.

Good to know.  I'll soften the language a bit:

      A surface has one or more content buffers containing the data for                                             
      the screen.  A typical surface maintains a pair (or more) of                                                  
      buffers that are swapped between the client and the compositor.

I don't know that we need to be any more detailed then this.  The purpose
of the high level docs should be to just introduce the concepts, and
leave the details to the reference docs, which look quite thorough in
this case.

Thanks for reviewing!

Bryce 
> > +      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