Bug 1037 - FBObject/GLFBODrawable: Do not assume using a TextureAttachment for a Colorbuffer, also make DEPTH optional.

API Change

+++

In certain cases a TextureAttachment for the FBO's color buffer
is not desired, either for performance reasons where texture functionality
is not required or to avoid texture restrictions like size, etc.

+++

GLFBODrawable shall use TextureAttachment for the FBO's color buffer
and a DEPTH buffer per default.
However, the user shall be allowed to use a plain ColorAttachment (renderbuffer)
and also no DEPTH buffer.

+++

FBObject Details:
 - Colorbuffer interface exposes Attachment details
   like format, size, etc as well as it's implementation
   specifics, isTextureAttachment() and getTextureAttachment() allowing a clean cast and type query.

 - Allow ColorAttachment to be used for non MSAA

 - Make TextureAttachment optional for method 'use(GL, TextureAttachment)'

 - Only validate size against MAX_TEXTURESIZE if using a TextureAttachment

 - API Change:
   - rename: getColorAttachmentCount() -> getColorbufferCount()
   - add: getTextureAttachmentCount()
   - change 'TextureAttachment getSamplingSink()' -> 'Colorbuffer getSamplingSink()'

2 files changed, 42 insertions, 11 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
index a34fca0fa..f423e0ee4 100644
--- a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
@@ -31,6 +31,8 @@ package javax.media.opengl;
 import javax.media.nativewindow.NativeWindowException;
 
 import com.jogamp.opengl.FBObject;
+import com.jogamp.opengl.FBObject.Colorbuffer;
+import com.jogamp.opengl.FBObject.ColorAttachment;
 import com.jogamp.opengl.FBObject.TextureAttachment;
 
 /**
@@ -62,12 +64,12 @@ import com.jogamp.opengl.FBObject.TextureAttachment;
  * </p>
  * <p>
  * It would be possible to implement double buffering simply using
- * {@link TextureAttachment}s with one {@link FBObject framebuffer}.
+ * {@link Colorbuffer}s with one {@link FBObject framebuffer}.
  * This would require mode selection and hence complicate the API. Besides, it would
  * not support differentiation of read and write framebuffer and hence not be spec compliant.
  * </p>
  * <p>
- * Actual swapping of the {@link TextureAttachment texture}s and/or {@link FBObject framebuffer}
+ * Actual swapping of the {@link Colorbuffer}s and/or {@link FBObject framebuffer}
  * is performed either in the {@link jogamp.opengl.GLContextImpl#contextMadeCurrent(boolean) context current hook}
  * or when {@link jogamp.opengl.GLDrawableImpl#swapBuffersImpl(boolean) swapping buffers}, whatever comes first.
  * </p>
@@ -75,19 +77,43 @@ import com.jogamp.opengl.FBObject.TextureAttachment;
 public interface GLFBODrawable extends GLDrawable {
     // public enum DoubleBufferMode { NONE, TEXTURE, FBO }; // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
 
+    /** FBO Mode Bit: Use a {@link TextureAttachment} for the {@link #getColorbuffer(int) render colorbuffer} ({@link #FBOMODE_DEFAULT default}), see {@link #setFBOMode(int)}. */
+    public static final int FBOMODE_USE_TEXTURE = 1 << 0;
+    /** FBO Mode Bit: Use a depth renderbuffer ({@link #FBOMODE_DEFAULT default}), see {@link #setFBOMode(int)}. */
+    public static final int FBOMODE_USE_DEPTH   = 1 << 1;
+
+    /** FBO Default Mode Bit: {@link #FBOMODE_USE_TEXTURE} | {@link #FBOMODE_USE_DEPTH}. */
+    public static final int FBOMODE_DEFAULT   = FBOMODE_USE_TEXTURE | FBOMODE_USE_DEPTH;
+
     /**
      * @return <code>true</code> if initialized, i.e. a {@link GLContext} is bound and made current once, otherwise <code>false</code>.
      */
     public boolean isInitialized();
 
     /**
+     * Set the FBO mode bits used for FBO creation.
+     * <p>
+     * See {@link #FBOMODE_DEFAULT} values.
+     * </p>
+     *
+     * @param modeBits custom FBO mode bits like {@link #FBOMODE_USE_TEXTURE} and {@link #FBOMODE_USE_DEPTH}.
+     * @throws IllegalStateException if the underlying FBO is already {@link #isInitialized()}.
+     */
+    void setFBOMode(final int modeBits) throws IllegalStateException;
+
+    /**
+     * @return the used FBO mode bits, mutable via {@link #setFBOMode(int)}
+     */
+    int getFBOMode();
+
+    /**
      * Notify this instance about upstream size change
      * to reconfigure the {@link FBObject}.
      * @param gl GL context object bound to this drawable, will be made current during operation.
      *           A prev. current context will be make current after operation.
      * @throws GLException if resize operation failed
      */
