Documentation work.

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
+
+*/

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
+ *  This function returns whether the specified
- *  context creation API extension is supported by the current context.  For
+ *  [OpenGL or context creation API extension](@ref glext) is supported by the
- *  example, on Windows both the OpenGL and WGL extension strings are checked.
+ *  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
+ *  This function returns the address of the specified
- *  it is supported by the current context.
+ *  [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