[PATCH wayland] doc: Fill in high level description for Surfaces
giuliocamuffo at gmail.com
Fri Dec 12 11:58:01 PST 2014
2014-12-12 21:37 GMT+02:00 Bryce Harrington <bryce at osg.samsung.com>:
> On Thu, Dec 11, 2014 at 09:49:28AM +0000, Daniel Stone wrote:
>> On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo at gmail.com>
>> > 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce at osg.samsung.com
>> > > + 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.
This means that state such as the buffer set with the attach request
is double buffered, that is it becomes the active state after a
commit(). It doesn't mean the surface has two buffers, the state is
double buffered, not the buffer. You can attach a different buffer
each time, or prerender an animation completely upfront and then feed
the compositor all the buffers you have one by one, that is a client
> 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 means other protocol extensions may add more state that becomes
active when the user calls commit(). As an example, i think the
geometry set in xdg_shell with xdg_surface.set_window_geometry is
> 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