Documentation work.

This commit is contained in:
Camilla Berglund 2013-04-11 20:18:46 +02:00
parent 2e8446fe74
commit 608109c249
2 changed files with 122 additions and 5 deletions

115
docs/glext.dox Normal file
View File

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

View File

@ -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