Commits

Jason McKesson committed 07fd117

Improved docs.

Comments (0)

Files changed (5)

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 [[Common_Extension_Files|standard extension files]], located in the {{{extfiles}}} directory.
+* 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. Note that here, you will need to prefix the filename with {{{extfiles/}}}; you don't do that with the {{{-stdext}}} option.
 * 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 scripts in this package are licensed under the terms of the MIT License.
 
+==Basic Usage==
+
 To use the code generator, with Lua in your path (assuming that {{{lua}}} is the name of your Lua executable), type this:
 
 {{{
 
 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.
+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.
 
-The [[Command_Line_Options|full command-line syntax documentation]] is available. The {{{-style}}} parameter's [[Styles|meaning is defined here]].
+You will need to call {{{ogl_LoadFunctions}}} to initialize the library if you use the {{{pointer_c}}} style. And you must call it //after// OpenGL context creation. For example, if you are using FreeGLUT, your code looks like this:
 
+{{{
+//Pre-window creation.
+int windowID = glutCreateWindow("Name");
+
+if(ogl_LoadFunctions() == ogl_LOAD_FAILED)
+{
+  glutDestroyWindow(windowID);
+}
+//Call functions here.
+}}}
+
+Replace the "Pre-window creation" and {{{glutCreateWindow}}} call with your usual OpenGL context creation code.
+
+The [[Command_Line_Options|full command-line syntax documentation]] is available. Of particular note is the {{{-style}}} parameter, which defines how the loader is generated. Different styles will have different initialization needs and so forth (you don't even need to initialize some styles at all). The available styles are:
+
+* [[Style_Pointer_C|{{{pointer_c}}}]]: Used for C-style loader generation.
+* [[Style_Pointer_CPP|{{{pointer_cpp}}}]]: Used for creating C++-style loaders, wrapping as much as possible in namespaces.
+* [[Style_No_Load_CPP|{{{noload_cpp}}}]]: Used for creating C++-style loaders that you don't need to call an initialization function on to get function pointers.
+
+Each linked page has instructions on how to use the generated interface.
+
+More about styles can be found on the [[Styles|style page]].
 ==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:

Style_No_Load_CPP.wiki

 
 To help alleviate this, the system does have variables to tell you which extensions are available (at least, according to the extension strings). They are located in the {{{exts}}} namespace, using the {{{var_<extension name>}}} syntax, and they are C++ {{{bool}}} types. However, unlike the magic function pointers, you have to actually initialize them. You can call {{{sys::CheckExtensions}}} to initialize them. This function only initializes the extension variables, so it cannot report on the number of functions that failed to load.
 
+==Example==
+
+This example is for loading the OpenGL functions; it expects the OpenGL header to be included. For loading WGL/GLX functions, include their headers and change the "gl" namespaces to "wgl" or "glx" as appropriate.
+
+{{{
+//Create OpenGL context and make it current.
+}}}
+
+That was a trick question: there is no initialization required. That is the whole point of this style, after all.
+
+However, if you want to query which extensions are around, you //need// to initialize that:
+
+{{{
+//Create OpenGL context and make it current.
+gl::sys::CheckExtensions();
+}}}
+
+The presence of extensions can be checked as follows:
+
+{{{
+if(gl::exts::var_EXT_texture_compression_s3tc)
+  gl::CompressedTexSubImage2D(gl::TEXTURE_2D, 0, 0, 0, 256, 256,
+    gl::COMPRESSED_RGBA_S3TC_DXT5_EXT, compressedSize, compressedPixels);
+else
+{
+  void *decompressedPixels = DecompressPixels(256, 256,
+    compressedSize, compressedPixels);
+
+  gl::TexSubImage2D(gl::TEXTURE_2D, 0, 0, 0, 256, 256,
+    gl::RGBA, gl::UNSIGNED_BYTE, decompressedPixels);
+  free(decompressedPixels);
+}
+}}}
+
 ==Versions==
 
 When you use this system and provide a version number of OpenGL, {{{noload_cpp}}} will assume that you are //serious// about that version number. Which means that if you create a 3.3 header, and you do not supply a context that claims support for at least OpenGL version 3.3, //crashing may occur//.

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.
+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. The generated source is compatible with C89.
 
 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.
+The 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, if it has some). 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.
 
 
 Also, this style will generate functions to query the version of the OpenGL context.
 
+==Example==
+
+This example is for loading the OpenGL functions; it expects the OpenGL header to be included. For loading WGL/GLX functions, include their headers and change the "ogl"s to "wgl" or "glx" as appropriate.
+
+{{{
+//Create OpenGL context and make it current.
+
+int loaded = ogl_LoadFunctions();
+if(loaded == ogl_LOAD_FAILED)
+{
+  //The context cannot work with the generated headers for some reason. Abort.
+  //Destroy the context
+  return;
+}
+
+int num_failed = loaded - ogl_LOAD_SUCCEEDED;
+printf("Number of functions that failed to load: %i.\n", num_failed);
+}}}
+
+The presence of extensions can be checked as follows:
+
+{{{
+if(ogl_ext_EXT_texture_compression_s3tc != ogl_LOAD_FAILED)
+  glCompressedTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, 256, 256,
+    GL_COMPRESSED_RGBA_S3TC_DXT5_EXT, compressedSize, compressedPixels);
+else
+{
+  void *decompressedPixels = DecompressPixels(256, 256,
+    compressedSize, compressedPixels);
+
+  glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, 256, 256,
+    GL_RGBA, GL_UNSIGNED_BYTE, decompressedPixels);
+  free(decompressedPixels);
+}
+}}}
+
+Of course, this requires asking for the {{{EXT_texture_compression_s3tc}}} extension on the command-line (or in a referenced file).
 ==Versions==
 
 When you use this system and provide a version number of OpenGL, {{{pointer_c}}} will assume that you are //serious// about that version number. Which means that if you create a 3.3 header, and you do not supply a context that claims support for at least OpenGL version 3.3, loading failure may occur.

Style_Pointer_CPP.wiki

 
 The system functions (the function that loads the function pointers, version getting, etc) are contained in the {{{<prefix>::<spec>::sys}}} namespace. The loader function will always be called {{{LoadFunctions}}}. It returns an {{{ext::LoadTest}}}, which works as above. It will only be false if it couldn't even attempt to load functions (due to being unable to get the extension string). The number of functions that failed to load refers to the core functions (and core extension functions).
 
+==Example==
+
+This example is for loading the OpenGL functions; it expects the OpenGL header to be included. For loading WGL/GLX functions, include their headers and change the "gl" namespaces to "wgl" or "glx" as appropriate.
+
+{{{
+//Create OpenGL context and make it current.
+
+gl::exts::LoadTest didLoad = gl::sys::LoadFunctions();
+if(!didLoad)
+{
+  //The context cannot work with the generated headers for some reason. Abort.
+  //Destroy the context
+  return;
+}
+
+printf("Number of functions that failed to load: %i.\n", didLoad.GetNumMissing());
+}}}
+
+The presence of extensions can be checked as follows:
+
+{{{
+if(gl::exts::var_EXT_texture_compression_s3tc)
+  gl::CompressedTexSubImage2D(gl::TEXTURE_2D, 0, 0, 0, 256, 256,
+    gl::COMPRESSED_RGBA_S3TC_DXT5_EXT, compressedSize, compressedPixels);
+else
+{
+  void *decompressedPixels = DecompressPixels(256, 256,
+    compressedSize, compressedPixels);
+
+  gl::TexSubImage2D(gl::TEXTURE_2D, 0, 0, 0, 256, 256,
+    gl::RGBA, gl::UNSIGNED_BYTE, decompressedPixels);
+  free(decompressedPixels);
+}
+}}}
+
 ==Versions==
 
 When you use this system and provide a version number of OpenGL, {{{pointer_cpp}}} will assume that you are //serious// about that version number. Which means that if you create a 3.3 header, and you do not supply a context that claims support for at least OpenGL version 3.3, loading failure may occur.