1 files changed, 41 insertions, 21 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();