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

[Daniel Stone]

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.

Cheers,
Danirl
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20141212/6eec4519/attachment.html>