mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-11-26 06:59:58 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

protocol: try to clarify wl_buffer doc

Browse source 
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@gmail.com>
Signed-off-by: Pekka Paalanen <ppaalanen@gmail.com>
This commit is contained in:
Pekka Paalanen 2012-10-12 14:29:01 +03:00 • committed by Kristian Høgsberg
parent cb2296778d
commit 6c3e9b8f54
1 changed files with 12 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

26
protocol/wayland.xml
View file

@ -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.
The client is now free to re-use or destroy this buffer and its
backing storage.
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
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.