dri: Add notes on what part of the loader interface are used by Xorg.

Reviewed-by: Adam Jackson <ajax@redhat.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/20044>

include/GL/internal/dri_interface.h

@@ -65,7 +65,7 @@ typedef struct __DRIframeTrackingExtensionRec	__DRIframeTrackingExtension;
 typedef struct __DRImediaStreamCounterExtensionRec	__DRImediaStreamCounterExtension;
 typedef struct __DRItexOffsetExtensionRec	__DRItexOffsetExtension;
 typedef struct __DRItexBufferExtensionRec	__DRItexBufferExtension;
-typedef struct __DRIlegacyExtensionRec		__DRIlegacyExtension;
+typedef struct __DRIlegacyExtensionRec		__DRIlegacyExtension; /* DRI1, structures of which have been deleted from the tree */
 typedef struct __DRIswrastExtensionRec		__DRIswrastExtension;
 typedef struct __DRIbufferRec			__DRIbuffer;
 typedef struct __DRIdri2ExtensionRec		__DRIdri2Extension;
@@ -123,6 +123,8 @@ struct __DRIextensionRec {
 
 /**
  * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension.
+ *
+ * Used by the X server in swrast mode.
  */
 #define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer"
 #define __DRI_COPY_SUB_BUFFER_VERSION 1
@@ -134,6 +136,8 @@ struct __DRIcopySubBufferExtensionRec {
 /**
  * Used by drivers that implement the GLX_SGI_swap_control or
  * GLX_MESA_swap_control extension.
+ *
+ * Used by the X server.
  */
 #define __DRI_SWAP_CONTROL "DRI_SwapControl"
 #define __DRI_SWAP_CONTROL_VERSION 1
@@ -145,6 +149,8 @@ struct __DRIswapControlExtensionRec {
 
 /**
  * Used by drivers that implement the GLX_SGI_video_sync extension.
+ *
+ * Not used by the X server.
  */
 #define __DRI_MEDIA_STREAM_COUNTER "DRI_MediaStreamCounter"
 #define __DRI_MEDIA_STREAM_COUNTER_VERSION 1
@@ -186,7 +192,7 @@ struct __DRItexBufferExtensionRec {
      * __DRIdrawable. 
      *
      * For GLX_EXT_texture_from_pixmap with AIGLX.  Deprecated in favor of
-     * setTexBuffer2 in version 2 of this interface
+     * setTexBuffer2 in version 2 of this interface.  Not used by post-2011 X.
      */
     void (*setTexBuffer)(__DRIcontext *pDRICtx,
 			 int target,
@@ -196,7 +202,8 @@ struct __DRItexBufferExtensionRec {
      * Method to override base texture image with the contents of a
      * __DRIdrawable, including the required texture format attribute.
      *
-     * For GLX_EXT_texture_from_pixmap with AIGLX.
+     * For GLX_EXT_texture_from_pixmap with AIGLX.  Used by the X server since
+     * 2011.
      *
      * \since 2
      */
@@ -205,10 +212,13 @@ struct __DRItexBufferExtensionRec {
 			  int format,
 			  __DRIdrawable *pDraw);
     /**
-     * Method to release texture buffer in case some special platform
+     * Called from glXReleaseTexImageEXT().
-     * need this.
      *
-     * For GLX_EXT_texture_from_pixmap with AIGLX.
+     * This was used by i965 in 24952160fde9 ("i965: Use finish_external instead
+     * of make_shareable in setTexBuffer2") to note when the user mis-used the
+     * interface in a way that would produce rendering bugs, and try to recover
+     * from them.  This has only ever been used from inside the Mesa tree and
+     * was never used by the X server.
      *
      * \since 3
      */
@@ -218,7 +228,7 @@ struct __DRItexBufferExtensionRec {
 };
 
 /**
- * Used by drivers that implement DRI2
+ * Used by drivers that implement DRI2.  Version 3 is used by the X server.
  */
 #define __DRI2_FLUSH "DRI2_Flush"
 #define __DRI2_FLUSH_VERSION 4
@@ -273,6 +283,8 @@ struct __DRI2flushExtensionRec {
 /**
  * Extension that the driver uses to request
  * throttle callbacks.
+ *
+ * Not used by the X server.
  */
 
 #define __DRI2_THROTTLE "DRI2_Throttle"
@@ -287,6 +299,8 @@ struct __DRI2throttleExtensionRec {
 
 /**
  * Extension for EGL_ANDROID_blob_cache
+ * *
+ * Not used by the X server.
  */
 
 #define __DRI2_BLOB "DRI2_Blob"
@@ -312,6 +326,8 @@ struct __DRI2blobExtensionRec {
 
 /**
  * Extension for fences / synchronization objects.
+ * *
+ * Not used by the X server.
  */
 
 #define __DRI2_FENCE "DRI2_Fence"
@@ -413,6 +429,8 @@ struct __DRI2fenceExtensionRec {
 /**
  * Extension for API interop.
  * See GL/mesa_glinterop.h.
+ * *
+ * Not used by the X server.
  */
 
 #define __DRI2_INTEROP "DRI2_Interop"
@@ -449,6 +467,8 @@ struct __DRI2interopExtensionRec {
 /**
  * Extension for limiting window system back buffer rendering to user-defined
  * scissor region.
+ *
+ * Not used by the X server.
  */
 
 #define __DRI2_BUFFER_DAMAGE "DRI2_BufferDamage"
@@ -507,6 +527,8 @@ typedef struct __DRIswrastLoaderExtensionRec __DRIswrastLoaderExtension;
 
 /**
  * Callback to get system time for media stream counter extensions.
+ *
+ * Not used by the X server.
  */
 #define __DRI_SYSTEM_TIME "DRI_SystemTime"
 #define __DRI_SYSTEM_TIME_VERSION 1
@@ -536,6 +558,8 @@ struct __DRIsystemTimeExtensionRec {
 
 /**
  * SWRast Loader extension.
+ *
+ * Version 1 is advertised by the X server.
  */
 #define __DRI_SWRAST_LOADER "DRI_SWRastLoader"
 #define __DRI_SWRAST_LOADER_VERSION 6
@@ -641,6 +665,8 @@ struct __DRIswrastLoaderExtensionRec {
  * indicate to the driver that it can use the new semantics.  A DRI
  * driver can use this to switch between the different semantics or
  * just refuse to initialize if this extension isn't present.
+ *
+ * Advertised by the X server.
  */
 #define __DRI_USE_INVALIDATE "DRI_UseInvalidate"
 #define __DRI_USE_INVALIDATE_VERSION 1
@@ -765,10 +791,11 @@ struct __DRIuseInvalidateExtensionRec {
 #define __DRI_ATTRIB_SWAP_UNDEFINED             0x8063
 
 /**
- * This extension defines the core DRI functionality.
+ * This extension defines the core DRI functionality.  It was introduced when
+ * DRI2 and AIGLX were added.
  *
  * Version >= 2 indicates that getConfigAttrib with __DRI_ATTRIB_SWAP_METHOD
- * returns a reliable value.
+ * returns a reliable value.  The X server requires v1 and uses v2.
  */
 #define __DRI_CORE "DRI_Core"
 #define __DRI_CORE_VERSION 2
@@ -776,6 +803,7 @@ struct __DRIuseInvalidateExtensionRec {
 struct __DRIcoreExtensionRec {
     __DRIextension base;
 
+    /* Not used by the X server. */
     __DRIscreen *(*createNewScreen)(int screen, int fd,
 				    unsigned int sarea_handle,
 				    const __DRIextension **extensions,
@@ -786,38 +814,48 @@ struct __DRIcoreExtensionRec {
 
     const __DRIextension **(*getExtensions)(__DRIscreen *screen);
 
+    /* Not used by the X server. */
     int (*getConfigAttrib)(const __DRIconfig *config,
 			   unsigned int attrib,
 			   unsigned int *value);
 
+    /* Not used by the X server. */
     int (*indexConfigAttrib)(const __DRIconfig *config, int index,
 			     unsigned int *attrib, unsigned int *value);
 
+    /* Not used by the X server. */
     __DRIdrawable *(*createNewDrawable)(__DRIscreen *screen,
 					const __DRIconfig *config,
 					unsigned int drawable_id,
 					unsigned int head,
 					void *loaderPrivate);
 
+    /* Used by the X server */
     void (*destroyDrawable)(__DRIdrawable *drawable);
 
+    /* Used by the X server in swrast mode. */
     void (*swapBuffers)(__DRIdrawable *drawable);
 
+    /* Used by the X server in swrast mode. */
     __DRIcontext *(*createNewContext)(__DRIscreen *screen,
 				      const __DRIconfig *config,
 				      __DRIcontext *shared,
 				      void *loaderPrivate);
 
+    /* Used by the X server. */
     int (*copyContext)(__DRIcontext *dest,
 		       __DRIcontext *src,
 		       unsigned long mask);
 
+    /* Used by the X server. */
     void (*destroyContext)(__DRIcontext *context);
 
+    /* Used by the X server. */
     int (*bindContext)(__DRIcontext *ctx,
 		       __DRIdrawable *pdraw,
 		       __DRIdrawable *pread);
 
+    /* Used by the X server. */
     int (*unbindContext)(__DRIcontext *ctx);
 };
 
@@ -829,6 +867,8 @@ struct __DRIcoreExtensionRec {
  * There are several data structures that explicitly store a major version,
  * minor version, and patch level.  These structures should be modified to
  * have a \c __DRIversionRec instead.
+ *
+ * Not used by the X server since DRI1 was deleted.
  */
 struct __DRIversionRec {
     int    major;        /**< Major version number. */
@@ -847,6 +887,8 @@ struct __DRIversionRec {
  *     __driUtilCreateNewScreen CallCreateNewScreen
  *
  * \bug This structure could be better named.
+ *
+ * Not used by the X server since DRI1 was deleted.
  */
 struct __DRIframebufferRec {
     unsigned char *base;    /**< Framebuffer base address in the CPU's
@@ -865,9 +907,9 @@ struct __DRIframebufferRec {
 
 
 /**
- * This extension provides alternative screen, drawable and context
+ * This extension provides alternative screen, drawable and context constructors
- * constructors for swrast DRI functionality.  This is used in
+ * for swrast DRI functionality.  This is used in conjunction with the core
- * conjunction with the core extension.
+ * extension.  Version 1 is required by the X server, and version 3 is used.
  */
 #define __DRI_SWRAST "DRI_SWRast"
 #define __DRI_SWRAST_VERSION 4
@@ -966,6 +1008,7 @@ typedef unsigned int
 /* Inofficial and for internal use. Increase when adding a new buffer token. */
 #define __DRI_BUFFER_COUNT		11
 
+/* Used by the X server. */
 struct __DRIbufferRec {
     unsigned int attachment;
     unsigned int name;
@@ -974,6 +1017,7 @@ struct __DRIbufferRec {
     unsigned int flags;
 };
 
+/* The X server implements up to version 3 of the DRI2 loader. */
 #define __DRI_DRI2_LOADER "DRI_DRI2Loader"
 #define __DRI_DRI2_LOADER_VERSION 5
 
@@ -1059,7 +1103,7 @@ struct __DRIdri2LoaderExtensionRec {
 
 /**
  * This extension provides alternative screen, drawable and context
- * constructors for DRI2.
+ * constructors for DRI2.  The X server uses up to version 4.
  */
 #define __DRI_DRI2 "DRI_DRI2"
 #define __DRI_DRI2_VERSION 4
@@ -1786,6 +1830,8 @@ struct __DRI2configQueryExtensionRec {
  * \c __DRI_CTX_FLAG_ROBUST_BUFFER_ACCESS flag and the
  * \c __DRI_CTX_ATTRIB_RESET_STRATEGY attribute in
  * \c __DRIdri2ExtensionRec::createContextAttribs.
+ *
+ * Used by the X server.
  */
 #define __DRI2_ROBUSTNESS "DRI_Robustness"
 #define __DRI2_ROBUSTNESS_VERSION 1
@@ -1803,6 +1849,8 @@ struct __DRIrobustnessExtensionRec {
  *
  * This extension is deprecated, and modern loaders will not use it. Please
  * use __DRI2_RENDERER_HAS_NO_ERROR_CONTEXT instead.
+ *
+ * Not used by the X server.
  */
 #define __DRI2_NO_ERROR "DRI_NoError"
 #define __DRI2_NO_ERROR_VERSION 1
@@ -1817,6 +1865,8 @@ typedef struct __DRInoErrorExtensionRec {
  * Existence of this extension means the driver can accept the
  * \c __DRI_CTX_ATTRIB_RELEASE_BEHAVIOR attribute in
  * \c __DRIdri2ExtensionRec::createContextAttribs.
+ *
+ * Used by the X server.
  */
 #define __DRI2_FLUSH_CONTROL "DRI_FlushControl"
 #define __DRI2_FLUSH_CONTROL_VERSION 1
@@ -2039,7 +2089,9 @@ struct __DRIimageLoaderExtensionRec {
 };
 
 /**
- * DRI extension.
+ * Main DRI3 interface extension.
+ *
+ * Not used by the X server.
  */
 
 #define __DRI_IMAGE_DRIVER           "DRI_IMAGE_DRIVER"
@@ -2140,6 +2192,8 @@ struct __DRIbackgroundCallableExtensionRec {
  *      care that SurfaceFlinger and hwcomposer can consume the compression
  *      format.
  *
+ * Not used by the X server.
+ *
  * \see __DRI_IMAGE_BUFFER_SHARED
  * \see __DRI_ATTRIB_MUTABLE_RENDER_BUFFER
  * \see __DRI_MUTABLE_RENDER_BUFFER_LOADER
@@ -2158,6 +2212,8 @@ struct __DRImutableRenderBufferDriverExtensionRec {
  * Requires loader extension DRI_IMAGE_LOADER, through which the loader sends
  * __DRI_IMAGE_BUFFER_SHARED to the driver.
  *
+ * Not used by the X server.
+ *
  * \see __DRI_MUTABLE_RENDER_BUFFER_DRIVER
  */
 #define __DRI_MUTABLE_RENDER_BUFFER_LOADER "DRI_MutableRenderBufferLoader"