Commits

Jason McKesson committed 028ae38

Doc updates for common extension files and such.

Comments (0)

Files changed (12)

docs/Command_Line_Options.xml

             <glossdef>
                 <para>The code generation suite has a number of different ways of outputting the
                     functions and enumerators that define OpenGL. This option allows the user to
-                    select between these particular mechanisms. It must be one of the following
-                    values:</para>
+                    select between these particular mechanisms.</para>
+                <para>The specific meaning of these parameters is <link xlink:href="Styles"
+                        >explained elsewhere.</link> Note that the system is designed to be
+                    user-extensible; new styles can be added by creating an appropriate script and
+                    hooking it into the right place in
+                    <filename>modules/Styles.lua</filename>.</para>
+                <para>It must be one of the following values:</para>
                 <itemizedlist>
                     <listitem>
                         <para><literal>pointer_c</literal>: default.</para>
                     </listitem>
                 </itemizedlist>
-                <para>The specific meaning of these parameters is explained elsewhere. Note that the
-                    system is designed to be extensible; new styles can be added by modifying an
-                    appropriate script and hooking it into the right place in
-                        <filename>modules/Styles.lua</filename>.</para>
             </glossdef>
         </glossentry>
         <glossentry>

docs/Common_Extension_Files.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>Common Extension Files</title>
+    <para><link xlink:href="Extension_Files">Extension files</link> 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.</para>
+    <para>To include these names from the command-line, you should use the
+            <literal>-stdext</literal> option, instead of <literal>-extfile</literal>. The
+        difference is where they search; <literal>extfile</literal> is always relative to the
+        directory you're currently in, while <literal>stdext</literal> is relative to LoadGen's
+        directory.</para>
+    <para>To include these names from an extension file, you should use <literal>#include
+            &lt;></literal> instead of <literal>#include ""</literal>, for the same reasons as
+        above.</para>
+    <para>All of these extension files are located in the directory <filename>extfiles</filename>.
+        Therefore, any inclusion of them should be as this: <literal>-stdext=extfiles/&lt;include
+            filename></literal> or <literal>#include &lt;extfiles/&lt;include
+        filename>></literal>.</para>
+    <para>Here is a list of the files and what they include:</para>
+    <glosslist>
+        <glossentry>
+            <glossterm>gl_ubiquitous</glossterm>
+            <glossdef>
+                <para>For the kinds of extensions that <emphasis>should</emphasis> be core OpenGL,
+                    but aren't for IP reasons. Namely, anisotropic filtering, and the extensions
+                    needed for S3TC.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>gl_core_post_3_3</glossterm>
+            <glossdef>
+                <para>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.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>gl_plat_3_3</glossterm>
+            <glossdef>
+                <para>Vendor-specific extensions that are implemented by multiple vendors. Things
+                    like NV_texture_barrier.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>gl_AMD_3_3</glossterm>
+            <glossdef>
+                <para>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).</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>gl_macosx_3_2</glossterm>
+            <glossdef>
+                <para>All of the extensions allowed by core 3.2 profiles in MacOSX, as of version
+                    MacOSX 10.8.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>wgl_common</glossterm>
+            <glossdef>
+                <para>Commonly useful non-vendor-specific WGL extensions. The basic stuff: getting
+                    extensions_string, create_context, swap_control, various pixel-format
+                    extensions, etc.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>wgl_AMD</glossterm>
+            <glossdef>
+                <para>Useful AMD vendor WGL extensions.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>wgl_NV</glossterm>
+            <glossdef>
+                <para>Useful NVIDIA vendor WGL extensions.</para>
+            </glossdef>
+        </glossentry>
+    </glosslist>
+</article>

docs/Extension_Files.xml

                 prefixes.</para>
         </listitem>
     </itemizedlist>
