Fixed Issue 173: Adjust gamma, brightness and contrast

Added com.sun.opengl.util.Gamma supporting adjusting of gamma,
brightness, and contrast. API and implementation derived from code in
the LWJGL project. Added demos.gamma.TestGamma demo illustrating how
to use the APIs. Tested on Linux, Mac OS X and Windows. No Solaris
support at this time, although future Solaris releases, being based on
the Xorg server, will probably have support for the required
XF86VidMode extension.


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@557 232f8b59-042b-4e1e-8c03-345bb8c30851

5 files changed, 442 insertions, 11 deletions

diff --git a/src/classes/com/sun/opengl/impl/GLDrawableFactoryImpl.java b/src/classes/com/sun/opengl/impl/GLDrawableFactoryImpl.java
index d47003e45..45a875361 100644
--- a/src/classes/com/sun/opengl/impl/GLDrawableFactoryImpl.java
+++ b/src/classes/com/sun/opengl/impl/GLDrawableFactoryImpl.java
@@ -42,8 +42,9 @@ package com.sun.opengl.impl;
 import java.awt.Component;
 import java.awt.GraphicsConfiguration;
 import java.awt.GraphicsDevice;
-import com.sun.gluegen.runtime.*;
+import java.nio.*;
 import javax.media.opengl.*;
