diff options
Diffstat (limited to 'src/net/java/games/jogl')
| -rwxr-xr-x | src/net/java/games/jogl/GLAutoDrawable.java | 58 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLCanvas.java | 12 | ||||
| -rwxr-xr-x | src/net/java/games/jogl/GLContext.java | 37 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLDrawable.java | 6 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLDrawableFactory.java | 17 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLEventListener.java | 15 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLJPanel.java | 65 | ||||
| -rw-r--r-- | src/net/java/games/jogl/GLPbuffer.java | 21 | ||||
| -rw-r--r-- | src/net/java/games/jogl/impl/GLPbufferImpl.java | 17 | ||||
| -rw-r--r-- | src/net/java/games/jogl/impl/x11/X11PbufferGLDrawable.java | 1 |
10 files changed, 136 insertions, 113 deletions
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) { |