Bug 975 - GLJPanel's OffscreenDrawable shall not double swap - Fix auto-swap mechanism ; Refined API doc getDefaultReadBuffer() ; Add GLDrawableUtil.swapBuffersBeforeRead(..)

Commit 82f679b064784213591b460fc5eaa1f5f196fbd1 which introduces the default swap-buffers
mechanism is erroneous:

The OffscreenBack backend requires the following operation order:

Order-1:
  [1] - GL display
  [2] - GL swapBuffers (always due to single-buffer non-MSAA or MSAA offscreen drawable)
  [3] - readPixels

+++

Commit 82f679b064784213591b460fc5eaa1f5f196fbd1 however introduced:

Order-2:
  [a] - GL display
  [b] - readPixels
  [c] - GL swapBuffers (always due to single-buffer non-MSAA or MSAA offscreen drawable)

since [a] and [b] happened in Updater's display method, and [c] followed the same
triggered by GLAutoDrawableHelper.

+++

The proof, commit d46d9ad8f998a7128d9f023294d5f489673d6d8a, is faulty,
since it always included the 'snapshot' GL event listener
which turned-off auto-swap and swapped before read-pixels.
TL;DR it enforced proper Order-1.

+++

This fix allows the Backend to intercept disable GLDrawableHelper's setAutoSwapBufferMode(..)
and perform the auto-swap mode itself in the proper Order-1.

The unit test has been refined to optionally disable the snapshot
to validate auto-swap mode.

+++

Refined GLBase and GLContext's API doc for 'getDefaultReadBuffer()'

+++

Add GLDrawableUtil.swapBuffersBeforeRead(..)
and reuse it for TileRendererBase (original impl.).

2 files changed, 23 insertions, 13 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java b/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
index ec6d54d66..cf88e7bf6 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
@@ -30,6 +30,8 @@ package com.jogamp.opengl.util;
 import javax.media.nativewindow.AbstractGraphicsDevice;
 import javax.media.opengl.GLAnimatorControl;
 import javax.media.opengl.GLAutoDrawable;
+import javax.media.opengl.GLBase;
+import javax.media.opengl.GLCapabilitiesImmutable;
 import javax.media.opengl.GLContext;
 import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLEventListener;
@@ -168,4 +170,23 @@ public class GLDrawableUtil {
     if(bIsPaused) { bAnim.resume(); }
   }
 
+  /**
+   * Determines whether the chosen {@link GLCapabilitiesImmutable}
+   * requires a {@link GLDrawable#swapBuffers() swap-buffers}
+   * before reading pixels.
+   * <p>
+   * Usually one uses the {@link GLBase#getDefaultReadBuffer() default-read-buffer}
+   * in which case {@link GLDrawable#swapBuffers() swap-buffers} shall happen <b>after</b> calling reading pixels, the default.
+   * </p>
+   * <p>
+   * However, <i>multisampling</i> offscreen {@link javax.media.opengl.GLFBODrawable}s
+   * utilize {@link GLDrawable#swapBuffers() swap-buffers} to <i>downsample</i>
+   * the multisamples into the readable sampling sink.
+   * In this case, we require {@link GLDrawable#swapBuffers() swap-buffers} <b>before</b> reading pixels.
+   * </p>
+   * @return chosenCaps.isFBO() && chosenCaps.getSampleBuffers()
+   */
+  public static final boolean swapBuffersBeforeRead(final GLCapabilitiesImmutable chosenCaps) {
+      return chosenCaps.isFBO() && chosenCaps.getSampleBuffers();
+  }
 }
diff --git a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
index 22f5c017c..dabde83dd 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
@@ -412,22 +412,11 @@ public abstract class TileRendererBase {
      * requires a <i>pre-{@link GLDrawable#swapBuffers() swap-buffers}</i>
      * before accessing the results, i.e. before {@link #endTile(GL)}.
      * <p>
-     * Usually one uses the {@link GL#getDefaultReadBuffer() default-read-buffer}, i.e.
-     * {@link GL#GL_FRONT} for single-buffer and {@link GL#GL_BACK} for double-buffer {@link GLDrawable}s
-     * and {@link GL#GL_COLOR_ATTACHMENT0} for offscreen framebuffer objects.<br>
-     * Here {@link GLDrawable#swapBuffers() swap-buffers} shall happen <b>after</b> calling {@link #endTile(GL)}, the default.
+     * See {@link GLDrawableUtil#swapBuffersBeforeRead(GLCapabilitiesImmutable)}.
      * </p>
-     * <p>
-     * However, <i>multisampling</i> offscreen {@link GLFBODrawable}s
-     * utilize {@link GLDrawable#swapBuffers() swap-buffers} to <i>downsample</i>
-     * the multisamples into the readable sampling sink.
-     * In this case, we require a {@link GLDrawable#swapBuffers() swap-buffers} <b>before</b> calling {@link #endTile(GL)}.
-     * </p>
-     * @param chosenCaps the chosen {@link GLCapabilitiesImmutable}
-     * @return chosenCaps.isFBO() && chosenCaps.getSampleBuffers()
      */
     public final boolean reqPreSwapBuffers(GLCapabilitiesImmutable chosenCaps) {
-        return chosenCaps.isFBO() && chosenCaps.getSampleBuffers();
+        return GLDrawableUtil.swapBuffersBeforeRead(chosenCaps);
     }
 
     /**