1. Jason McKesson
  2. glLoadGen

Commits

Jason McKesson  committed ae1fa68

Documentation update to match 2.0

  • Participants
  • Parent commits 1a5dfd0
  • Branches default

Comments (0)

Files changed (2)

File Home.wiki

View file
  • Ignore whitespace
 =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.
+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. This tool supports OpenGL 4.4 and the recent crop of OpenGL extensions.
 
 [[https://bitbucket.org/alfonse/glloadgen/downloads|Download it here;]] you will need to have the Lua runtime installed on your machine to use the code generation scripts. It's pretty tiny, so it shouldn't be a problem. Windows users can install [[http://code.google.com/p/luaforwindows/|Lua For Windows]], or just [[http://luabinaries.sourceforge.net/|the Lua binaries packages]]. The code should be compatible with Lua 5.1 and 5.2, but it has only been tested on 5.1.
 
 lua LoadGen.lua core_3_3 -style=pointer_c -spec=gl -version=3.3 -profile=core -stdext=gl_ubiquitous.txt -stdext=gl_core_post_3_3.txt
 }}}
 
-This command-line is for OpenGL 4.3, but with certain commonly-provided extensions that are generally useful.
+This command-line is for OpenGL 4.4, 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=gl_ubiquitous.txt -stdext=gl_plat_3_3.txt
+lua LoadGen.lua core_4_4 -style=pointer_c -spec=gl -version=4.4 -profile=core -stdext=gl_ubiquitous.txt -stdext=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):

File Structure_Reference.wiki

