Jason McKesson avatar Jason McKesson committed 2ee379a

Fix for Issue #27: misleading documentation.

Comments (0)

Files changed (5)

                     <filename>gl_core_3_3.c</filename> files. Simply include them in your project;
                 there is no library to build, no unresolved extenals to filter through.</para>
             <para>You will need to call <literal>ogl_LoadFunctions</literal> to initialize the
-                library. And you must call it <emphasis>after</emphasis> OpenGL context creation.
-                For example, if you are using FreeGLUT, your code looks like this:</para>
+                library if you use the <literal>pointer_c</literal> style. And you must call it
+                    <emphasis>after</emphasis> OpenGL context creation. For example, if you are
+                using FreeGLUT, your code looks like this:</para>
             <programlisting>//Pre-window creation.
 int windowID = glutCreateWindow("Name");
 
   glutDestroyWindow(windowID);
 }
 //Call functions here.</programlisting>
+            <para>Replace the "Pre-window creation" and <literal>glutCreateWindow</literal> call with
+                your usual OpenGL context creation code.</para>
             <para>The <link xlink:href="Command_Line_Options">full command-line syntax
                     documentation</link> is available. Of particular note is the
                     <literal>-style</literal> parameter, which defines how the loader is generated.
             <itemizedlist>
                 <listitem>
                     <para><link xlink:href="Style_Pointer_C"><literal>pointer_c</literal></link>:
-                        Used for C-style header generation.</para>
+                        Used for C-style loader generation.</para>
                 </listitem>
                 <listitem>
                     <para><link xlink:href="Style_Pointer_CPP"
                         initialization function on to get function pointers.</para>
                 </listitem>
             </itemizedlist>
+            <para>Each linked page has instructions on how to use the generated interface.</para>
             <para>More about styles can be found on the <link xlink:href="Styles">style
                 page</link>.</para>
         </section>

docs/Load Docs.xpr

                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Extension%20Files.xml</String>
+                                    <String xml:space="preserve">ToCreole.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">Style%20Pointer%20C.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Style%20Pointer%20C.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">ToCreole.xsl</String>
+                                    <String xml:space="preserve">Extension%20Files.xml</String>
                                 </field>
                             </scenarioAssociation>
                         </scenarioAssociation-array>

docs/Style_No_Load_CPP.xml

         initializes the extension variables, 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
+                <quote>gl</quote> namespaces to <quote>wgl</quote> or <quote>glx</quote> 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.
+gl::sys::CheckExtensions();</programlisting>
+        <para>The presence of extensions can be checked as follows:</para>
+        <programlisting>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);
+}</programlisting>
+    </section>
+    <section>
         <title>Versions</title>
         <para>When you use this system and provide a version number of OpenGL,
                 <literal>noload_cpp</literal> will assume that you are <emphasis>serious</emphasis>

docs/Style_Pointer_C.xml

     <para>The <literal>pointer_c</literal> style is the default style. It is also the one that most
         mimics the way common OpenGL loaders work. This style generates a <filename>.h</filename>
         and <filename>.c</filename> file. The header file can be included by C and C++; the source
-        file should be compiled as C.</para>
+        file should be compiled as C. The generated source is compatible with C89.</para>
     <para>Since these are compatible with C, all of the typedefs, enumerations, extension variables,
         and function pointers are global. The extension variables are of type
         <literal>int</literal>. Enumerations are <literal>#define</literal>s. The functions are
         function pointers with mangled names that have been <literal>#define</literal>d into the
         real OpenGL function name. The latter is done to avoid name conflicts with static linking of
         certain core OpenGL function names.</para>
-    <para>The loading function that loads the extensions and OpenGL version is called
+    <para>The function that loads the extensions and OpenGL version is called
             <literal>LoadFunction</literal>, 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.</para>
     <para>Also, this style will generate functions to query the version of the OpenGL
         context.</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
+                <quote>ogl</quote>s to <quote>wgl</quote> or <quote>glx</quote> as
+            appropriate.</para>
+        <programlisting>//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);</programlisting>
+        <para>The presence of extensions can be checked as follows:</para>
+        <programlisting>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);
+}</programlisting>
+        <para>Of course, this requires asking for the
+                <literal>EXT_texture_compression_s3tc</literal> extension on the command-line (or in
+            a referenced file).</para>
+    </section>
+    <section>
         <title>Versions</title>
         <para>When you use this system and provide a version number of OpenGL,
                 <literal>pointer_c</literal> will assume that you are <emphasis>serious</emphasis>

docs/Style_Pointer_CPP.xml

         The number of functions that failed to load refers to the core functions (and core extension
         functions).</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
+                <quote>gl</quote> namespaces to <quote>wgl</quote> or <quote>glx</quote> as
+            appropriate.</para>
+        <programlisting>//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());</programlisting>
+        <para>The presence of extensions can be checked as follows:</para>
+        <programlisting>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);
+}</programlisting>
+    </section>
+    <section>
         <title>Versions</title>
         <para>When you use this system and provide a version number of OpenGL,
                 <literal>pointer_cpp</literal> will assume that you are <emphasis>serious</emphasis>
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.