From 2c7e289d8b1d3c63ab55b64ab3961067fd5a1985 Mon Sep 17 00:00:00 2001 From: Ian Romanick Date: Wed, 15 Apr 2015 11:34:50 -0700 Subject: [PATCH] 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 Cc: Emil Velikov --- src/glx/glxextensions.c | 69 ++++++++++++++++++++++++++++++++++++++--- 1 file 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* */ -- 2.30.2