EGL_KHR_platform_wayland: Clarify requirements of eglSwapBuffers (#205)

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.

Co-authored-by: Jon Leech <4693344+oddhack@users.noreply.github.com>

extensions/KHR/EGL_KHR_platform_wayland.txt

diff --git a/extensions/KHR/EGL_KHR_platform_wayland.txt b/extensions/KHR/EGL_KHR_platform_wayland.txt
index 3a2b46c..989b07d 100644
--- a/extensions/KHR/EGL_KHR_platform_wayland.txt
+++ b/extensions/KHR/EGL_KHR_platform_wayland.txt
@@ -23,7 +23,7 @@
 
 Version
 
-    Version 4, 2026/04/03
+    Version 5, 2026/04/03
 
 Number
 
@@ -41,7 +41,8 @@
     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 EGL_KHR_swap_buffers_with_damage extensions are
+    also present.
 
 Overview
 
@@ -93,6 +94,19 @@
     until the next buffer swap. The rationale behind this behavior is to keep
     operations result accurate until the next swap.
 
+    Add the following text to subsection 3.10.1 titled "Posting to a
+    Window" after paragraph 3 of the description of eglSwapBuffers:
+
+    "When the <surface> refers to a Wayland platform surface, synchronously
+    within the call to eglSwapBuffers the EGL implementation will invoke a
+    series of requests on the associated wl_surface, including attaching the
+    new front buffer, an appropriate surface damage via wl_surface.damage or
+    wl_surface.damage_buffer, and finally a wl_surface.commit."
+
+    If the EGL implementation associated a wp_linux_drm_syncobj_surface_v1
+    object with the surface, an acquire and a release point will be associated
+    with the surface prior to the commit as well.
+
 Issues
 
     1. Should this extension permit EGL_DEFAULT_DISPLAY as input to
@@ -107,10 +121,16 @@
        RESOLVED. No. Wayland has no pixmap type.
 
 Revision History
-    Version 4, 2026/04/03 (Lennart Jablonka)
+
+    Version 5, 2026/04/03 (Lennart Jablonka)
         - Replace `struct wl_egl_surface` by `struct wl_egl_window`,
           as is implemented.
 
+    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.