Commits

Jason McKesson  committed 0e3c7eb

Documentation.

  • Participants
  • Parent commits de893e3

Comments (0)

Files changed (3)

File _GetOptions.lua

 	"style",
 	"style",
 	{"Export style."},
-	{"pointer_c", "pointer_c++"},
+	{"pointer_c", "pointer_cpp"},
 	1)
 parseOpts:array(
 	"exts",
 parseOpts:pos_opt(
 	1,
 	"outname",
-	"Base filename (sans extension",
+	"Base filename (sans extension)",
 	"outname")
 	
 local function LoadExtFile(extensions, extfilename)

File docs/Command Line Options.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>Command Line Options</title>
+    <para>The command-line options for the code generation tools are explained here. They work more
+        or less like the standard command-line options for typical Linux/Windows programs. Options
+        that have a single value can take their parameters as either
+            <literal>-opt_name=parameter</literal> or <literal>-opt_name parameter</literal>.</para>
+    <para>You must specify an output filename, which will be used as the base filename for
+        generating the output. It can have arbitrary path information, but it should not have an
+        extension. The generated files will take the base filename and append an appropriate suffix
+        and extension to it. You can give the system the same basename for the different
+        specifications (WGL, GLX, OpenGL) without issue.</para>
+    <para>The output filename should be specified before any of the options. You can specify it
+        after the options or even between options, but if you specify it after the
+            <literal>-exts</literal> option (but before any subsequent options), the system will
+        mistake it for an extension name. Just specify it first to be safe.</para>
+    <glosslist>
+        <glossentry>
+            <glossterm>-spec</glossterm>
+            <glossdef>
+                <para>Defines the particular specification to generate loading code for. It must be
+                    one of the following values:</para>
+                <itemizedlist>
+                    <listitem>
+                        <para><literal>gl</literal>: default</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>glX</literal></para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>wgl</literal></para>
+                    </listitem>
+                </itemizedlist>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-prefix</glossterm>
+            <glossdef>
+                <para>The code generation system will try to minimize the number of global variables
+                    as much as possible. However, it will have to use some non-static variables for
+                    various things.</para>
+                <para>While each individual specification is guaranteed not to have variable name
+                    collisions, it may be useful to have an application use multiple independent
+                    loaders for the same specification. For example, you could have a GL 2.1 set of
+                    functions and a GL 3.3 set (obviously each file must decide for itself which to
+                    use). Their global variables would conflict, making this unworkable.</para>
+                <para>The prefix option allows you to define a string that will be prepended to any
+                    non-static (or otherwise hidden) global variables, where possible. As such, the
+                    prefix should start with characters that are valid for C/C++ identifiers.</para>
+                <para>If the option is not specified, no prefix will be used.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-version</glossterm>
+            <glossdef>
+                <para>The highest version of OpenGL to export. You must use this
+                        <emphasis>only</emphasis> when <literal>-spec</literal> is
+                        <literal>gl</literal>. And you must use it when the specification is
+                        <literal>gl</literal>.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-profile</glossterm>
+            <glossdef>
+                <para>The OpenGL profile to export. For OpenGL versions that don't have the
+                    core/compatibility distinction, the option is ignored. It must be one of the
+                    following values:</para>
+                <itemizedlist>
+                    <listitem>
+                        <para><literal>core</literal>: default</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>compatibility</literal></para>
+                    </listitem>
+                </itemizedlist>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-style</glossterm>
+            <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>
+                <itemizedlist>
+                    <listitem>
+                        <para><literal>pointer_c</literal>: default.</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>pointer_cpp</literal></para>
+                    </listitem>
+                </itemizedlist>
+                <para>The specific meaning of these parameters is explained elsewhere.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-exts</glossterm>
+            <glossdef>
+                <para>Defines a list of extensions to the given specification to export. Every
+                    argument that doesn't start with a "-" following this option will be assumed to
+                    be an extension name. You do not need to prefix the extensions with GL_, WGL_,
+                    or GLX_, but you may do so if you wish.</para>
+                <para>This argument can be specified multiple times. It is fine to specify an
+                    extension name more than once.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-ext</glossterm>
+            <glossdef>
+                <para>Defines a single extension to export. It adds the given parameter to the list
+                    of extensions.</para>
+                <para>This argument can be specified multiple times. It is fine to specify an
+                    extension name more than once.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-extfile</glossterm>
+            <glossdef>
+                <para>Specifying dozens of extensions on the command line can be exceedingly
+                    tedious. Therefore, the system can be instructed to read a list of extensions
+                    from a file with this option. The file should be a plain text file, where each
+                    extension is specified on a single line.</para>
+                <para>This argument can be specified multiple times. It is fine to specify an
+                    extension name more than once, either in the file or on the command line.</para>
+            </glossdef>
+        </glossentry>
+    </glosslist>
+    <section>
+        <title>Styles</title>
+        <para>The different styles have specific meaning for how code is generated by the system.
+            These styles are:</para>
+        <section>
+            <title>pointer_c</title>
+            <para>This builds header/loader files that are C-compatible. Everything is global (since
+                there's nothing non-global in C). OpenGL enumerators are #defines.</para>
+            <para>The functions will be global function pointers (hence the <quote>pointer</quote>
+                in the name), but because of potential name conflicts with static OpenGL loading,
+                their function pointer names will not be their actual names (for example,
+                    <quote>glBindTexture</quote>'s function pointer will not be called that).
+                Instead, the function pointer will be mangled (and prefixed); a #define will be used
+                to effectively convert from the function pointer's actual name to user-expected
+                name.</para>
+            <para>The global function pointer names will be prefixed.</para>
+            <para>Here is an example:</para>
+        </section>
+        <section>
+            <title>pointer_cpp</title>
+            <para>This builds header/loader files that are in a C++ style. The only globals are
+                OpenGL typedefs (which can't be namespaced for various reasons). Everything else
+                lies in a namespace named <literal>&lt;prefix>&lt;spec></literal>.</para>
+            <para>Enumerators will be in an actual enumeration. Also, since the namespace already
+                segregates the OpenGL stuff into its own place, there is no need to have the
+                    <quote>gl</quote> and <quote>GL_</quote> prefixes for functions and
+                enumerators.</para>
+            <note>
+                <para>There are certain OpenGL enums that start with characters that are forbidden
+                    for C++ enumerators. Such enumerators will be prefixed with an <quote>_</quote>
+                    character.</para>
+            </note>
+            <para>Also, there is no #define gimmickry to get the function names right. The function
+                pointers are always named correctly.</para>
+            <para>Here is an example:</para>
+        </section>
+    </section>
+</article>

File docs/Load Docs.xpr

+<?xml version="1.0" encoding="UTF-8"?>
+<project version="12.0">
+    <meta>
+        <filters directoryPatterns="" filePatterns=""
+            positiveFilePatterns="" showHiddenFiles="false"/>
+        <options/>
+    </meta>
+    <projectTree name="Load%20Docs.xpr"/>
+</project>