The OpenGL Extension Wrangler Library

Copyright (C) 2002-2008, Milan Ikits <milan ikits[]ieee="" org=""></milan>

Copyright (C) 2002-2008, Marcelo E. Magallon <mmagallo[]debian org=""></mmagallo[]debian>

Copyright (C) 2002, Lev Povalahev

All rights reserved.

Redistribution and use in source and binary forms, with or without 

modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, 

  this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, 

  this list of conditions and the following disclaimer in the documentation 

  and/or other materials provided with the distribution.

* The name of the author may be used to endorse or promote products 

  derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF

THE POSSIBILITY OF SUCH DAMAGE.

-->

<title>GLEW: The OpenGL Extension Wrangler Library</title>

<meta content="text/html; charset=US-ASCII" http-equiv="Content-Type"> 

<link href="glew.css" rel="stylesheet" type="text/css">

Latest Release: 1.9.0

Download

Usage

Building

Installation

Source Generation

Credits & Copyright

Change Log

Project Page

Mailing Lists

Bug Tracker

Last Update: 08-06-12

height="35" border="0" alt="OpenGL Logo">

src="http://sourceforge.net/sflogo.php?group_id=67586&type=1"

width="88" height="31" border="0" alt="SourceForge Logo">

href="http://sourceforge.net/donate/index.php?group_id=67586">

src="http://images.sourceforge.net/images/project-support.jpg"

width="88" height="32" border="0" alt="Support This Project"> -->

The OpenGL Extension Wrangler Library

Automatic Code Generation

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 <tt>auto</tt> 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, but make sure that the

root directory is mounted in binary mode. The makefile in the

<tt>auto</tt> directory provides the following build targets:

<tt>make</tt>

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.

<tt>make clean</tt>

Delete the source files.

<tt>make clobber</tt>

Delete the source files and the descriptors.

<tt>make destroy</tt>

Delete the source files, the descriptors, and the spec files.

<tt>make custom</tt>

Create the source files for the extensions

listed in <tt>auto/custom.txt</tt>.
 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

<tt>auto/core</tt> and rerun the code generation scripts by typing

<tt>make clean; make</tt> in the <tt>auto</tt> directory.

The format of the descriptor file is given below. Items in

brackets are optional.

<Extension Name>

[<URL of Specification File>]

    [<Token Name> <Token Value>]

    [<Token Name> <Token Value>]

    ...

    [<Typedef>]

    [<Typedef>]

    ...

    [<Function Signature>]

    [<Function Signature>]

    ...

    [<Function Definition>]

    ...
 -->

Note that <tt>Function Definitions</tt> are copied to the header files

without changes and have to be terminated with a semicolon. In

contrast, <tt>Tokens</tt>, <tt>Function signatures</tt>, and

<tt>Typedefs</tt> should not be terminated with a semicolon.

-->

Take a look at one of the files in <tt>auto/core</tt> 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

<tt>auto/custom.txt</tt>. This is useful when you do not need all the

extensions and would like to reduce the size of the source files.

Type <tt>make clean; make custom</tt> in the <tt>auto</tt> 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.

WGL_ARB_extensions_string

WGL_ARB_multisample

WGL_ARB_pixel_format

WGL_ARB_pbuffer

WGL_EXT_extensions_string

WGL_ATI_pixel_format_float

WGL_NV_float_buffer

Multiple Rendering Contexts (GLEW MX)

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 <tt>GLEW_MX</tt> preprocessor token

defined.

For each rendering context, create a <tt>GLEWContext</tt> object

that will be available as long as the rendering context exists.

Define a macro or function called <tt>glewGetContext()</tt> that

returns a pointer to the <tt>GLEWContext</tt> 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 <tt>glewInit()</tt> after creating the

<tt>GLEWContext</tt> object in each rendering context.  Note, that the

<tt>GLEWContext</tt> pointer returned by <tt>glewGetContext()</tt> has

to reside in global or thread-local memory.

Note that according to the 

href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/opengl/ntopnglr_6yer.asp">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 <tt>glewInit()</tt> 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,

<tt>glFancyFunction</tt> is simply an alias to

<tt>glewFancyFunction</tt>.  The separate namespace does not effect

token and function pointer definitions.

Known Issues

GLEW requires GLX 1.2 for compatibility with GLUT.