[RFC krh/wayland/next 2/2] protocol: try to clarify wl_buffer doc
hoegsberg at gmail.com
Tue Oct 16 08:05:44 PDT 2012
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
> 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.
> <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.
> @@ -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.
More information about the wayland-devel