Removed GLAutoDrawable's dispose(boolean regenerate), and added it's semantic to it's documentation, plus references to the multihead display change

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

6 files changed, 86 insertions, 101 deletions

diff --git a/src/jogl/classes/com/sun/opengl/impl/GLPbufferImpl.java b/src/jogl/classes/com/sun/opengl/impl/GLPbufferImpl.java
index 30109dcf6..e414fbc8e 100644
--- a/src/jogl/classes/com/sun/opengl/impl/GLPbufferImpl.java
+++ b/src/jogl/classes/com/sun/opengl/impl/GLPbufferImpl.java
@@ -224,13 +224,8 @@ public class GLPbufferImpl implements GLPbuffer {
                                            PropertyChangeListener listener) {}
                                            */
 
-  public void dispose(boolean regenerate) {
-    // Offscreen ..
-    // FIXME: action required ?
-  }
-
   public void destroy() {
-    // FIXME: not calling event listeners ..
+    // FIXME: not calling event listeners .. see GLAutoDrawable spec
     if (Threading.isSingleThreaded() &&
         !Threading.isOpenGLThread()) {
       Threading.invokeOnOpenGLThread(destroyAction);
diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index 90a914a40..ed0e8bdca 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -50,17 +50,57 @@ import javax.media.opengl.glu.*;
     calls to {@link GLContext#makeCurrent makeCurrent} will block if
     the context is current on another thread. This allows the internal
     GLContext for the GLAutoDrawable to be used both by the event
-    based rendering mechanism as well by end users directly.<p>
+    based rendering mechanism as well by end users directly.<P>
 
     The implementation shall initialize itself as soon as possible,
-    ie if an attached window is become visible.
-    The it shall call {@link GLDrawable#setRealized setRealized(true)}
-    and create the GLContext.
-    The followup {@link #display display} call will ensure that all
-    {@link GLEventListener#init init} calls for
-    registered {@link GLEventListener}s will be made.
+    ie if the attached {@link javax.media.nativewindow.NativeWindow NativeWindow} is become visible. 
+    The following protocol shall be satisfied:
+    <ul>
+        <li> Notify {@link GLDrawable} to validate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.</li>
+        <li> Create the new {@link GLContext}.</li>
+        <li> Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
+             registered {@link GLEventListener}s. This can be done immediatly, or with the followup {@link #display display(..)} call.</li>
+    </ul><P>
+
+    Another implementation detail is the drawable reconfiguration. One use case is where a window is being 
+    dragged to another screen with a different pixel configuration, ie {@link GLCapabilities}. The implementation 
+    shall be able to detect such cases in conjunction with the associated {@link javax.media.nativewindow.NativeWindow NativeWindow}.<br>
+    For example, AWT's {@link java.awt.Canvas} 's {@link java.awt.Canvas#getGraphicsConfiguration getGraphicsConfiguration()}
+    is capable to determine a display device change. This is demonstrated within {@link javax.media.opengl.awt.GLCanvas}'s 
+    {@link javax.media.opengl.awt.GLCanvas#getGraphicsConfiguration getGraphicsConfiguration()} 
+    specialization. Another demonstration is NEWT's {@link javax.media.nativewindow.NativeWindow NativeWindow} 
+    implementation on the the Windows platform, which captures the native platform's <i>WM_DEVMODECHANGE</i> message.<br>
+    All OpenGL resources shall be regenerated, while the drawable's {@link GLCapabilities} has 
+    to be choosen again. The following protocol shall be satisfied.
+    <ul>
+        <li> Controlled disposal:</li>
+        <ul>
+            <li> Dispose all OpenGL resources by calling {@link GLEventListener#dispose dispose(..)} for all
+                 registered {@link GLEventListener}s.</li>
+            <li> Destroy the {@link GLContext}.</li>
+            <li> Notify {@link GLDrawable} of the invalid state by calling {@link GLDrawable#setRealized setRealized(false)}.</li>
+        </ul>
+        <li> Controlled regeneration:</li>
+        <ul>
+            <li> Notify {@link GLDrawable} to revalidate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.</li>
+            <li> Create the new {@link GLContext}.</li>
+            <li> Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
+                 registered {@link GLEventListener}s. This can be done immediatly, or with the followup {@link #display display(..)} call.</li>
+        </ul>
+    </ul>
   */
 public interface GLAutoDrawable extends GLDrawable {
+  /** FIXME:
+  ** Invalid state, the resources are not yet ready to render. *
+  public static final int STATE_INVALID = 0;
+
+  ** Valid state, all resources are ready to render, 
+      and all registered {@link GLEventListener#init init(..)} are called. *
+  public static final int STATE_VALID = 1;
+
+  ** Destroying state, currently executing the {@link #destroy()} method. *
+  public static final int STATE_DESTROYING = 2; */
+
   /**
    * Returns the context associated with this drawable. The returned
    * context will be synchronized.
@@ -85,44 +125,35 @@ public interface GLAutoDrawable extends GLDrawable {
       during this update cycle. */
   public void removeGLEventListener(GLEventListener listener);
 
-  /** Destroys the GLContext associated with this GLAutoDrawable. 
-      Causes disposing of all OpenGL resources
-      by calling {@link GLEventListener#dispose dispose} for all
-      registered {@link GLEventListener}s,
-      and then destroys the GLContext.
-      The implementation shall also call {@link GLDrawable#setRealized setRealized(false)}
-      to notify GLDrawable.<p>
-
-      If the argument <code>regenerate</code> is true,
-      the implementation shall call {@link GLDrawable#setRealized setRealized(true)}
-      and create a new GLContext.
-      The followup {@link #display display} call will ensure that all
-      {@link GLEventListener#init init} calls for
-      registered {@link GLEventListener}s will be made.*/
-  public void dispose(boolean regenerate);
+  /** FIXME: Returns the current state, 
+      {@link #STATE_INVALID}, {@link #STATE_VALID} or {@link #STATE_DESTROYING}.
+      Tool to determine, e.g. if a {@link GLEventListener#dispose dispose(..)}
+      event is send in the context of the destruction of this GLAutoDrawable.
+  public int getCurrentState(); */
 
   /** Destroys all resources associated with this GLAutoDrawable,
       inclusive the GLContext.
       If a window is attached to it's implementation, it shall be closed.
       Causes disposing of all OpenGL resources
-      by calling {@link GLEventListener#dispose dispose} for all
+      by calling {@link GLEventListener#dispose dispose(..)} for all
       registered {@link GLEventListener}s. Called automatically by the
       window system toolkit upon receiving a destroy notification. This
       routine may be called manually. */
   public void destroy();
 
   /** Causes OpenGL rendering to be performed for this GLAutoDrawable
-      by calling {@link GLEventListener#display display} for all
+      by calling {@link GLEventListener#display display(..)} for all
       registered {@link GLEventListener}s. Called automatically by the
       window system toolkit upon receiving a repaint() request. this
       routine may be called manually for better control over the
       rendering process. It is legal to call another GLAutoDrawable's
       display method from within the {@link GLEventListener#display
-      display} callback.<p>
+      display(..)} callback.<p>
       In case of a new generated OpenGL context, 
-      the implementation shall call {@link GLEventListener#init init} for all
+      the implementation shall call {@link GLEventListener#init init(..)} for all
       registered {@link GLEventListener}s <i>before</i> making the 
-      actual {@link GLEventListener#display display} calls.*/
+      actual {@link GLEventListener#display display(..)} calls,
+      in case this has not been done yet.*/
   public void display();
 
   /** Enables or disables automatic buffer swapping for this drawable.
@@ -130,7 +161,7 @@ public interface GLAutoDrawable extends GLDrawable {
       GLEventListeners have been called for a display() event, the
       front and back buffers are swapped, displaying the results of
       the render. When disabled, the user is responsible for calling
-      {@link #swapBuffers} manually. */
+      {@link #swapBuffers(..)} manually. */
   public void setAutoSwapBufferMode(boolean onOrOff);
 
   /** Indicates whether automatic buffer swapping is enabled for this
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index 023689a82..0cde24ff9 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -41,28 +41,6 @@ package javax.media.opengl;
 
 import javax.media.nativewindow.*;
 
-// FIXME: We need some way to tell when the device upon which the canvas is
-// being displayed has changed (e.g., the user drags the canvas's parent
-// window from one screen on multi-screen environment to another, when the
-// user changes the display bit depth or screen resolution, etc). When this
-// occurs, we need the canvas to reset the gl function pointer tables for the
-// canvas, because the new device may have different capabilities (e.g.,
-// doesn't support as many opengl extensions) from the original device. This
-// hook would also be useful in other GLDrawables (for example, offscreen
-// buffers such as pbuffers, whose contents may or may not be invalidated when
-// the display mode changes, depending on the vendor's GL implementation).
-//
-// Right now I'm not sure how hook into when this change occurs. There isn't
-// any AWT event corresponding to a device change (as far as I can
-// tell). We could constantly check the GraphicsConfiguration of the canvas's top-level
-// parent to see if it has changed, but this would be very slow (we'd have to
-// do it every time the context is made current). There has got to be a better
-// solution, but I'm not sure what it is.
-
-// FIXME: Subclasses need to call resetGLFunctionAvailability() on their
-// context whenever the displayChanged() function is called on our
-// GLEventListeners
-
 /** An abstraction for an OpenGL rendering target. A GLDrawable's
     primary functionality is to create OpenGL contexts which can be
     used to perform rendering. A GLDrawable does not automatically
@@ -119,13 +97,21 @@ public interface GLDrawable {
    * component. <code>setRealized</code> allows the
    * <code>GLDrawable</code> to re-initialize and destroy any
    * associated resources as the component becomes realized and
-   * unrealized, respectively.<br><br>
-   * The minimum implementation shall at least call 
-   * {@link NativeWindow#lockSurface() NativeWindow.lockSurface()} and if successfull 
-   * release it with {@link NativeWindow#unlockSurface() NativeWindow.unlockSurface()}
-   * in case realized is true.
-   * This is important since this resolve the window/surface handles,
-   * which are assumed to be present after <code>setRealized(true)</code>.
+   * unrealized, respectively.
+   *
+   * <P>
+   *
+   * With an argument of <code>true</code>, 
+   * the minimum implementation shall call 
+   * {@link NativeWindow#lockSurface() NativeWindow's lockSurface()} and if successfull:
+   * <ul>
+   *    <li> Update the {@link GLCapabilities}, which are associated with 
+   *         the attached {@link NativeWindow}'s {@link AbstractGraphicsConfiguration}.</li>
+   *    <li> Release the lock with {@link NativeWindow#unlockSurface() NativeWindow's unlockSurface()}.</li>
+   * </ul><br>
+   * This is important since {@link NativeWindow#lockSurface() NativeWindow's lockSurface()}
+   * ensures resolving the window/surface handles, and the drawable's {@link GLCapabilities}
+   * might have changed.
    *
    * <P>
    *
@@ -154,6 +140,9 @@ public interface GLDrawable {
       On some platforms, the pixel format is not directly associated
       with the drawable; a best attempt is made to return a reasonable
       value in this case. <br>
+      This object shall be directly associated to the attached {@link NativeWindow}'s 
+      {@link AbstractGraphicsConfiguration}, and if changes are necessary,
+      they should reflect those as well.
       @return A copy of the queried object.
     */
   public GLCapabilities getChosenGLCapabilities();
diff --git a/src/jogl/classes/javax/media/opengl/GLEventListener.java b/src/jogl/classes/javax/media/opengl/GLEventListener.java
index 08e4a84fb..15fae4a39 100644
--- a/src/jogl/classes/javax/media/opengl/GLEventListener.java
+++ b/src/jogl/classes/javax/media/opengl/GLEventListener.java
@@ -58,14 +58,14 @@ public interface GLEventListener extends EventListener {
   */
   public void init(GLAutoDrawable drawable);
   
-  /** Called by the drawable before the OpenGL context is
-      destroyed by an external event. 
-      This happens through notification by the 
-      native window manager, ie window close, but also 
-      manually by calling {@link GLAutoDrawable#destroy destroy}.
-      Shall be used to perform final release of all OpenGL
+  /** Notifies the listener to perform the release of all OpenGL
       resources per GLContext, such as memory buffers and GLSL programs.<P>
 
+      Called by the drawable before the OpenGL context is
+      destroyed by an external event, like a reconfiguration of the
+      {@link GLAutoDrawable} closing an attached window,
+      but also manually by calling {@link GLAutoDrawable#destroy destroy}.<P>
+
       Note that this event does not imply the end of life of the application.
       It could be produced with a followup call to {@link #init(GLAutoDrawable)}
       in case the GLContext has been recreated, 
@@ -89,34 +89,4 @@ public interface GLEventListener extends EventListener {
       client may not have to do anything in this method.
   */
   public void reshape(GLAutoDrawable drawable, int x, int y, int width, int height);
-
-  /** Called by the drawable when the display mode or the display device
-      associated with the GLAutoDrawable has changed. The two boolean parameters
-      indicate the types of change(s) that have occurred. 
-      <P>
-
-      An example of a display <i>mode</i> change is when the bit depth changes (e.g.,
-      from 32-bit to 16-bit color) on monitor upon which the GLAutoDrawable is
-      currently being displayed. <p>
-
-      An example of a display <i>device</i> change is when the user drags the
-      window containing the GLAutoDrawable from one monitor to another in a
-      multiple-monitor setup. <p>
-
-      The reason that this function handles both types of changes (instead of
-      handling mode and device changes in separate methods) is so that
-      applications have the opportunity to respond to display changes in the most
-      efficient manner. For example, the application may need make fewer
-      adjustments to compensate for a device change if it knows that the mode
-      on the new device is identical the previous mode.<p>
-
-      Note that this method is for application logic purpose only,
-      all necessary OpenGL specific reconfiguration are made through
-      {@link #dispose(GLAutoDrawable)} and {@link #init(GLAutoDrawable)},
-      if necessary.<p>
-
-      <b>NOTE: Implementations are not required to implement this method.  The
-        Reference Implementation DOES NOT IMPLEMENT this method.</b>
-  */
-  public void displayChanged(GLAutoDrawable drawable, boolean modeChanged, boolean deviceChanged);
 }
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index fa242ef08..8ea2e9ddf 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -330,7 +330,7 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable {
     }
   }
 
-  public void dispose(boolean regenerate) {
+  protected void dispose(boolean regenerate) {
     if(DEBUG) {
         Exception ex1 = new Exception("dispose("+regenerate+") - start");
         ex1.printStackTrace();
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index 2e7bbda64..825d11347 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -204,7 +204,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable {
     }
   }
 
-  public synchronized void dispose(boolean regenerate) {
+  protected void dispose(boolean regenerate) {
     if(DEBUG) {
         Exception ex1 = new Exception("dispose("+regenerate+") - start");
         ex1.printStackTrace();