+import com.sun.gluegen.runtime.*;
 
 /** Extends GLDrawableFactory with a few methods for handling
     typically software-accelerated offscreen rendering (Device
@@ -73,4 +74,159 @@ public abstract class GLDrawableFactoryImpl extends GLDrawableFactory implements
   public static GLDrawableFactoryImpl getFactoryImpl() {
     return (GLDrawableFactoryImpl) getFactory();
   }
+
+  //----------------------------------------------------------------------
+  // Gamma adjustment support
+  // Thanks to the LWJGL team for illustrating how to make these
+  // adjustments on various OSs.
+
+  /*
+   * Portions Copyright (c) 2002-2004 LWJGL Project
+   * All rights reserved.
+   *
+   * Redistribution and use in source and binary forms, with or without
+   * modification, are permitted provided that the following conditions are
+   * met:
+   *
+   * * Redistributions of source code must retain the above copyright
+   *   notice, this list of conditions and the following disclaimer.
+   *
+   * * Redistributions in binary form must reproduce the above copyright
+   *   notice, this list of conditions and the following disclaimer in the
+   *   documentation and/or other materials provided with the distribution.
+   *
+   * * Neither the name of 'LWJGL' nor the names of
+   *   its contributors may be used to endorse or promote products derived
+   *   from this software without specific prior written permission.
+   *
+   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+   * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+   */
+
+  /**
+   * Sets the gamma, brightness, and contrast of the current main
+   * display. Returns true if the settings were changed, false if
+   * not. If this method returns true, the display settings will
+   * automatically be reset 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 resetDisplayGamma(). Throws
+   * IllegalArgumentException if any of the parameters were
+   * out-of-bounds.
+   * 
+   * @param gamma The gamma value, typically > 1.0 (default value is
+   *   1.0)
+   * @param brightness The brightness value between -1.0 and 1.0,
+   *   inclusive (default value is 0)
+   * @param contrast The contrast, greater than 0.0 (default value is 1)
+   * @throws IllegalArgumentException if any of the parameters were
+   *   out-of-bounds
+   */
+  public boolean setDisplayGamma(float gamma, float brightness, float contrast) throws IllegalArgumentException {
+    if ((brightness < -1.0f) || (brightness > 1.0f)) {
+      throw new IllegalArgumentException("Brightness must be between -1.0 and 1.0");
+    }
+    if (contrast < 0) {
+      throw new IllegalArgumentException("Contrast must be greater than 0.0");
+    }
+    // FIXME: ensure gamma is > 1.0? Are smaller / negative values legal?
+    int rampLength = getGammaRampLength();
+    if (rampLength == 0) {
+      return false;
+    }
+    float[] gammaRamp = new float[rampLength];
+    for (int i = 0; i < rampLength; i++) {
+      float intensity = (float) i / (float) (rampLength - 1);
+      // apply gamma
+      float rampEntry = (float) java.lang.Math.pow(intensity, gamma);
+      // apply brightness
+      rampEntry += brightness;
+      // apply contrast
+      rampEntry = (rampEntry - 0.5f) * contrast + 0.5f;
+      // Clamp entry to [0, 1]
+      if (rampEntry > 1.0f)
+        rampEntry = 1.0f;
+      else if (rampEntry < 0.0f)
+        rampEntry = 0.0f;
+      gammaRamp[i] = rampEntry;
+    }
+    registerGammaShutdownHook();
+    return setGammaRamp(gammaRamp);
+  }
+
+  public synchronized void resetDisplayGamma() {
+    if (gammaShutdownHook == null) {
+      throw new IllegalArgumentException("Should not call this unless setDisplayGamma called first");
+    }
+    resetGammaRamp(originalGammaRamp);
+    unregisterGammeShutdownHook();
+  }
+
+  //------------------------------------------------------
+  // Gamma-related methods to be implemented by subclasses
+  //
+
+  /** Returns the length of the computed gamma ramp for this OS and
+      hardware. Returns 0 if gamma changes are not supported. */
+  protected int getGammaRampLength() {
+    return 0;
+  }
+
+  /** Sets the gamma ramp for the main screen. Returns false if gamma
+      ramp changes were not supported. */
+  protected boolean setGammaRamp(float[] ramp) {
+    return false;
+  }
+
+  /** Gets the current gamma ramp. This is basically an opaque value
+      used only on some platforms to reset the gamma ramp to its
+      original settings. */
+  protected Buffer getGammaRamp() {
+    return null;
+  }
+
+  /** Resets the gamma ramp, potentially using the specified Buffer as
+      data to restore the original values. */
+  protected void resetGammaRamp(Buffer originalGammaRamp) {
+  }
+
+  // Shutdown hook mechanism for resetting gamma
+  private boolean gammaShutdownHookRegistered;
+  private Thread  gammaShutdownHook;
+  private Buffer  originalGammaRamp;
+  private synchronized void registerGammaShutdownHook() {
+    if (gammaShutdownHookRegistered)
+      return;
+    if (gammaShutdownHook == null) {
+      gammaShutdownHook = new Thread(new Runnable() {
+          public void run() {
+            synchronized (GLDrawableFactoryImpl.this) {
+              resetGammaRamp(originalGammaRamp);
+            }
+          }
+        });
+      originalGammaRamp = getGammaRamp();
+    }
+    Runtime.getRuntime().addShutdownHook(gammaShutdownHook);
+    gammaShutdownHookRegistered = true;
+  }
+
+  private synchronized void unregisterGammeShutdownHook() {
+    if (!gammaShutdownHookRegistered)
+      return;
+    if (gammaShutdownHook == null) {
+      throw new InternalError("Error in gamma shutdown hook logic");
+    }
+    Runtime.getRuntime().removeShutdownHook(gammaShutdownHook);
+    gammaShutdownHookRegistered = false;
+    // Leave the original gamma ramp data alone
+  }
 }
diff --git a/src/classes/com/sun/opengl/impl/macosx/MacOSXGLDrawableFactory.java b/src/classes/com/sun/opengl/impl/macosx/MacOSXGLDrawableFactory.java
index b05886e15..fbc52e850 100644
--- a/src/classes/com/sun/opengl/impl/macosx/MacOSXGLDrawableFactory.java
+++ b/src/classes/com/sun/opengl/impl/macosx/MacOSXGLDrawableFactory.java
@@ -42,8 +42,8 @@ package com.sun.opengl.impl.macosx;
 import java.awt.Component;
 import java.awt.EventQueue;
 import java.lang.reflect.InvocationTargetException;
