glLoadGen / docs / Style_Pointer_C.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 Pointer C</title>
    <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>
    <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
            <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>If the value is <literal>LOAD_FAILED</literal>, then the extension was not found in the
        extension string, so no attempt was made to load it. If the value is
            <literal>LOAD_SUCCEEDED</literal>, then the extension was loaded in its entirety (all
        function pointers accounted for, if it has some). Otherwise, some number of function
        pointers failed to load. To get the number of functions that failed to load for the
        extension, take the integer value and subtract <literal>LOAD_SUCCEEDED</literal> from
        it.</para>
    <para>The return value for the function loader works mostly the same way.
            <literal>LOAD_FAILED</literal> does not signal the failure to load the core functions or
        some extensions. It signals the failure of the process to work <emphasis>at all.</emphasis>
        This is for something very basic, like the failure to get the function pointers needed to
        get the extension string. Without the extension string, we cannot detect what should and
        shouldn't be loaded. Therefore, if this is returned, <emphasis>nothing</emphasis> was
        loaded.</para>
    <para>For non-fail states, the value works like for the individual extension variables, except
        that the number that failed to load refer to core functions. So for specs that don't load
        core functions, it will always return <literal>LOAD_SUCCEEDED</literal>.</para>
    <para>Also, this style will generate functions to query the version of the OpenGL
        context.</para>
    <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>
            about that version number. Which means that if you create a 3.3 header, and you do not
            supply a context that claims support for at least OpenGL version 3.3, loading failure
            may occur.</para>
        <para>In particular, OpenGL changed the mechanism to check for the presence/absence of
            extensions in version 3.0. Therefore, <literal>pointer_c</literal> will also change how
            it checks for the presence/absence of extensions based on that. If you provide a version
            3.0 or greater, it will use the new style. Thus, if your context is only version 2.1,
            then this style will be unable to function and will return
                <literal>LOAD_FAILED</literal>.</para>
    </section>
    <section>
        <title>Compatibility</title>
        <para>This style is intended to be maximally compatible with regular OpenGL programs. You
            should be able to take this header and include it into a standard GL program and use it
            as is. Furthermore, it should be compatible with other systems like FreeGLUT, GLFW, and
            so forth, as it provides information in the way that traditional OpenGL headers
            do.</para>
        <para>However, in all cases, you should include these generated headers
                <emphasis>before</emphasis> anything from FreeGLUT, GLFW, etc.</para>
    </section>
</article>
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.