Commits

Jason McKesson committed 7a49e42

First dump from doc generation.

Comments (0)

Files changed (4)

Command Line Options.wiki

+The command-line options for the code generation tools are explained here. They work more or less like the standard command-line options for typical Linux/Windows programs. Options that have a single value can take their parameters as either {{{-opt_name=parameter}}} or {{{-opt_name parameter}}}.
+
+With Lua on the path, the command-line should be specified as follows:
+
+{{{lua pathToLoadgen/LoadGen.lua <output filename> <options>}}}The {{{<output filename>}}} must be specified. The path provided is relative to the current directory. The base filename of the path (everything after the last directory separator) will be decorated as appropriate for generating the output files. You should not provide an extension; the system will provide those as needed. The generated files will append an appropriate prefix, depending on which specifications you are generating (OpenGL, WGL, or GLX), so you can provide the same base filename for all of these.
+
+The output filename should be specified before any of the options. You can specify it after the options or even between options, but if you specify it after the {{{-exts}}} option (but before any subsequent options), the system will mistake it for an extension name. Just specify it first to be safe.
+
+**-spec**:
+
+Defines the particular specification to generate loading code for. It must be one of the following values:
+
+* {{{gl}}}: default
+* {{{glX}}}
+* {{{wgl}}}
+
+**-prefix**:
+
+The code generation system will try to minimize the number of non-static global variables it defines as much as possible. However, it will have to use some non-static variables for various things.
+
+Code generated from the different specifications are guaranteed not to have name collisions. However, if you generate code from the //same// specification, with different sets of extensions or versions, collisions will occur.
+
+The prefix option allows you to define a string that will be prepended to any non-static (or otherwise hidden) global variables, where possible. As such, the prefix should start with characters that are valid for C/C++ identifiers.
+
+If the option is not specified, no prefix will be used.
+
+**-version**:
+
+The highest version of OpenGL to export. You may //only// use this when {{{-spec}}} is {{{gl}}}. And you must use it when the specification is {{{gl}}}.
+
+**-profile**:
+
+The OpenGL profile to export. It must be one of the following values:
+
+* {{{core}}}: default
+* {{{compatibility}}}: It is an error to specify this for OpenGL versions that do not have the core/compatibility distinction.
+
+**-style**:
+
+The code generation suite has a number of different ways of outputting the functions and enumerators that define OpenGL. This option allows the user to select between these particular mechanisms. It must be one of the following values:
+
+* {{{pointer_c}}}: default.
+The specific meaning of these parameters is explained elsewhere. Note that the system is designed to be extensible; new styles can be added by modifying an appropriate script and hooking it into the right place in {{{modules/Styles.lua}}}.
+
+**-indent**:
+
+The indentation style for the output text. It must be one of the following:
+
+* {{{tab}}}: default
+* {{{space}}}: Will use 2 spaces to indent.
+
+**-exts**:
+
+Defines a list of extensions to the given specification to export. Every argument that doesn't start with a "-" following this option will be assumed to be an extension name. You do not need to prefix the extensions with GL_, WGL_, or GLX_, but you may do so if you wish.
+
+This argument can be specified multiple times. It is fine to specify an extension name more than once.
+
+**-ext**:
+
+Defines a single extension to export. It adds the given parameter to the list of extensions.
+
+This argument can be specified multiple times. It is fine to specify an extension name more than once.
+
+**-extfile**:
+
+Specifying dozens of extensions on the command line can be exceedingly tedious. Therefore, the system can be instructed to read a list of extensions from a file with this option. The file should be a plain text file, where each extension is specified on a single line.
+
+This argument can be specified multiple times. It is fine to specify an extension name more than once, either in the file or on the command line.
+
+The file's directory is relative to the path where the command line was invoked.
+
+**-stdext**:
+
+Works like {{{extfile}}}, except that the directory for the file is relative to the place where the {{{LoadGen.lua}}} file is.
+
+==Styles==
+
+Styles define how the system 
+
+The different styles have specific meaning for how code is generated by the system. These styles are:
+
+==pointer_c==
+
+This builds header/loader files that are C-compatible. Everything is global (since there's nothing non-global in C). OpenGL enumerators are #defines.
+
+The functions will be global function pointers (hence the "pointer" in the name), but because of potential name conflicts with static OpenGL loading, their function pointer names will not be their actual names (for example, "glBindTexture"'s function pointer will not be called that). Instead, the function pointer will be mangled (and prefixed); a #define will be used to effectively convert from the function pointer's actual name to user-expected name.
+
+The global function pointer names will be prefixed.
+
+Here is an example:
+==pointer_cpp==
+
+This builds header/loader files that are in a C++ style. The only globals are OpenGL typedefs (which can't be namespaced for various reasons). Everything else lies in a namespace named {{{<prefix><spec>}}}.
+
+Enumerators will be in an actual enumeration. Also, since the namespace already segregates the OpenGL stuff into its own place, there is no need to have the "gl" and "GL_" prefixes for functions and enumerators.
+
+There are certain OpenGL enums that start with characters that are forbidden for C++ enumerators. Such enumerators will be prefixed with an "_" character.
+Also, there is no #define gimmickry to get the function names right. The function pointers are always named correctly.
+
+Here is an example:
-= OpenGL Loader Generator =
+==OpenGL Loader Generator==
 
 This loader generation system is used to create OpenGL headers and loading code for your specific needs. Rather than getting every extension and core enumerator/function all in one massive header, you get only what you actually want and ask for.
 
 
 To use the code generator, with Lua in your path (assuming that {{{lua}}} is the name of your Lua executable), type this:
 
-{{{
-lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3
-}}}
+{{{lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3}}}This tells the system to generate a header/source pair for OpenGL ({{{-spec=gl}}}, as opposed to WGL or GLX), for version 3.3, the core profile. It will generate it in the {{{pointer_c}}} style, which means that it will use function pointer-style, with C linkage and source. Such code is usable from C and C++, or other languages that can interface with C.
 
-This tells the system to generate a header/source pair for OpenGL ({{{-spec=gl}}}, as opposed to WGL or GLX), for version 3.3, the core profile. It will generate it in the {{{pointer_c}}} style (which means that it will use function pointer-style, with C linkage and source. Such code is usable from C and C++, and can be compiled as either.
-
-The option {{{core_3_3}}} is the basic component of the filename that will be used for the generation. Since it is generating OpenGL loaders (again, as opposed to WGL or GLX), it will generate files named {{{gl_core_3_3.*}}}, where * is the extension used by the particular style. {{{pointer_c}}}, as the name suggests, generates function pointer-style loaders with C linkage and source code. Such code is usable from C and C++.
+The option {{{core_3_3}}} is the basic component of the filename that will be used for the generation. Since it is generating OpenGL loaders (again, as opposed to WGL or GLX), it will generate files named {{{gl_core_3_3.*}}}, where * is the extension used by the particular style.
 
 The above command line will generate {{{gl_core_3_3.h}}} and {{{gl_core_3_3.c}}} files. Simply include them in your project; there is no library to build, no unresolved extenals to filter through. They just work (Well, that's the plan ;) ).
 
-== Extensions ==
+==Extensions==
 
 Note that the above command line will //only// generate enumerators and functions for core OpenGL 3.3. It doesn't offer any extensions. To use extensions, you must ask for them with command line parameters, as follows:
 
-{{{
-lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3 -exts ARB_texture_view ARB_vertex_attrib_binding EXT_texture_filter_anisotropic -ext=EXT_texture_compression_s3tc -extfile=SomeFile.txt
-}}}
-
-The {{{-exts}}} option starts a list of space-separated extension names (note: don't try to put the output filename after {{{-exts}}}; the system can't tell the difference between a filename and an extension). The {{{-ext}}} option only specifies a single name.
+{{{lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3 -exts ARB_texture_view ARB_vertex_attrib_binding EXT_texture_filter_anisotropic -ext=EXT_texture_compression_s3tc -extfile=SomeFile.txt}}}The {{{-exts}}} option starts a list of space-separated extension names (note: don't try to put the output filename after {{{-exts}}}; the system can't tell the difference between a filename and an extension). The {{{-ext}}} option only specifies a single name.
 
 {{{-extfile}}} specifies a //filename// to load extensions from. 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.

Style Pointer C.wiki

+The {{{pointer_c}}} style is the default style. It is also the one that most mimics the way common OpenGL loaders work. This style generates a {{{.h}}} and {{{.c}}} file. The header file can be included by C and C++; the source file should be compiled as C.
+
+Since these are compatible with C, all of the typedefs, enumerations, extension variables, and function pointers are global. The extension variables are of type {{{int}}}. Enumerations are {{{#define}}}s. The functions are function pointers with mangled names that have been {{{#define}}}d into the real OpenGL function name. The latter is done to avoid name conflicts with static linking of certain core OpenGL function names.
+
+The loading function that loads the extensions and OpenGL version is called {{{LoadFunction}}}, prefixed by a specification-specific prefix. The return value of this function, as well as the value stored in the extension variables, is special. There is an enumeration, prefixed again by the spec-specific prefix.
+
+If the value is {{{LOAD_FAILED}}}, then the extension was not found in the extension string, so no attempt was made to load it. If the value is {{{LOAD_SUCCEEDED}}}, then the extension was loaded in its entirety (all function pointers accounted for). Otherwise, some number of function pointers failed to load. To get the number of functions that failed to load for the extension, take the integer value and subtract {{{LOAD_SUCCEEDED}}} from it.
+
+The return value for the function loader works the same way. It refers to the success or failure to load the core functions (obviously for WGL/GLX, there are no core functions, so it will always be successful). The attempt will always be made to load the core functions, so {{{LOAD_FAILED}}} is not a possibility.
+
+Also, this style will generate functions to query version availability for core OpenGL. 
+
+==Compatibility==
+
+This style is intended to be maximally compatible with regular OpenGL programs. You should be able to take this header and include it into a standard GL program and use it as is. Furthermore, it should be compatible with other systems like FreeGLUT, GLFW, and so forth, as it provides information in the way that traditional OpenGL headers do.
+
+However, in all cases, you should include these generated headers //before// anything from FreeGLUT, GLFW, etc.
+The {{{-style}}} command line option defines how the header and source files are generated. While the styles will have some differences, every style provides a common set of functionality (though exactly how it is exposed differs). Styles provide:
+
+* Typedefs for OpenGL concepts (GLenum, etc).
+* A means to tell whether each of the extensions specified by the user is loaded or not. This is usually exposed via a global variable who's name contains the extension name.
+* The enumerators for all of the extensions specified as well as any specified OpenGL versions/profiles (where applicable).
+* Functions (whether function pointers or something else, that's up to the style) for the various extensions specified, as well as any specified OpenGL versions/profiles (where applicable).
+* A function that will load all function pointers. Even if the style requires static linking, it will still provide a special function to do this. Until this function is called, you cannot use any of the mechanisms to test whether an extension is loaded, nor can you call any other functions.\\The function's return value will be a status code saying whether it succeeded. Success is defined solely in terms of loading the specified core OpenGL version; therefore, WGL or GLX loader functions will always "succeed". Test for individual extensions if you want to know what happened there.
+* Optionally, if using the OpenGL specification, the style will export a number of useful helper functions to query OpenGL version information. This is per-style.
+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.
+
+==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.
+
+With GL 3.0, the ARB changed things by making certain extensions core extensions. These are extensions where their declarations don't have the extension suffix. This represents APIs that do not change between extension and core. As such, the enums/functions/etc are considered part of both the extension and a version of OpenGL.
+
+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.
+
+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.
+
+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.
+==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.
+
+However, this may not be possible in every case. For example, take the {{{GL_QUADS}}} enumerator. This enumerator was defined way back in GL 1.1. But 3.1 removed it, so if you ask for a 3.1 core header, you shouldn't get {{{GL_QUADS}}}.
+
+The problem is that it didn't //stay// removed. GL 4.0/ARB_tessellation_shader brought it back (though only as a tessellation target). Which means if you ask for a 3.1 core header it should be gone, but if you ask for a 3.1 core header that includes ARB_tessellation_shader, it should return. As it should if you ask for a 4.1 core header (with or without ARB_tessellation_shader).
+
+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.