From 608109c249288e5089aef67a01129b63851d42b3 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Thu, 11 Apr 2013 20:18:46 +0200 Subject: [PATCH] Documentation work. --- docs/glext.dox | 115 +++++++++++++++++++++++++++++++++++++++++++++ include/GL/glfw3.h | 12 +++-- 2 files changed, 122 insertions(+), 5 deletions(-) create mode 100644 docs/glext.dox diff --git a/docs/glext.dox b/docs/glext.dox new file mode 100644 index 00000000..52021bb8 --- /dev/null +++ b/docs/glext.dox @@ -0,0 +1,115 @@ +/*! + +@page glext OpenGL extension handling + +One of the benefits of OpenGL is its extensibility. Independent hardware +vendors (IHVs) may include functionality in their OpenGL implementations that +expand upon the OpenGL standard before that functionality is included in a new +version of the OpenGL specification. + +An extension is defined by: + +- An extension name (e.g. `GL_ARB_debug_output`) +- New OpenGL tokens (e.g. `GL_DEBUG_SEVERITY_HIGH_ARB`) +- New OpenGL functions (e.g. `glGetDebugMessageLogARB`) + +Note the `ARB` affix, which stands for Architecture Review Board and is used +for official extensions. There are many different affixes, depending on who +wrote the extension. A list of extensions, together with their specifications, +can be found at the +[OpenGL Registry](http://www.opengl.org/registry/). + +To use a certain extension, you must first check whether the context exposes +that extension and then, if it introduces new functions, retrieve the pointers +to those functions. + +This can be done with GLFW, as will be described in this section, but usually +you will instead want to use a dedicated extension loading library such as +[GLEW](http://glew.sourceforge.net/). This kind of library greatly reduces the +amount of work necessary to use both OpenGL extensions and modern versions of +the OpenGL API. GLEW in particular has been extensively tested with and works +well with GLFW. + + +@section glext_header The glext.h header + +The `glext.h` header is a continually updated file that defines the interfaces +for all OpenGL extensions. The latest version of this can always be found at +the [OpenGL Registry](http://www.opengl.org/registry/). It it strongly +recommended that you use your own copy, as the one shipped with your development +environment may be several years out of date and may not include the extensions +you wish to use. + +The header defines function pointer types for all functions of all extensions it +supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for +`glGetDebugMessageLogARB`), i.e. the name is made uppercase, the `gl` prefix is +removed and `PFN` and `PROC` are added to the ends. + + +@section glext_string Checking for extensions + +A given machine may not actually support the extension (it may have older +drivers or a graphics card that lacks the necessary hardware features), so it +is necessary to check whether the context exposes the extension. This is done +with @ref glfwExtensionSupported. + +@code +if (glfwExtensionSupported("GL_ARB_debug_output")) +{ + // The extension is exposed by the current context +} +@endcode + +The argument is a null terminated ASCII string with the extension name. If the +extension is exposed, @ref glfwExtensionSupported returns non-zero, otherwise it +returns zero. + + +@section glext_proc Fetching function pointers + +Many extensions, though not all, require the use of new OpenGL functions. +These entry points are often not exposed by your link libraries, making +it necessary to fetch them at run time. With @ref glfwGetProcAddress you can +retrieve the address of extension and non-extension OpenGL functions. + +@code +PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB"); +@endcode + +In general, you should avoid giving the function pointer variables the (exact) +same name as the function, as this may confuse your linker. Instead, you can +use a different prefix, like above, or some other naming scheme. + +Now that all the pieces have been introduced, here is what they might look like +when used together. + +@code +#include "glext.h" + +#define glGetDebugMessageLogARB pfnGetDebugMessageLog +PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog; + +// Flag indicating whether the extension is present +int has_debug_output = 0; + +void load_extensions(void) +{ + if (glfwExtensionSupported("GL_ARB_debug_output")) + { + pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARB) glfwGetProcAddress("glGetDebugMessageLogARB"); + if (pfnGetDebugMessageLog) + { + // Both the extension name and the function pointer are present + has_debug_output = 1; + } + } +} + +void some_function(void) +{ + // Now the extension function can be called as usual + glGetDebugMessageLogARB(...); +} +@endcode + +*/ diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index 0ce69cc6..53115605 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -2048,9 +2048,10 @@ GLFWAPI void glfwSwapInterval(int interval); /*! @brief Returns whether the specified extension is available. * - * This function returns whether the specified OpenGL or platform-specific - * context creation API extension is supported by the current context. For - * example, on Windows both the OpenGL and WGL extension strings are checked. + * This function returns whether the specified + * [OpenGL or context creation API extension](@ref glext) is supported by the + * current context. For example, on Windows both the OpenGL and WGL extension + * strings are checked. * * @param[in] extension The ASCII encoded name of the extension. * @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise. @@ -2069,8 +2070,9 @@ GLFWAPI int glfwExtensionSupported(const char* extension); /*! @brief Returns the address of the specified function for the current * context. * - * This function returns the address of the specified client API function, if - * it is supported by the current context. + * This function returns the address of the specified + * [client API or extension function](@ref glext), if it is supported by the + * current context. * * @param[in] procname The ASCII encoded name of the function. * @return The address of the function, or `NULL` if the function is