-import java.util.ArrayList;
-import java.util.List;
+import java.nio.*;
+import java.util.*;
 import javax.media.opengl.*;
 import com.sun.opengl.impl.*;
 
@@ -136,4 +136,31 @@ public class MacOSXGLDrawableFactory extends GLDrawableFactoryImpl {
 
   public void unlockAWTForJava2D() {
   }
+
+  //------------------------------------------------------
+  // Gamma-related functionality
+  //
+
+  private static final int GAMMA_RAMP_LENGTH = 256;
+
+  /** Returns the length of the computed gamma ramp for this OS and
+      hardware. Returns 0 if gamma changes are not supported. */
+  protected int getGammaRampLength() {
+    return GAMMA_RAMP_LENGTH;
+  }
+
+  protected boolean setGammaRamp(float[] ramp) {
+    return CGL.setGammaRamp(ramp.length,
+                            ramp, 0,
+                            ramp, 0,
+                            ramp, 0);
+  }
+
+  protected Buffer getGammaRamp() {
+    return null;
+  }
+
+  protected void resetGammaRamp(Buffer originalGammaRamp) {
+    CGL.resetGammaRamp();
+  }
 }
diff --git a/src/classes/com/sun/opengl/impl/windows/WindowsGLDrawableFactory.java b/src/classes/com/sun/opengl/impl/windows/WindowsGLDrawableFactory.java
index b534a11fc..eab068bb4 100644
--- a/src/classes/com/sun/opengl/impl/windows/WindowsGLDrawableFactory.java
+++ b/src/classes/com/sun/opengl/impl/windows/WindowsGLDrawableFactory.java
@@ -41,14 +41,11 @@ package com.sun.opengl.impl.windows;
 
 import java.awt.Component;
 import java.awt.Rectangle;
-import java.io.File;
-import java.lang.reflect.InvocationTargetException;
-import java.security.AccessController;
-import java.security.PrivilegedAction;
-import java.util.ArrayList;
-import java.util.List;
+import java.nio.*;
+import java.util.*;
 import javax.media.opengl.*;
 import com.sun.opengl.impl.*;
+import com.sun.opengl.util.BufferUtil;
 
 public class WindowsGLDrawableFactory extends GLDrawableFactoryImpl {
   private static final boolean DEBUG = Debug.debug("WindowsGLDrawableFactory");
@@ -219,4 +216,50 @@ public class WindowsGLDrawableFactory extends GLDrawableFactoryImpl {
 
   public void unlockAWTForJava2D() {
   }
+
+  //------------------------------------------------------
+  // Gamma-related functionality
+  //
+
+  private static final int GAMMA_RAMP_LENGTH = 256;
+
+  protected int getGammaRampLength() {
+    return GAMMA_RAMP_LENGTH;
+  }
+
+  protected boolean setGammaRamp(float[] ramp) {
+    short[] rampData = new short[3 * GAMMA_RAMP_LENGTH];
+    for (int i = 0; i < GAMMA_RAMP_LENGTH; i++) {
+      short scaledValue = (short) (ramp[i] * 65535);
+      rampData[i] = scaledValue;
+      rampData[i +     GAMMA_RAMP_LENGTH] = scaledValue;
+      rampData[i + 2 * GAMMA_RAMP_LENGTH] = scaledValue;
+    }
+
+    long screenDC = WGL.GetDC(0);
+    boolean res = WGL.SetDeviceGammaRamp(screenDC, ShortBuffer.wrap(rampData));
+    WGL.ReleaseDC(0, screenDC);
+    return res;
+  }
+
+  protected Buffer getGammaRamp() {
+    ShortBuffer rampData = ShortBuffer.allocate(3 * GAMMA_RAMP_LENGTH);
+    long screenDC = WGL.GetDC(0);
+    boolean res = WGL.GetDeviceGammaRamp(screenDC, rampData);
+    WGL.ReleaseDC(0, screenDC);
+    if (!res) {
+      return null;
+    }
+    return rampData;
+  }
+
+  protected void resetGammaRamp(Buffer originalGammaRamp) {
+    if (originalGammaRamp == null) {
+      // getGammaRamp failed earlier
+      return;
+    }
+    long screenDC = WGL.GetDC(0);
+    WGL.SetDeviceGammaRamp(screenDC, originalGammaRamp);
+    WGL.ReleaseDC(0, screenDC);
+  }
 }
diff --git a/src/classes/com/sun/opengl/impl/x11/X11GLDrawableFactory.java b/src/classes/com/sun/opengl/impl/x11/X11GLDrawableFactory.java
index 289d06e93..4b8840e59 100644
--- a/src/classes/com/sun/opengl/impl/x11/X11GLDrawableFactory.java
+++ b/src/classes/com/sun/opengl/impl/x11/X11GLDrawableFactory.java
@@ -43,9 +43,9 @@ import java.awt.Component;
 import java.awt.GraphicsConfiguration;
 import java.awt.GraphicsDevice;
 import java.awt.GraphicsEnvironment;
+import java.nio.*;
 import java.security.*;
-import java.util.ArrayList;
-import java.util.List;
+import java.util.*;
 import javax.media.opengl.*;
 import com.sun.gluegen.runtime.*;
 import com.sun.opengl.impl.*;
@@ -468,4 +468,103 @@ public class X11GLDrawableFactory extends GLDrawableFactoryImpl {
       action.run();
     }
   }
