glLoadGen / docs / Home.xml

Full commit
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="" type="xml"?>
<?oxygen SCHSchema=""?>
<article xmlns="" xmlns:xi=""
    xmlns:xlink="" version="5.0">
        <title>OpenGL Loader Generator</title>
        <para>This loader generation system is used to create OpenGL headers and loading code for
            your specific needs. Rather than getting every extension and core enumerator/function
            all in one massive header, you get only what you actually want and ask for.</para>
        <para><link xlink:href="">Download it
                here;</link> you will need to have the Lua runtime installed on your machine to use
            the code generation scripts. It's pretty tiny, so it shouldn't be a problem. Windows
            users can install <link xlink:href="">Lua For
                Windows</link>, or just <link xlink:href="">the
                Lua binaries packages</link>. The code should be compatible with Lua 5.1 and 5.2,
            but it has only been tested on 5.1.</para>
        <para>Note: this script is designed to be stand-alone. There is a caveat: Lua lacks any real
            filesystem commands, so the script cannot create directories for the destination files.
            However, if you have installed the <link
                xlink:href="">Lua FileSystem</link>
            Lua module (such that Lua can detect it), then this script will access and use it to
            create directories. It comes with Lua For Windows, but you can use <link
                xlink:href="">LuaRocks</link> to install it on any platform
            as well.</para>
        <para>The scripts in this package are licensed under the terms of the MIT License.</para>
            <title>Basic Usage</title>
            <para>To use the code generator, with Lua in your path (assuming that
                    <literal>lua</literal> is the name of your Lua executable), type this:</para>
            <programlisting>lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3</programlisting>
            <para>This tells the system to generate a header/source pair for OpenGL
                    (<literal>-spec=gl</literal>, as opposed to WGL or GLX), for version 3.3, the
                core profile. It will generate it in the <literal>pointer_c</literal> style, which
                means that it will use function pointer-style, with C linkage and source. Such code
                is usable from C and C++, or other languages that can interface with C.</para>
            <para>The option <filename>core_3_3</filename> is the basic component of the filename
                that will be used for the generation. Since it is generating OpenGL loaders (again,
                as opposed to WGL or GLX), it will generate files named
                    <filename>gl_core_3_3.*</filename>, where * is the extension used by the
                particular style.</para>
            <para>The above command line will generate <filename>gl_core_3_3.h</filename> and
                    <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>
            <programlisting>//Pre-window creation.
int windowID = glutCreateWindow("Name");

if(ogl_LoadFunctions() == ogl_LOAD_FAILED)
//Call functions here.</programlisting>
            <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.
                Different styles will have different initialization needs and so forth (you don't
                even need to initialize some styles at all). The available styles are:</para>
                    <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_CPP"
                        ><literal>pointer_cpp</literal></link>: Used for creating C++-style loaders,
                        wrapping as much as possible in namespaces.</para>
                    <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>
            <para>More about styles can be found on the <link xlink:href="Styles">style
            <para>Note that the above command line will <emphasis>only</emphasis> generate
                enumerators and functions for core OpenGL 3.3. It doesn't offer any extensions. To
                use extensions, you must ask for them with command line parameters, as
            <programlisting>lua LoadGen.lua -style=pointer_c -spec=gl -version=3.3 -profile=core core_3_3 -exts ARB_texture_view ARB_vertex_attrib_binding EXT_texture_filter_anisotropic -ext=EXT_texture_compression_s3tc -extfile=SomeFile.txt</programlisting>
            <para>The <literal>-exts</literal> option starts a list of space-separated extension
                names (note: don't try to put the output filename after <literal>-exts</literal>;
                the system can't tell the difference between a filename and an extension). The
                    <literal>-ext</literal> option only specifies a single name.</para>
            <para><literal>-extfile</literal> specifies a <emphasis>filename</emphasis> to load
                extensions from. The format of this file is fairly simple; it is <link
                    xlink:href="Extension Files">explained here on this site</link>. The file is
                expected to contain extension names, one on each line. Extension files can also have
                    <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>
            <para>Here are some example command lines. This command-line generates loaders for core
                OpenGL 3.3, without proprietary extensions, but with non-hardware features that were
                added to OpenGL in later versions:</para>
            <programlisting>lua LoadGen.lua core_3_3 -style=pointer_c -spec=gl -version=3.3 -profile=core -stdext=gl_ubiquitous.txt -stdext=gl_core_post_3_3.txt</programlisting>
            <para>This command-line is for OpenGL 4.3, but with certain commonly-provided extensions
                that are generally useful.</para>
            <programlisting>lua LoadGen.lua core_4_3 -style=pointer_c -spec=gl -version=4.3 -profile=core -stdext=gl_ubiquitous.txt -stdext=gl_plat_3_3.txt</programlisting>
            <para>This command-line generates a header that exposes OpenGL 3.2 for what MacOSX 10.8
                uses (note: the loader generator files have not been tested with MacOSX of any
            <programlisting>lua LoadGen.lua core_3_2 -style=pointer_c -spec=gl -version=3.2 -profile=core -stdext=gl_ubiquitous.txt -stdext=gl_macosx_3_2.txt</programlisting>