aboutsummaryrefslogtreecommitdiffstats
path: root/src/classes/javax/media
diff options
context:
space:
mode:
authorKenneth Russel <[email protected]>2008-12-29 06:05:43 +0000
committerKenneth Russel <[email protected]>2008-12-29 06:05:43 +0000
commit20f707ac1cadf7ee6a1a14117a58be96672af809 (patch)
treefaac8507b929ad2ab20844dcbb0a048934996e86 /src/classes/javax/media
parent00b865b520d91cee6eda142cfcdf1fad4ab5a8c5 (diff)
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
Diffstat (limited to 'src/classes/javax/media')
-rw-r--r--src/classes/javax/media/opengl/GLDrawable.java62
-rw-r--r--src/classes/javax/media/opengl/awt/GLCanvas.java4
-rw-r--r--src/classes/javax/media/opengl/awt/GLJPanel.java4
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
//