Commits

Jason McKesson committed 061a3f9

Reorganization and extra documentation.

Comments (0)

Files changed (2)

 {{{-extfile}}} specifies a //filename// to load extensions from. The format of this file is fairly simple; it is [[Extension Files|explained here on this site]]. The file is expected to contain extension names, one on each line. Extension files can also have {{{#include}}} directives, which will include another extension file (relative pathing only). Please don't infinitely recurse your inclusions; there's no protection in the system to check for it.
 
 The system has a number of [[Common_Extension_Files|common extension files]] that store useful sets of extensions. You may use these as you wish.
+==Examples==
+
+Here are some example command lines. This command-line generates loaders for core OpenGL 3.3, without proprietary extensions, but with non-hardware features that were added to OpenGL in later versions:
+
+{{{
+lua LoadGen.lua core_3_3 -style=pointer_c -spec=gl -version=3.3 -profile=core -stdext=extfiles/gl_ubiquitous.txt -stdext=extfiles/gl_core_post_3_3.txt
+}}}
+
+This command-line is for OpenGL 4.3, but with certain commonly-provided extensions that are generally useful.
+
+{{{
+lua LoadGen.lua core_4_3 -style=pointer_c -spec=gl -version=4.3 -profile=core -stdext=extfiles/gl_ubiquitous.txt -stdext=extfiles/gl_plat_3_3.txt
+}}}
+
+This command-line generates a header that exposes OpenGL 3.2 for what MacOSX 10.8 uses (note: the loader generator files have not been tested with MacOSX of any kind):
+
+{{{
+lua LoadGen.lua core_3_2 -style=pointer_c -spec=gl -version=3.2 -profile=core -stdext=extfiles/gl_ubiquitous.txt -stdext=extfiles/gl_macosx_3_2.txt
+}}}
+
+<<toc>>
+
 The {{{-style}}} command line option defines how the header and source files are generated. They will always generate the same information (more or less); the difference between styles explains the form that this information takes. The information generated is:
 
 * Typedefs for OpenGL concepts (GLenum, etc).
 
 The different types of styles will decide what form these take (enumerators could be {{{const}}} variables of some kind instead of the usual {{{#define}}}s, for example). But each style must provide this set of information.
 
+==Available styles==
+
+There are a number of styles available, with documentation explaining exactly what they generate:
+
+* [[Style_Pointer_C|{{{pointer_c}}}]]: Used for C-style header generation.
+* [[Style_Pointer_CPP|{{{pointer_cpp}}}]]: Used for creating C++-style loaders, wrapping as much as possible in namespaces.
+
 ==Core Extensions==
 
 OpenGL 3.0 introduced the concept of "core extensions." Normally with extensions, even ARB extensions, the enumerators, functions and typedefs end in the extension type suffix: ARB, EXT, etc. This allows any extension that is to be inducted into the core to have its behavior modified where necessary.
 
 Core extensions are special in that part of OpenGL is effectively in an extension. For example, ARB_uniform_buffer_object is a core extension; all of the functions/enums it defines are part of GL 3.1 as well as the extension.
 
-Because of this, it is possible to ask for GL 3.1 (which will provide those functions/enums) //and// ARB_uniform_buffer_object at the same time. Or to ask for GL 3.0 (which won't provide them) and ARB_uniform_buffer_object. Or to ask for GL 3.1 //without// explicitly asking for ARB_uniform_buffer_object.
+Because of this, it is possible to ask for GL 3.1 (which will provide those functions/enums) //and// ARB_uniform_buffer_object at the same time. Or to ask for GL 3.0 (where it isn't core) and ARB_uniform_buffer_object. Or to ask for GL 3.1 //without// explicitly asking for ARB_uniform_buffer_object.
 
-The way this works is as follows. If you ask for an extension, no matter what, the system will provide you a way to query whether that extension is loaded. If you don't ask for the extension, but the version number effectively requires that extension (asking for GL 3.1+ requires ARB_uniform_buffer_object), you'll still get the enums and functions, but you //won't// get a way to query whether that extension specifically is loaded.
+The way this works is as follows. If you explicitly ask for an extension, the system will //always// provide you a way to query whether that extension is loaded. If you don't ask for the extension, but the version number effectively requires that extension (asking for GL 3.1+ requires ARB_uniform_buffer_object), you'll still get the enums and functions, but you //won't// get a way to query whether that extension specifically is loaded.
 
-In short, if you want GL 4.2, but you want to verify whether particular parts are "available," (if you only get GL 4.1, but there are 4.2 features exposed via extensions), you must explicitly request that extension.
+In short, if you want GL 4.2, but you want to verify whether particular parts are "available," (ie: if you only get GL version 4.1, but there are 4.2 features exposed via extensions), you must explicitly request each extension.
 ==Compatibility profile==
 
 The compatibility profile complicates code generation a bit. The system will do its best to cull inappropriate enumerators/functions based on core/compatibility.
 This system cannot due that, primarily because the source of the OpenGL specification information (the .spec files, as processed through various scripts) does not provide enough information. The spec files only define what is core or compatibility in the current OpenGL version, not what //used// to be core for a while, then was only in compatibility, then came back into core.
 
 Therefore, the system errs on the side of being inclusive. If it came back into core, it is considered to have never //left// core OpenGL. Thus, if you ask the system for 3.1, core profiles, you will see {{{GL_QUADS}}}, as well as a few others. The number of these are rather few, so it should not be a problem.
-==Available styles==
-
-There are a number of styles available, with documentation explaining exactly what they generate:
-
-* [[Style_Pointer_C|{{{pointer_c}}}]]: Used for C-style header generation.
-* [[Style_Pointer_CPP|{{{pointer_cpp}}}]]: Used for creating C++-style loaders, wrapping as much as possible in namespaces.
-
 ==User-created styles==
 
 The style mechanism is designed to be extensible. You should be able to write new styles relatively painlessly. This system is [[Style_Creation|covered in some detail]]. The general idea is that you write a Lua script that exposes a number of functions. Then you hook this script into the build system by adding a line of code to one of the files. At which point, you're done. Making the style script is the hard part.