diff options
-rw-r--r-- | protocol/wayland.xml | 28 |
1 files changed, 13 insertions, 15 deletions
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 @@ <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. |