-    void resetSize(GL gl) throws GLException;
+    void resetSize(final GL gl) throws GLException;
 
     /**
      * @return the used texture unit
@@ -98,7 +124,7 @@ public interface GLFBODrawable extends GLDrawable {
      *
      * @param unit the texture unit to be used
      */
-    void setTextureUnit(int unit);
+    void setTextureUnit(final int unit);
 
     /**
      * Set the number of sample buffers if using MSAA
@@ -108,7 +134,7 @@ public interface GLFBODrawable extends GLDrawable {
      * @param newSamples new sample size
      * @throws GLException if resetting the FBO failed
      */
-    void setNumSamples(GL gl, int newSamples) throws GLException;
+    void setNumSamples(final GL gl, final int newSamples) throws GLException;
 
     /**
      * @return the number of sample buffers if using MSAA, otherwise 0
@@ -126,7 +152,7 @@ public interface GLFBODrawable extends GLDrawable {
      * @return the new number of buffers (FBO) used, maybe different than the requested <code>bufferCount</code> (see above)
      * @throws GLException if already initialized, see {@link #isInitialized()}.
      */
-    int setNumBuffers(int bufferCount) throws GLException;
+    int setNumBuffers(final int bufferCount) throws GLException;
 
     /**
      * @return the number of buffers (FBO) being used. 1 if not using {@link GLCapabilities#getDoubleBuffered() double buffering},
@@ -162,19 +188,24 @@ public interface GLFBODrawable extends GLDrawable {
      * @return the named {@link FBObject}
      * @throws IllegalArgumentException if an illegal buffer name is being used
      */
-    FBObject getFBObject(int bufferName) throws IllegalArgumentException;
+    FBObject getFBObject(final int bufferName) throws IllegalArgumentException;
 
     /**
-     * Returns the named texture buffer.
+     * Returns the named {@link Colorbuffer} instance.
      * <p>
      * If MSAA is being used, only the {@link GL#GL_FRONT} buffer is accessible
      * and an exception is being thrown if {@link GL#GL_BACK} is being requested.
      * </p>
+     * <p>
+     * Depending on the {@link #setFBOMode(int) fbo mode} the resulting {@link Colorbuffer}
+     * is either a {@link TextureAttachment} ({@link #FBOMODE_DEFAULT default}) or a {@link ColorAttachment},
+     * see {@link Colorbuffer#isTextureAttachment()}.
+     * </p>
      * @param bufferName {@link GL#GL_FRONT} and {@link GL#GL_BACK} are valid buffer names
-     * @return the named {@link TextureAttachment}
+     * @return the named {@link Colorbuffer}
      * @throws IllegalArgumentException if using MSAA and {@link GL#GL_BACK} is requested or an illegal buffer name is being used
      */
-    FBObject.TextureAttachment getTextureBuffer(int bufferName) throws IllegalArgumentException;
+    Colorbuffer getColorbuffer(final int bufferName) throws IllegalArgumentException;
 
     /** Resizeable {@link GLFBODrawable} specialization */
     public interface Resizeable extends GLFBODrawable {
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index f0ba08c3e..40fc1001f 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -1812,7 +1812,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
 
             // perform vert-flipping via OpenGL/FBO
             final GLFBODrawable fboDrawable = (GLFBODrawable)offscreenDrawable;
-            final FBObject.TextureAttachment fboTex = fboDrawable.getTextureBuffer(GL.GL_FRONT);
+            final FBObject.TextureAttachment fboTex = fboDrawable.getColorbuffer(GL.GL_FRONT).getTextureAttachment();
 
             fboFlipped.bind(gl);