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 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. -- 1.7.8.6 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
