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

[Pekka Paalanen]

On Fri, 12 Dec 2014 20:29:29 +0000
Daniel Stone <daniel at fooishbar.org> wrote:

> Hi,
> 
> On Friday, December 12, 2014, Bill Spitzak <spitzak at gmail.com> wrote:
> 
> > I think talking about a surface having multiple buffers is misleading.
> >
> > A wl_surface only knows about one buffer after commit: the last buffer
> > attached to it. The wording being proposed here makes it sound like the
> > surface keeps track of the previous buffer and expects or requires it to be
> > used in the next attach.
> 
> 
> This is technically true, but I think helpful for the introduction.
> 
> 
> > I think the problem with the docs right now is that a lot of wl_surface
> > requests say "foo is double-buffered state, see wl_surface.commit". The
> > word double-buffered unfortunately immediately makes people think only
> > about pixel buffers, even though in fact it is other data that is being
> > double-buffered.
> >
> > I would avoid the use of the term "double buffered". Possible alternative:
> > "The change does not happen until the next wl_surface.commit." All current
> > talk about double-buffering in commit should use words like "deferred" or
> > "pending" instead.
> >
> 
> Or 'latched'. Either way, I think 'double-buffered' referring to the
> surface state updated on commit has to go.

I would be fine with that change. I started using the "double-buffered
state" term when nothing better came to my mind. After all, display
hardware can have double-buffered registers, etc. Yes, a latch.

All I want is that there is a single term which we use consistenly to
mean that wl_surface.foo(x) only readies the foo=x assignment in the
server, and the wl_surface.commit() actually makes it happen atomically
with all the other similar state for this wl_surface.


Thanks,
pq