Only use base pipelines for Trace/Debug, mock others (ES2, GL2, ..); BuildComposablePipeline: Unify GL identify methods

- Only use base pipelines for Trace/Debug, mock others (ES2, GL2, ..)
  The Trace/Debug generated pipelines consume quite some space
  and only the actual GL*Impl pipeline is actually required.

  To make this work, we have to identify the GL type via it's downstream instance
  to implement isGL*() and getGL*() methods, see below!

  Adding dummy Trace/Debug type wrapper for GL2, GL3, GL3bc, GL4 and GLES2.

BuildComposablePipeline: Unify GL identify methods
  As described above, Trace/Debug shall utilize downstream identification for isGL*() and getGL*() methods.

  Custom types, like FixedFuncImpl may choose to be identified by their class inheritance,
  by passing command-line argument 'gl_identity_by_assignable_class'.

12 files changed, 320 insertions, 36 deletions

diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildComposablePipeline.java b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildComposablePipeline.java
index 0bd3086c8..7659238fc 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildComposablePipeline.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildComposablePipeline.java
@@ -57,10 +57,31 @@ import java.util.Set;
 
 public class BuildComposablePipeline {
 
-    public static final int GEN_DEBUG = 1 << 0; // default
-    public static final int GEN_TRACE = 1 << 1; // default
+    /** <p>Default: true</p>. */
+    public static final int GEN_DEBUG = 1 << 0;
+    /** <p>Default: true</p>. */
+    public static final int GEN_TRACE = 1 << 1;
+    /** <p>Default: false</p>. */
     public static final int GEN_CUSTOM = 1 << 2;
+    /**
+     * By extra command-line argument: <code>prolog_xor_downstream</code>.
+     * <p>
+     * If true, either prolog (if exist) is called or downstream's method, but not both.
+     * By default, both methods would be called. 
+     * </p>
+     * <p>Default: false</p>
+     */
     public static final int GEN_PROLOG_XOR_DOWNSTREAM = 1 << 3;
+    /**
+     * By extra command-line argument: <code>gl_identity_by_assignable_class</code>.
+     * <p>
+     * If true, implementation does not utilize downstream's <code>isGL*()</code>
+     * implementation, but determines whether the GL profile is matched by interface inheritance.
+     * </p>
+     * <p>Default: false</p>
+     */
+    public static final int GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS = 1 << 4;
+    
     int mode;
     private String outputDir;
     private String outputPackage;
@@ -110,8 +131,12 @@ public class BuildComposablePipeline {
             classDownstream = getClass(args[4]);
             mode = GEN_CUSTOM;
             if (args.length > 5) {
-                if (args[5].equals("prolog_xor_downstream")) {
-                    mode |= GEN_PROLOG_XOR_DOWNSTREAM;
+                for(int i=5; i<args.length; i++) {
+                    if (args[i].equals("prolog_xor_downstream")) {
+                        mode |= GEN_PROLOG_XOR_DOWNSTREAM;
+                    } else if (args[i].equals("gl_identity_by_assignable_class")) {
+                        mode |= GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS;
+                    }
                 }
             }
         } else {
@@ -119,7 +144,7 @@ public class BuildComposablePipeline {
             outputName = null; // TBD ..
             classPrologOpt = null;
             classDownstream = classToComposeAround;
-            mode = GEN_DEBUG | GEN_TRACE;
+            mode = GEN_DEBUG | GEN_TRACE ;
         }
 
         BuildComposablePipeline composer =
@@ -604,11 +629,15 @@ public class BuildComposablePipeline {
         protected void emitGLIsMethod(PrintWriter output, String type) {
             output.println("  @Override");
             output.println("  public final boolean is" + type + "() {");
-            final Class<?> clazz = BuildComposablePipeline.getClass("javax.media.opengl." + type);
-            if (clazz.isAssignableFrom(baseInterfaceClass)) {
-                output.println("    return true;");
+            if( 0 != (GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS & getMode() ) ) {
+                final Class<?> clazz = BuildComposablePipeline.getClass("javax.media.opengl." + type);
+                if (clazz.isAssignableFrom(baseInterfaceClass)) {
+                    output.println("    return true;");
+                } else {
+                    output.println("    return false;");
+                }
             } else {
-                output.println("    return false;");
+                output.println("    return " + getDownstreamObjectName() + ".is" + type + "();");
             }
             output.println("  }");
         }
@@ -631,10 +660,14 @@ public class BuildComposablePipeline {
             emitGLIsMethod(output, "GL3ES3");
             emitGLIsMethod(output, "GL4ES3");
             emitGLIsMethod(output, "GL2GL3");
-            output.println("  @Override");
-            output.println("  public final boolean isGLES() {");
-            output.println("    return isGLES2() || isGLES1();");
-            output.println("  }");
+            if( 0 != (GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS & getMode() ) ) {
+                output.println("  @Override");
+                output.println("  public final boolean isGLES() {");
+                output.println("    return isGLES2() || isGLES1();");
+                output.println("  }");
+            } else {
+                emitGLIsMethod(output, "GLES");
+            }
             output.println("  @Override");
             output.println("  public final boolean isGLES2Compatible() {");
             output.println("    return " + getDownstreamObjectName() + ".isGLES2Compatible();");
@@ -651,11 +684,15 @@ public class BuildComposablePipeline {
         protected void emitGLGetMethod(PrintWriter output, String type) {
             output.println("  @Override");
             output.println("  public final javax.media.opengl." + type + " get" + type + "() {");
-            final Class<?> clazz = BuildComposablePipeline.getClass("javax.media.opengl." + type);
-            if (clazz.isAssignableFrom(baseInterfaceClass)) {
-                output.println("    return this;");
+            if( 0 != (GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS & getMode() ) ) {
+                final Class<?> clazz = BuildComposablePipeline.getClass("javax.media.opengl." + type);
+                if (clazz.isAssignableFrom(baseInterfaceClass)) {
+                    output.println("    return this;");
+                } else {
+                    output.println("    throw new GLException(\"Not a " + type + " implementation\");");
+                }
             } else {
-                output.println("    throw new GLException(\"Not a " + type + " implementation\");");
+                output.println("    return " + getDownstreamObjectName() + ".get" + type + "();");
             }
             output.println("  }");
         }
@@ -921,15 +958,20 @@ public class BuildComposablePipeline {
         }
 
         protected void emitClassDocComment(PrintWriter output) {
-            output.println("/** <P> Composable pipeline which wraps an underlying {@link GL} implementation,");
-            output.println("    providing error checking after each OpenGL method call. If an error occurs,");
-            output.println("    causes a {@link GLException} to be thrown at exactly the point of failure.");
-            output.println("    Sample code which installs this pipeline: </P>");
-            output.println();
-            output.println("<PRE>");
-            output.println("     GL gl = drawable.setGL(new DebugGL(drawable.getGL()));");
-            output.println("</PRE>");
-            output.println("*/");
+            output.println("/**");
+            output.println(" * <p>");
+            output.println(" * Composable pipeline which wraps an underlying {@link GL} implementation,");
+            output.println(" * providing error checking after each OpenGL method call. If an error occurs,");
+            output.println(" * causes a {@link GLException} to be thrown at exactly the point of failure.");
+            output.println(" * </p>");
+            output.println(" * <p>");
+            output.println(" * Sample code which installs this pipeline:");
+            output.println(" * <pre>");
+            output.println(" *   gl = drawable.setGL(new DebugGL(drawable.getGL()));");
+            output.println(" * </pre>");
+            output.println(" * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}");
+            output.println(" * </p>");
+            output.println(" */");
         }
 
         protected boolean hasPreDownstreamCallHook(Method m) {
@@ -1057,14 +1099,20 @@ public class BuildComposablePipeline {
         }
 
         protected void emitClassDocComment(PrintWriter output) {
-            output.println("/** <P> Composable pipeline which wraps an underlying {@link GL} implementation,");
-            output.println("    providing tracing information to a user-specified {@link java.io.PrintStream}");
-            output.println("    before and after each OpenGL method call. Sample code which installs this pipeline: </P>");
-            output.println();
-            output.println("<PRE>");
-            output.println("     GL gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));");
-            output.println("</PRE>");
-            output.println("*/");
+            output.println("/**");
+            output.println(" * <p>");
+            output.println(" * Composable pipeline which wraps an underlying {@link GL} implementation,");
+            output.println(" * providing tracing information to a user-specified {@link java.io.PrintStream}");
+            output.println(" * before and after each OpenGL method call.");
+            output.println(" * </p>");
+            output.println(" * <p>");
+            output.println(" * Sample code which installs this pipeline:");
+            output.println(" * <pre>");
+            output.println(" *   gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));");
+            output.println(" * </pre>");
+            output.println(" * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}");
+            output.println(" * </p>");
+            output.println(" */");
         }
 
         protected boolean hasPreDownstreamCallHook(Method m) {
diff --git a/src/jogl/classes/javax/media/opengl/DebugGL2.java b/src/jogl/classes/javax/media/opengl/DebugGL2.java
new file mode 100644
index 000000000..05bcf3d5e
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/DebugGL2.java
@@ -0,0 +1,21 @@
+package javax.media.opengl;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing error checking after each OpenGL method call. If an error occurs,
+ * causes a {@link GLException} to be thrown at exactly the point of failure.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new DebugGL(drawable.getGL()));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class DebugGL2 extends DebugGL4bc {
+    public DebugGL2(GL2 downstream) {
+        super((GL4bc)downstream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/DebugGL3.java b/src/jogl/classes/javax/media/opengl/DebugGL3.java
new file mode 100644
index 000000000..c17f90667
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/DebugGL3.java
@@ -0,0 +1,21 @@
+package javax.media.opengl;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing error checking after each OpenGL method call. If an error occurs,
+ * causes a {@link GLException} to be thrown at exactly the point of failure.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new DebugGL(drawable.getGL()));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class DebugGL3 extends DebugGL4bc {
+    public DebugGL3(GL3 downstream) {
+        super((GL4bc)downstream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/DebugGL3bc.java b/src/jogl/classes/javax/media/opengl/DebugGL3bc.java
new file mode 100644
index 000000000..6e294d42b
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/DebugGL3bc.java
@@ -0,0 +1,21 @@
+package javax.media.opengl;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing error checking after each OpenGL method call. If an error occurs,
+ * causes a {@link GLException} to be thrown at exactly the point of failure.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new DebugGL(drawable.getGL()));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class DebugGL3bc extends DebugGL4bc {
+    public DebugGL3bc(GL3bc downstream) {
+        super((GL4bc)downstream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/DebugGL4.java b/src/jogl/classes/javax/media/opengl/DebugGL4.java
new file mode 100644
index 000000000..d21d39390
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/DebugGL4.java
@@ -0,0 +1,21 @@
+package javax.media.opengl;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing error checking after each OpenGL method call. If an error occurs,
+ * causes a {@link GLException} to be thrown at exactly the point of failure.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new DebugGL(drawable.getGL()));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class DebugGL4 extends DebugGL4bc {
+    public DebugGL4(GL4 downstream) {
+        super((GL4bc)downstream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/DebugGLES2.java b/src/jogl/classes/javax/media/opengl/DebugGLES2.java
new file mode 100644
index 000000000..dee363c1b
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/DebugGLES2.java
@@ -0,0 +1,21 @@
+package javax.media.opengl;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing error checking after each OpenGL method call. If an error occurs,
+ * causes a {@link GLException} to be thrown at exactly the point of failure.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new DebugGL(drawable.getGL()));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class DebugGLES2 extends DebugGLES3 {
+    public DebugGLES2(GLES2 downstream) {
+        super((GLES3)downstream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/GLPipelineFactory.java b/src/jogl/classes/javax/media/opengl/GLPipelineFactory.java
index 2bfc77d4a..c6bf26235 100644
--- a/src/jogl/classes/javax/media/opengl/GLPipelineFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLPipelineFactory.java
@@ -51,8 +51,23 @@ public class GLPipelineFactory {
 
     /** 
      * Creates a pipelined GL instance using the given downstream <code>downstream</code>
-     * and optional arguments <code>additionalArgs</code> for the constructor.<br>
+     * and optional arguments <code>additionalArgs</code> for the constructor.
      *
+     * <p>
+     * Sample code which installs a Debug and Trace pipeline
+     * automatic w/ user defined interface, here: GL2ES2:
+     * <pre>
+     *     gl = drawable.setGL( GLPipelineFactory.create("javax.media.opengl.Debug", GL2ES2.class, gl, null) );
+     *     gl = drawable.setGL( GLPipelineFactory.create("javax.media.opengl.Trace", GL2ES2.class, gl, new Object[] { System.err } ) );
+     * </pre>
+     * or automatic w/ automatic defined class:
+     * <pre>
+     *     gl = drawable.setGL( GLPipelineFactory.create("javax.media.opengl.Debug",         null, gl, null) );
+     *     gl = drawable.setGL( GLPipelineFactory.create("javax.media.opengl.Trace",         null, gl, new Object[] { System.err } ) );
+     * </pre>
+     * </p>
+     * 
+     * <p>
      * The upstream GL instance is determined as follows:
      * <ul>
      *   <li> Use <code>pipelineClazzBaseName</code> as the class name's full basename, incl. package name</li>
@@ -65,7 +80,8 @@ public class GLPipelineFactory {
      *        <li> If upstream class is available use it, end loop.</li>
      *      </ul>
      *   </ul>
-     * </ul><br>
+     * </ul>
+     * </p>
      *
      * @param pipelineClazzBaseName the basename of the pipline class name
      * @param reqInterface optional requested interface to be used, may be null, in which case the first matching one is used
diff --git a/src/jogl/classes/javax/media/opengl/TraceGL2.java b/src/jogl/classes/javax/media/opengl/TraceGL2.java
new file mode 100644
index 000000000..58f5d9f99
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/TraceGL2.java
@@ -0,0 +1,23 @@
+package javax.media.opengl;
+
+import java.io.PrintStream;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing tracing information to a user-specified {@link java.io.PrintStream}
+ * before and after each OpenGL method call.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class TraceGL2 extends TraceGL4bc {
+    public TraceGL2(GL2 downstream, PrintStream stream) {
+        super((GL4bc)downstream, stream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/TraceGL3.java b/src/jogl/classes/javax/media/opengl/TraceGL3.java
new file mode 100644
index 000000000..616b31f61
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/TraceGL3.java
@@ -0,0 +1,23 @@
+package javax.media.opengl;
+
+import java.io.PrintStream;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing tracing information to a user-specified {@link java.io.PrintStream}
+ * before and after each OpenGL method call.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class TraceGL3 extends TraceGL4bc {
+    public TraceGL3(GL3 downstream, PrintStream stream) {
+        super((GL4bc)downstream, stream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/TraceGL3bc.java b/src/jogl/classes/javax/media/opengl/TraceGL3bc.java
new file mode 100644
index 000000000..f3761d4d6
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/TraceGL3bc.java
@@ -0,0 +1,23 @@
+package javax.media.opengl;
+
+import java.io.PrintStream;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing tracing information to a user-specified {@link java.io.PrintStream}
+ * before and after each OpenGL method call.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class TraceGL3bc extends TraceGL4bc {
+    public TraceGL3bc(GL3bc downstream, PrintStream stream) {
+        super((GL4bc)downstream, stream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/TraceGL4.java b/src/jogl/classes/javax/media/opengl/TraceGL4.java
new file mode 100644
index 000000000..a12bf0f47
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/TraceGL4.java
@@ -0,0 +1,23 @@
+package javax.media.opengl;
+
+import java.io.PrintStream;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing tracing information to a user-specified {@link java.io.PrintStream}
+ * before and after each OpenGL method call.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class TraceGL4 extends TraceGL4bc {
+    public TraceGL4(GL4 downstream, PrintStream stream) {
+        super((GL4bc)downstream, stream);
+    }
+}
diff --git a/src/jogl/classes/javax/media/opengl/TraceGLES2.java b/src/jogl/classes/javax/media/opengl/TraceGLES2.java
new file mode 100644
index 000000000..38d60e3ac
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/TraceGLES2.java
@@ -0,0 +1,23 @@
+package javax.media.opengl;
+
+import java.io.PrintStream;
+
+/**
+ * <p>
+ * Composable pipeline which wraps an underlying {@link GL} implementation,
+ * providing tracing information to a user-specified {@link java.io.PrintStream}
+ * before and after each OpenGL method call.
+ * </p>
+ * <p>
+ * Sample code which installs this pipeline, manual:
+ * <pre>
+ *     gl = drawable.setGL(new TraceGL(drawable.getGL(), System.err));
+ * </pre> 
+ * For automatic instantiation see {@link GLPipelineFactory#create(String, Class, GL, Object[])}.
+ * </p>
+ */
+public class TraceGLES2 extends TraceGLES3 {
+    public TraceGLES2(GLES2 downstream, PrintStream stream) {
+        super((GLES3)downstream, stream);
+    }
+}