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

[Bryce Harrington]

On Thu, Dec 11, 2014 at 09:49:28AM +0000, Daniel Stone wrote:
> Hi,
> 
> On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo at gmail.com>
> wrote:
> 
> > 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce at osg.samsung.com
> > <javascript:;>>:
> > > +      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.
> 
> 
> It would be good to make the linkage to wl_buffers clear, i.e. that
> surfaces do not have intrinsic storage of their own.
> 
> 
> > > +      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.
> 
> 
> Yeah, that was my first thought on reading this.
> 
> 
> > > +      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.
> >
> 
> It might also be nice to clarify that this can happen at any time:
> instantly (i.e. copying into a shadow buffer, such as SHM buffers on GL/RPi
> renderers), immediately on the next attach/commit (i.e. a renderer with no
> scanout promotion that does a blit for final presentation, such as GL
> buffers on GL renderer), or sometime later (buffer promoted directly to
> scanout, such as a DRM/atomic backend). But ideally without reference to
> those specific cases, as they're really just implementation details that
> can change.
> 
> Thanks a lot for doing this! Are you planning to do others?

I'm a documentation nerd so will certainly be sending more patches like
this.

But my motivation here is rather mercenary - I was trying to understand
what surfaces can do as I revamp the headless testing patchset, and
noticed the documentation was particularly sparse on this.  So the
feedback is useful to help me better understand this object.

Thanks both to you and Giulio.  I'll review and revise the docs changes.

Bryce