Commits

Jason McKesson committed c76a5cd

Added docs for the new styles.

Comments (0)

Files changed (6)

             <itemizedlist>
                 <listitem>
                     <para><link xlink:href="Style_Pointer_C"><literal>pointer_c</literal></link>:
-                        Used for C-style loader generation.</para>
+                        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).</para>
                 </listitem>
                 <listitem>
                     <para><link xlink:href="Style_Pointer_CPP"
-                        ><literal>pointer_cpp</literal></link>: Used for creating C++-style loaders,
-                        wrapping as much as possible in namespaces.</para>
+                        ><literal>pointer_cpp</literal></link>: 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.</para>
+                </listitem>
+                <listitem>
+                    <para><link xlink:href="Style_Function_CPP"><literal>func_cpp</literal></link>:
+                        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 <literal>pointer_cpp</literal>, 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.</para>
+                </listitem>
+                <listitem>
+                    <para><link xlink:href="Style_No_Load_C"><literal>noload_c</literal></link>:
+                        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 <literal>pointer_c</literal>.</para>
                 </listitem>
                 <listitem>
                     <para><link xlink:href="Style_No_Load_CPP"><literal>noload_cpp</literal></link>:
-                        Used for creating C++-style loaders that you don't need to call an
-                        initialization function on to get function pointers.</para>
+                        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.</para>
                 </listitem>
             </itemizedlist>
             <para>Each linked page has instructions on how to use the generated interface.</para>

docs/Load Docs.xpr

                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
+                                    <String xml:space="preserve">Style_No_Load_C.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Style_Function_CPP.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
                                     <String xml:space="preserve">Style_Creation.xml</String>
                                 </field>
                             </scenarioAssociation>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                 <field name="name">
+                                    <String xml:space="preserve">ToMarkdown</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">ToMarkdown.xsl</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
                                     <String xml:space="preserve">ToCreole</String>
                                 </field>
                                 <field name="type">
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">ToCreole.xsl</String>
+                                    <String xml:space="preserve">Extension%20Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Command%20Line%20Options.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Command%20Line%20Options.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Extension%20Files.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToMarkdown</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">ToMarkdown.xsl</String>
+                                    <String xml:space="preserve">ToCreole.xsl</String>
                                 </field>
                             </scenarioAssociation>
                         </scenarioAssociation-array>
         <file name="New_Style_Step_By_Step.xml"/>
         <file name="Structure_Reference.xml"/>
         <file name="Style_Creation.xml"/>
+        <file name="Style_Function_CPP.xml"/>
+        <file name="Style_No_Load_C.xml"/>
         <file name="Style_No_Load_CPP.xml"/>
         <file name="Style_Pointer_C.xml"/>
         <file name="Style_Pointer_CPP.xml"/>

docs/Style_Function_CPP.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng" type="xml"?>
+<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Style Function C++</title>
+    <para>The <literal>func_cpp</literal> style is functionally equivalent to <link
+            xlink:href="Style_Pointer_CPP"><literal>pointer_cpp</literal></link> 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.</para>
+    <para>The <emphasis>only</emphasis> reason to use this style over <literal>pointer_cpp</literal>
+        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.</para>
+</article>

docs/Style_No_Load_C.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng" type="xml"?>
+<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Style No Load C</title>
+    <para>The <literal>noload_c</literal> 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.</para>
+    <para>As a C style, it follows the naming conventions of the <literal
+            xlink:href="Style_Pointer_CPP">pointer_c</literal> style. It prefixes enums and
+        functions with <literal>GL/WGL/GLX</literal> and <literal>gl/wgl/glX</literal> as
+        appropriate.</para>
+    <para>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.</para>
+    <para>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
+            <literal>ogl/wgl/glx_exts_&lt;extension name></literal>. These are
+            <literal>int</literal> types. However, unlike the magic function pointers, you have to
+        call another function to initialize them. You must call
+            <literal>ogl/wgl/glx_CheckExtensions</literal>. This function only checks what is
+        exported by the extension string, so it cannot report on the number of functions that failed
+        to load.</para>
+    <section>
+        <title>Example</title>
+        <para>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
+                <literal>ogl_</literal> prefixes to <literal>wgl</literal> or <literal>glx</literal>
+            as appropriate.</para>
+        <programlisting>//Create OpenGL context and make it current.</programlisting>
+        <para>That was a trick question: there is no initialization required. That is the whole
+            point of this style, after all.</para>
+        <para>However, if you want to query which extensions are around, you
+                <emphasis>need</emphasis> to initialize that:</para>
+        <programlisting>//Create OpenGL context and make it current.
+ogl_CheckExtensions();</programlisting>
+        <para>The presence of extensions can be checked as follows:</para>
+        <programlisting>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);
+}</programlisting>
+    </section>
+    <section>
+        <title>Versions</title>
+        <para>When you use this system and provide a version number of OpenGL,
+                <literal>noload_c</literal> will assume that you are <emphasis>serious</emphasis>
+            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, <emphasis>crashing
+                may occur</emphasis>.</para>
+        <para>In particular, OpenGL changed the mechanism to check for the presence/absence of
+            extensions in version 3.0. Therefore, <literal>noload_c</literal> 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.</para>
+    </section>
+</article>

docs/Style_No_Load_CPP.xml

 <?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
 <article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
-    <title>Style No Load</title>
+    <title>Style No Load C++</title>
     <para>The <literal>noload_cpp</literal> 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
         is:</para>
     <itemizedlist>
         <listitem>
-            <para>Typedefs for OpenGL concepts (GLenum, etc).</para>
+            <para>Typedefs for OpenGL types (<literal>GLenum</literal>, <literal>GLint</literal>,
+                etc).</para>
         </listitem>
         <listitem>
             <para>A means to tell whether each of the extensions specified by the user is loaded or
             they generate:</para>
         <itemizedlist>
             <listitem>
-                <para><link xlink:href="Style_Pointer_C"><literal>pointer_c</literal></link>: Used
-                    for C-style header generation.</para>
+                <para><link xlink:href="Style_Pointer_C"><literal>pointer_c</literal></link>:
+                    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).</para>
             </listitem>
             <listitem>
                 <para><link xlink:href="Style_Pointer_CPP"><literal>pointer_cpp</literal></link>:
-                    Used for creating C++-style loaders, wrapping as much as possible in
-                    namespaces.</para>
+                    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.</para>
+            </listitem>
+            <listitem>
+                <para><link xlink:href="Style_Function_CPP"><literal>func_cpp</literal></link>:
+                    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 <literal>pointer_cpp</literal>, 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.</para>
+            </listitem>
+            <listitem>
+                <para><link xlink:href="Style_No_Load_C"><literal>noload_c</literal></link>:
+                    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 <literal>pointer_c</literal>.</para>
             </listitem>
             <listitem>
                 <para><link xlink:href="Style_No_Load_CPP"><literal>noload_cpp</literal></link>:
-                    Used for creating C++-style loaders that you don't need to call an
-                    initialization function on to get function pointers.</para>
+                    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.</para>
             </listitem>
         </itemizedlist>
     </section>
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.