Bug 1035 - Allow Gamma [Brightness, Contrast] settings to be performed on display/screen of a NativeSurface

Currently GLDrawableFactoryImpl's gamma settings are performed
only on the main screen.

Allow passing a NativeSurface, so it's display/screen
gamma values will be changed.

Further, promote low-level gamma settings to GLDrawableFactory
for direct usage.

Change com.jogamp.opengl.util.Gamma to use a GLDrawable
instead of a GL object to clarify that we use the drawable.

Also add a GLAutoDrawable variant, allowing proper locking
of its 'upstream-lock' to guarantee atomicity.

+++

Tested manually w/ TestGearsES2NEWT on X11 and Windows
using the 'g' and 'G' to modify gamma.
Value is properly reset on exit.

1 files changed, 65 insertions, 2 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index 82808a3cb..c11195c58 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -222,7 +222,7 @@ public abstract class GLDrawableFactory {
                 System.err.println("GLDrawableFactory.shutdownAll["+(i+1)+"/"+gldfCount+"]:  "+gldf.getClass().getName());
             }
             try {
-                gldf.resetDisplayGamma();
+                gldf.resetAllDisplayGammaNoSync();
                 gldf.shutdownImpl();
             } catch (final Throwable t) {
                 System.err.println("GLDrawableFactory.shutdownImpl: Caught "+t.getClass().getName()+" during factory shutdown #"+(i+1)+"/"+gldfCount+" "+gldf.getClass().getName());
@@ -259,7 +259,70 @@ public abstract class GLDrawableFactory {
 
   protected abstract void shutdownImpl();
 
-  public abstract void resetDisplayGamma();
+  /**
+   * Sets the gamma, brightness, and contrast of the display associated with the given <code>surface</code>.
+   * <p>
+   * This functionality is not available on all platforms and
+   * graphics hardware. Returns true if the settings were successfully
+   * changed, false if not. This method may return false for some
+   * values of the incoming arguments even on hardware which does
+   * support the underlying functionality. </p>
+   * <p>
+   * If this method returns true, the display settings will
+   * automatically be reset to their original values upon JVM exit
+   * (assuming the JVM does not crash); if the user wishes to change
+   * the display settings back to normal ahead of time,
+   * use {@link #resetDisplayGamma(NativeSurface)} or {@link #resetAllDisplayGamma()}.
+   * </p>
+   * <p>
+   * It is recommended to call {@link #resetDisplayGamma(NativeSurface)} or {@link #resetAllDisplayGamma()}
+   * before calling e.g. <code>System.exit()</code> from the application rather than
+   * rely on the shutdown hook functionality due to inevitable race
+   * conditions and unspecified behavior during JVM teardown.
+   * </p>
+   * <p>
+   * This method may be called multiple times during the application's
+   * execution, but calling {@link #resetDisplayGamma(NativeSurface)}
+   * will only reset the settings to the values
+   * before the first call to this method. </p>
+   *
+   * @param surface denominates the display device
+   * @param gamma The gamma value, typically > 1.0 (default values vary, but typically roughly 1.0)
+   * @param brightness The brightness value between -1.0 and 1.0, inclusive (default values vary, but typically 0)
+   * @param contrast The contrast, greater than 0.0 (default values vary, but typically 1)
+   *
+   * @return true if gamma settings were successfully changed, false if not
+   * @throws IllegalArgumentException if any of the parameters were out-of-bounds
+   * @see #resetDisplayGamma(NativeSurface)
+   * @see #resetAllDisplayGamma()
+   */
+  public abstract boolean setDisplayGamma(final NativeSurface surface, final float gamma, final float brightness, final float contrast) throws IllegalArgumentException;
+
+  /**
+   * Resets the gamma, brightness and contrast values of the display associated with the given <code>surface</code>
+   * to its original values before {@link #setDisplayGamma(NativeSurface, float, float, float) setDisplayGamma}
+   * was called the first time.
+   * <p>
+   * While it is not explicitly required that this method be called before
+   * exiting manually, calling it is recommended because of the inevitable
+   * unspecified behavior during JVM teardown.
+   * </p>
+   */
+  public abstract void resetDisplayGamma(final NativeSurface surface);
+
+  /**
+   * Resets the gamma, brightness and contrast values of all modified
+   * displays to their original values before {@link #setDisplayGamma(NativeSurface, float, float, float) setDisplayGamma}
+   * was called the first time.
+   * <p>
+   * While it is not explicitly required that this method be called before
+   * exiting manually, calling it is recommended because of the inevitable
+   * unspecified behavior during JVM teardown.
+   * </p>
+   */
+  public abstract void resetAllDisplayGamma();
+
+  protected abstract void resetAllDisplayGammaNoSync();
 
   /**
    * Retrieve the default <code>device</code> {@link AbstractGraphicsDevice#getConnection() connection},