EGL_KHR_platform_wayland: Clarify requirements of eglSwapBuffers

The EGL implementation attaching the front buffer, posting damage, and
committing during the call to eglSwapBuffers(WithDamage)() is a well
established requirement that EGL Wayland clients currently rely upon,
thus should be explicitly documented.

extensions/KHR/EGL_KHR_platform_wayland.txt

@@ -41,7 +41,8 @@ Dependencies
     20140122).
 
     The behavior of part of this extension is different depending on whether
-    the EGL_EXT_buffer_age extension is also present.
+    the EGL_EXT_buffer_age and KHR_swap_buffers_with_damage extensions are also
+    present.
 
 Overview
 
@@ -93,6 +94,16 @@ New Behavior
     until the next buffer swap. The rationale behind this behavior is to keep
     operations result accurate until the next swap.
 
+    During the call to eglSwapBuffers wl_surface.attach will be requested with
+    the new front buffer, a full surface damage is requested via
+    wl_surface.damage or wl_surface.damage_buffer, and a wl_surface.commit will
+    be requested to commit the new state.
+
+    If KHR_swap_buffers_with_damage is available, the equivalent to calling
+    eglSwapBuffers will take place, with the exception that the damage
+    according to <rects> and <n_rects> may be requested via
+    wl_surface.damage_buffer, instead of requesting a full damage.
+
 Issues
 
     1. Should this extension permit EGL_DEFAULT_DISPLAY as input to
@@ -107,6 +118,11 @@ Issues
        RESOLVED. No. Wayland has no pixmap type.
 
 Revision History
+    Version 4, 2024/09/09 (Jonas Ådahl)
+        - Clarify wl_surface commit requirements.
+        - Clarify wl_surface damage responsibilities.
+        - Add dependency on KHR_swap_buffers_with_damage
+
     Version 3, 2022/07/14 (Kirill Chibisov)
         - Clarify EGLSurface back buffer locking behavior with regards to
           rendering and surface querying operations.