From 23ae98cef0d4ba4bced881148c2dc5ea0d03f21e Mon Sep 17 00:00:00 2001
From: Demi Marie Obenour <demi@invisiblethingslab.com>
Date: Sun, 8 Sep 2024 15:53:40 -0400
Subject: [PATCH] Document that wl_shm.format is not authoritative

Compositors are allowed to announce formats that are not in the
wl_shm.format enum, and clients are allowed to use these formats.
Therefore, the enum="format" and enum="wl_shm.format" attributes
in the XML are unhelpful at best and misleading at worst.  Clients
and compositors should reference drm_fourcc.h instead.

Signed-off-by: Demi Marie Obenour <demi@invisiblethingslab.com>
---
 protocol/wayland.xml | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 9418c62f..644a1d24 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -242,7 +242,7 @@
       <arg name="width" type="int" summary="buffer width, in pixels"/>
       <arg name="height" type="int" summary="buffer height, in pixels"/>
       <arg name="stride" type="int" summary="number of bytes from the beginning of one row to the beginning of the next row"/>
-      <arg name="format" type="uint" enum="wl_shm.format" summary="buffer pixel format"/>
+      <arg name="format" type="uint" summary="buffer pixel format"/>
     </request>
 
     <request name="destroy" type="destructor">
@@ -308,6 +308,13 @@
 
 	For all wl_shm formats and unless specified in another protocol
 	extension, pre-multiplied alpha is used for pixel values.
+
+	Except for the first two entries (argb8888 and xrgb8888), this enum is
+	deprecated.  Compositors and clients should use the macros in drm_fourcc.h
+	instead.  Compositors are allowed to announce formats that are not members
+	of this enum.  Clients may used any format that the compositor has
+	announced, even if it is not a member of this enum.  The generated
+	validation function for this enum should not be used.
       </description>
       <!-- Note to protocol writers: don't update this list manually, instead
 	   run the automated script that keeps it in sync with drm_fourcc.h. -->
@@ -455,7 +462,7 @@
 	can be used for buffers. Known formats include
 	argb8888 and xrgb8888.
       </description>
-      <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
+      <arg name="format" type="uint" summary="buffer pixel format"/>
     </event>
 
     <!-- Version 2 additions -->