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

Bryce Harrington bryce at osg.samsung.com
Fri Dec 12 11:37:54 PST 2014

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!)


More information about the wayland-devel mailing list