[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 reference docs for wl_surface::attach say,

 Surface contents are double-buffered state, see wl_surface.commit. 

Most of the other wl_surface requests similarly mention double-buffered
surfaces.  Nothing there discusses single-buffers, and nothing describes
a multi-buffered state, although wl_surface::commit includes this
(rather ambiguous) statement:

 Other interfaces may add further double-buffered surface state. 

(Whatever this actually means, it probably should be elaborated on.)

It's possible I've missed something or I'm just dumb, but if >2 buffers
is a thing that should be documented to users, then I'd expect the
reference docs to cover it.

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

Alright, I've rephrased this - hopefully not butchering the meaning in
the process.  Please review my updated patch, which i'll post directly.

Thanks for the review (and explanations of how things work!)

Bryce