Source

glLoadGen / docs / Command Line Options.xml

Full commit
<?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. Note that the
                    system is extensible; new styles can be added by modifying an appropriate script
                    and hooking it into the right place in <filename>_Styles.lua</filename>.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>-indent</glossterm>
            <glossdef>
                <para>The indentation style for the output text. It must be one of the
                    following:</para>
                <itemizedlist>
                    <listitem>
                        <para><literal>tab</literal>: default</para>
                    </listitem>
                    <listitem>
                        <para><literal>space</literal>: Will use 2 spaces to indent.</para>
                    </listitem>
                </itemizedlist>
            </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>