mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
116 lines
4.1 KiB
Plaintext
116 lines
4.1 KiB
Plaintext
/*!
|
|
|
|
@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
|
|
|
|
*/
|