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

1 files changed, 12 insertions, 2 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLBase.java b/src/jogl/classes/javax/media/opengl/GLBase.java
index 2d6aed139..3f0c77949 100644
--- a/src/jogl/classes/javax/media/opengl/GLBase.java
+++ b/src/jogl/classes/javax/media/opengl/GLBase.java
@@ -627,14 +627,24 @@ public interface GLBase {
     * Returns the default color buffer within the current bound
     * {@link #getDefaultReadFramebuffer()}, i.e. GL_READ_FRAMEBUFFER,
     * which will be used as the source for pixel reading commands,
-    * like {@link GL#glReadPixels(int, int, int, int, int, int, java.nio.Buffer)} etc.
+    * like {@link GL#glReadPixels(int, int, int, int, int, int, java.nio.Buffer) glReadPixels} etc.
     * <p>
     * For offscreen framebuffer objects this is {@link GL#GL_COLOR_ATTACHMENT0},
     * otherwise this is {@link GL#GL_FRONT} for single buffer configurations
     * and {@link GL#GL_BACK} for double buffer configurations.
     * </p>
+    * <p>
+    * Note-1: Neither ES1 nor ES2 supports selecting the read buffer via glReadBuffer
+    * and {@link GL#GL_BACK} is the default.
+    * </p>
+    * <p>
+    * Note-2: ES3 only supports {@link GL#GL_BACK}, {@link GL#GL_NONE} or {@link GL#GL_COLOR_ATTACHMENT0}+i
+    * </p>
+    * <p>
+    * Note-3: See {@link com.jogamp.opengl.util.GLDrawableUtil#swapBuffersBeforeRead(GLCapabilitiesImmutable) swapBuffersBeforeRead}
+    * for read-pixels and swap-buffers implications.
+    * </p>
     */
    public int getDefaultReadBuffer();
-
 }