From 77521f233ff052096b25d9899bf3618fdc668740 Mon Sep 17 00:00:00 2001 From: Kenneth Russel Date: Tue, 19 Jul 2005 06:59:40 +0000 Subject: 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 --- .../gluegen/opengl/BuildComposablePipeline.java | 2 +- src/net/java/games/jogl/GLAutoDrawable.java | 58 +++++++++++-------- src/net/java/games/jogl/GLCanvas.java | 12 ++-- src/net/java/games/jogl/GLContext.java | 37 +++++++++--- src/net/java/games/jogl/GLDrawable.java | 6 ++ src/net/java/games/jogl/GLDrawableFactory.java | 17 +++--- src/net/java/games/jogl/GLEventListener.java | 15 ++--- src/net/java/games/jogl/GLJPanel.java | 65 +++++++++------------- src/net/java/games/jogl/GLPbuffer.java | 21 +++---- src/net/java/games/jogl/impl/GLPbufferImpl.java | 17 ++---- .../games/jogl/impl/x11/X11PbufferGLDrawable.java | 1 - 11 files changed, 137 insertions(+), 114 deletions(-) (limited to 'src/net/java/games') 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("/**

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:

"); + output.println(" before and after each OpenGL method call. Sample code which installs this pipeline:

"); output.println(); output.println("
");
       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.
-   * 

- * 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.*; /**

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.

+ mechanism for creating {@link GLDrawable}s.

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.

+ 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.

*/ 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.

+ + 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) { -- cgit v1.2.3