From 6c3e9b8f54fb988494443304ca172b2c95ea7efe Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Fri, 12 Oct 2012 14:29:01 +0300 Subject: protocol: try to clarify wl_buffer doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Pekka Paalanen --- protocol/wayland.xml | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) (limited to 'protocol') diff --git a/protocol/wayland.xml b/protocol/wayland.xml index e88cc95..019816d 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -226,16 +226,17 @@ - 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. - 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 @@ 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. -- cgit v1.2.3