advanced.html 11.4 KB
Newer Older
1
<!-- begin header.html -->
ikits's avatar
ikits committed
2
<!--
ikits's avatar
ikits committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
The OpenGL Extension Wrangler Library
Copyright (C) 2002-2008, Milan Ikits <milan ikits[]ieee org>
Copyright (C) 2002-2008, Marcelo E. Magallon <mmagallo[]debian org>
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.
ikits's avatar
ikits committed
31
-->
ikits's avatar
ikits committed
32
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html/4/loose.dtd">
ikits's avatar
ikits committed
33 34 35
<!-- &nbsp;<img src="new.png" height="12" alt="NEW!"> -->
<html>
<head>
36
<title>GLEW: The OpenGL Extension Wrangler Library</title>
ikits's avatar
ikits committed
37 38
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 
<link href="glew.css" type="text/css" rel="stylesheet">
ikits's avatar
ikits committed
39 40
</head>
<body bgcolor="#fff0d0">
ikits's avatar
ikits committed
41
<table border="0" width="100%" cellpadding="12" cellspacing="8" style="height:100%">
ikits's avatar
ikits committed
42 43 44 45 46
<tr>
<td bgcolor="#ffffff" align="left" valign="top" width="200">
<table border="0" width="100%" cellpadding="0" cellspacing="0" align="left">
<tr>
<td valign="top">
47

ikits's avatar
ikits committed
48
<table border="0" width="100%" cellpadding="0" cellspacing="0" align="left">
49
<tr><td align="center"><i>Latest Release: <a href="https://sourceforge.net/projects/glew/files/glew/1.5.8/">1.5.8</a></i></td></tr>
ikits's avatar
ikits committed
50 51 52 53 54
<tr><td align="center"><br></td></tr>
<tr><td align="center"><img src="./glew.png" alt="GLEW Logo" width="97" height="75"></td></tr>
<tr><td align="center"><br></td></tr>
<tr><td align="center">
<table border="0" cellpadding="0" cellspacing="0" align="center">
ikits's avatar
ikits committed
55
<tr><td align="center"><a href="index.html">Download</a></td></tr>
ikits's avatar
ikits committed
56
<tr><td align="center"><a href="install.html">Installation</a></td></tr>
ikits's avatar
ikits committed
57
<tr><td align="center"><a href="basic.html">Basic Usage</a></td></tr>
58
<tr><td align="center">Advanced Usage</td></tr>
ikits's avatar
ikits committed
59 60 61
<tr><td align="center"><a href="credits.html">Credits & Copyright</a></td></tr>
<tr><td align="center"><a href="log.html">Change Log</a></td></tr>
<tr><td align="center"><a href="http://sourceforge.net/projects/glew/">Project Page</a></td></tr>
ikits's avatar
ikits committed
62
<tr><td align="center"><a href="https://sourceforge.net/mail/?group_id=67586">Mailing Lists</a></td></tr>
ikits's avatar
ikits committed
63 64 65 66 67 68 69
<tr><td align="center"><a href="http://sourceforge.net/tracker/?group_id=67586">Bug Tracker</a></td></tr>
</table>
<tr><td align="center"><br></tr>
</table>
</td>
</tr>
<tr>
70

ikits's avatar
ikits committed
71 72
<td valign="bottom">
<table border="0" width="100%" cellpadding="5" cellspacing="0" align="left">
73
<tr><td align="center"><i>Last Update: 01-31-11</i></td></tr>
ikits's avatar
ikits committed
74 75
<tr><td align="center">
<a href="http://www.opengl.org"> <img src="./ogl_sm.jpg" width="68"
ikits's avatar
ikits committed
76
height="35" border="0" alt="OpenGL Logo"></a>
ikits's avatar
ikits committed
77 78
<a href="http://sourceforge.net"> <img
src="http://sourceforge.net/sflogo.php?group_id=67586&amp;type=1"
ikits's avatar
ikits committed
79
width="88" height="31" border="0" alt="SourceForge Logo"></a>
ikits's avatar
ikits committed
80 81
</td>
</tr>
82
<!--- <tr><td align="center"><a
ikits's avatar
ikits committed
83 84
href="http://sourceforge.net/donate/index.php?group_id=67586"><img
src="http://images.sourceforge.net/images/project-support.jpg"
85
width="88" height="32" border="0" alt="Support This Project"></a></td></tr> -->
ikits's avatar
ikits committed
86 87 88 89 90 91 92
</table>
</td>
</tr>
</table>
</td>

