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

[Daniel Stone]

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?

Cheers,
Daniel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20141211/c394aef6/attachment-0001.html>