Documentation updates and minor cleanups

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

11 files changed, 137 insertions, 114 deletions

diff --git a/src/net/java/games/gluegen/opengl/BuildComposablePipeline.java b/src/net/java/games/gluegen/opengl/BuildComposablePipeline.java
index eaed4a100..5c971ab8f 100644
--- a/src/net/java/games/gluegen/opengl/BuildComposablePipeline.java
+++ b/src/net/java/games/gluegen/opengl/BuildComposablePipeline.java
@@ -511,7 +511,7 @@ public class BuildComposablePipeline
     {
       output.println("/** <P> Composable pipline which wraps an underlying {@link GL} implementation,");
       output.println("    providing tracing information to a user-specified {@link java.io.PrintStream}");
-      output.println("    before after each OpenGL method call. Sample code which installs this pipeline: </P>");
+      output.println("    before and after each OpenGL method call. Sample code which installs this pipeline: </P>");
       output.println();
       output.println("<PRE>");
       output.println("     drawable.setGL(new TraceGL(drawable.getGL(), System.err));");
diff --git a/src/net/java/games/jogl/GLAutoDrawable.java b/src/net/java/games/jogl/GLAutoDrawable.java
index 71b5c6dd3..2494483f5 100755
--- a/src/net/java/games/jogl/GLAutoDrawable.java
+++ b/src/net/java/games/jogl/GLAutoDrawable.java
@@ -39,6 +39,17 @@
 
 package net.java.games.jogl;
 
+/** A higher-level abstraction than {@link GLDrawable} which supplies
+    an event based mechanism ({@link GLEventListener}) for performing
+    OpenGL rendering. A GLAutoDrawable automatically creates a primary
+    rendering context which is associated with the GLAutoDrawable for
+    the lifetime of the object. This context has the {@link
+    GLContext#setSynchronized synchronized} property enabled so that
+    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. */
+
 public interface GLAutoDrawable extends GLDrawable, ComponentEvents {
   /**
    * Returns the context associated with this drawable. The returned
@@ -59,12 +70,13 @@ public interface GLAutoDrawable extends GLDrawable, ComponentEvents {
   public void removeGLEventListener(GLEventListener listener);
 
   /** Causes OpenGL rendering to be performed for this GLAutoDrawable
-      by calling {@link GLEventListener#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 {@link GLEventListener#display}. */
+      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. */
   public void display();
 
   /** Enables or disables automatic buffer swapping for this drawable.
@@ -79,27 +91,29 @@ public interface GLAutoDrawable extends GLDrawable, ComponentEvents {
       drawable. See {@link #setAutoSwapBufferMode}. */
   public boolean getAutoSwapBufferMode();
 
-  /** Returns the {@link GL} pipeline object this GLDrawable uses.  If
-      this method is called outside of the {@link GLEventListener}'s
-      callback methods (init, display, etc.) it may return null. Users
-      should not rely on the identity of the returned GL object; for
-      example, users should not maintain a hash table with the GL
-      object as the key. Additionally, the GL object should not be
-      cached in client code, but should be re-fetched from the
-      GLDrawable at the beginning of each call to init, display,
-      etc. */
+  /** Returns the {@link GL} pipeline object this GLAutoDrawable uses.
+      If this method is called outside of the {@link
+      GLEventListener}'s callback methods (init, display, etc.) it may
+      return null. Users should not rely on the identity of the
+      returned GL object; for example, users should not maintain a
+      hash table with the GL object as the key. Additionally, the GL
+      object should not be cached in client code, but should be
+      re-fetched from the GLAutoDrawable at the beginning of each call
+      to init, display, etc. */
   public GL getGL();
 
-  /** Sets the {@link GL} pipeline object this GLDrawable uses. This
-      should only be called from within the GLEventListener's callback
-      methods, and usually only from within the init() method, in
-      order to install a composable pipeline. See the JOGL demos for
-      examples. */
+  /** Sets the {@link GL} pipeline object this GLAutoDrawable uses.
+      This should only be called from within the GLEventListener's
+      callback methods, and usually only from within the init()
+      method, in order to install a composable pipeline. See the JOGL
+      demos for examples. */
   public void setGL(GL gl);
 
-  /** Returns the {@link GLU} pipeline object this GLDrawable uses. */
+  /** Returns the {@link GLU} pipeline object this GLAutoDrawable
+      uses. */
   public GLU getGLU();
 
-  /** Sets the {@link GLU} pipeline object this GLDrawable uses. */
+  /** Sets the {@link GLU} pipeline object this GLAutoDrawable
+      uses. */
   public void setGLU(GLU glu);
 }
diff --git a/src/net/java/games/jogl/GLCanvas.java b/src/net/java/games/jogl/GLCanvas.java
index 1089a22cb..3a3a995eb 100644
--- a/src/net/java/games/jogl/GLCanvas.java
+++ b/src/net/java/games/jogl/GLCanvas.java
@@ -68,8 +68,8 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
   private boolean autoSwapBufferMode = true;
   private boolean sendReshape = false;
 
-  /** Creates a new GLCanvas object. The passed GLCapabilities must be
-      non-null and specifies the OpenGL capabilities for the
+  /** Creates a new GLCanvas component. The passed GLCapabilities must
+      be non-null and specifies the OpenGL capabilities for the
       component. The GLCapabilitiesChooser must be non-null and
       specifies the algorithm for selecting one of the available
       GLCapabilities for the component; the GLDrawableFactory uses a
@@ -167,19 +167,19 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
   }
 
   public GL getGL() {
-    return context.getGL();
+    return getContext().getGL();
   }
 
   public void setGL(GL gl) {
-    context.setGL(gl);
+    getContext().setGL(gl);
   }
 
   public GLU getGLU() {
-    return context.getGLU();
+    return getContext().getGLU();
   }
   
   public void setGLU(GLU glu) {
-    context.setGLU(glu);
+    getContext().setGLU(glu);
   }
   
   public void setAutoSwapBufferMode(boolean onOrOff) {
diff --git a/src/net/java/games/jogl/GLContext.java b/src/net/java/games/jogl/GLContext.java
index e784e1de1..7d9aa94aa 100755
--- a/src/net/java/games/jogl/GLContext.java
+++ b/src/net/java/games/jogl/GLContext.java
@@ -39,9 +39,25 @@
 
 package net.java.games.jogl;
 
+/** Abstraction for an OpenGL rendering context. In order to perform
+    OpenGL rendering, a context must be "made current" on the current
+    thread. OpenGL rendering semantics specify that only one context
+    may be current on the current thread at any given time, and also
+    that a given context may be current on only one thread at any
+    given time. Because components can be added to and removed from
+    the component hierarchy at any time, it is possible that the
+    underlying OpenGL context may need to be destroyed and recreated
+    multiple times over the lifetime of a given component. This
+    process is handled by the implementation, and the GLContext
+    abstraction provides a stable object which clients can use to
+    refer to a given context. */
+
 public abstract class GLContext {
+  /** Indicates that the context was not made current during the last call to {@link #makeCurrent makeCurrent}. */
   public static final int CONTEXT_NOT_CURRENT = 0;
+  /** Indicates that the context was made current during the last call to {@link #makeCurrent makeCurrent}. */
   public static final int CONTEXT_CURRENT     = 1;
+  /** Indicates that a newly-created context was made current during the last call to {@link #makeCurrent makeCurrent}. */
   public static final int CONTEXT_CURRENT_NEW = 2;
 
   private static ThreadLocal currentContext = new ThreadLocal();
@@ -90,7 +106,7 @@ public abstract class GLContext {
   /**
    * Releases control of this GLContext from the current thread.
    *
-   * @throw GLException if the context had not previously been made
+   * @throws GLException if the context had not previously been made
    * current on the current thread
    */
   public abstract void release() throws GLException;
@@ -118,10 +134,6 @@ public abstract class GLContext {
   
   /**
    * Destroys this OpenGL context and frees its associated resources.
-   * <P>
-   * For onscreen GLDrawables, should be used to indicate to the
-   * GLContext implementation that the underlying window has been
-   * destroyed.
    */
   public abstract void destroy();
 
@@ -135,14 +147,23 @@ public abstract class GLContext {
    */
   public abstract void setSynchronized(boolean isSynchronized);
 
-  // 'GL' and 'GLU' pipelines allow instrumenting the actual
-  // pipeline for debugging, tracing, etc.
-
+  /**
+   * Returns the GL pipeline object for this GLContext.
+   */
   public abstract GL getGL();
 
+  /**
+   * Returns the GLU pipeline object for this GLContext.
+   */
   public abstract GLU getGLU();
 
+  /**
+   * Sets the GL pipeline object for this GLContext.
+   */
   public abstract void setGL(GL gl);
 
+  /**
+   * Sets the GLU pipeline object for this GLContext.
+   */
   public abstract void setGLU(GLU glu);
 }
diff --git a/src/net/java/games/jogl/GLDrawable.java b/src/net/java/games/jogl/GLDrawable.java
index 3eea12448..6d8457d92 100644
--- a/src/net/java/games/jogl/GLDrawable.java
+++ b/src/net/java/games/jogl/GLDrawable.java
@@ -61,6 +61,12 @@ package net.java.games.jogl;
 // 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
+    create an OpenGL context, but all implementations of {@link
+    GLAutoDrawable} do so upon creation. */
+
 public interface GLDrawable {
   /**
    * Creates a new context for drawing to this drawable that will
diff --git a/src/net/java/games/jogl/GLDrawableFactory.java b/src/net/java/games/jogl/GLDrawableFactory.java
index 8f0749d24..a8211dedd 100644
--- a/src/net/java/games/jogl/GLDrawableFactory.java
+++ b/src/net/java/games/jogl/GLDrawableFactory.java
@@ -45,8 +45,7 @@ import java.awt.GraphicsEnvironment;
 import net.java.games.jogl.impl.*;
 
 /** <P> Provides a virtual machine- and operating system-independent
-    mechanism for creating {@link net.java.games.jogl.GLCanvas} and {@link
-    net.java.games.jogl.GLJPanel} objects. </P>
+    mechanism for creating {@link GLDrawable}s. </P>
 
     <P> The {@link net.java.games.jogl.GLCapabilities} objects passed in to the
     various factory methods are used as a hint for the properties of
@@ -66,7 +65,9 @@ import net.java.games.jogl.impl.*;
     process are (unfortunately) left unspecified for now. The current
     implementation will cause a {@link GLException} to be raised
     during the first repaint of the {@link GLCanvas} or {@link
-    GLJPanel} if the capabilities can not be met. </P>
+    GLJPanel} if the capabilities can not be met. Pbuffers are always
+    created immediately and their creation will fail with a {@link
+    GLException} if errors occur. </P>
 */
 
 public abstract class GLDrawableFactory {
@@ -123,7 +124,7 @@ public abstract class GLDrawableFactory {
    * returns null on platforms on which the OpenGL pixel format
    * selection process is performed later.
    *
-   * @see java.awt.Canvas(java.awt.GraphicsConfiguration)
+   * @see java.awt.Canvas#Canvas(java.awt.GraphicsConfiguration)
    */
   public abstract GraphicsConfiguration
     chooseGraphicsConfiguration(GLCapabilities capabilities,
@@ -140,10 +141,10 @@ public abstract class GLDrawableFactory {
    * passed GLCapabilitiesChooser object is null, uses a
    * DefaultGLCapabilitiesChooser instance.
    *
-   * @throw IllegalArgumentException if the passed target is either
-   *        null or its data type is not supported by this GLDrawableFactory.
-   * @throw GLException if any window system-specific errors caused
-   *        the creation of the GLDrawable to fail.
+   * @throws IllegalArgumentException if the passed target is either
+   *         null or its data type is not supported by this GLDrawableFactory.
+   * @throws GLException if any window system-specific errors caused
+   *         the creation of the GLDrawable to fail.
    */
   public abstract GLDrawable getGLDrawable(Object target,
                                            GLCapabilities capabilities,
diff --git a/src/net/java/games/jogl/GLEventListener.java b/src/net/java/games/jogl/GLEventListener.java
index a680716a0..05053bf01 100644
--- a/src/net/java/games/jogl/GLEventListener.java
+++ b/src/net/java/games/jogl/GLEventListener.java
@@ -42,25 +42,26 @@ package net.java.games.jogl;
 import java.util.EventListener;
 
 /** Declares events which client code can use to manage OpenGL
-    rendering into a {@link GLDrawable}. At the time any of these
+    rendering into a {@link GLAutoDrawable}. At the time any of these
     methods is called, the drawable has made its associated OpenGL
     context current, so it is valid to make OpenGL calls. */
 
 public interface GLEventListener extends EventListener {
   /** Called by the drawable immediately after the OpenGL context is
       initialized. Can be used to perform one-time OpenGL
-      initialization such as setup of lights and display lists.  Note
+      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 GLAutoDrawable is destroyed and recreated,
-      for example if a GLCanvas is removed from the widget hierarchy
-      and later added again.
+      OpenGL context for the GLAutoDrawable is destroyed and
+      recreated, for example if a GLCanvas is removed from the widget
+      hierarchy and later added again.
   */
   public void init(GLAutoDrawable drawable);
   
   /** Called by the drawable to initiate OpenGL rendering by the
       client. After all GLEventListeners have been notified of a
-      display event, the drawable will swap its buffers if necessary.
-  */
+      display event, the drawable will swap its buffers if {@link
+      GLAutoDrawable#setAutoSwapBufferMode setAutoSwapBufferMode} is
+      enabled. */
   public void display(GLAutoDrawable drawable);
 
   /** Called by the drawable during the first repaint after the
diff --git a/src/net/java/games/jogl/GLJPanel.java b/src/net/java/games/jogl/GLJPanel.java
index f07a79902..856bfd306 100644
--- a/src/net/java/games/jogl/GLJPanel.java
+++ b/src/net/java/games/jogl/GLJPanel.java
@@ -74,12 +74,17 @@ import net.java.games.jogl.impl.*;
     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.
+    methods as side-effect-free as possible. <P>
+
+    The GLJPanel can be made transparent by creating it with a
+    GLCapabilities object with alpha bits specified and calling {@link
+    #setOpaque}(false). Pixels with resulting OpenGL alpha values less
+    than 1.0 will be overlaid on any underlying Java2D rendering.
 */
 
 public class GLJPanel extends JPanel implements GLAutoDrawable {
-  protected static final boolean DEBUG = Debug.debug("GLJPanel");
-  protected static final boolean VERBOSE = Debug.verbose();
+  private static final boolean DEBUG = Debug.debug("GLJPanel");
+  private static final boolean VERBOSE = Debug.verbose();
 
   private GLDrawableHelper drawableHelper = new GLDrawableHelper();
   private volatile boolean isInitialized;
@@ -162,9 +167,9 @@ public class GLJPanel extends JPanel implements GLAutoDrawable {
     }
   }
 
-  /** Overridden from JComponent; calls {@link
-      GLEventListener#display}. Should not be invoked by applications
-      directly. */
+  /** Overridden from JComponent; calls event listeners' {@link
+      GLEventListener#display display} methods. Should not be invoked
+      by applications directly. */
   public void paintComponent(Graphics g) {
     if (shouldInitialize) {
       initialize();
@@ -182,6 +187,8 @@ public class GLJPanel extends JPanel implements GLAutoDrawable {
     }
   }
 
+  /** Overridden from JPanel; used to indicate that an OpenGL context
+      may be created for the component. */
   public void addNotify() {
     super.addNotify();
     shouldInitialize = true;
@@ -215,10 +222,10 @@ public class GLJPanel extends JPanel implements GLAutoDrawable {
     super.removeNotify();
   }
 
-  /** Overridden from Canvas; causes {@link GLDrawableHelper#reshape}
-      to be called on all registered {@link GLEventListener}s. Called
-      automatically by the AWT; should not be invoked by applications
-      directly. */
+  /** Overridden from Canvas; causes {@link GLEventListener#reshape
+      reshape} to be called on all registered {@link
+      GLEventListener}s. Called automatically by the AWT; should not
+      be invoked by applications directly. */
   public void reshape(int x, int y, int width, int height) {
     super.reshape(x, y, width, height);
 
@@ -338,44 +345,26 @@ public class GLJPanel extends JPanel implements GLAutoDrawable {
   }
 
   public GL getGL() {
-    if (!hardwareAccelerationDisabled) {
-      if (pbuffer == null) {
-        return null;
-      }
-      return pbuffer.getGL();
-    } else {
-      if (offscreenContext == null) {
-        return null;
-      }
-      return offscreenContext.getGL();
-    }
+    GLContext context = getContext();
+    return (context == null) ? null : context.getGL();
   }
 
   public void setGL(GL gl) {
-    if (!hardwareAccelerationDisabled) {
-      if (pbuffer != null) {
-        pbuffer.setGL(gl);
-      }
-    } else {
-      if (offscreenContext != null) {
-        offscreenContext.setGL(gl);
-      }
+    GLContext context = getContext();
+    if (context != null) {
+      context.setGL(gl);
     }
   }
 
   public GLU getGLU() {
-    if (!hardwareAccelerationDisabled) {
-      return pbuffer.getGLU();
-    } else {
-      return offscreenContext.getGLU();
-    }
+    GLContext context = getContext();
+    return (context == null) ? null : context.getGLU();
   }
   
   public void setGLU(GLU glu) {
-    if (!hardwareAccelerationDisabled) {
-      pbuffer.setGLU(glu);
-    } else {
-      offscreenContext.setGLU(glu);
+    GLContext context = getContext();
+    if (context != null) {
+      context.setGLU(glu);
     }
   }
   
diff --git a/src/net/java/games/jogl/GLPbuffer.java b/src/net/java/games/jogl/GLPbuffer.java
index 4dd3c1e00..074d8b3c4 100644
--- a/src/net/java/games/jogl/GLPbuffer.java
+++ b/src/net/java/games/jogl/GLPbuffer.java
@@ -39,12 +39,13 @@
 
 package net.java.games.jogl;
 
-/** Offscreen rendering support via pbuffers. This class adds very
-    little functionality over the GLDrawable class; the only methods
-    are those which allow access to the pbuffer's contents as a
-    texture map and which enable offscreen rendering to floating-point
-    buffers. These methods are currently highly experimental and may
-    be removed in a future release. */
+/** Provides offscreen rendering support via pbuffers. The principal
+    addition of this interface is a {@link #destroy} method to
+    deallocate the pbuffer and its associated resources. It also
+    contains experimental methods for accessing the pbuffer's contents
+    as a texture map and enabling rendering to floating-point frame
+    buffers. These methods are not guaranteed to be supported on all
+    platforms and may change or be removed in a future release. */
 
 public interface GLPbuffer extends GLAutoDrawable {
   /** Indicates the GL_APPLE_float_pixels extension is being used for this pbuffer. */
@@ -71,12 +72,12 @@ public interface GLPbuffer extends GLAutoDrawable {
   /** Unbinds the pbuffer from its internal texture target. */
   public void releaseTexture();
 
-  /** Queries initialization status of this pBuffer. */
-  public boolean isInitialized();
-
   /** Destroys the native resources associated with this pbuffer. It
       is not valid to call display() or any other routines on this
-      pbuffer after it has been destroyed. */
+      pbuffer after it has been destroyed. Before destroying the
+      pbuffer, the application must destroy any additional OpenGL
+      contexts which have been created for the pbuffer via {@link
+      #createContext}. */
   public void destroy();
 
   /** Indicates which vendor's extension is being used to support
diff --git a/src/net/java/games/jogl/impl/GLPbufferImpl.java b/src/net/java/games/jogl/impl/GLPbufferImpl.java
index 7583abe89..3aa50d7b7 100644
--- a/src/net/java/games/jogl/impl/GLPbufferImpl.java
+++ b/src/net/java/games/jogl/impl/GLPbufferImpl.java
@@ -55,7 +55,6 @@ public class GLPbufferImpl implements GLPbuffer {
   private GLDrawableImpl pbufferDrawable;
   private GLContextImpl context;
   private GLDrawableHelper drawableHelper = new GLDrawableHelper();
-  private boolean isInitialized=false;
   private int floatMode;
 
   public GLPbufferImpl(GLDrawableImpl pbufferDrawable,
@@ -108,19 +107,19 @@ public class GLPbufferImpl implements GLPbuffer {
   }
 
   public GL getGL() {
-    return context.getGL();
+    return getContext().getGL();
   }
 
   public void setGL(GL gl) {
-    context.setGL(gl);
+    getContext().setGL(gl);
   }
 
   public GLU getGLU() {
-    return context.getGLU();
+    return getContext().getGLU();
   }
   
   public void setGLU(GLU glu) {
-    context.setGLU(glu);
+    getContext().setGLU(glu);
   }
   
   public void setAutoSwapBufferMode(boolean onOrOff) {
@@ -176,13 +175,6 @@ public class GLPbufferImpl implements GLPbuffer {
   public void removePropertyChangeListener(String propertyName,
                                            PropertyChangeListener listener) {}
 
-    /** Queries initialization status of this pBuffer.
-     * @return true if initialized
-     * */
-  public boolean isInitialized(){
-    return isInitialized;
-  }
-
   public void destroy() {
     context.destroy();
     pbufferDrawable.destroy();
@@ -225,7 +217,6 @@ public class GLPbufferImpl implements GLPbuffer {
 
   class InitAction implements Runnable {
     public void run() {
-      isInitialized=true;
       floatMode = context.getFloatingPointMode();
       drawableHelper.init(GLPbufferImpl.this);
     }
diff --git a/src/net/java/games/jogl/impl/x11/X11PbufferGLDrawable.java b/src/net/java/games/jogl/impl/x11/X11PbufferGLDrawable.java
index 44c755384..8bbde41da 100644
--- a/src/net/java/games/jogl/impl/x11/X11PbufferGLDrawable.java
+++ b/src/net/java/games/jogl/impl/x11/X11PbufferGLDrawable.java
@@ -168,7 +168,6 @@ public class X11PbufferGLDrawable extends X11GLDrawable {
       int screen = 0; // FIXME: provide way to specify this?
 
       if (capabilities.getOffscreenFloatingPointBuffers()) {
-        // FIXME: 
         String glXExtensions = GLX.glXQueryExtensionsString(display, screen);
         if (glXExtensions == null ||
             glXExtensions.indexOf("GLX_NV_float_buffer") < 0) {