src/macos/glew-1.4.0/doc/advanced.html - vendor/opensource/projectM - Git at Google

 <!--
  Copyright (C) 2002-2007, Milan Ikits <milan ikits[]ieee org>
  Copyright (C) 2002-2007, Marcelo E. Magallon <mmagallo[]debian org>
  This documentation may not be modified or redistributed in any
  form, except by the copyright holder.
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html/4/loose.dtd">
 <!-- &nbsp;<img src="new.png" height="12" alt="NEW!"> -->
 <html>
 <head>
 <title>
 GLEW: The OpenGL Extension Wrangler Library
 </title>
 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <link href="glew.css" type="text/css" rel="stylesheet">
 </head>
 <body bgcolor="#fff0d0">
 <table border="0" width="100%" cellpadding="12" cellspacing="8" style="height:100%">
 <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">
 <table border="0" width="100%" cellpadding="0" cellspacing="0" align="left">
 <tr><td align="center"><i>Latest Release: <a href="https://sourceforge.net/project/showfiles.php?group_id=67586&amp;package_id=67942&amp;release_id=504079">1.4.0</a></i></td></tr>
 <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">
 <tr><td align="center"><a href="index.html">Download</a></td></tr>
 <tr><td align="center"><a href="install.html">Installation</a></td></tr>
 <tr><td align="center"><a href="basic.html">Basic Usage</a></td></tr>
 <tr><td align="center"><b>Advanced Usage</b></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>
 <tr><td align="center"><a href="https://sourceforge.net/mail/?group_id=67586">Mailing Lists</a></td></tr>
 <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>
 <td valign="bottom">
 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="left">
 <tr><td align="center"><i>Last Update: 04-27-07</i></td></tr>
 <tr><td align="center">
 <a href="http://www.opengl.org"> <img src="./ogl_sm.jpg" width="68"
 height="35" border="0" alt="OpenGL Logo"></a>
 <a href="http://sourceforge.net"> <img
 src="http://sourceforge.net/sflogo.php?group_id=67586&amp;type=1"
 width="88" height="31" border="0" alt="SourceForge Logo"></a>
 </td>
 </tr>
 <tr><td align="center"><a
 href="http://sourceforge.net/donate/index.php?group_id=67586"><img
 src="http://images.sourceforge.net/images/project-support.jpg"
 width="88" height="32" border="0" alt="Support This Project"></a></td></tr>
 </table>
 </td>
 </tr>
 </table>
 </td>

 <td bgcolor="#ffffff" align="left" valign="top">

 <h1>The OpenGL Extension Wrangler Library</h1>

 <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
 <a href="http://www.cygwin.com/">Cygwin</a>, 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:
 </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>

 </td>
 </tr>

 </table>

 </body>
	<!--
	Copyright (C) 2002-2007, Milan Ikits <milan ikits[]ieee org>
	Copyright (C) 2002-2007, Marcelo E. Magallon <mmagallo[]debian org>
	This documentation may not be modified or redistributed in any
	form, except by the copyright holder.
	-->
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html/4/loose.dtd">
	<!--  <img src="new.png" height="12" alt="NEW!"> -->
	<html>
	<head>
	<title>
	GLEW: The OpenGL Extension Wrangler Library
	</title>
	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	<link href="glew.css" type="text/css" rel="stylesheet">
	</head>
	<body bgcolor="#fff0d0">
	<table border="0" width="100%" cellpadding="12" cellspacing="8" style="height:100%">
	<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">
	<table border="0" width="100%" cellpadding="0" cellspacing="0" align="left">
	<tr><td align="center"><i>Latest Release: <a href="https://sourceforge.net/project/showfiles.php?group_id=67586&package_id=67942&release_id=504079">1.4.0</a></i></td></tr>
	<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">
	<tr><td align="center"><a href="index.html">Download</a></td></tr>
	<tr><td align="center"><a href="install.html">Installation</a></td></tr>
	<tr><td align="center"><a href="basic.html">Basic Usage</a></td></tr>
	<tr><td align="center"><b>Advanced Usage</b></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>
	<tr><td align="center"><a href="https://sourceforge.net/mail/?group_id=67586">Mailing Lists</a></td></tr>
	<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>
	<td valign="bottom">
	<table border="0" width="100%" cellpadding="5" cellspacing="0" align="left">
	<tr><td align="center"><i>Last Update: 04-27-07</i></td></tr>
	<tr><td align="center">
	<a href="http://www.opengl.org"> <img src="./ogl_sm.jpg" width="68"
	height="35" border="0" alt="OpenGL Logo"></a>
	<a href="http://sourceforge.net"> <img
	src="http://sourceforge.net/sflogo.php?group_id=67586&type=1"
	width="88" height="31" border="0" alt="SourceForge Logo"></a>
	</td>
	</tr>
	<tr><td align="center"><a
	href="http://sourceforge.net/donate/index.php?group_id=67586"><img
	src="http://images.sourceforge.net/images/project-support.jpg"
	width="88" height="32" border="0" alt="Support This Project"></a></td></tr>
	</table>
	</td>
	</tr>
	</table>
	</td>

	<td bgcolor="#ffffff" align="left" valign="top">

	<h1>The OpenGL Extension Wrangler Library</h1>

	<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
	<a href="http://www.cygwin.com/">Cygwin</a>, 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:
	</p>

	<center>
	<table border=0 cellpadding=0 cellspacing=0> <!-- bgcolor="#f0f0f0" -->
	<tr><td align="right" valign="top" width="25%"><tt>make</tt></td>
	<td>    </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>    </td>
	<td align=left>Delete the source files.</td></tr>
	<tr><td align="right" valign="top"><tt>make clobber</tt></td>
	<td>    </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>    </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>    </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">
	<Extension Name><br>
	[<URL of Specification File>]<br>
	[<Token Name> <Token Value>]<br>
	[<Token Name> <Token Value>]<br>
	...<br>
	[<Typedef>]<br>
	[<Typedef>]<br>
	...<br>
	[<Function Signature>]<br>
	[<Function Signature>]<br>
	...<br>
	<!--     [<Function Definition>]<br>
	[<Function Definition>]<br>
	...<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>

	</td>
	</tr>

	</table>

	</body>