-
-The goal of the OpenGL Extension Wrangler Library (GLEW) is to assist
-C/C++ OpenGL developers with two tedious tasks: initializing and using
-extensions and writing portable applications. GLEW provides an
-efficient run-time mechanism to determine whether a certain extension
-is supported by the driver or not. OpenGL core and extension
-functionality is exposed via a single header file. GLEW currently
-supports a variety of platforms and operating systems, including
-Windows, Linux, Darwin, Irix, and Solaris.
-
-
-There are two ways to build your project with GLEW.
-
-
-
Including the source files / project file
-
-
-The simpler but less flexible way is to include glew.h and
-glew.c into your project and define the GLEW_STATIC
-preprocessor constant for the static library or executable you are
-building together with GLEW (Windows only). You also need to replace
-<GL/gl.h> and <GL/glu.h> with
-<glew.h> in your code and set the appropriate include
-flag (-I) to tell the compiler where to look for it. For
-example:
-
-
#include <glew.h>
-#include <GL/glut.h>
-<gl, glu, and glut functionality is available here>
-
-
-Depending on where you put glew.h you may also need to change
-the include directives in glew.c. Note that if you are using
-GLEW together with GLUT, you have to include glew.h first.
-In addition, glew.h includes glu.h, so you don't
-need to include it separately.
-
-
-On Windows you also have the option of adding the supplied project
-file glew_static.dsp to your workspace (solution) and compile
-it together with your other projects. In this case you need to change
-the GLEW_BUILD preprocessor constant to GLEW_STATIC,
-otherwise you get build errors. Note that GLEW does not use the C
-runtime library, so it does not matter which version (single-threaded,
-multi-threaded or multi-threaded DLL) it is linked with (without
-debugging information). It is, however, always a good idea to compile all
-your projects including GLEW with the same C runtime settings.
-
-
-
-
Using GLEW as a shared library
-
-
-Alternatively, you can use the provided project files / makefile to
-build a separate shared library you can link your projects with later.
-In this case the best practice is to install glew.h,
-glew32.lib, and glew32.dll / libGLEW.so to
-where the OpenGL equivalents gl.h, opengl32.lib, and
-opengl32.dll / libGL.so are located. Note that you
-need administrative privileges to do this. If you do not have
-administrator access and your system administrator will not do it for
-you, you can install GLEW into your own lib and include subdirectories
-and tell the compiler where to find it. Then you can just replace
-<GL/gl.h> with <GL/glew.h> in your
-program:
-
-
#include <GL/glew.h>
-#include <GL/glut.h>
-<gl, glu, and glut functionality is available here>
-
-
-or:
-
-
#include <GL/glew.h>
-<gl and glu functionality is available here>
-
-
-
-Don't forget to link your project with glew32.lib,
-glu32.lib, and opengl32.lib on Windows and
-libGLEW.so, libGLU.so, and libGL.so on
-Linux and IRIX (-lGLEW -lGLU -lGL).
-
-
-It is important to keep in mind that glew.h includes neither
-windows.h nor gl.h. Also, GLEW will warn you by
-issuing a preprocessor error in case you have included gl.h,
-glext.h, or glATI.h before glew.h.
-
-To install the shared library version of GLEW you need to copy the
-headers and libraries into their destination directories. On Windows
-this boils down to copying (no, we will not write a Windows installer
-for you).
-
-
-
-
-
lib/glew32.dll
to
-
%SystemRoot%/system32
-
lib/glew32.lib
to
-
{VC Root}/Lib
-
include/GL/glew.h
to
-
{VC Root}/Include/GL
-
include/GL/wglew.h
to
-
{VC Root}/Include/GL
-
-
-
-
-where {VC Root} is your Visual C++ directory, typically
-C:/Program Files/Microsoft Visual Studio/VC98 for Visual
-Studio 6.0 or C:/Program Files/Microsoft Visual
-Studio/Vc7/PlatformSDK for Visual Studio .NET.
-
-
-On Linux and IRIX, typing "make install" will attempt to install GLEW
-into /usr/include/GL and /usr/lib. You can
-customize the installation target via the GLEW_DEST
-environment variable if you do not have write access
-to these directories.
-
-
-First you need to create a valid OpenGL rendering context and call
-glewInit() to initialize the extension entry points. If
-glewInit() returns GLEW_OK, the initialization
-succeeded and you can use the available extensions as well as core
-OpenGL functionality. For example:
-
-
-
-Starting from GLEW 1.1.0, you can find out if a particular extension
-is available on your platform by querying globally defined variables
-of the form GLEW_{extension_name}:
-
-
if (GLEW_ARB_vertex_program)
-{
- /* it is safe to use the ARB_vertex_program extension here */
- glGenProgramsARB(...);
-}
-
-
-In GLEW 1.0.x, a global structure was used for this task. To ensure
-binary compatibility between releases, the struct was replaced with a
-set of variables.
-
-
-
-You can also check for core OpenGL functionality. For example, to
-see if OpenGL 1.3 is supported:
-
-
if (GLEW_VERSION_1_3)
-{
- /* Yay! OpenGL 1.3 is supported! */
-}
-
-
-In general, you can check if GLEW_{extension_name} or
-GLEW_VERSION_{version} is set or not.
-
-
-
-For extensions glewGetExtension provides a slower alternative:
-
-
if (GL_TRUE == glewGetExtension("GL_ARB_fragment_program"))
-{
- /* Looks like ARB_fragment_program is supported. */
-}
-
-
-
-
-
-
Experimental drivers
-
-
-GLEW works by querying the supported extensions from the graphics
-driver. Experimental drivers, however, might not report every
-available extension through the standard mechanism, in which case GLEW
-will report it unsupported. To circumvent this situation, the
-glewExperimental global switch can be turned on by setting it
-to GL_TRUE before calling glewInit(). This makes
-sure that all extensions with valid entry points will be exposed.
-
-
-
-
Platform specific extensions
-
-
-Platform specific extensions are separated into two header files:
-wglew.h and glxew.h, which define the available
-WGL and GLX extensions. To determine if a certain
-extension is supported, query WGLEW_{extension name} or
-GLXEW_{extension_name}. For example:
-
-
#include <GL/wglew.h>
-
-if (WGLEW_ARB_pbuffer)
-{
- /* OK, we can use pbuffers */
-}
-else
-{
- /* Sorry, pbuffers will not work on this platform */
-}
-
-
-GLEW provides two command line tools: one for creating a list of
-available extensions and visuals; and another for verifying extension
-entry points.
-
-
-
-
visualinfo: extensions and visuals
-
-
-visualinfo is an extended version of glxinfo. On
-Windows, by default it creates a file called visualinfo.txt
-that contains a list of available OpenGL, WGL, and GLU extensions as
-well as a table of visuals aka. pixel formats. Pbuffer and multiple
-output capable visuals are also included. For additional usage
-information, type visualinfo -h.
-
-
-
-
glewinfo: extension verification utility
-
-
-glewinfo allows you to verify the entry points for the
-extensions supported on your platform. It uses GLEW to find out which
-extensions and entry points are available. On Windows it reports the
-results to a text file called glewinfo.txt, on Unix it prints
-them to stdout.
-
-Windows Usage:
glewinfo [-pf <id>]
-
-where <id> is the pixelformat id for which the
-capabilities are displayed.
-
-
-Unix Usage:
-
glewinfo [-display <dpy>] [-visual <id>]
-
-where <dpy> is the X11 display and <id> is
-the visual id for which the capabilities are displayed.
-
-
-Starting with release 1.1.0, the source code and parts of the
-documentation are automatically generated from the extension
-specifications via a two-step process. In the first step,
-specification files from the OpenGL registry are parsed and skeleton
-descriptors are created for each extension. These descriptors contain
-all necessary information for creating the source code and
-documentation in a simple and compact format, including the name of
-the extension, url, tokens, function declarations, typedefs and struct
-definitions. In the second step, the header files as well as the
-library and glewinfo source are generated from the descriptor
-files. The code generation scripts are located in the auto
-subdirectory.
-
-
-
-To avoid name clashes when linking with libraries that include the
-same symbol, extension entry points are declared in a separate
-namespace (release 1.1.0 and up). This is achieved by aliasing OpenGL
-function names to their GLEW equivalents. For instance,
-glFancyFunction is simply an alias to
-glewFancyFunction. Note that the separate namespace doesn't
-effect token and function pointer definitions.
-
-
-Starting with release 1.2.0, thread-safe support for multiple
-rendering contexts (possibly with different capabilities) is
-available. Since this is not required by most users, it is not added
-to the binary releases to maintain compatibility between different
-versions. To include multi-context support, you have to do the
-following:
-
-
-
Compile and use GLEW with the GLEW_MX preprocessor token
-defined.
-
For each rendering context, create a GLEWContext object
-that will be available as long as the rendering context exists.
-
Define a macro or function called glewGetContext() that
-returns a pointer to the GLEWContext object associated with
-the rendering context from which OpenGL/WGL/GLX calls are
-issued. (This dispatch mechanism is primitive, but generic.)
-
Replace the global glewInit() call with
-glewContextInit(glewGetContext()). Note, that the
-GLEWContext pointer returned by glewGetContext() has
-to reside in global or thread-local memory. Also, remember to call
-glewContextInit after creating the GLEWContext object
-in each rendering context.
-
-
-
Note that according to WGL
-documentation, you have to initialize the entry points for every
-rendering context you create that use pixel formats with different
-capabilities (for example the pixel formats provided by the generic
-software OpenGL implementation by Microsoft vs. the hardware
-accelerated pixel formats). GLEW by default ignores this
-requirement, and does not define per-context entry points (you can
-however do this using the steps described above). Assuming a
-global namespace for the entry points works in most situations,
-because typically all hardware accelerated pixel formats provide the
-same entry points and capabilities (and why would anyone want to use
-the software renderer when hardware acceleration is available?). This
-means that unless you use the multi-context version of GLEW, you need
-to call glewInit() only once in your program, or more
-precisely, once per process.
-
-GLEW was developed by Milan Ikits and Marcelo Magallon. They also
-perform occasional maintainance to make sure that GLEW stays in mint
-condition. Aaron Lefohn, Joe Kniss, and Chris Wyman were the first
-users and also assisted with the design and debugging process. The
-acronym GLEW originates from Aaron Lefohn. Pasi Kärkkäinen
-identified and fixed several problems with GLX and SDL. Nate Robins
-created the wglinfo utility, to which modifications were
-added by Michael Wimmer.
-
-
-
-GLEW is originally derived from the EXTGL project by Lev Povalahev. The
-source code is licensed under the modified BSD license, the SGI Free Software License B, and the GLX Public License. The automatic code
-generation scripts and the config.guess script (from the GNU config tools) are
-released under the GPL.
-
-
+Starting from release 1.1.0, the source code and parts of the
+documentation are automatically generated from the extension
+specifications in a two-step process. In the first step,
+specification files from the OpenGL registry are downloaded and
+parsed. Skeleton descriptors are created for each extension. These
+descriptors contain all necessary information for creating the source
+code and documentation in a simple and compact format, including the
+name of the extension, url link to the specification, tokens, function
+declarations, typedefs and struct definitions. In the second step,
+the header files as well as the library and glewinfo source are
+generated from the descriptor files. The code generation scripts are
+located in the auto subdirectory.
+
+
+
+The code generation scripts require GNU make, wget, and perl. On
+Windows, the simplest way to get access to these tools is to install
+Cygwin. The makefile in the
+auto directory provides the following build targets:
+
+
+
+
+
make
+
+
Create the source files from the descriptors. If the
+descriptors do not exist, create them from the spec files. If the spec
+files do not exist, download them from the OpenGL repository.
+
make clean
+
+
Delete the source files.
+
make clobber
+
+
Delete the source files and the descriptors.
+
make destroy
+
+
Delete the source files, the descriptors, and the spec files.
+
make custom
+
+
Create the source files for the extensions
+listed in auto/custom.txt. See "Custom Code
+Generation" below for more details.
+
+
+
+
Adding a New Extension
+
+
+To add a new extension, create a descriptor file for the extension in
+auto/core and rerun the code generation scripts by typing
+make clean; make in the auto directory.
+
+
+
+The format of the descriptor file is given below. Items in
+brackets are optional.
+
+Take a look at one of the files in auto/core for an
+example. Note that typedefs and function signatures should not be
+terminated with a semicolon.
+
+
+
Custom Code Generation
+
+Starting from GLEW 1.3.0, it is possible to control which extensions
+to include in the libarary by specifying a list in
+auto/custom.txt. This is useful when you do not need all the
+extensions and would like to reduce the size of the source files.
+Type make clean; make custom in the auto directory
+to rerun the scripts with the custom list of extensions.
+
+
+
+For example, the following is the list of extensions needed to get GLEW and the
+utilities to compile.
+
Starting with release 1.2.0, thread-safe support for multiple
+rendering contexts, possibly with different capabilities, is
+available. Since this is not required by most users, it is not added
+to the binary releases to maintain compatibility between different
+versions. To include multi-context support, you have to do the
+following:
+
+
Compile and use GLEW with the GLEW_MX preprocessor token
+defined.
+
For each rendering context, create a GLEWContext object
+that will be available as long as the rendering context exists.
+
Define a macro or function called glewGetContext() that
+returns a pointer to the GLEWContext object associated with
+the rendering context from which OpenGL/WGL/GLX calls are issued. This
+dispatch mechanism is primitive, but generic.
+
Make sure that you call glewInit() after creating the
+GLEWContext object in each rendering context. Note, that the
+GLEWContext pointer returned by glewGetContext() has
+to reside in global or thread-local memory.
+
+
+
Note that according to the MSDN
+WGL documentation, you have to initialize the entry points for
+every rendering context that use pixel formats with different
+capabilities For example, the pixel formats provided by the generic
+software OpenGL implementation by Microsoft vs. the hardware
+accelerated pixel formats have different capabilities. GLEW by
+default ignores this requirement, and does not define per-context
+entry points (you can however do this using the steps described
+above). Assuming a global namespace for the entry points works in
+most situations, because typically all hardware accelerated pixel
+formats provide the same entry points and capabilities. This means
+that unless you use the multi-context version of GLEW, you need to
+call glewInit() only once in your program, or more precisely,
+once per process.
+
+
Separate Namespace
+
+
+To avoid name clashes when linking with libraries that include the
+same symbols, extension entry points are declared in a separate
+namespace (release 1.1.0 and up). This is achieved by aliasing OpenGL
+function names to their GLEW equivalents. For instance,
+glFancyFunction is simply an alias to
+glewFancyFunction. The separate namespace does not effect
+token and function pointer definitions.
+
+
+
Known Issues
+
+
+GLEW requires GLX 1.2 for compatibility with GLUT.
+
+First you need to create a valid OpenGL rendering context and call
+glewInit() to initialize the extension entry points. If
+glewInit() returns GLEW_OK, the initialization
+succeeded and you can use the available extensions as well as core
+OpenGL functionality. For example:
+
+Starting from GLEW 1.1.0, you can find out if a particular extension
+is available on your platform by querying globally defined variables
+of the form GLEW_{extension_name}:
+
+
+
+if (GLEW_ARB_vertex_program)
+{
+ /* It is safe to use the ARB_vertex_program extension here. */
+ glGenProgramsARB(...);
+}
+
+
+
+In GLEW 1.0.x, a global structure was used for this task. To ensure
+binary compatibility between releases, the struct was replaced with a
+set of variables.
+
+
+
+You can also check for core OpenGL functionality. For example, to
+see if OpenGL 1.3 is supported, do the following:
+
+In general, you can check if GLEW_{extension_name} or
+GLEW_VERSION_{version} is true or false.
+
+
+
+It is also possible to perform extension checks from string
+input. Starting from the 1.3.0 release, use glewIsSupported
+to check if the required core or extension functionality is
+available:
+
+
+
+if (glewIsSupported("GL_VERSION_1_4 GL_ARB_point_sprites"))
+{
+ /* Great, we have OpenGL 1.4 + point sprites. */
+}
+
+
+
+For extensions only, glewGetExtension provides a slower alternative
+(GLEW 1.0.x-1.2.x). Note that in the 1.3.0 release
+glewGetExtensionwas replaced with
+glewIsSupported.
+
+
+
+if (glewGetExtension("GL_ARB_fragment_program"))
+{
+ /* Looks like ARB_fragment_program is supported. */
+}
+
+
+
Experimental Drivers
+
+
+GLEW obtains information on the supported extensions from the graphics
+driver. Experimental or pre-release drivers, however, might not
+report every available extension through the standard mechanism, in
+which case GLEW will report it unsupported. To circumvent this
+situation, the glewExperimental global switch can be turned
+on by setting it to GL_TRUE before calling
+glewInit(), which ensures that all extensions with valid
+entry points will be exposed.
+
+
+
Platform Specific Extensions
+
+
+Platform specific extensions are separated into two header files:
+wglew.h and glxew.h, which define the available
+WGL and GLX extensions. To determine if a certain
+extension is supported, query WGLEW_{extension name} or
+GLXEW_{extension_name}. For example:
+
+
+
+#include <GL/wglew.h>
+
+if (WGLEW_ARB_pbuffer)
+{
+ /* OK, we can use pbuffers. */
+}
+else
+{
+ /* Sorry, pbuffers will not work on this platform. */
+}
+
+
+
+Alternatively, use wglewIsSupported or
+glxewIsSupported to check for extensions from a string:
+
+
+
+if (wglewIsSupported("WGL_ARB_pbuffer"))
+{
+ /* OK, we can use pbuffers. */
+}
+
+
+
Utilities
+
+
+GLEW provides two command-line utilities: one for creating a list of
+available extensions and visuals; and another for verifying extension
+entry points.
+
+
+
visualinfo: extensions and visuals
+
+
+visualinfo is an extended version of glxinfo. The
+Windows version creates a file called visualinfo.txt, which
+contains a list of available OpenGL, WGL, and GLU extensions as well
+as a table of visuals aka. pixel formats. Pbuffer and MRT capable
+visuals are also included. For additional usage information, type
+visualinfo -h.
+
+
+
glewinfo: extension verification utility
+
+
+glewinfo allows you to verify the entry points for the
+extensions supported on your platform. The Windows version
+reports the results to a text file called glewinfo.txt. The
+Unix version prints the results to stdout.
+
+
+
Windows usage:
+
glewinfo [-pf <id>]
+
+
where <id> is the pixel format id for which the
+capabilities are displayed.
+
+
Unix usage:
+
glewinfo [-display <dpy>] [-visual <id>]
+
+
where <dpy> is the X11 display and <id> is
+the visual id for which the capabilities are displayed.
+GLEW was developed by Milan
+Ikits and Marcelo
+Magallon. They also perform occasional maintainance to make sure
+that GLEW stays in mint condition. Aaron Lefohn, Joe Kniss, and Chris
+Wyman were the first users and also assisted with the design and
+debugging process. The acronym GLEW originates from Aaron Lefohn.
+Pasi Kärkkäinen identified and fixed several problems with
+GLX and SDL. Nate Robins created the wglinfo utility, to
+which modifications were made by Michael Wimmer.
+
+
+
Copyright
+
+
+GLEW is originally derived from the EXTGL project by Lev Povalahev. The
+source code is licensed under the modified BSD license, the SGI Free Software License B, and the GLX Public License. The automatic code
+generation scripts are released under the GPL.
+
+The OpenGL Extension Wrangler Library (GLEW) is a cross-platform C/C++
+extension loading library. GLEW provides efficient run-time
+mechanisms for determining which OpenGL extensions are supported by
+the driver. OpenGL core and extension functionality is exposed in a
+single header file. GLEW currently supports a variety of platforms
+and operating systems, including Windows, Linux, Mac OSX, FreeBSD,
+Irix, and Solaris.
+
+
+
Supported Extensions
+
+The 1.3.0 release contains support for OpenGL 2.0 and the following extensions:
+
+To use the shared library version of GLEW, you need to copy the
+headers and libraries into their destination directories. On Windows
+this typically boils down to copying:
+
+
+
+
lib/glew32.dll
to
+
%SystemRoot%/system32
+
lib/glew32.lib
to
+
{VC Root}/Lib
+
include/GL/glew.h
to
+
{VC Root}/Include/GL
+
include/GL/wglew.h
to
+
{VC Root}/Include/GL
+
+
+
+
+
+where {VC Root} is the Visual C++ root directory, typically
+C:/Program Files/Microsoft Visual Studio/VC98 for Visual
+Studio 6.0 or C:/Program Files/Microsoft Visual
+Studio/Vc7/PlatformSDK for Visual Studio .NET.
+
+
+
+On Unix, typing make install will attempt to install GLEW
+into /usr/include/GL and /usr/lib. You can
+customize the installation target via the GLEW_DEST
+environment variable if you do not have write access to these
+directories.
+
+
+
Building Your Project with GLEW
+
+There are two ways to build your project with GLEW.
+
+
Including the source files / project file
+
+The simpler but less flexible way is to include glew.h and
+glew.c into your project. On Windows, you also need to
+define the GLEW_STATIC preprocessor token when building a
+static library or executable, and the GLEW_BUILD preprocessor
+token when building a dll. You also need to replace
+<GL/gl.h> and <GL/glu.h> with
+<glew.h> in your code and set the appropriate include
+flag (-I) to tell the compiler where to look for it. For
+example:
+
+
+#include <glew.h>
+#include <GL/glut.h>
+<gl, glu, and glut functionality is available here>
+
+
+Depending on where you put glew.h you may also need to change
+the include directives in glew.c. Note that if you are using
+GLEW together with GLUT, you have to include glew.h first.
+In addition, glew.h includes glu.h, so you do not
+need to include it separately.
+
+
+On Windows, you also have the option of adding the supplied project
+file glew_static.dsp to your workspace (solution) and compile
+it together with your other projects. In this case you also need to
+change the GLEW_BUILD preprocessor constant to
+GLEW_STATIC when building a static library or executable,
+otherwise you get build errors.
+
+
+Note that GLEW does not use the C
+runtime library, so it does not matter which version (single-threaded,
+multi-threaded or multi-threaded DLL) it is linked with (without
+debugging information). It is, however, always a good idea to compile all
+your projects including GLEW with the same C runtime settings.
+
+
+
Using GLEW as a shared library
+
+
+Alternatively, you can use the provided project files / makefile to
+build a separate shared library you can link your projects with later.
+In this case the best practice is to install glew.h,
+glew32.lib, and glew32.dll / libGLEW.so to
+where the OpenGL equivalents gl.h, opengl32.lib, and
+opengl32.dll / libGL.so are located. Note that you
+need administrative privileges to do this. If you do not have
+administrator access and your system administrator will not do it for
+you, you can install GLEW into your own lib and include subdirectories
+and tell the compiler where to find it. Then you can just replace
+<GL/gl.h> with <GL/glew.h> in your
+program:
+
+
+
+#include <GL/glew.h>
+#include <GL/glut.h>
+<gl, glu, and glut functionality is available here>
+
+
+
+or:
+
+
+
+#include <GL/glew.h>
+<gl and glu functionality is available here>
+
+
+
+Remember to link your project with glew32.lib,
+glu32.lib, and opengl32.lib on Windows and
+libGLEW.so, libGLU.so, and libGL.so on
+Unix (-lGLEW -lGLU -lGL).
+
+
+
+It is important to keep in mind that glew.h includes neither
+windows.h nor gl.h. Also, GLEW will warn you by
+issuing a preprocessor error in case you have included gl.h,
+glext.h, or glATI.h before glew.h.
+
