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 <[email protected]> > Signed-off-by: Pekka Paalanen <[email protected]> > --- > 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 > created through factory interfaces such as wl_drm, wl_shm or > - similar. It has a width and a height and can be attached to a > + similar. It has a width and a height and can be attached to a > wl_surface, but the mechanism by which a client provides and > - updates the contents is defined by the buffer factory interface > + updates the contents is defined by the buffer factory interface. > </description> > > <request name="destroy" type="destructor"> > <description summary="destroy a buffer"> > - Destroy a buffer. This will invalidate the object id. > + Destroy a buffer. If and how you need to release the backing > + storage is defined by the buffer factory interface. > > For possible side-effects to a surface, see wl_surface.attach. > </description> > @@ -244,17 +245,14 @@ > <event name="release"> > <description summary="compositor releases buffer"> > Sent when this wl_buffer is no longer used by the compositor. > - > - If a client does not get a release event before the frame callback > - requested in the same wl_surface.commit that attaches this wl_buffer > - to a surface, then the client may assume, that the compositor will > - be using this wl_buffer until the client attaches another wl_buffer. > - Therefore the client will need a second wl_buffer to update the > - surface contents again. > - > - Otherwise, if a release event arrives before the frame callback, the > - client is immediately free to re-use the buffer and its backing > - storage, and does not necessarily need a second buffer. Typically > + The client is now free to re-use or destroy this buffer and its > + backing storage. > + > + If a client receives a release event before the frame callback > + requested in the same wl_surface.commit that attaches this > + wl_buffer to a surface, then the client is immediately free to > + re-use the buffer and its backing storage, and does not need a > + second buffer for the next surface content update. Typically > this is possible, when the compositor maintains a copy of the > wl_surface contents, e.g. as a GL texture. This is an important > optimization for GL(ES) compositors with wl_shm clients. Yeah, that reads a little better. Kristian > -- > 1.7.8.6 > _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
