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'.

11 files changed, 238 insertions, 2 deletions

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);
+    }
+}