+
+  //----------------------------------------------------------------------
+  // Gamma-related functionality
+  //
+
+  boolean gotGammaRampLength;
+  int gammaRampLength;
+  protected synchronized int getGammaRampLength() {
+    if (gotGammaRampLength) {
+      return gammaRampLength;
+    }
+
+    int[] size = new int[1];
+    lockToolkit();
+    long display = getDisplayConnection();
+    boolean res = GLX.XF86VidModeGetGammaRampSize(display,
+                                                  GLX.DefaultScreen(display),
+                                                  size, 0);
+    unlockToolkit();
+    if (!res)
+      return 0;
+    gotGammaRampLength = true;
+    gammaRampLength = size[0];
+    return gammaRampLength;
+  }
+
+  protected boolean setGammaRamp(float[] ramp) {
+    int len = ramp.length;
+    short[] rampData = new short[len];
+    for (int i = 0; i < len; i++) {
+      rampData[i] = (short) (ramp[i] * 65535);
+    }
+
+    lockToolkit();
+    long display = getDisplayConnection();
+    boolean res = GLX.XF86VidModeSetGammaRamp(display,
+                                              GLX.DefaultScreen(display),
+                                              rampData.length,
+                                              rampData, 0,
+                                              rampData, 0,
+                                              rampData, 0);
+    unlockToolkit();
+    return res;
+  }
+
+  protected Buffer getGammaRamp() {
+    int size = getGammaRampLength();
+    ShortBuffer rampData = ShortBuffer.allocate(3 * size);
+    rampData.position(0);
+    rampData.limit(size);
+    ShortBuffer redRampData = rampData.slice();
+    rampData.position(size);
+    rampData.limit(2 * size);
+    ShortBuffer greenRampData = rampData.slice();
+    rampData.position(2 * size);
+    rampData.limit(3 * size);
+    ShortBuffer blueRampData = rampData.slice();
+    lockToolkit();
+    long display = getDisplayConnection();
+    boolean res = GLX.XF86VidModeGetGammaRamp(display,
+                                              GLX.DefaultScreen(display),
+                                              size,
+                                              redRampData,
+                                              greenRampData,
+                                              blueRampData);
+    unlockToolkit();
+    if (!res)
+      return null;
+    return rampData;
+  }
+
+  protected void resetGammaRamp(Buffer originalGammaRamp) {
+    if (originalGammaRamp == null)
+      return; // getGammaRamp failed originally
+    ShortBuffer rampData = (ShortBuffer) originalGammaRamp;
+    int capacity = rampData.capacity();
+    if ((capacity % 3) != 0) {
+      throw new IllegalArgumentException("Must not be the original gamma ramp");
+    }
+    int size = capacity / 3;
+    rampData.position(0);
+    rampData.limit(size);
+    ShortBuffer redRampData = rampData.slice();
+    rampData.position(size);
+    rampData.limit(2 * size);
+    ShortBuffer greenRampData = rampData.slice();
+    rampData.position(2 * size);
+    rampData.limit(3 * size);
+    ShortBuffer blueRampData = rampData.slice();
+    lockToolkit();
+    long display = getDisplayConnection();
+    GLX.XF86VidModeSetGammaRamp(display,
+                                GLX.DefaultScreen(display),
+                                size,
+                                redRampData,
+                                greenRampData,
+                                blueRampData);
+    unlockToolkit();
+  }
 }
