Bug 1135 - Change JOGL's GlueGen Plugin to support EGL 1.5 , ES 3.1 and GL 4.5

- BuildStaticGLInfo
  - Needs to allow 3rd if-def block in header files

- GLConfiguration Changes
  - 'GLHeader' -> 'GLSemHeader' + 'GLDocHeader'
    This allows us to provide all header files,
    exposing all cross-references (extensions and aliases) for our API doc.

    However, inclusions/exclusion semantics
    shall only operate on the actual header files
    used for code generation.

  - All AliasedSymbol's extensions must be covered by 'IgnoredExtension'
    to be excluded.

  - Sync w/ GlueGen commit 5f66fafec303de7d7904a499fefb8e3d023b61ae

5 files changed, 345 insertions, 200 deletions

diff --git a/make/build-jogl.xml b/make/build-jogl.xml
index 119bb9d3d..9bd98490c 100644
--- a/make/build-jogl.xml
+++ b/make/build-jogl.xml
@@ -512,7 +512,8 @@
                  config="${config.jogl}/gl-if-gl2_es3.cfg" 
                  includeRefid="stub.includes.fileset.all.gldesktop"
                  literalInclude="${stub.includes.gluegen.gg}"
-                 emitter="com.jogamp.gluegen.opengl.GLEmitter">
+                 emitter="com.jogamp.gluegen.opengl.GLEmitter"
+                 debug="false">
             <classpath refid="gluegen-gl.classpath" />
         </gluegen>
     </target>
@@ -904,7 +905,8 @@
                  config="${config.jogl}/cg-common.cfg"
                  includeRefid="stub.includes.cg.fileset.all"
                  literalInclude="${stub.includes.gluegen.gg}"
