Commits

Jason McKesson committed 27c58f5

New documentation, particularly for common extension files.

Comments (0)

Files changed (5)

Command_Line_Options.wiki

 
 **-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.
+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. [[Extension Files|The format is fairly simple]], but it does have an inclusion mechanism to include other extension files.
 
 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.
 
 
 **-stdext**:
 
-Works like {{{extfile}}}, except that the directory for the file is relative to the place where the {{{LoadGen.lua}}} file is.
+Works like {{{extfile}}}, except that the directory for the file is relative to the place where the {{{LoadGen.lua}}} file is. These are used primarily for working with [[Common_Extension_Files|the library of common extension files]].
 

Common_Extension_Files.wiki

+[[Extension_Files|Extension files]] are a good mechanism for collating useful sets of extensions for easy referencing. The LoadGen system comes with a small library of pre-built extension files which you may find useful.
+
+To include these names from the command-line, you should use the {{{-stdext}}} option, instead of {{{-extfile}}}. The difference is where they search; {{{extfile}}} is always relative to the directory you're currently in, while {{{stdext}}} is relative to LoadGen's directory.
+
+To include these names from an extension file, you should use {{{#include <>}}} instead of {{{#include ""}}}, for the same reasons as above.
+
+All of these extension files are located in the directory {{{extfiles}}}. Therefore, any inclusion of them should be as this: {{{-stdext=extfiles/<include filename>}}} or {{{#include <extfiles/<include filename>>}}}.
+
+Here is a list of the files and what they include:
+
+**gl_ubiquitous**:
+
+For the kinds of extensions that //should// be core OpenGL, but aren't for IP reasons. Namely, anisotropic filtering, and the extensions needed for S3TC.
+
+**gl_core_post_3_3**:
+
+Core extensions that are widely available on OpenGL 3.3, but aren't part of GL 3.3 itself. These are for post-3.3 API improvements, like internalformat_query, shading_language_420pack, separate_shader_objects, and so forth.
+
+**gl_plat_3_3**:
+
+Vendor-specific extensions that are implemented by multiple vendors. Things like NV_texture_barrier.
+
+**gl_AMD_3_3**:
+
+AMD's HD-2xxx, 3xxx, and 4xxx line of hardware all support GL 3.3. However, they also support some features of 4.x-class hardware via non-core extensions. This file includes these extensions (transform_feedback2/3, draw_buffers_blend, etc).
+
+**gl_macosx_3_2**:
+
+All of the extensions allowed by core 3.2 profiles in MacOSX, as of version MacOSX 10.8.
+
+**wgl_common**:
+
+Commonly useful non-vendor-specific WGL extensions. The basic stuff: getting extensions_string, create_context, swap_control, various pixel-format extensions, etc.
+
+**wgl_AMD**:
+
+Useful AMD vendor WGL extensions.
+
+**wgl_NV**:
+
+Useful NVIDIA vendor WGL extensions.
+

Extension_Files.wiki

 
 * Nothing. An empty line, spaces, anything that isn't visible text.
 * A {{{#include ""}}} statement. This will cause the loading of another extension file named in the {{{""}}}s. The //current file's location// will be the base directory for any relative paths. So if you do {{{#include "more.txt"}}}, it will search for {{{more.txt}}} in the same directory as this extension file.
-* A {{{#include <>}}} statement. This will cause the loading of another extension file named in the {{{<>}}}s. The location of the glLoadGen will be used for the base directory of any relative paths. This is mostly intended to allow easy inclusion of the standard extension files, located in the {{{extfiles}}} directory. Therefore, 
+* A {{{#include <>}}} statement. This will cause the loading of another extension file named in the {{{<>}}}s. The location of the glLoadGen will be used for the base directory of any relative paths. This is mostly intended to allow easy inclusion of the [[Common_Extension_Files|standard extension files]], located in the {{{extfiles}}} directory.
 * Anything starting with {{{//}}} will be ignored as a comment.
 * Anything starting with {{{--}}} will be ignored as a comment.
 * Any other text in a line will be interpreted as an extension name. Extension names should not have the "GL_"/"WGL_"/"GLX_" prefixes.
-The inclusion mechanism is quite powerful.
+
+Note that the system will cull out duplicates, so don't worry too much about putting the same name in multiple times. The system will also error out if type an extension that doesn't exist.
+
+What the system will not do is handle //infinite recursion.// You could include a file that includes itself ad-infinitum, and the system will just stack-overflow. And there are no include-guards to cover this case; you are expected to deal with such inclusion yourself.
 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 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.
 * 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 uses static linking, a function will still be provided. 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==
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.