diff options
Diffstat (limited to 'src/net/java/games/jogl/GLDrawable.java')
| -rw-r--r-- | src/net/java/games/jogl/GLDrawable.java | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/src/net/java/games/jogl/GLDrawable.java b/src/net/java/games/jogl/GLDrawable.java new file mode 100644 index 000000000..6197688b1 --- /dev/null +++ b/src/net/java/games/jogl/GLDrawable.java @@ -0,0 +1,183 @@ +/* + * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * - Redistribution of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistribution in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * Neither the name of Sun Microsystems, Inc. or the names of + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * This software is provided "AS IS," without a warranty of any kind. ALL + * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, + * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A + * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN + * MIDROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR + * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR + * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR + * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR + * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE + * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, + * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF + * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + * + * You acknowledge that this software is not designed or intended for use + * in the design, construction, operation or maintenance of any nuclear + * facility. + * + * Sun gratefully acknowledges that this software was originally authored + * and developed by Kenneth Bradley Russell and Christopher John Kline. + */ + +package net.java.games.jogl; + +import java.awt.Dimension; + +// FIXME: We need some way to tell when the device upon which the canvas is +// being displayed has changed (e.g., the user drags the canvas's parent +// window from one screen on multi-screen environment to another, when the +// user changes the display bit depth or screen resolution, etc). When this +// occurs, we need the canvas to reset the gl function pointer tables for the +// canvas, because the new device may have different capabilities (e.g., +// doesn't support as many opengl extensions) from the original device. This +// hook would also be useful in other GLDrawables (for example, offscreen +// buffers such as pbuffers, whose contents may or may not be invalidated when +// the display mode changes, depending on the vendor's GL implementation). +// +// Right now I'm not sure how hook into when this change occurs. There isn't +// any AWT event corresponding to a device change (as far as I can +// tell). We could constantly check the GraphicsConfiguration of the canvas's top-level +// parent to see if it has changed, but this would be very slow (we'd have to +// do it every time the context is made current). There has got to be a better +// solution, but I'm not sure what it is. + +// FIXME: Subclasses need to call resetGLFunctionAvailability() on their +// context whenever the displayChanged() function is called on our +// GLEventListeners + +/** Abstracts common functionality among the OpenGL components {@link + GLCanvas} and {@link GLJPanel}. */ + +public interface GLDrawable extends ComponentEvents { + /** Adds a {@link GLEventListener} to this drawable. If multiple + listeners are added to a given drawable, they are notified of + events in an arbitrary order. */ + public void addGLEventListener(GLEventListener listener); + + /** Removes a {@link GLEventListener} from this drawable. Note that + if this is done from within a particular drawable's {@link + GLEventListener} handler (reshape, display, etc.) that it is not + guaranteed that all other listeners will be evaluated properly + during this update cycle. */ + public void removeGLEventListener(GLEventListener listener); + + /** Sets the size of this GLDrawable. */ + public void setSize(int width, int height); + + /** Sets the size of this GLDrawable. */ + public void setSize(Dimension d); + + /** Returns the size of this GLDrawable as a newly-created Dimension + object. */ + public Dimension getSize(); + + /** Stores the size of this GLDrawable into the user-provided + Dimension object, returning that object. If the provided + Dimension is null a new one will be allocated and returned. */ + public Dimension getSize(Dimension d); + + /** Returns the {@link GL} pipeline object this GLDrawable uses. */ + public GL getGL(); + + /** Sets the {@link GL} pipeline object this GLDrawable uses. */ + public void setGL(GL gl); + + /** Returns the {@link GLU} pipeline object this GLDrawable uses. */ + public GLU getGLU(); + + /** Sets the {@link GLU} pipeline object this GLDrawable uses. */ + public void setGLU(GLU glu); + + /** Causes OpenGL rendering to be performed for this GLDrawable by + calling {@link GLEventListener#display} for all registered + {@link GLEventListener}s. Called automatically by the window + system toolkit upon receiving a repaint() request. When used in + conjunction with {@link + net.java.games.jogl.GLDrawable#setRenderingThread}, this routine may be + called manually by the application's main loop for higher + performance and better control over the rendering process. */ + public void display(); + + /** <P> Changes this GLDrawable to allow OpenGL rendering only from + the supplied thread, which must either be the current thread or + null. Attempts by other threads to perform OpenGL operations + like rendering or resizing the window will be ignored as long as + the thread is set. Setting up the rendering thread is not + required but enables the system to perform additional + optimizations, in particular when the application requires + control over the rendering loop. Before exiting, + <code>setRenderingThread(null)</code> must be called or other + threads will be unable to perform OpenGL rendering to this + drawable. Throws {@link GLException} if the rendering thread for + this drawable has been set and attempts are made to set or clear + the rendering thread from another thread, or if the passed + thread is not equal to the current thread or null. </P> + + <P> <B>NOTE:</B> Currently this routine is only advisory, which + means that on some platforms the underlying optimizations are + disabled and setting the rendering thread has no effect. + Applications should not rely on setRenderingThread to prevent + rendering from other threads. <P> + + @throws GLException if the rendering thread for this drawable has + been set by another thread or if the passed thread is not equal + to the current thread or null + */ + public void setRenderingThread(Thread currentThreadOrNull) throws GLException; + + /** Returns the rendering thread for this drawable, or null if none + has been set. */ + public Thread getRenderingThread(); + + /** Disables automatic redraws of this drawable if possible. This is + provided as an overriding mechanism for applications which + perform animation on the drawable and for which the (currently + advisory) {@link #setRenderingThread} does not provide strict + enough guarantees. Its sole purpose is to avoid deadlocks that + are unfortunately all too easy to run into when both animating a + drawable from a given thread as well as having updates performed + by the AWT event thread (repaints, etc.). When it is enabled, + repaint requests driven by the AWT will not result in the OpenGL + event listeners' display methods being called from the AWT + thread, unless (as with GLJPanel) this is the only mechanism by + which repaints are done. The necessity of this API may be + rethought in a future release. Defaults to false. */ + public void setNoAutoRedrawMode(boolean noAutoRedraws); + + /** Returns whether automatic redraws are disabled for this + drawable. Defaults to false. */ + public boolean getNoAutoRedrawMode(); + + /** Indicates whether this drawable is capable of fabricating a + subordinate offscreen drawable for advanced rendering techniques + which require offscreen hardware-accelerated surfaces. */ + public boolean canCreateOffscreenDrawable(); + + /** Creates a subordinate offscreen drawable (pbuffer) for this + drawable. This routine should only be called if {@link + #canCreateOffscreenDrawable} returns true. The passed + capabilities are matched according to the platform-dependent + pbuffer format selection algorithm, which currently can not be + overridden. */ + public GLPbuffer createOffscreenDrawable(GLCapabilities capabilities, + int initialWidth, + int initialHeight); +} |