glLoadGen / docs / Style_Pointer_CPP.xml

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="" type="xml"?>
<?oxygen SCHSchema=""?>
<article xmlns="" xmlns:xi=""
    xmlns:xlink="" version="5.0">
    <title>Style Pointer C++</title>
    <para>The <literal>pointer_cpp</literal> style is designed to work well in C++. Where
            <literal>pointer_c</literal> maximizes interoperability with other systems (it defines
        global functions with the expected C names), <literal>pointer_cpp</literal> is primarily
        about making it easy for intellisense and the like to find the function definitions for easy
    <para>With the exception of the typedefs, everything lives in a C++ namespace based on each
        spec: <literal>gl</literal>, <literal>wgl</literal>, and <literal>glx</literal>. If the
            <literal>-prefix</literal> option was provided, then the spec namespace will itself be
        within a namespace named for the prefix.</para>
    <para>The extension variables are in their own namespace:
            <literal>&lt;prefix>::&lt;spec>::exts</literal>. The type of the variable is not a mere
            <literal>bool</literal>; it is an <literal>exts::LoadTest</literal>. This type is
        convertible to bool (via the safe-bool idiom, so no need to worry about that), but it also
        has a function to see how many functions failed to load for that extension. It will always
        report that it loaded if the extension string is in the spec; the
            <literal>exts::LoadTest::GetNumFailed()</literal> will return the number of functions
        that failed to load (if any).</para>
    <para>The enumerators are actual C++ enums now. There is no enumeration name; all of the enums
        live in one big enumeration. Because the enumerators are namespace-qualified now, there is
        no need to put the <literal>(W)GL(X)_</literal> in front of them. So we do not. However,
        this causes two problems:</para>
            <para>Some enumerators (<literal>2D</literal>, for example. Yes, that is an OpenGL
                enumerator; it's for feedback rendering) begin with characters that C++ doesn't
                allow as identifiers. Thus, these enumerators are prefixed with an
                        <quote><literal>_</literal></quote> character. So <literal>2D</literal>
                becomes <literal>_2D</literal>.</para>
            <para>Certain enumerators use widely used by OS's for various things. Windows for
                example <literal>#define</literal>s <literal>TRUE</literal> and
                    <literal>FALSE</literal>, among others. There's no automated way to detect this,
                so there's just a list of the known ones. These known enumerators will be suffixed
                with an <quote><literal>_</literal></quote> character. So <literal>TRUE</literal>
                becomes <literal>TRUE_</literal>.</para>
    <para>The functions are function pointers, but their names are not hidden behind a
            <literal>#define</literal>. This should allow code-completion tools to be more useful.
        They also aren't prefixed with <literal>(w)gl(X)</literal>, since they live in a
    <para>The system functions (the function that loads the function pointers, version getting, etc)
        are contained in the <literal>&lt;prefix>::&lt;spec>::sys</literal> namespace. The loader
        function will always be called <literal>LoadFunctions</literal>. It returns an
            <literal>ext::LoadTest</literal>, which works as above. It will only be false if it
        couldn't even attempt to load functions (due to being unable to get the extension string).
        The number of functions that failed to load refers to the core functions (and core extension
        <para>These headers are "compatible" with headers from other libraries (FreeGLUT, GLFW,
            etc), but only in the sense that they define the appropriate typedefs globally. If any
            of these headers have inline functions that make calls into GL, expecting functions to
            be named in the standard GL style, then they're in trouble. Also, these headers
                <emphasis>prevent</emphasis> the later inclusion of <filename>gl.h</filename> and
            similar headers, so that kind of code will likely complain.</para>
        <para>If you're using some kind of hybrid like this, you need to create an insulation layer
            between those inline functions and the appropriate typedefs.</para>