net.java.games.jogl

Interface GLDrawable

All Superinterfaces:
ComponentEvents
Known Subinterfaces:
GLPbuffer
Known Implementing Classes:
GLCanvas, GLJPanel, GLPbufferImpl

public interface GLDrawable
extends ComponentEvents

Abstracts common functionality among the OpenGL components GLCanvas and GLJPanel.

Method Summary

void
addGLEventListener(GLEventListener listener)
Adds a GLEventListener to this drawable.
boolean
canCreateOffscreenDrawable()
Indicates whether this drawable is capable of fabricating a subordinate offscreen drawable for advanced rendering techniques which require offscreen hardware-accelerated surfaces.
GLPbuffer
createOffscreenDrawable(GLCapabilities capabilities, int initialWidth, int initialHeight)
Creates a subordinate offscreen drawable (pbuffer) for this drawable.
void
display()
Causes OpenGL rendering to be performed for this GLDrawable by calling GLEventListener.display(GLDrawable) for all registered GLEventListeners.
boolean
getAutoSwapBufferMode()
Indicates whether automatic buffer swapping is enabled for this drawable.
GL
getGL()
Returns the GL pipeline object this GLDrawable uses.
GLU
getGLU()
Returns the GLU pipeline object this GLDrawable uses.
boolean
getNoAutoRedrawMode()
Returns whether automatic redraws are disabled for this drawable.
Thread
getRenderingThread()
Returns the rendering thread for this drawable, or null if none has been set.
Dimension
getSize()
Returns the size of this GLDrawable as a newly-created Dimension object.
Dimension
getSize(Dimension d)
Stores the size of this GLDrawable into the user-provided Dimension object, returning that object.
void
removeGLEventListener(GLEventListener listener)
Removes a GLEventListener from this drawable.
void
setAutoSwapBufferMode(boolean onOrOff)
Enables or disables automatic buffer swapping for this drawable.
void
setGL(GL gl)
Sets the GL pipeline object this GLDrawable uses.
void
setGLU(GLU glu)
Sets the GLU pipeline object this GLDrawable uses.
void
setNoAutoRedrawMode(boolean noAutoRedraws)
Disables automatic redraws of this drawable if possible.
void
setRenderingThread(Thread currentThreadOrNull)
Changes this GLDrawable to allow OpenGL rendering only from the supplied thread, which must either be the current thread or null.
void
setSize(Dimension d)
Sets the size of this GLDrawable.
void
setSize(int width, int height)
Sets the size of this GLDrawable.
void
swapBuffers()
Swaps the front and back buffers of this drawable.

Methods inherited from interface net.java.games.jogl.ComponentEvents

addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener

Method Details

addGLEventListener

public void addGLEventListener(GLEventListener listener)
Adds a GLEventListener to this drawable. If multiple listeners are added to a given drawable, they are notified of events in an arbitrary order.

canCreateOffscreenDrawable

public boolean canCreateOffscreenDrawable()
Indicates whether this drawable is capable of fabricating a subordinate offscreen drawable for advanced rendering techniques which require offscreen hardware-accelerated surfaces. Note that this method is only guaranteed to return a correct result once your GLEventListener's init() method has been called.

createOffscreenDrawable

public GLPbuffer createOffscreenDrawable(GLCapabilities capabilities,
                                         int initialWidth,
                                         int initialHeight)
Creates a subordinate offscreen drawable (pbuffer) for this drawable. This routine should only be called if canCreateOffscreenDrawable() returns true. The passed capabilities are matched according to the platform-dependent pbuffer format selection algorithm, which currently can not be overridden.

display

public void display()
Causes OpenGL rendering to be performed for this GLDrawable by calling GLEventListener.display(GLDrawable) for all registered GLEventListeners. Called automatically by the window system toolkit upon receiving a repaint() request. When used in conjunction with setRenderingThread(Thread), this routine may be called manually by the application's main loop for higher performance and better control over the rendering process. It is legal to call another GLDrawable's display method from within GLEventListener.display(GLDrawable).

getAutoSwapBufferMode

public boolean getAutoSwapBufferMode()

getGL

public GL getGL()
Returns the GL pipeline object this GLDrawable uses. If this method is called outside of the 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.

getGLU

public GLU getGLU()
Returns the GLU pipeline object this GLDrawable uses.

getNoAutoRedrawMode

public boolean getNoAutoRedrawMode()
Returns whether automatic redraws are disabled for this drawable. Defaults to false.

getRenderingThread

public Thread getRenderingThread()
Returns the rendering thread for this drawable, or null if none has been set.

getSize

public Dimension getSize()
Returns the size of this GLDrawable as a newly-created Dimension object.

getSize

public Dimension getSize(Dimension d)
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.

removeGLEventListener

public void removeGLEventListener(GLEventListener listener)
Removes a GLEventListener from this drawable. Note that if this is done from within a particular drawable's GLEventListener handler (reshape, display, etc.) that it is not guaranteed that all other listeners will be evaluated properly during this update cycle.

setAutoSwapBufferMode

public void setAutoSwapBufferMode(boolean onOrOff)

setGL

public void setGL(GL gl)
Sets the 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.

setGLU

public void setGLU(GLU glu)
Sets the GLU pipeline object this GLDrawable uses.

setNoAutoRedrawMode

public void setNoAutoRedrawMode(boolean noAutoRedraws)
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) setRenderingThread(Thread) 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.

setRenderingThread

public void setRenderingThread(Thread currentThreadOrNull)
            throws GLException
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, setRenderingThread(null) must be called or other threads will be unable to perform OpenGL rendering to this drawable. Throws 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. Also throws GLException if the current thread attempts to call setRenderingThread on more than one drawable.

NOTE: 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.

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

setSize

public void setSize(Dimension d)
Sets the size of this GLDrawable.

setSize

public void setSize(int width,
                    int height)
Sets the size of this GLDrawable.

swapBuffers

public void swapBuffers()
Swaps the front and back buffers of this drawable. When automatic buffer swapping is enabled (as is the default), it is not necessary to call this method and doing so may have undefined results.