basic.html 9.51 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>
57
<tr><td align="center">Basic Usage</td></tr>
ikits's avatar
ikits committed
58 59 60 61
<tr><td align="center"><a href="advanced.html">Advanced Usage</a></td></tr>
<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
<h1>The OpenGL Extension Wrangler Library</h1>
ikits's avatar
ikits committed
95

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 119 120 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
<h2>Initializing GLEW</h2>
<p>
First you need to create a valid OpenGL rendering context and call
<tt>glewInit()</tt> to initialize the extension entry points.  If
<tt>glewInit()</tt> returns <tt>GLEW_OK</tt>, the initialization
succeeded and you can use the available extensions as well as core
OpenGL functionality. For example:
</p>

<p class="pre">
#include &lt;GL/glew.h&gt;<br>
#include &lt;GL/glut.h&gt;<br>
...<br>
glutInit(&amp;argc, argv);<br>
glutCreateWindow("GLEW Test");<br>
GLenum err = glewInit();<br>
if (GLEW_OK != err)<br>
{<br>
&nbsp;&nbsp;/* Problem: glewInit failed, something is seriously wrong. */<br>
&nbsp;&nbsp;fprintf(stderr, "Error: %s\n", glewGetErrorString(err));<br>
&nbsp;&nbsp;...<br>
}<br>
fprintf(stdout, "Status: Using GLEW %s\n", glewGetString(GLEW_VERSION));<br>
</p>

<h2>Checking for Extensions</h2>

<p>
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 <tt>GLEW_{extension_name}</tt>:
</p>

<p class="pre">
if (GLEW_ARB_vertex_program)<br>
{<br>
&nbsp;&nbsp;/* It is safe to use the ARB_vertex_program extension here. */<br>
&nbsp;&nbsp;glGenProgramsARB(...);<br>
}<br>
</p>

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

<p>
You can also check for core OpenGL functionality.  For example, to
see if OpenGL 1.3 is supported, do the following:
</p>

<p class="pre">
if (GLEW_VERSION_1_3)<br>
{<br>
&nbsp;&nbsp;/* Yay! OpenGL 1.3 is supported! */<br>
}<br>
</p>

<p>
In general, you can check if <tt>GLEW_{extension_name}</tt> or
<tt>GLEW_VERSION_{version}</tt> is true or false.
</p>

<p>
It is also possible to perform extension checks from string
input. Starting from the 1.3.0 release, use <tt>glewIsSupported</tt>
to check if the required core or extension functionality is
available:
</p>

<p class="pre">
ikits's avatar
ikits committed
171
if (glewIsSupported("GL_VERSION_1_4&nbsp;&nbsp;GL_ARB_point_sprite"))<br>
ikits's avatar
ikits committed
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 275 276 277 278
{<br>
&nbsp;&nbsp;/* Great, we have OpenGL 1.4 + point sprites. */<br>
}<br>
</p>

<p>
For extensions only, <tt>glewGetExtension</tt> provides a slower alternative
(GLEW 1.0.x-1.2.x). <b>Note that in the 1.3.0 release </b>
<tt>glewGetExtension</tt> <b>was replaced with </b>
<tt>glewIsSupported</tt>.
</p>

<p class="pre">
if (glewGetExtension("GL_ARB_fragment_program"))<br>
{<br>
&nbsp;&nbsp;/* Looks like ARB_fragment_program is supported. */<br>
}<br>
</p>

<h2>Experimental Drivers</h2>

<p>
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 <tt>glewExperimental</tt> global switch can be turned
on by setting it to <tt>GL_TRUE</tt> before calling
<tt>glewInit()</tt>, which ensures that all extensions with valid
entry points will be exposed.
</p>

<h2>Platform Specific Extensions</h2>

<p>
Platform specific extensions are separated into two header files:
<tt>wglew.h</tt> and <tt>glxew.h</tt>, which define the available
<tt>WGL</tt> and <tt>GLX</tt> extensions.  To determine if a certain
extension is supported, query <tt>WGLEW_{extension name}</tt> or
<tt>GLXEW_{extension_name}</tt>.  For example:
</p>

<p class="pre">
#include &lt;GL/wglew.h&gt;<br>
<br>
if (WGLEW_ARB_pbuffer)<br>
{<br>
&nbsp;&nbsp;/* OK, we can use pbuffers. */<br>
}<br>
else<br>
{<br>
&nbsp;&nbsp;/* Sorry, pbuffers will not work on this platform. */<br>
}<br>
</p>

<p>
Alternatively, use <tt>wglewIsSupported</tt> or
<tt>glxewIsSupported</tt> to check for extensions from a string:
</p>

<p class="pre">
if (wglewIsSupported("WGL_ARB_pbuffer"))<br>
{<br>
&nbsp;&nbsp;/* OK, we can use pbuffers. */<br>
}<br>
</p>

<h2>Utilities</h2>

<p>
GLEW provides two command-line utilities: one for creating a list of
available extensions and visuals; and another for verifying extension
entry points.
</p>

<h3>visualinfo: extensions and visuals</h3>

<p>
<tt>visualinfo</tt> is an extended version of <tt>glxinfo</tt>. The
Windows version creates a file called <tt>visualinfo.txt</tt>, 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
<tt>visualinfo -h</tt>.
</p>

<h3>glewinfo: extension verification utility</h3>

<p>
<tt>glewinfo</tt> 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 <tt>glewinfo.txt</tt>. The
Unix version prints the results to <tt>stdout</tt>.
</p>

<p>Windows usage:</p>
 <blockquote><pre>glewinfo [-pf &lt;id&gt;]</pre></blockquote>

<p>where <tt>&lt;id&gt;</tt> is the pixel format id for which the
capabilities are displayed.</p>

<p>Unix usage:</p>
<blockquote><pre>glewinfo [-display &lt;dpy&gt;] [-visual &lt;id&gt;]</pre></blockquote>

<p>where <tt>&lt;dpy&gt;</tt> is the X11 display and <tt>&lt;id&gt;</tt> is
the visual id for which the capabilities are displayed.</p>

279 280 281
<!-- begin footer.html -->
</td></tr></table></body>
<!-- end footer.html -->
ikits's avatar
ikits committed
282