[RFC krh/wayland/next 2/2] protocol: try to clarify wl_buffer doc

[Pekka Paalanen]

On Tue, 16 Oct 2012 11:05:44 -0400
Kristian Høgsberg <hoegsberg at gmail.com> wrote:

> On Fri, Oct 12, 2012 at 02:29:01PM +0300, Pekka Paalanen wrote:
> > Fix few typos in wl_buffer description.
> > 
> > Mention backing storage in wl_buffer.destroy.
> > 
> > Try to clarify the wl_buffer.release semantics by not explaining what
> > *might* happen. It is important to not suggest, that if release does not
> > come before frame callback, it will not come before attaching a new
> > buffer to the surface. We want to allow the following scenario:
> > 
> > The compositor is able to texture from wl_buffers directly, but it also
> > keeps a copy of the surface contents. The copy is updated when the
> > compositor is idle, to avoid the performance hit on
> > wl_surface.attach/commit. When the copy completes some time later, the
> > server sends the release event. If the client has not yet allocated a
> > second buffer (e.g. it updates rarely), it can reuse the old buffer.
> > 
> > Reported-by: John Kåre Alsaker <john.kare.alsaker at gmail.com>
> > Signed-off-by: Pekka Paalanen <ppaalanen at gmail.com>
> > ---
> >  protocol/wayland.xml |   28 +++++++++++++---------------
> >  1 files changed, 13 insertions(+), 15 deletions(-)
> > 
> > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > index bd05c75..1b75f9b 100644
> > --- a/protocol/wayland.xml
> > +++ b/protocol/wayland.xml
> > @@ -226,16 +226,17 @@
> >  
> >    <interface name="wl_buffer" version="1">
> >      <description summary="content for a wl_surface">
> > -      A buffer provides the content for a wl_surface.  Buffers are
> > +      A buffer provides the content for a wl_surface. Buffers are
> 
> Ok, let's do this then, but I'll just point you to this for a bit of
> background:
> 
>   http://en.wikipedia.org/wiki/Sentence_spacing

Oh it was deliberate? It looked like just a left-over from
re-flowing the text, like trailing whitespace. Sorry.

I didn't expect to see such literal typographic formatting in
source code. I'm used to LaTeX.


Thanks,
pq