Bug 1202 - Add support of Adaptive Vsync via [GLX|WGL]_EXT_swap_control_tear

[GLX|WGL]_EXT_swap_control_tear extensions support
asynchronous buffer swaps, i.e. adaptive Vsync.

<https://www.opengl.org/wiki/SwapInterval_aka_vsync#Adaptive_Vsync>
<https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt>
<https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt>

<http://keithp.com/blogs/async_flip/>

The extensions utilizes a negative interval value,
enabling late swaps to occur without synchronization to the video frame.

Hence '-1' has new semantics, previously it was the 'default value'
of 'untouched vsync interval'.

New default is:
  - 0 for unrealized context
  - 1 for realized context

+++

It requires [GLX|WGL]_EXT_swap_control,
hence we shall ensure to use use this extension
in the implementation of GLContext.setSwapInterval(..).

+++

Mesa3D seems to support GLX_SGI_swap_control only.

+++

Implemented on Windows and X11.

+++

On GNU/Linux using NVidia driver w/ my setup(*), sadly the query
  GLX.glXQueryDrawable(displayHandle, drawable.getHandle(), GLX.GLX_LATE_SWAPS_TEAR_EXT, val);
always returns zero here, indicating async vsync is not supported.

(Queried the attribute for every frame in windowed or fullscreen mode)

Fullscreen
(*)
  - Debian 8
  - Kernel 3.16
  - KDE/Kwin
  - GL Version     4.5 (Core profile, arb, compat[ES2, ES3, ES31], FBO, hardware) - 4.5.0 NVIDIA 355.06 [GL 4.5.0, vendor 355.6.0 (NVIDIA 355.06)]
  - GL_RENDERER    GeForce GTX 660/PCIe/SSE2
  - Samsung U28D590 (DFP-4): Internal DisplayPort

+++

