FBObject: Clarify reset(..), resetSamplingSink(..) ; Rename syncFramebuffer(..) -> syncSamplingSink(..)

- reset(..) adds a new argument, boolean resetSamplingSink, allowing to trigger a reset
on the samplink sink as well. Use cases are documented.

- made public: resetSamplingSink()

- Rename syncFramebuffer(..) -> syncSamplingSink(..) to clarify semantics

4 files changed, 74 insertions, 46 deletions

diff --git a/make/scripts/tests.sh b/make/scripts/tests.sh
index 3dc983072..4fc1211db 100755
--- a/make/scripts/tests.sh
+++ b/make/scripts/tests.sh
@@ -276,9 +276,9 @@ function testawtswt() {
 
 #testnoawt com.jogamp.opengl.test.junit.newt.TestDisplayLifecycle02NEWT
 #testnoawt com.jogamp.opengl.test.junit.newt.TestWindows01NEWT $*
-testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestInitConcurrent01NEWT $*
-testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestInitConcurrent02NEWT $*
-#testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestFBOMix2DemosES2NEWT $*
+#testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestInitConcurrent01NEWT $*
+#testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestInitConcurrent02NEWT $*
+testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestFBOMix2DemosES2NEWT $*
 #testawt com.jogamp.opengl.test.junit.newt.parenting.TestParenting04AWT $*
 #testnoawt com.jogamp.opengl.test.junit.newt.TestRemoteGLWindows01NEWT $*
 #testswt com.jogamp.opengl.test.junit.jogl.swt.TestSWTEclipseGLCanvas01GLn $*
diff --git a/src/jogl/classes/com/jogamp/opengl/FBObject.java b/src/jogl/classes/com/jogamp/opengl/FBObject.java
index 59d1c9fa6..b32c8cdcc 100644
--- a/src/jogl/classes/com/jogamp/opengl/FBObject.java
+++ b/src/jogl/classes/com/jogamp/opengl/FBObject.java
@@ -47,7 +47,7 @@ import com.jogamp.opengl.FBObject.Attachment.Type;
  * Core utility class simplifying usage of framebuffer objects (FBO)
  * with all {@link GLProfile}s. 
  * <p>
- * Supports on-the-fly reconfiguration of dimension and multisample buffers via {@link #reset(GL, int, int, int)}
+ * Supports on-the-fly reconfiguration of dimension and multisample buffers via {@link #reset(GL, int, int, int, boolean)}
  * while preserving the {@link Attachment} references.
  * </p>
  * <p>
@@ -866,7 +866,7 @@ public class FBObject {
             throw new GLException("size "+width+"x"+height+" exceeds on of the maxima [texture "+maxTextureSize+", renderbuffer "+maxRenderbufferSize+"]");
         }
 
-        resetMSAATexture2DSink(gl);
+        resetSamplingSink(gl);
         
         // generate fbo ..
         gl.glGenFramebuffers(1, val, 0);
@@ -911,7 +911,7 @@ public class FBObject {
      * @throws GLException in case of an error
      */
     public final void reset(GL gl, int newWidth, int newHeight) {
-        reset(gl, newWidth, newHeight, 0);
+        reset(gl, newWidth, newHeight, 0, false);
     }
     
     /**
@@ -932,9 +932,14 @@ public class FBObject {
      * @param newWidth the new width, it's minimum is capped to 1
      * @param newHeight the new height, it's minimum is capped to 1
      * @param newSamples if > 0, MSAA will be used, otherwise no multisampling. Will be capped to {@link #getMaxSamples()}.
+     * @param resetSamplingSink <code>true</code> calls {@link #resetSamplingSink(GL)} immediatly. 
+     *                          <code>false</code> postpones resetting the sampling sink until {@link #use(GL, TextureAttachment)} or {@link #syncSamplingSink(GL)},
+     *                          allowing to use the samples sink's FBO and texture until then. The latter is useful to benefit 
+     *                          from implicit double buffering while resetting the sink just before it's being used, eg. at swap-buffer. 
+     *                          
      * @throws GLException in case of an error, i.e. size too big, etc ..
      */
-    public final void reset(GL gl, int newWidth, int newHeight, int newSamples) {
+    public final void reset(GL gl, int newWidth, int newHeight, int newSamples, boolean resetSamplingSink) {
         if(!initialized) {
             init(gl, newWidth, newHeight, newSamples);
             return;
@@ -959,16 +964,11 @@ public class FBObject {
             width = newWidth;
             height = newHeight;
             samples = newSamples;
-            detachAllImpl(gl, true , true);
+            detachAllImpl(gl, true , true);            
+            if(resetSamplingSink) {
+                resetSamplingSink(gl);
+            }
             
-            /** 
-             * Postpone reset of samplesSink until syncFramebuffer,
-             * issued at use(..) method (swapBuffer usually initiates it).
-             * This allows another thread to still use the 'samplesSinkTexture'
-             * until swapBuffer happens and does not invalidate the GL_FRONT
-             * FBO (framebuffer & texture). 
-               resetMSAATexture2DSink(gl);
-            */ 
             samplesSinkDirty = true;
 
             if(!wasBound) {
@@ -1925,7 +1925,20 @@ public class FBObject {
         return depthMismatch || stencilMismatch;                
     }
         
-    private final void resetMSAATexture2DSink(GL gl) throws GLException {
+    /**
+     * Manually reset the MSAA sampling sink, if used.
+     * <p>
+     * Automatically called by {@link #reset(GL, int, int, int, boolean)} 
+     * and {@link #syncSamplingSink(GL)}.
+     * </p>
+     * <p>
+     * It is recommended to call this method after initializing the FBO and attaching renderbuffer etc for the 1st time
+     * if access to sampling sink resources is required.
+     * </p>
+     * @param gl the current GL context
+     * @throws GLException in case of an error, i.e. size too big, etc ..
+     */
+    public final void resetSamplingSink(GL gl) throws GLException {
         if(null == samplesSink ) {
             return; // this is the sample sink!
         }
@@ -2082,12 +2095,13 @@ public class FBObject {
      * If multisampling is being used and flagged dirty by a previous call of {@link #bind(GL)} or after initialization,
      * the msaa-buffers are sampled to it's sink {@link #getSamplingSink()}.
      * <p>
-     * Method also updates the sampling sink configuration (if used). Hence it is recommended to call this 
-     * method after your have initialized the FBO and attached renderbuffer etc for the 1st time.
+     * Method also resets the sampling sink configuration via {@link #resetSamplingSink(GL)} if used and required.
+     * </p>
+     * <p>
      * Method is called automatically by {@link #use(GL, TextureAttachment)}.
      * </p>
      * <p>
-     * Methos always resets the framebuffer binding to default in the end.
+     * Method always resets the framebuffer binding to default in the end.
      * If full FBO is supported, sets the read and write framebuffer individually to default after sampling, hence not disturbing 
      * an optional operating MSAA FBO, see {@link GLBase#getDefaultReadFramebuffer()} and {@link GLBase#getDefaultDrawFramebuffer()}
      * </p>
@@ -2101,11 +2115,11 @@ public class FBObject {
      * @param ta {@link TextureAttachment} to use, prev. attached w/  {@link #attachTexture2D(GL, int, boolean, int, int, int, int) attachTexture2D(..)}
      * @throws IllegalArgumentException  
      */
-    public final void syncFramebuffer(GL gl) {
+    public final void syncSamplingSink(GL gl) {
         markUnbound();
         if(samples>0 && samplesSinkDirty) {
             samplesSinkDirty = false;
-            resetMSAATexture2DSink(gl);
+            resetSamplingSink(gl);
             gl.glBindFramebuffer(GL2GL3.GL_READ_FRAMEBUFFER, fbName);
             gl.glBindFramebuffer(GL2GL3.GL_DRAW_FRAMEBUFFER, samplesSink.getWriteFramebuffer());
             ((GL2GL3)gl).glBlitFramebuffer(0, 0, width, height, 0, 0, width, height, // since MSAA is supported, casting to GL2GL3 is OK
@@ -2126,7 +2140,7 @@ public class FBObject {
      * 
      * <p>If using multiple texture units, ensure you call {@link GL#glActiveTexture(int)} first!</p>
      * 
-     * <p>{@link #syncFramebuffer(GL)} is being called</p>
+     * <p>{@link #syncSamplingSink(GL)} is being called</p>
      *  
      * <p>Leaves the FBO unbound!</p>
      * 
@@ -2135,8 +2149,8 @@ public class FBObject {
      * @throws IllegalArgumentException  
      */
     public final void use(GL gl, TextureAttachment ta) throws IllegalArgumentException {
-        if(null == ta) { throw new IllegalArgumentException("null TextureAttachment, this: "+toString()); }
-        syncFramebuffer(gl);
+        if(null == ta) { throw new IllegalArgumentException("Null TextureAttachment, this: "+toString()); }
+        syncSamplingSink(gl);
         gl.glBindTexture(GL.GL_TEXTURE_2D, ta.getName()); // use it ..
     }
 
@@ -2210,7 +2224,7 @@ public class FBObject {
     
     /**
      * Returns <code>true</code> if this instance has been initialized with {@link #reset(GL, int, int)} 
-     * or {@link #reset(GL, int, int, int)}, otherwise <code>false</code>
+     * or {@link #reset(GL, int, int, int, boolean)}, otherwise <code>false</code>
      */
     public final boolean isInitialized() { return initialized; }
     /** Returns the width */
diff --git a/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
index d7de7ca50..503b70af7 100644
--- a/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
@@ -102,7 +102,7 @@ public class GLFBODrawableImpl extends GLDrawableImpl implements GLFBODrawable {
             
             for(int i=0; i<fbosN; i++) {
                 fbos[i] = new FBObject();
-                fbos[i].reset(gl, getWidth(), getHeight(), samples);
+                fbos[i].reset(gl, getWidth(), getHeight(), samples, false);
                 if(fbos[i].getNumSamples() != samples) {
                     throw new InternalError("Sample number mismatch: "+samples+", fbos["+i+"] "+fbos[i]);
                 }
@@ -117,7 +117,7 @@ public class GLFBODrawableImpl extends GLDrawableImpl implements GLFBODrawable {
                     fbos[i].attachRenderbuffer(gl, Attachment.Type.DEPTH, 24);
                 }
             }
-            fbos[fboIFront].syncFramebuffer(gl);
+            fbos[fboIFront].resetSamplingSink(gl);
             fboBound = false;
             final GLCapabilities fboCapsNative = (GLCapabilities) surface.getGraphicsConfiguration().getChosenCapabilities();
             fbos[0].formatToGLCapabilities(fboCapsNative);
@@ -148,14 +148,14 @@ public class GLFBODrawableImpl extends GLDrawableImpl implements GLFBODrawable {
     
     private final void reset(GL gl, int idx, int width, int height, int samples, int alphaBits, int stencilBits) {
         if( !FBOResetQuirk ) {
-            fbos[idx].reset(gl, width, height, samples); // implicit glClear(..)
+            fbos[idx].reset(gl, width, height, samples, false);
             if(fbos[idx].getNumSamples() != samples) {
                 throw new InternalError("Sample number mismatch: "+samples+", fbos["+idx+"] "+fbos[idx]);
             }
         } else {
             fbos[idx].destroy(gl);
             fbos[idx] = new FBObject();
-            fbos[idx].reset(gl, getWidth(), getHeight(), samples);
+            fbos[idx].reset(gl, getWidth(), getHeight(), samples, false);
             if(fbos[idx].getNumSamples() != samples) {
                 throw new InternalError("Sample number mismatch: "+samples+", fbos["+idx+"] "+fbos[idx]);
             }
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/FBOMix2DemosES2.java b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/FBOMix2DemosES2.java
index 992f0261c..9d2c73f08 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/FBOMix2DemosES2.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/FBOMix2DemosES2.java
@@ -157,26 +157,19 @@ public class FBOMix2DemosES2 implements GLEventListener {
         st.useProgram(gl, false);
         
         System.err.println("**** Init");
-        resetFBOs(gl, drawable);
+        initFBOs(gl, drawable);
         
-        fbo0.attachRenderbuffer(gl, Type.DEPTH, 24);
-        fbo0.unbind(gl);
-        fbo1.attachRenderbuffer(gl, Type.DEPTH, 24);
-        fbo1.unbind(gl);
-        gl.glEnable(GL2ES2.GL_DEPTH_TEST);
-        
-        numSamples=fbo0.getNumSamples();
+        gl.glEnable(GL2ES2.GL_DEPTH_TEST);        
     }
     
-    /** Since we switch MSAA and non-MSAA we need to take extra care, i.e. sync msaa for both FBOs ..*/
-    private void resetFBOs(GL gl, GLAutoDrawable drawable) {
+    private void initFBOs(GL gl, GLAutoDrawable drawable) {
         // remove all texture attachments, since MSAA uses just color-render-buffer
         // and non-MSAA uses texture2d-buffer
         fbo0.detachAllColorbuffer(gl);
         fbo1.detachAllColorbuffer(gl);
             
-        fbo0.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples);
-        fbo1.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples);
+        fbo0.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples, false);
+        fbo1.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples, false);
         if(fbo0.getNumSamples() != fbo1.getNumSamples()) {
             throw new InternalError("sample size mismatch: \n\t0: "+fbo0+"\n\t1: "+fbo1);
         }        
@@ -184,15 +177,38 @@ public class FBOMix2DemosES2 implements GLEventListener {
         
         if(numSamples>0) {
             fbo0.attachColorbuffer(gl, 0, true);
+            fbo0.resetSamplingSink(gl);
             fbo1.attachColorbuffer(gl, 0, true);
+            fbo1.resetSamplingSink(gl);
             fbo0Tex = fbo0.getSamplingSink();
             fbo1Tex = fbo1.getSamplingSink();
         } else {
             fbo0Tex = fbo0.attachTexture2D(gl, 0, true);
             fbo1Tex = fbo1.attachTexture2D(gl, 0, true);
         }        
+        numSamples=fbo0.getNumSamples();
+        fbo0.attachRenderbuffer(gl, Type.DEPTH, 24);
+        fbo0.unbind(gl);
+        fbo1.attachRenderbuffer(gl, Type.DEPTH, 24);
+        fbo1.unbind(gl);
     }
 
+    private void resetFBOs(GL gl, GLAutoDrawable drawable) {
+        fbo0.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples, true);
+        fbo1.reset(gl, drawable.getWidth(), drawable.getHeight(), numSamples, true);
+        if(fbo0.getNumSamples() != fbo1.getNumSamples()) {
+            throw new InternalError("sample size mismatch: \n\t0: "+fbo0+"\n\t1: "+fbo1);
+        }        
+        numSamples = fbo0.getNumSamples();
+        if(numSamples>0) {
+            fbo0Tex = fbo0.getSamplingSink();
+            fbo1Tex = fbo1.getSamplingSink();
+        } else {
+            fbo0Tex = (TextureAttachment) fbo0.getColorbuffer(0);
+            fbo1Tex = (TextureAttachment) fbo1.getColorbuffer(0);
+        }        
+    }
+    
     @Override
     public void dispose(GLAutoDrawable drawable) {
         final GL2ES2 gl = drawable.getGL().getGL2ES2();
@@ -265,10 +281,8 @@ public class FBOMix2DemosES2 implements GLEventListener {
             gl.setSwapInterval(swapInterval); // in case switching the drawable (impl. may bound attribute there)
         }
         
-        // if(drawable.getWidth() == fbo0.getWidth() && drawable.getHeight() == fbo0.getHeight() ) {
-            System.err.println("**** Reshape: "+width+"x"+height);
-            resetFBOs(gl, drawable);            
-        //}        
+        System.err.println("**** Reshape: "+width+"x"+height);
+        resetFBOs(gl, drawable);            
         
         fbo0.bind(gl);
         demo0.reshape(drawable, x, y, width, height);