<td bgcolor="#ffffff" align="left" valign="top">
ikits's avatar
ikits committed
93

ikits's avatar
ikits committed
94 95
<h1>The OpenGL Extension Wrangler Library</h1>

96 97 98
<!-- end header.html -->


ikits's avatar
ikits committed
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
<h2>Automatic Code Generation</h2>

<p>
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.
</p>

<p>
The code generation scripts require GNU make, wget, and perl. On
Windows, the simplest way to get access to these tools is to install
ikits's avatar
ikits committed
119 120
<a href="http://www.cygwin.com/">Cygwin</a>, but make sure that the
root directory is mounted in binary mode. The makefile in the
ikits's avatar
ikits committed
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
<tt>auto</tt> directory provides the following build targets:
</p>

<center>
<table border=0 cellpadding=0 cellspacing=0> <!-- bgcolor="#f0f0f0" -->
<tr><td align="right" valign="top" width="25%"><tt>make</tt></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td align=left>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.</td></tr>
<tr><td align="right" valign="top"><tt>make clean</tt></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td align=left>Delete the source files.</td></tr>
<tr><td align="right" valign="top"><tt>make clobber</tt></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td align=left>Delete the source files and the descriptors.</td></tr>
<tr><td align="right" valign="top"><tt>make destroy</tt></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td align=left>Delete the source files, the descriptors, and the spec files.</td></tr>
<tr><td align="right" valign="top"><tt>make custom</tt></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td align=left>Create the source files for the extensions
listed in <tt>auto/custom.txt</tt>. See "Custom Code
Generation" below for more details.</td></tr>
</table>
</center>

<h3>Adding a New Extension</h3>

<p>
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.
</p>

<p>
The format of the descriptor file is given below. Items in
brackets are optional.
</p>

<p class="pre">
&lt;Extension Name&gt;<br>
[&lt;URL of Specification File&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Token Name&gt; &lt;Token Value&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Token Name&gt; &lt;Token Value&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Typedef&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Typedef&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Function Signature&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Function Signature&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br>
<!-- &nbsp;&nbsp;&nbsp;&nbsp;[&lt;Function Definition&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;[&lt;Function Definition&gt;]<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br> -->
</p>

<!--
<p>
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.
</p>
-->

<p>
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.
</p>

<h3>Custom Code Generation</h3>
<p>
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.
</p>

<p>
For example, the following is the list of extensions needed to get GLEW and the
utilities to compile.
</p>

<p class="pre">
WGL_ARB_extensions_string<br>
WGL_ARB_multisample<br>
WGL_ARB_pixel_format<br>
WGL_ARB_pbuffer<br>
WGL_EXT_extensions_string<br>
WGL_ATI_pixel_format_float<br>
WGL_NV_float_buffer<br>
</p>

<h2>Multiple Rendering Contexts (GLEW MX)</h2>

<p>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:</p>
<ol>
<li>Compile and use GLEW with the <tt>GLEW_MX</tt> preprocessor token
defined.</li>
<li>For each rendering context, create a <tt>GLEWContext</tt> object
that will be available as long as the rendering context exists.</li>
<li>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.
<li>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.
</ol>

<p>Note that according to the <a
href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/opengl/ntopnglr_6yer.asp">MSDN
WGL documentation</a>, 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.  <b>GLEW by
default ignores this requirement, and does not define per-context
entry points (you can however do this using the steps described
above).</b> 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.</p>

<h2>Separate Namespace</h2>

<p>
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.
</p>

<h2>Known Issues</h2>

<p>
GLEW requires GLX 1.2 for compatibility with GLUT.
</p>

275 276 277
<!-- begin footer.html -->
</td></tr></table></body>
<!-- end footer.html -->
ikits's avatar
ikits committed
278