diff --git a/src/classes/com/sun/opengl/util/Gamma.java b/src/classes/com/sun/opengl/util/Gamma.java
new file mode 100755
index 000000000..8be4f4edf
--- /dev/null
+++ b/src/classes/com/sun/opengl/util/Gamma.java
@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ * 
+ * - Redistribution of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * 
+ * - Redistribution in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * 
+ * Neither the name of Sun Microsystems, Inc. or the names of
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ * 
+ * This software is provided "AS IS," without a warranty of any kind. ALL
+ * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
+ * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
+ * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
+ * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
+ * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
+ * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
+ * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
+ * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
+ * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
+ * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ * 
+ * You acknowledge that this software is not designed or intended for use
+ * in the design, construction, operation or maintenance of any nuclear
+ * facility.
+ * 
+ * Sun gratefully acknowledges that this software was originally authored
+ * and developed by Kenneth Bradley Russell and Christopher John Kline.
+ */
+
+package com.sun.opengl.util;
+
+import com.sun.opengl.impl.*;
+
+/** Provides control over the primary display's gamma, brightness and
+    contrast controls via the hardware gamma ramp tables. Not
+    supported on all platforms or graphics hardware. <P>
+
+    Thanks to the LWJGL project for illustrating how to access gamma
+    control on the various platforms.
+*/
+
+public class Gamma {
+  private Gamma() {}
+
+  /**
+   * Sets the gamma, brightness, and contrast of the current main
+   * display. 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>
+   *
+   * 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 resetDisplayGamma}(). It is recommended to
+   * call {@link #resetDisplayGamma resetDisplayGamma} 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>
+   *
+   * This method may be called multiple times during the application's
+   * execution, but calling {@link #resetDisplayGamma
+   * resetDisplayGamma} will only reset the settings to the values
+   * before the first call to this method. <P>
+   *
+   * @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
+   */
+  public static boolean setDisplayGamma(float gamma, float brightness, float contrast) throws IllegalArgumentException {
+    return GLDrawableFactoryImpl.getFactoryImpl().setDisplayGamma(gamma, brightness, contrast);
+  }
+
+  /**
+   * Resets the gamma, brightness and contrast values for the primary
+   * display to their original values before {@link #setDisplayGamma
+   * setDisplayGamma} was called the first time. {@link
+   * #setDisplayGamma setDisplayGamma} must be called before calling
+   * this method or an unspecified exception will be thrown. While it
+   * is not explicitly required that this method be called before
+   * exiting, calling it is recommended because of the inevitable
+   * unspecified behavior during JVM teardown.
+   */
+  public static void resetDisplayGamma() {
+    GLDrawableFactoryImpl.getFactoryImpl().resetDisplayGamma();
+  }
+}