Updated spec based on comments from rexguo on javagaming.org forums

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

3 files changed, 47 insertions, 5 deletions

diff --git a/src/classes/javax/media/opengl/GLCanvas.java b/src/classes/javax/media/opengl/GLCanvas.java
index f2ca1bf80..26a55ab3c 100644
--- a/src/classes/javax/media/opengl/GLCanvas.java
+++ b/src/classes/javax/media/opengl/GLCanvas.java
@@ -44,6 +44,8 @@ import java.awt.EventQueue;
 import java.awt.Graphics;
 import java.awt.GraphicsConfiguration;
 import java.awt.GraphicsDevice;
+import java.lang.reflect.*;
+import java.security.*;
 import com.sun.opengl.impl.*;
 
 // FIXME: Subclasses need to call resetGLFunctionAvailability() on their
@@ -121,6 +123,7 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
       create an OpenGL context for the component. */
   public void addNotify() {
     super.addNotify();
+    disableBackgroundErase();
     drawable.setRealized(true);
     if (DEBUG) {
       System.err.println("GLCanvas.addNotify()");
@@ -247,4 +250,39 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
   }
   private SwapBuffersOnEventDispatchThreadAction swapBuffersOnEventDispatchThreadAction =
     new SwapBuffersOnEventDispatchThreadAction();
+
+  // Disables the AWT's erasing of this Canvas's background on Windows
+  // in Java SE 6. This internal API is not available in previous
+  // releases, but the system property
+  // -Dsun.awt.noerasebackground=true can be specified to get similar
+  // results globally in previous releases.
+  private static boolean disableBackgroundEraseInitialized;
+  private static Method  disableBackgroundEraseMethod;
+  private void disableBackgroundErase() {
+    if (!disableBackgroundEraseInitialized) {
+      try {
+        AccessController.doPrivileged(new PrivilegedAction() {
+            public Object run() {
+              try {
+                disableBackgroundEraseMethod =
+                  getToolkit().getClass().getDeclaredMethod("disableBackgroundErase",
+                                                            new Class[] { Canvas.class });
+                disableBackgroundEraseMethod.setAccessible(true);
+              } catch (Exception e) {
+              }
+              return null;
+            }
+          });
+      } catch (Exception e) {
+      }
+      disableBackgroundEraseInitialized = true;
+    }
+    if (disableBackgroundEraseMethod != null) {
+      try {
+        disableBackgroundEraseMethod.invoke(getToolkit(), new Object[] { this });
+      } catch (Exception e) {
+        throw new GLException(e);
+      }
+    }
+  }
 }
diff --git a/src/classes/javax/media/opengl/GLContext.java b/src/classes/javax/media/opengl/GLContext.java
index 82997bc8f..970c7cb00 100644
--- a/src/classes/javax/media/opengl/GLContext.java
+++ b/src/classes/javax/media/opengl/GLContext.java
@@ -133,7 +133,9 @@ public abstract class GLContext {
   }
   
   /**
-   * Destroys this OpenGL context and frees its associated resources.
+   * Destroys this OpenGL context and frees its associated
+   * resources. The context should have been released before this
+   * method is called.
    */
   public abstract void destroy();
 
diff --git a/src/classes/javax/media/opengl/GLDrawable.java b/src/classes/javax/media/opengl/GLDrawable.java
index 5b54bd369..a1780bd2a 100644
--- a/src/classes/javax/media/opengl/GLDrawable.java
+++ b/src/classes/javax/media/opengl/GLDrawable.java
@@ -70,10 +70,12 @@ package javax.media.opengl;
 public interface GLDrawable {
   /**
    * Creates a new context for drawing to this drawable that will
-   * share display lists with the given GLContext.
+   * optionally share display lists and other server-side OpenGL
+   * objects with the specified GLContext.
    *
    * The GLContext <code>share</code> need not be associated with this
-   * GLDrawable.
+   * GLDrawable and may be null if sharing of display lists and other
+   * objects is not desired.
    */
   public GLContext createContext(GLContext shareWith);
 
@@ -112,7 +114,7 @@ public interface GLDrawable {
 
   /** Swaps the front and back buffers of this drawable. For {@link
       GLAutoDrawable} implementations, when automatic buffer swapping
-      is enabled (as is the default), it is not necessary to call this
-      method and doing so may have undefined results. */
+      is enabled (as is the default), this method is called
+      automatically and should not be called by the end user. */
   public void swapBuffers() throws GLException;
 }