From deff49c901915e007f43a1df1a0d217a786e9f06 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Thu, 27 Aug 2015 13:15:44 +0200
Subject: 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

+++
---
 src/jogl/classes/com/jogamp/opengl/GLBase.java | 60 ++++++++++++++++----------
 1 file changed, 37 insertions(+), 23 deletions(-)

(limited to 'src/jogl/classes/com/jogamp/opengl/GLBase.java')

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);
 
-- 
cgit v1.2.3