Commits

Jason McKesson committed 59bd5e1

Docs for new style.
Fixed a bug in compatibility generation.

  • Participants
  • Parent commits 91f08f2

Comments (0)

Files changed (5)

docs/Load Docs.xpr

                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
+                                    <String xml:space="preserve">Style_Pointer_CPP.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
                                     <String xml:space="preserve">Style_Creation.xml</String>
                                 </field>
                             </scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">ToCreole.xsl</String>
+                                    <String xml:space="preserve">Style_Pointer_C.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Style%20Pointer%20C.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Command%20Line%20Options.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Extension%20Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Command_Line_Options.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Common_Extension_Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Extension_Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Home.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Style_Pointer_C.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Home.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Extension_Files.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Common_Extension_Files.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Command_Line_Options.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Extension%20Files.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Command%20Line%20Options.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Style%20Pointer%20C.xml</String>
+                                    <String xml:space="preserve">ToCreole.xsl</String>
                                 </field>
                             </scenarioAssociation>
                         </scenarioAssociation-array>
         <file name="Home.xml"/>
         <file name="Style_Creation.xml"/>
         <file name="Style_Pointer_C.xml"/>
+        <file name="Style_Pointer_CPP.xml"/>
         <file name="Styles.xml"/>
     </projectTree>
 </project>

docs/Style_Pointer_CPP.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_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
+        work.</para>
+    <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>
+    <orderedlist>
+        <listitem>
+            <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>
+        </listitem>
+        <listitem>
+            <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>
+        </listitem>
+    </orderedlist>
+    <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
+        namespace.</para>
+    <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
+        functions).</para>
+    <section>
+        <title>Compatibility</title>
+        <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>
+    </section>
+</article>
                 <para><literal><link xlink:href="Style_Pointer_C">pointer_c</link></literal>: Used
                     for C-style header generation.</para>
             </listitem>
+            <listitem>
+                <para><literal><link xlink:href="Style_Pointer_CPP">pointer_cpp</link></literal>:
+                    Used for creating C++-style loaders, wrapping as much as possible in
+                    namespaces.</para>
+            </listitem>
         </itemizedlist>
     </section>
     <section>

modules/Generate.lua

 local function GetCoreFunctions(core, specData, spec, options, version)
 	--Only remove from core profile.
 	if(options.profile ~= "core") then
-		return core.func
+		return core.funcs
 	end
 
 	local targetVersion = tonumber(options.version)

modules/StylePointerCPP.lua

 			common.GetFuncReturnType(func, typemap),
 			spec.GetCodegenPtrType(),
 			GenFuncPtrName(func, spec, options),
-			common.GetFuncParamList(func, typemap))
+			common.GetFuncParamList(func, typemap, true))
 	end
 
 	local function GenFuncPtrDefTypedef(func, typemap, spec, options)
 		GenFuncPtrTypedefName(func, spec, options),
 		common.GetProcAddressName(spec),
 		spec.FuncNamePrefix(), func.name)
-	hFile:fmt('if(!%s) numFailed++;\n', GenFuncPtrName(func, spec, options))
+	hFile:fmt('if(!%s) ++numFailed;\n', GenFuncPtrName(func, spec, options))
 end
 
 function my_style.source.WriteBeginCoreFuncDefBlock(hFile, version, spec, options)
 	--Special hack for DSA_EXT functions in core functions.
 	--They do not count against the loaded count.
 	if(func.name:match("EXT$")) then
-		hFile:write("//An EXT_direct_state_access-based function. Don't count it if it fails to load.")
+		hFile:write("//An EXT_direct_state_access-based function. Don't count it if it fails to load.\n")
 	else
-		hFile:fmt('if(!%s) numFailed++;\n', GenFuncPtrName(func, spec, options))
+		hFile:fmt('if(!%s) ++numFailed;\n', GenFuncPtrName(func, spec, options))
 	end
 end