Commits

Jason McKesson committed 46f7f11

Added docs for two new styles.

  • Participants
  • Parent commits 9da1c25

Comments (0)

Files changed (4)

 
 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.
+* [[Style_Pointer_C|{{{pointer_c}}}]]: Function-pointer-based style for C. It is the most widely compatible, comparable to GLEW. It has variables to test whether an extension was loaded (and how many of its functions were loaded). Like GLEW, it requires calling an initialization function to set it up. This is best used for C or C++ users who need to be able to share the headers with other tools (note: usually, you don't need to do this).
+* [[Style_Pointer_CPP|{{{pointer_cpp}}}]]: Function-pointer-based style for C++. It wraps all function pointers, extension variables, and enumerators in a namespace (not the typedefs). It requires calling an initialization function to set it up. This is best used for C++ users who don't need compatibility, but would like OpenGL stuff to not pollute the global namespace so much.
+* [[Style_Function_CPP|{{{func_cpp}}}]]: Inline-function-based style for C++. This means that the header contains actual inline functions, which forward their parameters to the actual function pointers internally. Like {{{pointer_cpp}}}, most of OpenGL is in a namespace. This is best used for C++ users who want the best possible autocompletion from their IDE or coding tool of choice.
+* [[Style_No_Load_C|{{{noload_c}}}]]: Automatic loading style for C. This is similar to the old loading tool GLee. Unlike the other styles, it does not require an initialization function; you simply call whatever function you want to use. The first time a call is encountered, it will load that function. This is best used for C or C++ users who don't want to do explicit initialization, and also want header compatibility like {{{pointer_c}}}.
+* [[Style_No_Load_CPP|{{{noload_cpp}}}]]: Automatic loading style for C++. This is similar to the old loading tool GLee. Unlike the other styles, it does not require an initialization function; you simply call whatever function you want to use. The first time a call is encountered, it will load that function. It will wrap most of OpenGL in a namespace. This is best used for C++ users who don't want to do explicit initialization.
 
 Each linked page has instructions on how to use the generated interface.
 

Style_Function_CPP.wiki

+The {{{func_cpp}}} style is functionally equivalent to [[Style_Pointer_CPP|{{{pointer_cpp}}}]] in every way except for one. Instead of using function pointers directly, it uses inline functions in the headers. These forward the calls to the function pointers.
+
+The //only// reason to use this style over {{{pointer_cpp}}} is that it makes it easier for IDEs and other autocompletion tools to recognize a function call. Many such tools can handle function pointers, but if yours cannot, you can use this to give it the help it needs.

Style_No_Load_C.wiki

+The {{{noload_c}}} style works a lot like the near-defunct GLee loader. You don't need to call a function to load all of the function pointers; instead, you simply call the GL functions as normal. If it hasn't been loaded, it will be. This makes it among the most user-friendly of the loader styles.
+
+As a C style, it follows the naming conventions of the {{{pointer_c}}} style. It prefixes enums and functions with {{{GL/WGL/GLX}}} and {{{gl/wgl/glX}}} as appropriate.
+
+The system is designed to be automatic, responding to your application's needs. However, calling a function that cannot be loaded from the implementation will result in a crash.
+
+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 named by this convention {{{ogl/wgl/glx_exts_<extension name>}}}. These are {{{int}}} types. However, unlike the magic function pointers, you have to call another function to initialize them. You must call {{{ogl/wgl/glx_CheckExtensions}}}. This function only checks what is exported by the extension string, 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 {{{ogl_}}} prefixes 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.
+ogl_CheckExtensions();
+}}}
+
+The presence of extensions can be checked as follows:
+
+{{{
+if(ogl_exts_EXT_texture_compression_s3tc)
+  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,
+    GLRGBA, GL_UNSIGNED_BYTE, decompressedPixels);
+  free(decompressedPixels);
+}
+}}}
+
+==Versions==
+
+When you use this system and provide a version number of OpenGL, {{{noload_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, //crashing may occur//.
+
+In particular, OpenGL changed the mechanism to check for the presence/absence of extensions in version 3.0. Therefore, {{{noload_c}}} will also change how it checks for the presence/absence of extensions based on that. If you provide a version 3.0 or greater, it will use the new style of extension querying. Thus, if your context is only version 2.1, then this style will be unable to function and will likely crash when it fails to load an appropriate function pointer.
 
 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).
+* Typedefs for OpenGL types ({{{GLenum}}}, {{{GLint}}}, 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).
 
 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.
-* [[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.
+* [[Style_Pointer_C|{{{pointer_c}}}]]: Function-pointer-based style for C. It is the most widely compatible, comparable to GLEW. It has variables to test whether an extension was loaded (and how many of its functions were loaded). Like GLEW, it requires calling an initialization function to set it up. This is best used for C or C++ users who need to be able to share the headers with other tools (note: usually, you don't need to do this).
+* [[Style_Pointer_CPP|{{{pointer_cpp}}}]]: Function-pointer-based style for C++. It wraps all function pointers, extension variables, and enumerators in a namespace (not the typedefs). It requires calling an initialization function to set it up. This is best used for C++ users who don't need compatibility, but would like OpenGL stuff to not pollute the global namespace so much.
+* [[Style_Function_CPP|{{{func_cpp}}}]]: Inline-function-based style for C++. This means that the header contains actual inline functions, which forward their parameters to the actual function pointers internally. Like {{{pointer_cpp}}}, most of OpenGL is in a namespace. This is best used for C++ users who want the best possible autocompletion from their IDE or coding tool of choice.
+* [[Style_No_Load_C|{{{noload_c}}}]]: Automatic loading style for C. This is similar to the old loading tool GLee. Unlike the other styles, it does not require an initialization function; you simply call whatever function you want to use. The first time a call is encountered, it will load that function. This is best used for C or C++ users who don't want to do explicit initialization, and also want header compatibility like {{{pointer_c}}}.
+* [[Style_No_Load_CPP|{{{noload_cpp}}}]]: Automatic loading style for C++. This is similar to the old loading tool GLee. Unlike the other styles, it does not require an initialization function; you simply call whatever function you want to use. The first time a call is encountered, it will load that function. It will wrap most of OpenGL in a namespace. This is best used for C++ users who don't want to do explicit initialization.
 
 ==Core Extensions==