2 files changed, 18 insertions, 3 deletions
diff --git a/src/net/java/games/jogl/GLEventListener.java b/src/net/java/games/jogl/GLEventListener.java
index 8a768af87..eca1a0649 100644
--- a/src/net/java/games/jogl/GLEventListener.java
+++ b/src/net/java/games/jogl/GLEventListener.java
@@ -48,8 +48,12 @@ import java.util.EventListener;
 
 public interface GLEventListener extends EventListener {
   /** Called by the drawable immediately after the OpenGL context is
-      initialized for the first time. Can be used to perform one-time
-      OpenGL initialization such as setup of lights and display lists.
+      initialized. Can be used to perform one-time OpenGL
+      initialization such as setup of lights and display lists.  Note
+      that this method may be called more than once if the underlying
+      OpenGL context for the GLDrawable is destroyed and recreated,
+      for example if a GLCanvas is removed from the widget hierarchy
+      and later added again.
   */
   public void init(GLDrawable drawable);
   
diff --git a/src/net/java/games/jogl/GLJPanel.java b/src/net/java/games/jogl/GLJPanel.java
index 8b0c9f383..761843d75 100644
--- a/src/net/java/games/jogl/GLJPanel.java
+++ b/src/net/java/games/jogl/GLJPanel.java
@@ -64,7 +64,18 @@ import net.java.games.jogl.impl.*;
     use hardware-accelerated rendering via pbuffers and falls back on
     to software rendering if problems occur. This class can not be
     instantiated directly; use {@link GLDrawableFactory} to construct
-    them. */
+    them. <P>
+
+    Note that because this component attempts to use pbuffers for
+    rendering, and because pbuffers can not be resized, somewhat
+    surprising behavior may occur during resize operations; the {@link
+    GLEventListener#init} method may be called multiple times as the
+    pbuffer is resized to be able to cover the size of the GLJPanel.
+    This behavior is correct, as the textures and display lists for
+    the GLJPanel will have been lost during the resize operation. The
+    application should attempt to make its GLEventListener.init()
+    methods as side-effect-free as possible.
+*/
 
 public final class GLJPanel extends JPanel implements GLDrawable {
   protected static final boolean DEBUG = Debug.debug("GLJPanel");