-    <para>The inclusion mechanism is quite powerful.</para>
+    <para>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.</para>
 </article>
                 <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. They just work (Well,
             that's the plan ;) ).</para>
+        <para>The <link xlink:href="Command_Line_Options">full command-line syntax
+                documentation</link> is available. The <literal>-style</literal> parameter's <link
+                xlink:href="Styles">meaning is defined here</link>.</para>
         <section>
             <title>Extensions</title>
             <para>Note that the above command line will <emphasis>only</emphasis> generate
                     <literal>#include</literal> 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.</para>
+            <para>The system has a number of <link xlink:href="Common_Extension_Files">common
+                    extension files</link> that store useful sets of extensions. You may use these
+                as you wish.</para>
         </section>
     </section>
 </article>

docs/Load Docs.xpr

                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Style_Pointer_C.xml</String>
+                                    <String xml:space="preserve">Common_Extension_Files.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>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
+                                    <String xml:space="preserve">Styles.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>
+                                <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_Line_Options.xml</String>
                                 </field>
                             </scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">ToCreole.xsl</String>
+                                    <String xml:space="preserve">Home.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_Pointer_C.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Home.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>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Styles.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%20Pointer%20C.xml</String>
                                 </field>
                             </scenarioAssociation>
             <file name="ToCreole.xsl"/>
         </folder>
         <file name="Command_Line_Options.xml"/>
+        <file name="Common_Extension_Files.xml"/>
         <file name="Extension_Files.xml"/>
         <file name="Home.xml"/>
+        <file name="Style_Creation.xml"/>
         <file name="Style_Pointer_C.xml"/>
         <file name="Styles.xml"/>
     </projectTree>

docs/Style_Creation.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 Creation</title>
+    <para>The style system is designed to be extensible and as simple as possible. That doesn't mean
+        it's not somewhat complex.</para>
+</article>
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
     <title>Styles</title>
     <para>The <literal>-style</literal> command line option defines how the header and source files
-        are generated. While the styles will have some differences, every style provides a common
-        set of functionality (though exactly how it is exposed differs). Styles provide:</para>
+        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:</para>
     <itemizedlist>
         <listitem>
             <para>Typedefs for OpenGL concepts (GLenum, etc).</para>
                 versions/profiles (where applicable).</para>
         </listitem>
         <listitem>
-            <para>A function that will load all function pointers. Even if the style requires static
-                linking, it will still provide a special function to do this. 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.</para>
+            <para>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.</para>
             <para>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 <quote>succeed</quote>. Test for
             the system for 3.1, core profiles, you will see <literal>GL_QUADS</literal>, as well as
             a few others. The number of these are rather few, so it should not be a problem.</para>
     </section>
+    <section>
+        <title>Available styles</title>
+        <para>There are a number of styles available, with documentation explaining exactly what
+            they generate:</para>
+        <itemizedlist>
+            <listitem>
+                <para><literal><link xlink:href="Style_Pointer_C">pointer_c</link></literal>: Used
+                    for C-style header generation.</para>
+            </listitem>
+        </itemizedlist>
+    </section>
+    <section>
+        <title>User-created styles</title>
+        <para>The style mechanism is designed to be extensible. You should be able to write new
+            styles relatively painlessly. This system is <link xlink:href="Style_Creation">covered
+                in some detail</link>. The general idea is that you write a Lua script that exposes
+            a number of functions. Then you hook this script into the build system by adding a line
+            of code to one of the files. At which point, you're done. Making the style script is the
+            hard part.</para>
+    </section>
 </article>

docs/ToCreole.xsl

     
     <xsl:template match="db:itemizedlist|db:orderedlist" mode="file">
         <xsl:apply-templates select="*|text()" mode="#current"/>
-        <xsl:if test="not(following-sibling::*)">
-            <xsl:text>
+        <xsl:text>
 </xsl:text>
-        </xsl:if>
     </xsl:template>
     
     <xsl:template match="db:programlisting" mode="file">

extfiles/gl_macosx_3_2.txt

+-- All of the extensions supported by core 3.2 in MacOSX.
+
+ARB_instanced_arrays
+ARB_occlusion_query2
+ARB_shader_bit_encoding
+ARB_timer_query
+EXT_depth_bounds_test
+EXT_framebuffer_multisample_blit_scaled
+EXT_texture_compression_s3tc
+EXT_texture_filter_anisotropic
+EXT_texture_mirror_clamp
+EXT_texture_sRGB_decode
+APPLE_client_storage
+APPLE_container_object_shareable
+APPLE_object_purgeable
+APPLE_rgb_422
+APPLE_row_bytes
+APPLE_texture_range

extfiles/gl_ubiquitous.txt

 --Extensions that are *widely* available and vital for basic functionality.
 --IE: things that should be core, but aren't.
+
 EXT_texture_compression_s3tc
 EXT_texture_sRGB
 EXT_texture_filter_anisotropic

extfiles/wgl_common.txt

+ARB_multisample
+ARB_extensions_string
+ARB_pixel_format
+ARB_pixel_format_float
+ARB_framebuffer_sRGB
+ARB_create_context
+ARB_create_context_profile
+ARB_create_context_robustness
+EXT_swap_control
+EXT_pixel_format_packed_float
+EXT_create_context_es2_profile
+EXT_swap_control_tear
+NV_swap_group

extfiles/wgl_commonexts.txt

-ARB_multisample
-ARB_extensions_string
-ARB_pixel_format
-ARB_pixel_format_float
-ARB_framebuffer_sRGB
-ARB_create_context
-ARB_create_context_profile
-ARB_create_context_robustness
-EXT_swap_control
-EXT_pixel_format_packed_float
-EXT_create_context_es2_profile
-EXT_swap_control_tear
-NV_swap_group
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.