-                 emitter="com.jogamp.gluegen.procaddress.ProcAddressEmitter">
+                 emitter="com.jogamp.gluegen.procaddress.ProcAddressEmitter"
+                 debug="false">
             <classpath refid="gluegen-gl.classpath" />
         </gluegen>
     </target>
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
index 3b08b5386..8644f1696 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
@@ -206,7 +206,7 @@ public class BuildStaticGLInfo {
             int type = 0; // 1-define, 2-function
             if ( 0 < block ) { // inside a #ifndef GL_XXX block and matching a function, if block > 0
                 String identifier = null;
-                if( 2 >= block ) {  // not within sub-blocks > 2, i.e. further typedefs
+                if( 3 >= block ) {  // not within sub-blocks > 3, i.e. further typedefs
                     if ((m = funcPattern.matcher(line)).matches()) {
                         identifier = m.group(funcIdentifierGroup).trim();
                         type = 2;
@@ -264,14 +264,15 @@ public class BuildStaticGLInfo {
     }
 
     public void dump() {
+        System.err.println("BuildStaticGLInfo.dump():");
         for (final String name : extensionToDeclarationMap.keySet()) {
             final Set<String> decls = extensionToDeclarationMap.get(name);
-            System.out.println("<" + name + "> :");
+            System.err.println("<" + name + "> :");
             final List<String> l = new ArrayList<String>();
             l.addAll(decls);
             Collections.sort(l);
             for (final String str : l) {
-                System.out.println("  <" + str + ">");
+                System.err.println("  <" + str + ">");
             }
         }
     }
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
index 5da45abfe..f8655feea 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
@@ -39,11 +39,15 @@
  */
 package com.jogamp.gluegen.opengl;
 
+import static java.util.logging.Level.INFO;
+
 import com.jogamp.gluegen.GlueEmitterControls;
 import com.jogamp.gluegen.GlueGen;
 import com.jogamp.gluegen.MethodBinding;
+import com.jogamp.gluegen.cgram.types.AliasedSymbol;
 import com.jogamp.gluegen.procaddress.ProcAddressConfiguration;
 import com.jogamp.gluegen.runtime.opengl.GLNameResolver;
+
 import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
@@ -59,11 +63,19 @@ import java.util.StringTokenizer;
 public class GLConfiguration extends ProcAddressConfiguration {
 
     // The following data members support ignoring an entire extension at a time
-    private final List<String> glHeaders = new ArrayList<String>();
+    private final List<String> glSemHeaders = new ArrayList<String>();
     private final Set<String> ignoredExtensions = new HashSet<String>();
     private final Set<String> forcedExtensions = new HashSet<String>();
-    private final Set<String> extensionsRenamedIntoCore = new HashSet<String>();
-    private BuildStaticGLInfo glInfo;
+    private final Set<String> renameExtensionsIntoCore = new HashSet<String>();
+    private BuildStaticGLInfo glSemInfo;
+
+    // GLDocHeaders include GLSemHeaders!
+    boolean dropDocInfo = false;
+    private final List<String> glDocHeaders = new ArrayList<String>();
+    // GLDocInfo include GLSemInfo!
+    private BuildStaticGLInfo glDocInfo;
+    private final Map<String, String> javaDocSymbolRenames = new HashMap<String, String>();
+    private final Map<String, Set<String>> javaDocRenamedSymbols = new HashMap<String, Set<String>>();
 
     // Maps function names to the kind of buffer object it deals with
     private final Map<String, GLEmitter.BufferObjectKind> bufferObjectKinds = new HashMap<String, GLEmitter.BufferObjectKind>();
@@ -97,14 +109,26 @@ public class GLConfiguration extends ProcAddressConfiguration {
             forcedExtensions.add(sym);
         } else if (cmd.equalsIgnoreCase("RenameExtensionIntoCore")) {
             final String sym = readString("RenameExtensionIntoCore", tok, filename, lineNo);
-            extensionsRenamedIntoCore.add(sym);
+            renameExtensionsIntoCore.add(sym);
         } else if (cmd.equalsIgnoreCase("AllowNonGLExtensions")) {
             allowNonGLExtensions = readBoolean("AllowNonGLExtensions", tok, filename, lineNo).booleanValue();
         } else if (cmd.equalsIgnoreCase("AutoUnifyExtensions")) {
             autoUnifyExtensions = readBoolean("AutoUnifyExtensions", tok, filename, lineNo).booleanValue();
-        } else if (cmd.equalsIgnoreCase("GLHeader")) {
-            final String sym = readString("GLHeader", tok, filename, lineNo);
-            glHeaders.add(sym);
+        } else if (cmd.equalsIgnoreCase("GLSemHeader")) {
+            final String sym = readString("GLSemHeader", tok, filename, lineNo);
+            if( !glSemHeaders.contains(sym) ) {
+                glSemHeaders.add(sym);
+            }
+            if( !dropDocInfo && !glDocHeaders.contains(sym) ) {
+                glDocHeaders.add(sym);
+            }
+        } else if (cmd.equalsIgnoreCase("GLDocHeader")) {
+            final String sym = readString("GLDocHeader", tok, filename, lineNo);
+            if( !dropDocInfo && !glDocHeaders.contains(sym) ) {
+                glDocHeaders.add(sym);
+            }
+        } else if (cmd.equalsIgnoreCase("DropAllGLDocHeader")) {
+            dropDocInfo = readBoolean("DropAllGLDocHeader", tok, filename, lineNo).booleanValue();
         } else if (cmd.equalsIgnoreCase("BufferObjectKind")) {
             readBufferObjectKind(tok, filename, lineNo);
         } else if (cmd.equalsIgnoreCase("BufferObjectOnly")) {
@@ -209,111 +233,133 @@ public class GLConfiguration extends ProcAddressConfiguration {
     }
 
     @Override
-    public void dumpIgnores() {
-        System.err.println("GL Ignored extensions: ");
+    public void logIgnores() {
+        LOG.log(INFO, "GL Ignored extensions: {0}", ignoredExtensions.size());
         for (final String str : ignoredExtensions) {
-            System.err.println("\t" + str);
+            LOG.log(INFO, "\t{0}", str);
         }
-        System.err.println("GL Forced extensions: ");
+        LOG.log(INFO, "GL Forced extensions: {0}", forcedExtensions.size());
         for (final String str : forcedExtensions) {
-            System.err.println("\t" + str);
+            LOG.log(INFO, "\t{0}", str);
         }
-        super.dumpIgnores();
+        super.logIgnores();
     }
 
-    protected boolean shouldIgnoreExtension(final String symbol, final boolean criteria) {
-        if (criteria && glInfo != null) {
-            final Set<String> extensionNames = glInfo.getExtension(symbol);
-            if( null != extensionNames ) {
-                boolean ignoredExtension = false;
-                for(final Iterator<String> i=extensionNames.iterator(); !ignoredExtension && i.hasNext(); ) {
-                    final String extensionName = i.next();
-                    if ( extensionName != null && ignoredExtensions.contains(extensionName) ) {
-                        if (DEBUG_IGNORES) {
-                            System.err.print("Ignore symbol <" + symbol + "> of extension <" + extensionName + ">");
-                            if(extensionNames.size()==1) {
-                                System.err.println(", single .");
-                            } else {
-                                System.err.println(", WARNING MULTIPLE OCCURENCE: "+extensionNames);
-                            }
-                        }
-                        ignoredExtension = true;
-                    }
-                }
-                if( ignoredExtension ) {
-                    ignoredExtension = !shouldForceExtension( symbol, true, symbol );
-                    if( ignoredExtension ) {
-                        final Set<String> origSymbols = getRenamedJavaSymbols( symbol );
-                        if(null != origSymbols) {
-                            for(final String origSymbol : origSymbols) {
-                                if( shouldForceExtension( origSymbol, true, symbol ) ) {
-                                    ignoredExtension = false;
-                                    break;
-                                }
-                            }
-                        }
-                    }
+    @Override
+    public void logRenames() {
+        LOG.log(INFO, "GL Renamed extensions into core: {0}", renameExtensionsIntoCore.size());
+        for (final String str : renameExtensionsIntoCore) {
+            LOG.log(INFO, "\t{0}", str);
+        }
+        super.logRenames();
+    }
+
+    protected boolean shouldIgnoreExtension(final AliasedSymbol symbol) {
+        final Set<String> symExtensionNames;
+        // collect current-name symbol extensions
+        {
+            final Set<String> s = glSemInfo.getExtension(symbol.getName());
+            if( null != s ) {
+                symExtensionNames = s;
+            } else {
+                symExtensionNames = new HashSet<String>();
+            }
+        }
+        // collect renamed symbol extensions
+        if( symbol.hasAliases() ) {
+            final Set<String> aliases = symbol.getAliasedNames();
+            for(final String alias : aliases) {
+                final Set<String> s = glSemInfo.getExtension(alias);
+                if( null != s && s.size() > 0 ) {
+                    symExtensionNames.addAll(s);
                 }
-                if( ignoredExtension ) {
-                    return true;
+            }
+        }
+        boolean ignoreExtension = symExtensionNames.size() > 0 &&
+                                  ignoredExtensions.containsAll(symExtensionNames);
+
+        if( LOG.isLoggable(INFO) ) {
+            final Set<String> ignoredSymExtensionNames = new HashSet<String>();
+            final Set<String> notIgnoredSymExtensionNames = new HashSet<String>();
+            for(final Iterator<String> i=symExtensionNames.iterator(); i.hasNext(); ) {
+                final String extensionName = i.next();
+                if ( null != extensionName && ignoredExtensions.contains(extensionName) ) {
+                    ignoredSymExtensionNames.add(extensionName);
+                } else {
+                    notIgnoredSymExtensionNames.add(extensionName);
                 }
             }
-            final boolean isGLEnum = GLNameResolver.isGLEnumeration(symbol);
-            final boolean isGLFunc = GLNameResolver.isGLFunction(symbol);
+            if( ignoreExtension ) {
+                LOG.log(INFO, "Ignored symbol {0} of all extensions <{1}>", symbol.getAliasedString(), symExtensionNames);
+            } else if( ignoredSymExtensionNames.size() > 0 ) {
+                LOG.log(INFO, "Not ignored symbol {0};  Ignored in <{1}>, but active in <{2}>",
+                        symbol.getAliasedString(), ignoredSymExtensionNames, notIgnoredSymExtensionNames);
+            }
+        }
+        if( !ignoreExtension ) {
+            // Check whether the current-name denotes an ignored vendor extension
+            final String name = symbol.getName();
+            final boolean isGLEnum = GLNameResolver.isGLEnumeration(name);
+            final boolean isGLFunc = GLNameResolver.isGLFunction(name);
+            String extSuffix = null;
             if (isGLFunc || isGLEnum) {
-                if (GLNameResolver.isExtensionVEN(symbol, isGLFunc)) {
-                    final String extSuffix = GLNameResolver.getExtensionSuffix(symbol, isGLFunc);
+                if (GLNameResolver.isExtensionVEN(name, isGLFunc)) {
+                    extSuffix = GLNameResolver.getExtensionSuffix(name, isGLFunc);
                     if (getDropUniqVendorExtensions(extSuffix)) {
-                        if (DEBUG_IGNORES) {
-                            System.err.println("Ignore UniqVendorEXT: " + symbol + ", vendor " + extSuffix);
-                        }
-                        return true;
+                        LOG.log(INFO, "Ignore UniqVendorEXT: {0}, vendor {1}, isGLFunc {2}, isGLEnum {3}",
+                                symbol.getAliasedString(), extSuffix, isGLFunc, isGLEnum);
+                        ignoreExtension = true;
                     }
                 }
             }
+            if (!ignoreExtension) {
+                LOG.log(INFO, "Not ignored UniqVendorEXT: {0}, vendor {1}, isGLFunc {2}, isGLEnum {3}",
+                        symbol.getAliasedString(), extSuffix, isGLFunc, isGLEnum);
+            }
         }
-        return false;
+        if( ignoreExtension ) {
+            ignoreExtension = !shouldForceExtension( symbol, symExtensionNames);
+        }
+        return ignoreExtension;
     }
-
-    public boolean shouldForceExtension(final String symbol, final boolean criteria, final String renamedSymbol) {
-        if (criteria && glInfo != null) {
-            final Set<String> extensionNames = glInfo.getExtension(symbol);
-            if( null != extensionNames ) {
-                for(final Iterator<String> i=extensionNames.iterator(); i.hasNext(); ) {
-                    final String extensionName = i.next();
-                    if ( extensionName != null && forcedExtensions.contains(extensionName) ) {
-                        if (DEBUG_IGNORES) {
-                            System.err.print("Not Ignore symbol <" + symbol + " -> " + renamedSymbol + "> of extension <" + extensionName + ">");
-                            if(extensionNames.size()==1) {
-                                System.err.println(", single .");
-                            } else {
-                                System.err.println(", WARNING MULTIPLE OCCURENCE: "+extensionNames);
-                            }
-                        }
-                        return true;
-                    }
-                }
+    public boolean shouldForceExtension(final AliasedSymbol symbol, final Set<String> symExtensionNames) {
+        for(final Iterator<String> i=symExtensionNames.iterator(); i.hasNext(); ) {
+            final String extensionName = i.next();
+            if ( extensionName != null && forcedExtensions.contains(extensionName) ) {
+                LOG.log(INFO, "Not ignored symbol {0} of extension <{1}>",
+                        symbol.getAliasedString(), extensionName);
+                return true;
             }
         }
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Implementation extends the exclusion query w/ {@link #shouldIgnoreExtension(AliasedSymbol) the list of ignored extensions}.
+     * </p>
+     * <p>
+     * If passing the former, it calls down to {@link #shouldIgnoreInInterface_Int(AliasedSymbol)}.
+     * </p>
+     */
     @Override
-    public boolean shouldIgnoreInInterface(final String symbol) {
-        return shouldIgnoreInInterface(symbol, true);
-    }
-
-    public boolean shouldIgnoreInInterface(final String symbol, final boolean checkEXT) {
-        return shouldIgnoreExtension(symbol, checkEXT) || super.shouldIgnoreInInterface(symbol);
+    public boolean shouldIgnoreInInterface(final AliasedSymbol symbol) {
+        return shouldIgnoreExtension(symbol) || shouldIgnoreInInterface_Int(symbol);
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Implementation extends the exclusion query w/ {@link #shouldIgnoreExtension(AliasedSymbol) the list of ignored extensions}.
+     * </p>
+     * <p>
+     * If passing the former, it calls down to {@link #shouldIgnoreInImpl_Int(AliasedSymbol)}.
+     * </p>
+     */
     @Override
-    public boolean shouldIgnoreInImpl(final String symbol) {
-        return shouldIgnoreInImpl(symbol, true);
-    }
-
-    public boolean shouldIgnoreInImpl(final String symbol, final boolean checkEXT) {
-        return shouldIgnoreExtension(symbol, checkEXT) || super.shouldIgnoreInImpl(symbol);
+    public boolean shouldIgnoreInImpl(final AliasedSymbol symbol) {
+        return shouldIgnoreExtension(symbol) || shouldIgnoreInImpl_Int(symbol);
     }
 
     /** Should we automatically ignore extensions that have already been
@@ -348,27 +394,114 @@ public class GLConfiguration extends ProcAddressConfiguration {
         return bufferObjectOnly.contains(name);
     }
 
-    /** Parses any GL headers specified in the configuration file for
-    the purpose of being able to ignore an extension at a time. */
-    public void parseGLHeaders(final GlueEmitterControls controls) throws IOException {
-        if (!glHeaders.isEmpty()) {
-            glInfo = new BuildStaticGLInfo();
-            glInfo.setDebug(GlueGen.debug());
-            for (final String file : glHeaders) {
+    /**
+     * Parses any GL headers specified in the configuration file for
+     * the purpose of being able to ignore an extension at a time.
+     * <p>
+     * Targeting semantic information, i.e. influences code generation.
+     * </p>
+     */
+    public void parseGLSemHeaders(final GlueEmitterControls controls) throws IOException {
+        glSemInfo = new BuildStaticGLInfo();
+        glSemInfo.setDebug(GlueGen.debug());
+        if (!glSemHeaders.isEmpty()) {
+            for (final String file : glSemHeaders) {
+                final String fullPath = controls.findHeaderFile(file);
+                if (fullPath == null) {
+                    throw new IOException("Unable to locate header file \"" + file + "\"");
+                }
+                glSemInfo.parse(fullPath);
+            }
+        }
+    }
+
+    /**
+     * Returns the information about the association between #defines,
+     * function symbols and the OpenGL extensions they are defined in.
+     * <p>
+     * This instance targets semantic information, i.e. influences code generation.
+     * </p>
+     */
+    public BuildStaticGLInfo getGLSemInfo() {
+        return glSemInfo;
+    }
+
+    /**
+     * Parses any GL headers specified in the configuration file for
+     * the purpose of being able to ignore an extension at a time.
+     * <p>
+     * Targeting API documentation information, i.e. <i>not</i> influencing code generation.
+     * </p>
+     */
+    public void parseGLDocHeaders(final GlueEmitterControls controls) throws IOException {
+        glDocInfo = new BuildStaticGLInfo();
+        glDocInfo.setDebug(GlueGen.debug());
+        if (!glDocHeaders.isEmpty()) {
+            for (final String file : glDocHeaders) {
                 final String fullPath = controls.findHeaderFile(file);
                 if (fullPath == null) {
                     throw new IOException("Unable to locate header file \"" + file + "\"");
                 }
-                glInfo.parse(fullPath);
+                glDocInfo.parse(fullPath);
             }
         }
     }
 
-    /** Returns the information about the association between #defines,
-    function symbols and the OpenGL extensions they are defined
-    in. */
-    public BuildStaticGLInfo getGLInfo() {
-        return glInfo;
+    @Override
+    public Set<String> getAliasedDocNames(final AliasedSymbol symbol) {
+        return getRenamedJavaDocSymbols(symbol.getName());
+    }
+
+    /**
+     * Returns the information about the association between #defines,
+     * function symbols and the OpenGL extensions they are defined in.
+     * <p>
+     * This instance targets API documentation information, i.e. <i>not</i> influencing code generation.
+     * </p>
+     * <p>
+     * GLDocInfo include GLSemInfo!
+     * </p>
+     */
+    public BuildStaticGLInfo getGLDocInfo() {
+        return glDocInfo;
+    }
+
+    /** Returns a set of replaced javadoc names to the given <code>aliasedName</code>. */
+    public Set<String> getRenamedJavaDocSymbols(final String aliasedName) {
+        return javaDocRenamedSymbols.get(aliasedName);
+    }
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Also adds a javadoc rename directive for the given symbol.
+     * </p>
+     */
+    @Override
+    public void addJavaSymbolRename(final String origName, final String newName) {
+        super.addJavaSymbolRename(origName, newName);
+        if( !dropDocInfo ) {
+            addJavaDocSymbolRename(origName, newName);
+        }
+    }
+
+    /**
+     * Adds a javadoc rename directive for the given symbol.
+     */
+    public void addJavaDocSymbolRename(final String origName, final String newName) {
+        LOG.log(INFO, "\tDoc Rename {0} -> {1}", origName, newName);
+        final String prevValue = javaDocSymbolRenames.put(origName, newName);
+        if(null != prevValue && !prevValue.equals(newName)) {
+            throw new RuntimeException("Doc-Rename-Override Attampt: "+origName+" -> "+newName+
+                    ", but "+origName+" -> "+prevValue+" already exist. Run in 'debug' mode to analyze!");
+        }
+
+        Set<String> origNames = javaDocRenamedSymbols.get(newName);
+        if(null == origNames) {
+            origNames = new HashSet<String>();
+            javaDocRenamedSymbols.put(newName, origNames);
+        }
+        origNames.add(origName);
     }
 
     /** Returns the OpenGL extensions that should have all of their
@@ -376,6 +509,6 @@ public class GLConfiguration extends ProcAddressConfiguration {
     namespace; for example, glGenFramebuffersEXT to
     glGenFramebuffers and GL_FRAMEBUFFER_EXT to GL_FRAMEBUFFER. */
     public Set<String> getExtensionsRenamedIntoCore() {
-        return extensionsRenamedIntoCore;
+        return renameExtensionsIntoCore;
     }
 }
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
index bc230c83a..ccac4cf6b 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
@@ -39,9 +39,12 @@
  */
 package com.jogamp.gluegen.opengl;
 
+import static java.util.logging.Level.INFO;
+
 import com.jogamp.gluegen.ConstantDefinition;
 import com.jogamp.gluegen.FunctionEmitter;
 import com.jogamp.gluegen.GlueEmitterControls;
+import com.jogamp.gluegen.GlueGen;
 import com.jogamp.gluegen.JavaConfiguration;
 import com.jogamp.gluegen.JavaEmitter;
 import com.jogamp.gluegen.JavaMethodBindingEmitter;
@@ -49,6 +52,7 @@ import com.jogamp.gluegen.JavaType;
 import com.jogamp.gluegen.MethodBinding;
 import com.jogamp.gluegen.SymbolFilter;
 import com.jogamp.gluegen.cgram.types.FunctionSymbol;
+import com.jogamp.gluegen.cgram.types.Type;
 import com.jogamp.gluegen.procaddress.ProcAddressEmitter;
 import com.jogamp.gluegen.procaddress.ProcAddressJavaMethodBindingEmitter;
 import com.jogamp.gluegen.runtime.opengl.GLNameResolver;
@@ -56,7 +60,6 @@ import com.jogamp.gluegen.runtime.opengl.GLNameResolver;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.IdentityHashMap;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
@@ -78,34 +81,38 @@ public class GLEmitter extends ProcAddressEmitter {
 
     @Override
     public void beginEmission(final GlueEmitterControls controls) throws IOException {
-        getGLConfig().parseGLHeaders(controls);
+        getGLConfig().parseGLSemHeaders(controls);
+        if( null == getGLConfig().getGLSemInfo() ) {
+            throw new RuntimeException("No 'GLSemHeader' defined.");
+        }
+        getGLConfig().parseGLDocHeaders(controls);
+        if( null == getGLConfig().getGLDocInfo() ) {
+            throw new InternalError("XXX"); // since GLDocHeader contains all GLSemHeader ..
+        }
         renameExtensionsIntoCore();
-        if (getGLConfig().getAutoUnifyExtensions()) {
+        if ( getGLConfig().getAutoUnifyExtensions() ) {
             unifyExtensions(controls);
         }
         super.beginEmission(controls);
     }
 
     protected void renameExtensionsIntoCore() {
+        final GLConfiguration config = getGLConfig();
+        renameExtensionsIntoCore(config, config.getGLSemInfo(), true);
+        renameExtensionsIntoCore(config, config.getGLDocInfo(), false);
+    }
+    protected void renameExtensionsIntoCore(final GLConfiguration config, final BuildStaticGLInfo glInfo, final boolean isSemHeader) {
         // This method handles renaming of entire extensions into the
         // OpenGL core namespace. For example, it is used to move certain
         // OpenGL ES (OES) extensions into the core namespace which are
         // already in the core namespace in desktop OpenGL. It builds upon
         // renaming mechanisms that are built elsewhere.
 
-        final GLConfiguration config = getGLConfig();
-        final Set<String> extensionsRenamedIntoCore = config.getExtensionsRenamedIntoCore();
-        final BuildStaticGLInfo glInfo = config.getGLInfo();
-        if (null == glInfo) {
-            if (extensionsRenamedIntoCore.size() > 0) {
-                throw new RuntimeException("ExtensionRenamedIntoCore (num: " + extensionsRenamedIntoCore.size() + "), but no GLHeader");
-            }
-            return;
-        }
-        for (final String extension : extensionsRenamedIntoCore) {
-            if(JavaConfiguration.DEBUG_RENAMES) {
-                System.err.println("<RenameExtensionIntoCore: "+extension+" BEGIN");
-            }
+        final String headerType = isSemHeader ? "GLSemHeader" : "GLDocHeader";
+        final Set<String> extensionSet = isSemHeader ? config.getExtensionsRenamedIntoCore() : glInfo.getExtensions();
+
+        for (final String extension : extensionSet) {
+            LOG.log(INFO, "<RenameExtensionIntoCore: {0} BEGIN {1}", extension, headerType);
             final Set<String> declarations = glInfo.getDeclarations(extension);
             if (declarations != null) {
                 for (final Iterator<String> iterator = declarations.iterator(); iterator.hasNext();) {
@@ -118,14 +125,18 @@ public class GLEmitter extends ProcAddressEmitter {
                     if (isGLFunction || isGLEnumeration) {
                         final String renamed = GLNameResolver.normalize(decl, isGLFunction);
                         if (!renamed.equals(decl)) {
-                            config.addJavaSymbolRename(decl, renamed);
+                            if( isSemHeader ) {
+                                // Sem + Doc
+                                config.addJavaSymbolRename(decl, renamed);
+                            } else {
+                                // Doc only
+                                config.addJavaDocSymbolRename(decl, renamed);
+                            }
                         }
                     }
                 }
             }
-            if(JavaConfiguration.DEBUG_RENAMES) {
-                System.err.println("RenameExtensionIntoCore: "+extension+" END>");
-            }
+            LOG.log(INFO, "RenameExtensionIntoCore: {0} END>", extension, headerType);
         }
     }
 
@@ -135,35 +146,28 @@ public class GLEmitter extends ProcAddressEmitter {
         private List<FunctionSymbol> functions;
 
         @Override
-        public void filterSymbols(final List<ConstantDefinition> constants,
-                final List<FunctionSymbol> functions) {
-            this.constants = constants;
-            this.functions = functions;
-            doWork();
-        }
-
-        @Override
         public List<ConstantDefinition> getConstants() {
             return constants;
         }
-
         @Override
         public List<FunctionSymbol> getFunctions() {
             return functions;
         }
 
-        private void doWork() {
-            final BuildStaticGLInfo glInfo = getGLConfig().getGLInfo();
+        @Override
+        public void filterSymbols(final List<ConstantDefinition> inConstList,
+                                  final List<FunctionSymbol> inFuncList) {
+            final BuildStaticGLInfo glInfo = getGLConfig().getGLSemInfo();
             if (glInfo == null) {
                 return;
             }
             // Try to retain a "good" ordering for these symbols
             final Map<String, ConstantDefinition> constantMap = new LinkedHashMap<String, ConstantDefinition>();
-            for (final ConstantDefinition def : constants) {
+            for (final ConstantDefinition def : inConstList) {
                 constantMap.put(def.getName(), def);
             }
             final Map<String, FunctionSymbol> functionMap = new LinkedHashMap<String, FunctionSymbol>();
-            for (final FunctionSymbol sym : functions) {
+            for (final FunctionSymbol sym : inFuncList) {
                 functionMap.put(sym.getName(), sym);
             }
 
@@ -277,6 +281,10 @@ public class GLEmitter extends ProcAddressEmitter {
 
         // Need to expand each one of the generated bindings to take a
         // Java long instead of a Buffer for each void* argument
+        if( GlueGen.debug() ) {
+            System.err.println("expandMethodBinding: j "+binding.toString());
+            System.err.println("expandMethodBinding: c "+binding.getCSymbol());
+        }
 
         // for (MethodBinding cur : bindings) {
         int j=0;
@@ -294,24 +302,38 @@ public class GLEmitter extends ProcAddressEmitter {
             }
 
             MethodBinding result = cur;
+            int replacedCount = 0;
             for (int i = 0; i < cur.getNumArguments(); i++) {
-                if (cur.getJavaArgumentType(i).isNIOBuffer()) {
+                final JavaType jt = cur.getJavaArgumentType(i);
+                if( jt.isOpaqued() ) {
+                    replacedCount++; // already replaced, i.e. due to opaque
+                } else if ( jt.isNIOBuffer() ) {
                     result = result.replaceJavaArgumentType(i, JavaType.createForClass(Long.TYPE));
+                    replacedCount++;
+                }
+                if( GlueGen.debug() ) {
+                    final Type ct = cur.getCArgumentType(i);
+                    System.err.println("  ["+i+"]: #"+replacedCount+", "+ct.getDebugString()+", "+jt.getDebugString());
                 }
             }
 
-            if (result == cur) {
+            if ( 0 == replacedCount ) {
                 throw new RuntimeException("Error: didn't find any void* arguments for BufferObject function "
-                        + binding.getName());
+                        + binding.toString());
             }
 
-            newBindings.add(result);
             // Now need to flag this MethodBinding so that we generate the
             // correct flags in the emitters later
             bufferObjectMethodBindings.put(result, result);
 
-            if( bufferObjectOnly ) {
-                bindings.remove(j);
+            if( result != cur ) {
+                // replaced
+                newBindings.add(result);
+                if( bufferObjectOnly ) {
+                    bindings.remove(j);
+                } else {
+                    j++;
+                }
             } else {
                 j++;
             }
@@ -323,12 +345,14 @@ public class GLEmitter extends ProcAddressEmitter {
 
     @Override
     protected boolean needsModifiedEmitters(final FunctionSymbol sym) {
-        if ((!needsProcAddressWrapper(sym) && !needsBufferObjectVariant(sym))
-                || getConfig().isUnimplemented(sym.getName())) {
+        if ( ( !callThroughProcAddress(sym) && !needsBufferObjectVariant(sym) ) ||
+             getConfig().isUnimplemented(sym)
+           )
+        {
             return false;
+        } else {
+            return true;
         }
-
-        return true;
     }
 
     public boolean isBufferObjectMethodBinding(final MethodBinding binding) {
@@ -337,14 +361,10 @@ public class GLEmitter extends ProcAddressEmitter {
 
     @Override
     public void emitDefine(final ConstantDefinition def, final String optionalComment) throws Exception {
-        final BuildStaticGLInfo glInfo = getGLConfig().getGLInfo();
-        if (null == glInfo) {
-            throw new Exception("No GLInfo for: " + def);
-        }
         final String symbolRenamed = def.getName();
         final StringBuilder newComment = new StringBuilder();
         newComment.append("Part of ");
-        if (0 == addExtensionsOfSymbols2Buffer(newComment, ", ", "; ", symbolRenamed, def.getAliasedNames())) {
+        if (0 == addExtensionsOfSymbols2Doc(newComment, ", ", ", ", symbolRenamed)) {
             if (def.isEnum()) {
                 final String enumName = def.getEnumName();
                 if (null != enumName) {
@@ -361,16 +381,13 @@ public class GLEmitter extends ProcAddressEmitter {
                     // #define GL_EXT_lala 1
                     // ...
                     // #endif
-                    if (JavaConfiguration.DEBUG_IGNORES) {
-                        final StringBuilder sb = new StringBuilder();
-                        JavaEmitter.addStrings2Buffer(sb, ", ", symbolRenamed, def.getAliasedNames());
-                        System.err.println("Dropping marker: " + sb.toString());
-                    }
+                    final StringBuilder sb = new StringBuilder();
+                    JavaEmitter.addStrings2Buffer(sb, ", ", symbolRenamed, def.getAliasedNames());
+                    LOG.log(INFO, "Dropping marker: {0}", sb.toString());
                     return;
                 }
             }
         }
-
         if (null != optionalComment) {
             newComment.append("<br>");
             newComment.append(optionalComment);
@@ -379,9 +396,9 @@ public class GLEmitter extends ProcAddressEmitter {
         super.emitDefine(def, newComment.toString());
     }
 
-    private int addExtensionListOfSymbol2Buffer(final BuildStaticGLInfo glInfo, final StringBuilder buf, final String sep1, final String name) {
+    private int addExtensionListOfSymbol2Doc(final BuildStaticGLInfo glDocInfo, final StringBuilder buf, final String sep1, final String name) {
         int num = 0;
-        final Set<String> extensionNames = glInfo.getExtension(name);
+        final Set<String> extensionNames = glDocInfo.getExtension(name);
         if(null!=extensionNames) {
             for(final Iterator<String> i=extensionNames.iterator(); i.hasNext(); ) {
                 final String extensionName = i.next();
@@ -398,49 +415,35 @@ public class GLEmitter extends ProcAddressEmitter {
         }
         return num;
     }
-    private int addExtensionListOfAliasedSymbols2Buffer(final BuildStaticGLInfo glInfo, final StringBuilder buf, final String sep1, final String sep2, final String name, final Collection<String> exclude) {
+    private int addExtensionListOfAliasedSymbols2Doc(final BuildStaticGLInfo glDocInfo, final StringBuilder buf, final String sep1, final String sep2, final String name) {
         int num = 0;
         if(null != name) {
-            num += addExtensionListOfSymbol2Buffer(glInfo, buf, sep1, name); // extensions of given name
-            boolean needsSep2 = 0<num;
-            final Set<String> origNames = cfg.getRenamedJavaSymbols(name);
-            if(null != origNames) {
-                for(final String origName : origNames) {
-                    if(!exclude.contains(origName)) {
-                        if (needsSep2) {
-                            buf.append(sep2); // diff-name seperator
-                        }
-                        final int num2 = addExtensionListOfSymbol2Buffer(glInfo, buf, sep1, origName); // extensions of orig-name
-                        needsSep2 = num<num2;
-                        num += num2;
+            num += addExtensionListOfSymbol2Doc(glDocInfo, buf, sep1, name); // extensions of given name
+            boolean needsSep2 = num > 0;
+            final Set<String> aliases = ((GLConfiguration)cfg).getRenamedJavaDocSymbols(name);
+            if(null != aliases) {
+                for(final String alias : aliases) {
+                    if (needsSep2) {
+                        buf.append(sep2);
                     }
+                    final int num2 = addExtensionListOfSymbol2Doc(glDocInfo, buf, sep1, alias); // extensions of orig-name
+                    needsSep2 = num2 > 0;
+                    num += num2;
                 }
             }
         }
         return num;
     }
 
-    public int addExtensionsOfSymbols2Buffer(StringBuilder buf, final String sep1, final String sep2, final String first, final Collection<String> col) {
-        final BuildStaticGLInfo glInfo = getGLConfig().getGLInfo();
-        if (null == glInfo) {
-            throw new RuntimeException("No GLInfo for: " + first);
+    public int addExtensionsOfSymbols2Doc(StringBuilder buf, final String sep1, final String sep2, final String first) {
+        final BuildStaticGLInfo glDocInfo = getGLConfig().getGLDocInfo();
+        if (null == glDocInfo) {
+            throw new RuntimeException("No GLDocInfo for: " + first);
         }
-        int num = 0;
         if (null == buf) {
             buf = new StringBuilder();
         }
-
-        num += addExtensionListOfAliasedSymbols2Buffer(glInfo, buf, sep1, sep2, first, col);
-        boolean needsSep2 = 0<num;
-        for(final Iterator<String> iter = col.iterator(); iter.hasNext(); ) {
-            if(needsSep2) {
-                buf.append(sep2); // diff-name seperator
-            }
-            final int num2 = addExtensionListOfAliasedSymbols2Buffer(glInfo, buf, sep1, sep2, iter.next(), col);
-            needsSep2 = num<num2;
-            num += num2;
-        }
-        return num;
+        return addExtensionListOfAliasedSymbols2Doc(glDocInfo, buf, sep1, sep2, first);
     }
 
     //----------------------------------------------------------------------
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
index d491a3712..afd9163ee 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
@@ -103,7 +103,6 @@ public class GLJavaMethodBindingEmitter extends ProcAddressJavaMethodBindingEmit
 
         @Override
         protected void emitBindingCSignature(final MethodBinding binding, final PrintWriter writer) {
-
             final String symbolRenamed = binding.getName();
             final StringBuilder newComment = new StringBuilder();
 
@@ -113,18 +112,25 @@ public class GLJavaMethodBindingEmitter extends ProcAddressJavaMethodBindingEmit
             writer.print(" </code> ");
 
             newComment.append("<br>Part of ");
-            if (0 == glEmitter.addExtensionsOfSymbols2Buffer(newComment, ", ", "; ", symbolRenamed, binding.getAliasedNames())) {
+            if (0 == glEmitter.addExtensionsOfSymbols2Doc(newComment, ", ", ", ", symbolRenamed)) {
                 if (glEmitter.getGLConfig().getAllowNonGLExtensions()) {
                     newComment.append("CORE FUNC");
                 } else {
-                    final StringBuilder sb = new StringBuilder();
-                    JavaEmitter.addStrings2Buffer(sb, ", ", symbolRenamed, binding.getAliasedNames());
-                    final RuntimeException ex = new RuntimeException("Couldn't find extension to: " + binding + " ; " + sb.toString());
-                    glEmitter.getGLConfig().getGLInfo().dump();
-                    // glEmitter.getGLConfig().dumpRenames();
-                    throw ex;
+                    if( !((GLConfiguration)cfg).dropDocInfo ) {
+                        final StringBuilder sb = new StringBuilder();
+                        JavaEmitter.addStrings2Buffer(sb, ", ", symbolRenamed, binding.getAliasedNames());
+                        final RuntimeException ex = new RuntimeException("Couldn't find extension to: " + binding + " ; " + sb.toString());
+                        System.err.println(ex.getMessage());
+                        glEmitter.getGLConfig().getGLDocInfo().dump();
+                        // glEmitter.getGLConfig().dumpRenames();
+                        throw ex;
+                    } else {
+                        newComment.append("UNDEFINED");
+                    }
                 }
             }
+            newComment.append("<br>");
+            emitAliasedDocNamesComment(funcSym, newComment);
             writer.print(newComment.toString());
         }
     }