After more thought, realized once again that because most Java window

toolkits create persistent Java heap objects corresponding to
components that might be realized and unrealized multiple times, the
programming model of JOGL implies that GLDrawables must be persistent
with regard to the components for which they are created, and that the
setRealized(true/false) hook must be the indicator that any OpenGL
resources associated with that window are to be created or
destroyed. Removed GLDrawable.destroy(); it is now once again only
present for GLPbuffer. Fixed up various on-screen and off-screen
GLDrawable implementations. Refactored EGLDrawable implementation to
trigger on setRealized(true/false); these changes have been compiled
but not tested. Clarified documentation of GLDrawable.setRealized.


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

3 files changed, 41 insertions, 29 deletions

diff --git a/src/classes/javax/media/opengl/GLDrawable.java b/src/classes/javax/media/opengl/GLDrawable.java
index 219af33c4..50c95e688 100644
--- a/src/classes/javax/media/opengl/GLDrawable.java
+++ b/src/classes/javax/media/opengl/GLDrawable.java
@@ -83,32 +83,52 @@ public interface GLDrawable {
 
   /**
    * Indicates to on-screen GLDrawable implementations whether the
-   * underlying window has been created and can be drawn into. This
-   * method must be called from GLDrawables obtained from the
-   * GLDrawableFactory via the {@link GLDrawableFactory#getGLDrawable
-   * GLDrawableFactory.getGLDrawable()} method. It must typically be
-   * called with an argument of <code>true</code> in the
-   * <code>addNotify</code> method of components performing OpenGL
-   * rendering and with an argument of <code>false</code> in the
-   * <code>removeNotify</code> method. Calling this method has no
-   * other effects. For example, if <code>removeNotify</code> is
-   * called on a Canvas implementation for which a GLDrawable has been
-   * created, it is also necessary to destroy all OpenGL contexts
-   * associated with that GLDrawable. This is not done automatically
-   * by the implementation. It is not necessary to call
-   * <code>setRealized</code> on a GLCanvas, a GLJPanel, or a
+   * underlying window has been created and can be drawn into. End
+   * users do not need to call this method; it is not necessary to
+   * call <code>setRealized</code> on a GLCanvas, a GLJPanel, or a
    * GLPbuffer, as these perform the appropriate calls on their
    * underlying GLDrawables internally.
+   *
+   * <P>
+   *
+   * Developers implementing new OpenGL components for various window
+   * toolkits need to call this method against GLDrawables obtained
+   * from the GLDrawableFactory via the {@link
+   * GLDrawableFactory#getGLDrawable
+   * GLDrawableFactory.getGLDrawable()} method. It must typically be
+   * called with an argument of <code>true</code> when the component
+   * associated with the GLDrawable is realized and with an argument
+   * of <code>false</code> just before the component is unrealized.
+   * For the AWT, this means calling <code>setRealized(true)</code> in
+   * the <code>addNotify</code> method and with an argument of
+   * <code>false</code> in the <code>removeNotify</code> method.
+   *
+   * <P>
+   *
+   * <code>GLDrawable</code> implementations should handle multiple
+   * cycles of <code>setRealized(true)</code> /
+   * <code>setRealized(false)</code> calls. Most, if not all, Java
+   * window toolkits have a persistent object associated with a given
+   * component, regardless of whether that component is currently
+   * realized. The <CODE>GLDrawable</CODE> object associated with a
+   * particular component is intended to be similarly persistent. A
+   * <CODE>GLDrawable</CODE> is intended to be created for a given
+   * component when it is constructed and live as long as that
+   * 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.
+   *
+   * <P>
+   *
+   * Calling this method has no other effects. For example, if
+   * <code>removeNotify</code> is called on a Canvas implementation
+   * for which a GLDrawable has been created, it is also necessary to
+   * destroy all OpenGL contexts associated with that GLDrawable. This
+   * is not done automatically by the implementation.
    */
   public void setRealized(boolean realized);
 
-  /**
-   * Cleanup the complete association to the native Canvas's display,
-   * and releases all ressources.
-   * This implies a call to <code>setRealized(false)</code>
-   */
-  public void destroy();
-
   /** Returns the current width of this GLDrawable. */
   public int getWidth();
 
diff --git a/src/classes/javax/media/opengl/awt/GLCanvas.java b/src/classes/javax/media/opengl/awt/GLCanvas.java
index fe64ee90b..bce58be0f 100644
--- a/src/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/classes/javax/media/opengl/awt/GLCanvas.java
@@ -418,10 +418,6 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable {
     return drawable.getFactory();
   }
 
-  public void destroy() {
-    drawable.destroy();
-  }
-
   //----------------------------------------------------------------------
   // Internals only below this point
   //
diff --git a/src/classes/javax/media/opengl/awt/GLJPanel.java b/src/classes/javax/media/opengl/awt/GLJPanel.java
index 2eaf932a0..d5f44ff21 100644
--- a/src/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/classes/javax/media/opengl/awt/GLJPanel.java
@@ -396,10 +396,6 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable {
     return factory;
   }
 
-  public void destroy() {
-    throw new GLException("FIXME");
-  }
-
   //----------------------------------------------------------------------
   // Internals only below this point
   //