glLoadGen / docs / Style_Pointer_C.xml

<?oxygen RNGSchema="" type="xml"?>
<?oxygen SCHSchema=""?>
<article xmlns="" xmlns:xi=""
    xmlns: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. The generated source is compatible with C89.</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 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
    <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
    <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. They
            <para><literal>&lt;prefix>ogl_GetMajorVersion()</literal>: Returns an integer
                identifying the major version number of this OpenGL context.</para>
            <para><literal>&lt;prefix>ogl_GetMinorVersion()</literal>: Returns an integer
                identifying the minor version number of this OpenGL context.</para>
            <para><literal>&lt;prefix>ogl_ogl_IsVersionGEQ(int majorVersion, int
                    minorVersion)</literal>: Returns non-zero if the current context version is
                larger than or equal to the given major and minor versions.</para>
        <para>This example is for loading the OpenGL functions; it expects the OpenGL header
            generated by glLoadGen to be included. For loading WGL/GLX functions, include their
            headers and change the <quote>ogl</quote>s to <quote>wgl</quote> or <quote>glx</quote>
            as appropriate.</para>
        <programlisting>//Create OpenGL context and make it current.

int loaded = ogl_LoadFunctions();
if(loaded == ogl_LOAD_FAILED)
  //The context cannot work with the generated headers for some reason. Abort.
  //Destroy the context

int num_failed = loaded - ogl_LOAD_SUCCEEDED;
printf("Number of functions that failed to load: %i.\n", num_failed);</programlisting>
        <para>The presence of extensions can be checked as follows:</para>
        <programlisting>if(ogl_ext_EXT_texture_compression_s3tc != ogl_LOAD_FAILED)
  glCompressedTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, 256, 256,
    GL_COMPRESSED_RGBA_S3TC_DXT5_EXT, compressedSize, compressedPixels);
  void *decompressedPixels = DecompressPixels(256, 256,
    compressedSize, compressedPixels);

    GL_RGBA, GL_UNSIGNED_BYTE, decompressedPixels);
        <para>Of course, this requires asking for the
                <literal>EXT_texture_compression_s3tc</literal> extension on the command-line (or in
            a referenced file).</para>
        <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
        <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
        <para>However, in all cases, you should include these generated headers
                <emphasis>before</emphasis> anything from FreeGLUT, GLFW, etc.</para>
Tip: Use camelCasing e.g. ProjME to search for