[PATCH] documentation: clarify the need for wl_surface.damage

Mahdi Khanalizadeh mahdi at khanalizadeh.com
Mon Oct 2 15:39:56 UTC 2017

Add an explanation for wl_surface.attach why a wl_surface.damage request
is necessary. Explicitly declare it implementation defined behaviour if the
wl_surface.damage request is omitted to give the compositor some leeway
on how it handles attaches.

Signed-off-by: Mahdi Khanalizadeh <mahdi at khanalizadeh.com>
 protocol/wayland.xml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index aabc7ae..6f6cc11 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1365,6 +1365,11 @@
 	wl_buffer before receiving the wl_buffer.release event, the surface
 	contents become undefined immediately.
+	Attaching a buffer should always be accompanied by a
+	wl_surface.damage request to signal the compositor that the
+	contents of the buffer have changed. Otherwise it is implementation
+	defined whether the wl_surface.attach request has any visible effect.
 	If wl_surface.attach is sent with a NULL wl_buffer, the
 	following wl_surface.commit will remove the surface content.

More information about the wayland-devel mailing list