2 files changed, 63 insertions, 60 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLBase.java b/src/jogl/classes/com/jogamp/opengl/GLBase.java
index dee5f1488..e0c784398 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLBase.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLBase.java
@@ -446,29 +446,43 @@ public interface GLBase {
 
    public boolean isTextureFormatBGRA8888Available();
 
-   /** Provides a platform-independent way to specify the minimum swap
-       interval for buffer swaps. An argument of 0 disables
-       sync-to-vertical-refresh completely, while an argument of 1
-       causes the application to wait until the next vertical refresh
-       until swapping buffers. The default, which is platform-specific,
-       is usually either 0 or 1. This function is not guaranteed to
-       have an effect, and in particular only affects heavyweight
-       onscreen components.
-
-       @see #getSwapInterval
-       @throws GLException if this context is not the current
+   /**
+    * Set the swap interval of the current context and attached <i>onscreen {@link GLDrawable}</i>.
+    * <p>
+    * <i>offscreen {@link GLDrawable}</i> are ignored and {@code false} is returned.
+    * </p>
+    * <p>
+    * The {@code interval} semantics:
+    * <ul>
+    *   <li><i>0</i> disables the vertical synchronization</li>
+    *   <li><i>&ge;1</i> is the number of vertical refreshes before a swap buffer occurs</li>
+    *   <li><i>&lt;0</i> enables <i>late swaps to occur without synchronization to the video frame</i>, a.k.a <i>EXT_swap_control_tear</i>.
+    *              If supported, the absolute value is the minimum number of
+    *              video frames between buffer swaps. If not supported, the absolute value is being used, see above.
+    *   </li>
+    * </ul>
+    * </p>
+    * @param interval see above
+    * @return true if the operation was successful, otherwise false
+    * @throws GLException if the context is not current.
+    * @see GLContext#setSwapInterval(int)
+    * @see #getSwapInterval()
     */
-   public void setSwapInterval(int interval);
-
-   /** Provides a platform-independent way to get the swap
-       interval set by {@link #setSwapInterval}. <br>
+   public void setSwapInterval(int interval) throws GLException;
 
-       If the interval is not set by {@link #setSwapInterval} yet,
-       -1 is returned, indicating that the platforms default
-       is being used.
-
-       @see #setSwapInterval
-     */
+   /**
+    * Return the current swap interval.
+    * <p>
+    * If the context has not been made current at all,
+    * the default value {@code 0} is returned.
+    * </p>
+    * <p>
+    * For a valid context w/ an <o>onscreen {@link GLDrawable}</i> the default value is {@code 1},
+    * otherwise the default value is {@code 0}.
+    * </p>
+    * @see GLContext#getSwapInterval()
+    * @see #setSwapInterval(int)
+    */
    public int getSwapInterval();
 
    /**
@@ -494,12 +508,12 @@ public interface GLBase {
     * for accessing it, including which class or interface contains the
     * functions.
     *
-    * <P>
-    *
+    * <p>
     * Note: it is the intent to add new extensions as quickly as possible
     * to the core GL API. Therefore it is unlikely that most vendors will
     * use this extension mechanism, but it is being provided for
     * completeness.
+    * </p>
     */
    public Object getExtension(String extensionName);
 
diff --git a/src/jogl/classes/com/jogamp/opengl/GLContext.java b/src/jogl/classes/com/jogamp/opengl/GLContext.java
index f68c029df..3ac5df7d4 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLContext.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLContext.java
@@ -237,7 +237,6 @@ public abstract class GLContext {
   protected String ctxVersionString;
   protected VersionNumberString ctxVendorVersion;
   protected VersionNumber ctxGLSLVersion;
-  private int currentSwapInterval;
   protected GLRendererQuirks glRendererQuirks;
 
   /** Did the drawable association changed ? see {@link GLRendererQuirks#NoSetSwapIntervalPostRetarget} */
@@ -258,7 +257,6 @@ public abstract class GLContext {
       ctxGLSLVersion = VersionNumber.zeroVersion;
       attachedObjects.clear();
       contextHandle=0;
-      currentSwapInterval = -1;
       glRendererQuirks = null;
       drawableRetargeted = false;
   }
@@ -1246,50 +1244,41 @@ public abstract class GLContext {
   }
 
   /**
-   * Set the swap interval of the current context and attached drawable.
-   * @param interval Should be &ge; 0. 0 disables the vertical synchronization,
-   *                 where &ge; 1 is the number of vertical refreshes before a swap buffer occurs.
-   *                 A value &lt; 0 is ignored.
+   * Set the swap interval of the current context and attached <i>onscreen {@link GLDrawable}</i>.
+   * <p>
+   * <i>offscreen {@link GLDrawable}</i> are ignored and {@code false} is returned.
+   * </p>
+   * <p>
+   * The {@code interval} semantics:
+   * <ul>
+   *   <li><i>0</i> disables the vertical synchronization</li>
+   *   <li><i>&ge;1</i> is the number of vertical refreshes before a swap buffer occurs</li>
+   *   <li><i>&lt;0</i> enables <i>late swaps to occur without synchronization to the video frame</i>, a.k.a <i>EXT_swap_control_tear</i>.
+   *              If supported, the absolute value is the minimum number of
+   *              video frames between buffer swaps. If not supported, the absolute value is being used, see above.
+   *   </li>
+   * </ul>
+   * </p>
+   * @param interval see above
    * @return true if the operation was successful, otherwise false
-   *
    * @throws GLException if the context is not current.
+   * @see #getSwapInterval()
    */
-  public final boolean setSwapInterval(final int interval) throws GLException {
-    validateCurrent();
-    if(0<=interval) {
-        if( !drawableRetargeted || !hasRendererQuirk(GLRendererQuirks.NoSetSwapIntervalPostRetarget) ) {
-            if( setSwapIntervalImpl(interval) ) {
-                currentSwapInterval = interval;
-                return true;
-            }
-        }
-    }
-    return false;
-  }
-  protected boolean setSwapIntervalImpl(final int interval) {
-      return false;
-  }
-  /** Return the current swap interval.
+  public abstract boolean setSwapInterval(final int interval) throws GLException;
+
+  /**
+   * Return the current swap interval.
    * <p>
    * If the context has not been made current at all,
-   * the default value <code>-1</code> is returned.
+   * the default value {@code 0} is returned.
    * </p>
    * <p>
-   * For a valid context the default value is <code>1</code>
-   * in case of an EGL based profile (ES1 or ES2) and <code>-1</code>
-   * (undefined) for desktop.
+   * For a valid context w/ an <o>onscreen {@link GLDrawable}</i> the default value is {@code 1},
+   * otherwise the default value is {@code 0}.
    * </p>
+   * @see #setSwapInterval(int)
    */
-  public final int getSwapInterval() {
-    return currentSwapInterval;
-  }
-  protected final void setDefaultSwapInterval() {
-    if(this.isGLES()) {
-        currentSwapInterval = 1;
-    } else {
-        currentSwapInterval = -1;
-    }
-  }
+  public abstract int getSwapInterval();
 
   public final boolean queryMaxSwapGroups(final int[] maxGroups, final int maxGroups_offset,
                                           final int[] maxBarriers, final int maxBarriers_offset) {