The implementation shall initialize itself as soon as possible, ie if the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible/realized. The following protocol shall be satisfied:
Another implementation detail is the drawable reconfiguration. One use case is where a window is being
dragged to another screen with a different pixel configuration, ie {@link GLCapabilities}. The implementation
shall be able to detect such cases in conjunction with the associated {@link javax.media.nativewindow.NativeSurface NativeSurface}.
For example, AWT's {@link java.awt.Canvas} 's {@link java.awt.Canvas#getGraphicsConfiguration getGraphicsConfiguration()}
is capable to determine a display device change. This is demonstrated within {@link javax.media.opengl.awt.GLCanvas}'s
and NEWT's AWTCanvas {@link javax.media.opengl.awt.GLCanvas#getGraphicsConfiguration getGraphicsConfiguration()}
specialization. Another demonstration is NEWT's {@link javax.media.nativewindow.NativeWindow NativeWindow}
implementation on the Windows platform, which utilizes the native platform's MonitorFromWindow(HWND) function.
All OpenGL resources shall be regenerated, while the drawable's {@link GLCapabilities} has
to be choosen again. The following protocol shall be satisfied.
However, to not introduce to much breakage with older applications and because of the situation
mentioned above, the boolean system property jogl.screenchange.action will control the
screen change action as follows:
-Djogl.screenchange.action=false Disable the drawable reconfiguration (the default)
-Djogl.screenchange.action=true Enable the drawable reconfiguration
*/
public interface GLAutoDrawable extends GLDrawable {
/** Flag reflecting wheather the drawable reconfiguration will be issued in
* case a screen device change occured, e.g. in a multihead environment,
* where you drag the window to another monitor. */
public static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true);
/**
* Returns the context associated with this drawable. The returned
* context will be synchronized.
* Don't rely on it's identity, the context may change.
*/
public GLContext getContext();
/**
* Associate a new context to this drawable.
*/
public void setContext(GLContext context);
/** Adds a {@link GLEventListener} to the end of this drawable queue.
The listeners are notified of events in the order of the queue. */
public void addGLEventListener(GLEventListener listener);
/**
* Adds a {@link GLEventListener} at the given index of this drawable queue.
* The listeners are notified of events in the order of the queue.
* @param index Position where the listener will be inserted.
* Should be within (0 <= index && index <= size()).
* An index value of -1 is interpreted as the end of the list, size().
* @param listener The GLEventListener object to be inserted
* @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
*/
public void addGLEventListener(int index, GLEventListener listener)
throws IndexOutOfBoundsException;
/** 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);
/**
* * Registers the usage of an animator, an {@link javax.media.opengl.GLAnimatorControl} implementation. * The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not.
* This method shall be called by an animator implementation only,
* e.g. {@link com.jogamp.opengl.util.Animator#add(javax.media.opengl.GLAutoDrawable)}, passing it's control implementation,
* and {@link com.jogamp.opengl.util.Animator#remove(javax.media.opengl.GLAutoDrawable)}, passing null.
* Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.
null reference indicates no animator is using
* this GLAutoDrawable,GLAutoDrawable.
*
* @throws GLException if an animator is already registered.
* @see #display()
* @see #invoke(boolean, GLRunnable)
* @see javax.media.opengl.GLAnimatorControl
*/
public abstract void setAnimator(GLAnimatorControl animatorControl) throws GLException;
/**
* @return the registered {@link javax.media.opengl.GLAnimatorControl} implementation, using this GLAutoDrawable.
*
* @see #setAnimator(javax.media.opengl.GLAnimatorControl)
* @see javax.media.opengl.GLAnimatorControl
*/
public GLAnimatorControl getAnimator();
/**
* * Enqueues a one-shot {@link javax.media.opengl.GLRunnable GLRunnable}, * which will be executed with the next {@link #display()} call.
*
* If no {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating (default),
* or if the current thread is the animator thread,
* a {@link #display()} call is issued after enqueue the GLRunnable.
* No extra synchronization is performed in case wait is true, since it is executed in the current thread.
* If an {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating,
* no {@link #display()} call is issued, since the animator thread performs it.
* If wait is true, the implementation waits until the GLRunnable is executed.
*
* Causes OpenGL rendering to be performed for this GLAutoDrawable * in the following order: *
* May be called periodically by a running {@link javax.media.opengl.GLAnimatorControl} implementation,
* which must register itself with {@link #setAnimator(javax.media.opengl.GLAnimatorControl)}.
* Called automatically by the window system toolkit upon receiving a repaint() request,
* except an {@link javax.media.opengl.GLAnimatorControl} implementation {@link javax.media.opengl.GLAnimatorControl#isAnimating()}.
* This routine may also 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.
** In case of a new generated OpenGL context, * the implementation shall call {@link GLEventListener#init init(..)} for all * registered {@link GLEventListener}s before making the * actual {@link GLEventListener#display display(..)} calls, * in case this has not been done yet.
* * @see #setAnimator(javax.media.opengl.GLAnimatorControl) */ public void display(); /** Enables or disables automatic buffer swapping for this drawable. By default this property is set to true; when true, after all GLEventListeners have been called for a display() event, the front and back buffers are swapped, displaying the results of the render. When disabled, the user is responsible for calling {@link #swapBuffers(..)} manually. */ public void setAutoSwapBufferMode(boolean enable); /** Indicates whether automatic buffer swapping is enabled for this drawable. See {@link #setAutoSwapBufferMode}. */ public boolean getAutoSwapBufferMode(); /** * @param flags Additional context creation flags. * * @see GLContext#setContextCreationFlags(int) * @see GLContext#enableGLDebugMessage(boolean) */ public void setContextCreationFlags(int flags); /** * @return Additional context creation flags */ public int getContextCreationFlags(); /** 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 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. @return the set GL pipeline or null if not successful */ public GL setGL(GL gl); }