From 898f22082db36617ac0e1d4776750598a0dc1ea0 Mon Sep 17 00:00:00 2001 From: Nigel Stewart Date: Tue, 2 Aug 2011 17:17:30 -0400 Subject: [PATCH] Add a build.html documentation page for describing some of the make targets and variables. --- auto/Makefile | 1 + auto/doc/advanced.html | 25 ++-- auto/doc/build.html | 35 ++++++ auto/src/header.html | 5 +- doc/build.html | 279 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 327 insertions(+), 18 deletions(-) create mode 100644 auto/doc/build.html create mode 100644 doc/build.html diff --git a/auto/Makefile b/auto/Makefile index f4a24d1..619afab 100644 --- a/auto/Makefile +++ b/auto/Makefile @@ -64,6 +64,7 @@ D.TARGETS = \ $(D.DEST)/install.html \ $(D.DEST)/basic.html \ $(D.DEST)/advanced.html \ + $(D.DEST)/build.html \ $(D.DEST)/credits.html \ $(D.DEST)/log.html \ $(D.DEST)/glew.html \ diff --git a/auto/doc/advanced.html b/auto/doc/advanced.html index 45a3ada..4bf2aa8 100644 --- a/auto/doc/advanced.html +++ b/auto/doc/advanced.html @@ -23,29 +23,22 @@ root directory is mounted in binary mode. 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 + + + - - + - - + - - + - - +
makeCreate 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    
make clean Delete the source files.
make clobber    
make clobber Delete the source files and the descriptors.
make destroy    
make destroy Delete the source files, the descriptors, and the spec files.
make custom    
make custom Create the source files for the extensions -listed in auto/custom.txt. See "Custom Code +listed in auto/custom.txt.
See "Custom Code Generation" below for more details.
-

Adding a New Extension

diff --git a/auto/doc/build.html b/auto/doc/build.html new file mode 100644 index 0000000..888f3f5 --- /dev/null +++ b/auto/doc/build.html @@ -0,0 +1,35 @@ +

Building GLEW

+ +

Windows

+ +

A MS Visual Studio project is provided in the build/vc6 directory.

+

Pre-built shared and static libraries are also available for download.

+ +

Makefile

+ +

For platforms other than MS Windows, the provided Makefile is used.

+ +

Command-line variables:

+ + + + + + +
SYSTEMautoTarget system to build: darwin, linux, solaris, etc.
For a full list of supported targets: ls config/Makefile.*
+config.guess is used to auto detect, as necessary.
GLEW_DEST/usrBase directory for installation.
+ +

Make targets:

+ + + + + + + + + + + + +
allBuild everything.
glew.libBuild static and dynamic GLEW libraries.
glew.lib.mxBuild static and dynamic GLEWmx libraries.
glew.binBuild glewinfo and visualinfo utilities.
cleanDelete temporary and built files.
install.allInstall everything.
installInstall GLEW libraries.
install.mxInstall GLEWmx libraries.
install.binInstall glewinfo and visualinfo utilities.
uninstallDelete installed files.
diff --git a/auto/src/header.html b/auto/src/header.html index 4cbd3df..5fa4911 100644 --- a/auto/src/header.html +++ b/auto/src/header.html @@ -53,9 +53,10 @@ THE POSSIBILITY OF SUCH DAMAGE.
+ + - - + diff --git a/doc/build.html b/doc/build.html new file mode 100644 index 0000000..028e61d --- /dev/null +++ b/doc/build.html @@ -0,0 +1,279 @@ + + + + + + +GLEW: The OpenGL Extension Wrangler Library + + + + +
Download
Usage
Building
Installation
Basic Usage
Advanced Usage
Source Generation
Credits & Copyright
Change Log
Project Page
+ + + +
+ + + + + + + + +
+ + + + + + + +
Latest Release: 1.6.0

GLEW Logo

+ + + + + + + + + + + +
Download
Installation
Basic Usage
Source Generation
Building
Credits & Copyright
Change Log
Project Page
Mailing Lists
Bug Tracker
+

+
+ + + + + +
Last Update: 04-27-11
+ OpenGL Logo + SourceForge Logo +
+
+		 + +

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 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, but make sure that the +root directory is mounted in binary mode. 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. +

+ +

+<Extension Name>
+[<URL of Specification File>]
+    [<Token Name> <Token Value>]
+    [<Token Name> <Token Value>]
+    ...
+    [<Typedef>]
+    [<Typedef>]
+    ...
+    [<Function Signature>]
+    [<Function Signature>]
+    ...
+ +

+ + + +

+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. +

+ +

+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:

+
    +
  1. Compile and use GLEW with the GLEW_MX preprocessor token +defined.
    2. +
  2. For each rendering context, create a GLEWContext object +that will be available as long as the rendering context exists.
    3. +
  3. 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. +
  4. 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. +

+ + +
+ +