View file
  • Ignore whitespace
 ** [[Structure_Reference#!file|File]]
 ** [[Structure_Reference#!iterators|Iterators]]
 ** [[Structure_Reference#!common-attributes|Common Attributes]]
-* [[Structure_Reference#!function-parameters|Function Parameters]]
+* [[Structure_Reference#!standard-context-variables|Standard Context Variables]]
 * [[Structure_Reference#!common-structure|Common Structure]]
 
 
 }
 }}}
 
-The contents of the base structure is an array of values. Once you have created the table, the actual datastructure is created as follows:
+The contents of the base structure is an array of values. Once you have created the table, the actual data structure is created as follows:
 
 {{{
 local Structure = require "Structure"
 
 The return value is a special object that should be returned along with your style.
 
-Each element of a structure is called an **action.** The type of action is defined by the {{{type}}} field. Using an invalid type will result in a build-time error (ie: {{{BuildStructure}}} will error). This makes it easy to do some basic verification by simply executing your structure's script. It won't verify things like function existence or parameter correctness, but at least you know you've spelled your action type correctly.
+Each element of a structure is called an **action.** The type of action is defined by the {{{type}}} field. Using an invalid type will result in a build-time error (ie: {{{BuildStructure}}} will error). This makes it easy to do some basic verification by simply executing your structure's script. That won't verify things like whether a function exists or the correctness of parameters, but at least you know you've spelled your action types correctly.
 
 Each type can have a number of attributes. Some attributes are specific to certain types, while others can be used anywhere.
 
-Actions can be nested within other actions. For some actions, it generally does not make sense to nest them, while others are designed for nesting. How the actions nested within an action are processed depends on the type of actions. Actions that iterate over something will execute their contents once per iteration. There are actions that can will execute their contents only if a style-provided function returns true. And so forth.
+Actions can be nested within other actions. For some actions, it generally does not make sense to nest them, while others only make sense if they contain other actions. The outer action can influence how inner actions are processed. For example, actions that iterate over something will execute their contents once per iteration. There are actions that will execute their contents only if a style-provided function returns true. And so forth.
 
-When a structure is processed, each action will be executed in the order provided. Do note that no steps are taken to prevent infinite recursion/iteration; if your structure uses a variable which uses another variable which uses the original, that is a legal table in Lua. Attempting to process with {{{BuildStructure}}} will halt with a stack overflow (or execute infinitely).
+When a structure is processed, each action will be executed in the order provided. Do note that no steps are taken to prevent infinite recursion/iteration; if your structure uses a table which uses another table which itself contains the first table, that is a legal table in Lua. Attempting to process such a structure with {{{BuildStructure}}} will halt with a Lua stack overflow or execute infinitely.
 
 ===Context===
 
-There is a notion of a current **context**. The context represents all of the information currently available to an action (and therefore whatever style code it calls). Some actions will augment the current context with new information. These take the form of parameters passed to style functions.
+There is a notion of a current **context**. The context represents all of the information currently available to an action (and therefore whatever style functions it calls). Some actions will augment the current context with new information. These take the form of parameters passed to style functions.
 
-If an action provides some new context variable(s), then all child actions may access that.
+If an action provides some new context variable(s), then all child actions may access them. Actions that provide new context variables will provide them to all child actions contained within that action.
 
 Some actions //require// certain context variables to be available. If they are not, then a runtime error will result. For example, the function iterator action iterates over all of the functions within the current extension or version (both of which are context variables). If no extension or version is available, then the action will fail to execute.
 
 Similarly, actions cannot modify already existing context variables. So you cannot nest actions that provide the same context variable(s).
 
-In the reference table below, there will be text that says, "must be within the scope of." This means that the action needs to be inside something that provides this context variable.
+In the reference table below, there will be text that says, "must be within the scope of X." This means that the action needs to be inside an action that provides the context variable(s) X.
 ===Current Style===
 
 When style functions need to be called, the system will use the current style to do so. The style will be the table provided to the generation system.
 
 This is a list of all of the actions and their associated attributes.
 
-When an action says, "Provides access to the X parameter," this also means that the action //cannot nest// with any action that provides this parameter. Including itself.
+When an action says, "Provides access to the X variable," this also means that the action //cannot nest// with any action that provides the X variable. Including itself.
 
 ===System===
 
 
 **filter**:
 
-Will execute its child actions only if the given function returns true. The default parameters are {{{()}}} (ie: none).
+Will execute its child actions only if the named style function returns true. The default parameters are {{{()}}} (ie: no parameters).
 
 * {{{name}}}: The base name of the function that does filtering. The full name will be prefixed by "{{{Filter}}}".
 * {{{neg}}}: If this is true, then the meaning of the return value is inverted. That is, if the function returns true, then it will //not// process the children. This is useful for reusing filter functions in opposite ways without having to write a new one.
 
 Adds a user-defined value to the current context. This will create a new parameter within the scope of this action that any function can reference. The default parameter list is {{{()}}}.
 
-* {{{key}}}: The string name of the new context variable. Required. Must end in the "{{{_}}}" character, to ensure that it doesn't conflict with other variables.
+* {{{key}}}: The string name of the new context variable. Required. Must end in the "{{{_}}}" character, to ensure that it doesn't conflict with system context variables.
 * {{{data}}}: A Lua value that represents the new context variable's data.
 * {{{name}}}: The base name of the function to call to fill in the context variable. The full name will be prefixed by "{{{State}}}".
 * {{{dispose}}}: The base name of a function that takes the context variable (and //only// the context variable, so no parameter selection). This will be called when the variable is disposed of. This would be for clean-up work, like for file closing and such. The full name will be prefixed by "{{{Dispose}}}".
 
-Either {{{name}}} or {{{data}}} must be defined. {{{data}}} takes priority.
+Either {{{name}}} or {{{data}}} must be defined. {{{data}}} takes priority if both are defined.
 
 Provides access to the parameter named by {{{key}}}. Note that this means you can't nest {{{context}}}'s that provide the same variable.
 
 **call**:
 
-Calls a given function. The default parameter list is {{{()}}}.
+Calls a given style function. The default parameter list is {{{()}}}.
 
-* {{{name}}}: The name of the function to call.
+* {{{name}}}: The name of the function to call. The name will be exactly as specified.
 
 ===File===
 
 
 Creates a tabbed-file. See the TabbedFile.lua module to understand what this is. The default function parameters are: {{{(basename, options)}}}
 
-* {{{name}}}: The exact name of a function to call that returns the full pathname of the file to create
+* {{{name}}}: The exact name of the style function to call that returns the full pathname of the file to create
 
-Provides access to the {{{hFile}}} parameter.
+Provides access to the {{{hFile}}} variable.
 
-Note that you really need the {{{basename}}} variable. At the very least, you should extract the directory name from it, as you will need to attach that to the front of the return value from this function. You can use {{{util.ParsePath}}} for this. Thus, your code should look like:
+Note that you really need the {{{basename}}} variable. At the very least, you should extract the directory name from it, so that the user can provide a proper directory name. You can use {{{util.ParsePath}}} for this. Thus, your code should look like:
 
 {{{
 function style_name.GetFilenameFunc(basename, ...)
 
 **ext-iter**:
 
-Executes its children once for every extension that the user explicitly asked to generate code for.
+Executes its children once for every extension that the user has explicitly asked to generate code for.
 
 Provides access to the {{{extName}}} parameter.
 
 
 This is useful for generating a group of functions or files that do something for each version, and for each version of OpenGL <= that version. For example, you can have a bunch of headers that only provide functions/enums for features introduced within that version. Then, you can generate a file for each version, which includes headers only for the contents of everything //up to// that version of OpenGL and not just within it.
 
-**core-ext-iter**:
-
-Executes its children once for every core extension of the current {{{version}}} parameter. Note that this will iterate over the core extensions introduced in version //only.//
-
-Must be within the scope of {{{version}}}. Provides access to the {{{extName}}} parameter.
-
-**core-ext-cull-iter**:
-
-Executes its children once for every core extension of the current {{{version}}} parameter which //was not requested// by the user to be exported. That is, these are the extensions that you need to look at because they are core extensions (and thus part of the current version) and won't have looked at already as part of the regular extension iteration process.
-
-Must be within the scope of {{{version}}}. Provides access to the {{{extName}}} parameter.
-
 **enum-iter**:
 
 Executes its children once for every enumerator within scope. "Scope" is defined by the {{{extName}}} and/or {{{version}}} parameters. If {{{extName}}} is available, then it will iterate over all enums in the extension. If {{{version}}} is available, then it will iterate over all enums that were introduced within that particular version (and //only// them). If both are available, {{{extName}}} takes priority.
 
 Executes its children once for every function within scope. Scope is defined as for {{{enum-iter}}}.
 
-Must be within the scope of {{{extName}}} or {{{version}}}. Provides access to the {{{func}}} and {{{typemap}}} parameters.
+Must be within the scope of {{{extName}}} or {{{version}}}. Provides access to the {{{func}}} parameters.
 
 **enum-seen**:
 
 
 **optional**:
 
-Normally, the inability to resolve a function name to a function will result in an error. If this is set to true, then the failure to resolve a function will simply mean that the function is not called. All children are processed as though the function had been called normally, //UNLESS// it is a filter action. In that case, the filter will be assumed to have returned false, meaning that children will not be processed (unless {{{neg}}} is //also// set, in which case it will flip that into {{{true}}}, thus always processing children if the function isn't present).
+Normally, the inability to resolve a function name to a function will result in an error. If this attribute is set to true however, then the failure to resolve a function will simply mean that the function is not called. All children are processed as though the function had been called normally, //UNLESS// it is a filter action. In that case, the filter will be assumed to have returned false, meaning that children will not be processed (unless {{{neg}}} is //also// set, in which case it will flip that into {{{true}}}, thus always processing children if the function isn't present).
 
 **first**:
 
 * {{{func-iter}}}
 * {{{core-funcs}}}: Returns true if the spec has core functions/enumerators at all. Basically, checks if the specification is OpenGL and not WGL or GLX. Technically {{{version-iter}}} would do the same job, but in a less obvious way.
 
-==Function Parameters==
+==Standard Context Variables==
 
-Here are a list of the various standard function parameters, with references to the actions that provide them.
+Here are a list of the various standard context variables, with references to the actions that provide them.
 
-Again, //DO NOT MODIFY THEM!// You can call member functions on them and inspect them. But unless they're user-defined parameters, do not change their tables.
+Again, //DO NOT MODIFY THEM!// You can call member functions on them and inspect them. But unless they're user-defined parameters, do not directly change their tables.
 
 **specData**:
 
 
 If you want to get the parameters (C-style) in a function, you can use {{{common.GetFuncParamList}}}, which requires a {{{typename}}} (see below). Otherwise, you would have to deal with the many difficulties of pulling a viable parameter list from a {{{func}}}.
 
-**typemap**:
-
-This is a mapping between types as defined in {{{func}}} (for parameters and values) and types as defined by C/C++, as well as the standard OpenGL/system typedefs and such. It is from {{{specData.typemap}}}.
-
-This parameter is provided by the {{{func-iter}}} action.
-
 **enumSeen**:
 
 A table indexed by enumerator name. If an entry is present, then the enumerator was already seen at least once before.
 
 **Functions**:
 
-This function optionally takes one argument and returns a group of actions that will iterate over every function in every extension and version that the user asked to export. This will respect core/compatibility. For each function, it will call a function named {{{WriteFunction(hFile, func, typemap, spec, options, funcSeen)}}} to write each function.
+This function optionally takes one argument and returns a group of actions that will iterate over every function in every extension and version that the user asked to export. This will respect core/compatibility. For each function, it will call a function named {{{WriteFunction(hFile, func, spec, options, funcSeen)}}} to write each function.
 
 It will iterate over functions in the same group order as with enumerators. It will write headers where appropriate, which can be omitted.