glx: Massive update of comments in struct extension_info

In response to another patch, Emil asked for some clarification how this
stuff works.  Rather than just reply to the e-mail, I decided to update
the exlanation in the code.

Signed-off-by: Ian Romanick <[email protected]>
Cc: Emil Velikov <[email protected]>

1 files changed, 65 insertions, 4 deletions

diff --git a/src/glx/glxextensions.c b/src/glx/glxextensions.c
index a326f0ded8a..cb8cd665a88 100644
--- a/src/glx/glxextensions.c
+++ b/src/glx/glxextensions.c
@@ -61,12 +61,73 @@ struct extension_info
     */
    unsigned char version_major;
    unsigned char version_minor;
+
+   /**
+    * The client (i.e., libGL) supports this extension.
+    *
+    * Except during bring up, all extensions should have this set to Y.  There
+    * are a few cases of extensions that have partial (or speculative)
+    * support, but these are rare.  There also shouldn't be any new ones
+    * added.
+    *
+    * Generally, extensions require server support and ::client_support to be
+    * enabled.  If the display is capable of direct rendering,
+    * ::direct_support is also required.
+    *
+    * \sa ::client_only
+    */
    unsigned char client_support;
+
+   /**
+    * The direct-renderer (e.g., i965_dri.so) supports this extension.
+    *
+    * For cases where all of the infrastructure to support the extension is a
+    * required part of the loader/driver interface, this can default to Y.
+    * For most cases, extended functionality, usually in the form of DRI2
+    * extensions, is necessary to support the extension.  The loader will set
+    * the flag true if all the requirements are met.
+    *
+    * If the display is capable of direct rendering, ::direct_support is
+    * required for the extension to be enabled.
+    */
    unsigned char direct_support;
-   unsigned char client_only;        /** Is the extension client-side only? */
-   unsigned char direct_only;        /** Is the extension for direct
-				      * contexts only?
-				      */
+
+   /**
+    * The extension depends only on client support.
+    *
+    * This is for extensions like GLX_ARB_get_proc_address that are contained
+    * entirely in the client library.  There is no dependency on the server or
+    * the direct-renderer.
+    *
+    * These extensions will be enabled if ::client_support is set.
+    *
+    * \note
+    * An extension \b cannot be both client-only and direct-only because being
+    * direct-only implies a dependency on the direct renderer.
+    *
+    * \sa ::client_support, ::direct_only
+    */
+   unsigned char client_only;
+
+   /**
+    * The extension only functions with direct-rendering contexts
+    *
+    * The extension has no GLX protocol, and, therefore, no explicit
+    * dependency on the server.  The functionality is contained entirely in
+    * the client library and the direct renderer.  A few of the swap-related
+    * extensions are intended to behave this way.
+    *
+    * These extensions will be enabled if both ::client_support and
+    * ::direct_support are set.
+    *
+    * \note
+    * An extension \b cannot be both client-only and direct-only because being
+    * client-only implies that all functionality is outside the
+    * direct-renderer.
+    *
+    * \sa ::direct_support, ::client_only
+    */
+   unsigned char direct_only;
 };
 
 /* *INDENT-OFF* */