/**
* Copyright 2012 JogAmp Community. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are
* permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this list of
* conditions and the following disclaimer.
*
* 2. Redistributions 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.
*
* THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
* FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* The views and conclusions contained in the software and documentation are those of the
* authors and should not be interpreted as representing official policies, either expressed
* or implied, of JogAmp Community.
*/
package com.jogamp.opengl.util;
import com.jogamp.nativewindow.AbstractGraphicsDevice;
import com.jogamp.nativewindow.NativeSurface;
import com.jogamp.opengl.GLAnimatorControl;
import com.jogamp.opengl.GLAutoDrawable;
import com.jogamp.opengl.GLBase;
import com.jogamp.opengl.GLCapabilitiesImmutable;
import com.jogamp.opengl.GLContext;
import com.jogamp.opengl.GLDrawable;
import com.jogamp.opengl.GLEventListener;
import com.jogamp.opengl.GLException;
import com.jogamp.opengl.GLRunnable;
import com.jogamp.opengl.Threading;
import com.jogamp.common.util.locks.RecursiveLock;
import com.jogamp.opengl.GLEventListenerState;
import jogamp.opengl.Debug;
/**
* Providing utility functions dealing w/ {@link GLDrawable}s, {@link GLAutoDrawable} and their {@link GLEventListener}.
*/
public class GLDrawableUtil {
protected static final boolean DEBUG = Debug.debug("GLDrawable");
public static final boolean isAnimatorStartedOnOtherThread(final GLAnimatorControl animatorCtrl) {
return ( null != animatorCtrl ) ? animatorCtrl.isStarted() && animatorCtrl.getThread() != Thread.currentThread() : false ;
}
public static final boolean isAnimatorStarted(final GLAnimatorControl animatorCtrl) {
return ( null != animatorCtrl ) ? animatorCtrl.isStarted() : false ;
}
public static final boolean isAnimatorAnimatingOnOtherThread(final GLAnimatorControl animatorCtrl) {
return ( null != animatorCtrl ) ? animatorCtrl.isAnimating() && animatorCtrl.getThread() != Thread.currentThread() : false ;
}
public static final boolean isAnimatorAnimating(final GLAnimatorControl animatorCtrl) {
return ( null != animatorCtrl ) ? animatorCtrl.isAnimating() : false ;
}
/**
* {@link GLRunnable} to issue {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int)},
* returning <code>true</code> on {@link GLRunnable#run(GLAutoDrawable)}.
*/
public static class ReshapeGLEventListener implements GLRunnable {
private final GLEventListener listener;
private final boolean displayAfterReshape;
/**
*
* @param listener
* @param displayAfterReshape <code>true</code> to issue {@link GLEventListener#display(GLAutoDrawable)}
* after {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int)},
* otherwise false.
*/
public ReshapeGLEventListener(final GLEventListener listener, final boolean displayAfterReshape) {
this.listener = listener;
this.displayAfterReshape = displayAfterReshape;
}
@Override
public boolean run(final GLAutoDrawable drawable) {
listener.reshape(drawable, 0, 0, drawable.getSurfaceWidth(), drawable.getSurfaceHeight());
if( displayAfterReshape ) {
listener.display(drawable);
}
return true;
}
}
/**
* Moves the designated {@link GLEventListener} from {@link GLAutoDrawable} <code>src</code> to <code>dest</code>.
* If <code>preserveInitState</code> is <code>true</code>, it's initialized state is preserved
* and {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(..)} issued w/ the next {@link GLAutoDrawable#display()} call.
* <p>
* Note that it is only legal to pass <code>preserveInitState := true</code>,
* if the {@link GLContext} of both <code>src</code> and <code>dest</code> are shared, or has itself moved from <code>src</code> to <code>dest</code>.
* </p>
* <p>
* Also note that the caller is encouraged to pause an attached {@link GLAnimatorControl}.
* </p>
* @param src
* @param dest
* @param listener
* @param preserveInitState
*/
public static final void moveGLEventListener(final GLAutoDrawable src, final GLAutoDrawable dest, final GLEventListener listener, final boolean preserveInitState) {
final boolean initialized = src.getGLEventListenerInitState(listener);
if( preserveInitState ) {
src.removeGLEventListener(listener);
dest.addGLEventListener(listener);
if( initialized ) {
dest.setGLEventListenerInitState(listener, true);
dest.invoke(false, new ReshapeGLEventListener(listener, true));
}
} else {
src.disposeGLEventListener(listener, true);
dest.addGLEventListener(listener);
}
}
/**
* Moves all {@link GLEventListener} from {@link GLAutoDrawable} <code>src</code> to <code>dest</code>.
* If <code>preserveInitState</code> is <code>true</code>, it's initialized state is preserved
* and {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(..)} issued w/ the next {@link GLAutoDrawable#display()} call.
* <p>
* Note that it is only legal to pass <code>preserveInitState := true</code>,
* if the {@link GLContext} of both <code>src</code> and <code>dest</code> are shared, or has itself moved from <code>src</code> to <code>dest</code>.
* </p>
* <p>
* Also note that the caller is encouraged to pause an attached {@link GLAnimatorControl}.
* </p>
* @param src
* @param dest
* @param listener
* @param preserveInitState
*/
public static final void moveAllGLEventListener(final GLAutoDrawable src, final GLAutoDrawable dest, final boolean preserveInitState) {
for(int count = src.getGLEventListenerCount(); 0<count; count--) {
final GLEventListener listener = src.getGLEventListener(0);
moveGLEventListener(src, dest, listener, preserveInitState);
}
}
/**
* Return a heuristic value whether switching the {@link GLContext} is safe between {@link GLAutoDrawable}s,
* i.e. via {@link #swapGLContext(GLAutoDrawable, GLAutoDrawable)} or {@link #swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)}.
* <p>
* Method currently returns <code>false</code> if:
* <ul>
* <li>Switching between on- and offscreen and one of the following is <code>true</code>:
* <ul>
* <li>{@link GLCapabilitiesImmutable#getSampleBuffers() MSAA is <i>used</i>} [1] in <code>chosenCapsA</code> or <code>chosenCapsB</code></li>
* <li>{@link GLCapabilitiesImmutable#getStereo() Stereo is <i>used</i>} in <code>chosenCapsA</code> or <code>chosenCapsB</code></li>
* <li>{@link GLCapabilitiesImmutable#getAccumAlphaBits() Accumulator Buffer is <i>requested</i>} [2] in <code>requestedCaps</code></li>
* </ul></li>
* </ul>
* Otherwise method returns <code>true</code>
* </p>
* <pre>
* [1] See Bug 830: swapGLContextAndAllGLEventListener and onscreen MSAA w/ NV/GLX
* On NVidia GPUs w/ it's proprietary driver context swapping does not work if MSAA is involved
* and when swapping on- to offscreen.
* </pre>
* <pre>
* [2] On AMD GPUs w/ it's proprietary driver, requesting an accumulator buffer leads to receive an accumulator buffer configuration,
* for which context swapping does not work when swapping on- to offscreen and vice-versa, i.e. cannot make context current.
* With AMD and Mesa drivers we only receive an accumulator buffer if requested,
* where on NVidia drivers all configurations contain the accumulator buffer.
* On both drivers, NVidia and Mesa, context swapping with accumulator buffer works.
* </pre>
* @param requestedCaps requested {@link GLCapabilitiesImmutable} which are intended for usage by both {@link GLAutoDrawable}s A and B
* @param chosenCapsA chosen {@link GLCapabilitiesImmutable} of {@link GLAutoDrawable} A, which {@link GLContext} is intended to be swapped
* @param chosenCapsB chosen {@link GLCapabilitiesImmutable} of {@link GLAutoDrawable} B, which {@link GLContext} is intended to be swapped
* @see #swapGLContext(GLAutoDrawable, GLAutoDrawable)
* @see #swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)
*/
public static boolean isSwapGLContextSafe(final GLCapabilitiesImmutable requestedCaps, final GLCapabilitiesImmutable chosenCapsA, final GLCapabilitiesImmutable chosenCapsB) {
final boolean usingAccumulatorBuffer = requestedCaps.getAccumAlphaBits() > 0 ||
requestedCaps.getAccumRedBits() > 0 ||
requestedCaps.getAccumGreenBits() > 0 ||
requestedCaps.getAccumBlueBits() > 0;
if( ( chosenCapsA.isOnscreen() && !chosenCapsB.isOnscreen() || !chosenCapsA.isOnscreen() && chosenCapsB.isOnscreen() ) && // switching between on- and offscreen
(
( chosenCapsA.getSampleBuffers() || chosenCapsB.getSampleBuffers() ) || // MSAA involved
( chosenCapsA.getStereo() || chosenCapsB.getStereo() ) || // Stereo involved
usingAccumulatorBuffer // Using accumulator buffer
)
)
{
return false;
} else {
return true;
}
}
/**
* Swaps the {@link GLContext} and all {@link GLEventListener} between {@link GLAutoDrawable} <code>a</code> and <code>b</code>,
* while preserving it's initialized state, resets the GL-Viewport and issuing {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(..)}.
* <p>
* The {@link GLAutoDrawable} to {@link GLAnimatorControl} association
* is also swapped.
* </p>
* <p>
* If an {@link GLAnimatorControl} is being attached to {@link GLAutoDrawable} <code>a</code> or <code>b</code>
* and the current thread is different than {@link GLAnimatorControl#getThread() the animator's thread}, it is paused during the operation.
* </p>
* <p>
* During operation, both {@link GLAutoDrawable auto-drawable's}
* {@link GLAutoDrawable#getUpstreamLock() upstream-locks} and {@link GLAutoDrawable#getNativeSurface() surfaces} are locked,
* hence atomicity of operation is guaranteed,
* see <a href="../../../../com/jogamp/opengl/GLAutoDrawable.html#locking">GLAutoDrawable Locking</a>.
* </p>
* <p>
* Because of above mentioned locking, if this method is not performed
* on {@link GLAutoDrawable#isThreadGLCapable() a OpenGL capable thread} of <i>both</i>
* {@link GLAutoDrawable}s, it must be invoked on such an OpenGL capable thread,
* e.g. via {@link Threading#invokeOnOpenGLThread(boolean, Runnable)}.
* </p>
* @throws GLException if the {@link AbstractGraphicsDevice} are incompatible w/ each other.
* @see #isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable, GLCapabilitiesImmutable)
*/
public static final void swapGLContextAndAllGLEventListener(final GLAutoDrawable a, final GLAutoDrawable b) {
final GLEventListenerState gllsA = GLEventListenerState.moveFrom(a, true);
final GLEventListenerState gllsB = GLEventListenerState.moveFrom(b, true);
final Runnable gllsAUnlockOp = gllsA.getUnlockSurfaceOp();
final Runnable gllsBUnlockOp = gllsB.getUnlockSurfaceOp();
try {
gllsA.moveTo(b, gllsBUnlockOp);
gllsB.moveTo(a, gllsAUnlockOp);
} finally {
// guarantee unlock in case of an exception
gllsBUnlockOp.run();
gllsAUnlockOp.run();
}
}
/**
* Swaps the {@link GLContext} of given {@link GLAutoDrawable}
* and {@link GLAutoDrawable#disposeGLEventListener(GLEventListener, boolean) disposes}
* each {@link GLEventListener} w/o removing it.
* <p>
* The GL-Viewport is reset and {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(..)} issued implicit.
* </p>
* <p>
* If an {@link GLAnimatorControl} is being attached to GLAutoDrawable src or dest and the current thread is different
* than {@link GLAnimatorControl#getThread() the animator's thread}, it is paused during the operation.
* </p>
* <p>
* During operation, both {@link GLAutoDrawable auto-drawable's}
* {@link GLAutoDrawable#getUpstreamLock() upstream-locks} and {@link GLAutoDrawable#getNativeSurface() surfaces} are locked,
* hence atomicity of operation is guaranteed,
* see <a href="../../../../com/jogamp/opengl/GLAutoDrawable.html#locking">GLAutoDrawable Locking</a>.
* </p>
* <p>
* Because of above mentioned locking, if this method is not performed
* on {@link GLAutoDrawable#isThreadGLCapable() a OpenGL capable thread} of <i>both</i>
* {@link GLAutoDrawable}s, it must be invoked on such an OpenGL capable thread,
* e.g. via {@link Threading#invokeOnOpenGLThread(boolean, Runnable)}.
* </p>
* @param a
* @param b
* @see #isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable, GLCapabilitiesImmutable)
*/
public static final void swapGLContext(final GLAutoDrawable a, final GLAutoDrawable b) {
final GLAnimatorControl aAnim = a.getAnimator();
final GLAnimatorControl bAnim = b.getAnimator();
final boolean aIsPaused = isAnimatorAnimatingOnOtherThread(aAnim) && aAnim.pause();
final boolean bIsPaused = isAnimatorAnimatingOnOtherThread(bAnim) && bAnim.pause();
final RecursiveLock aUpstreamLock = a.getUpstreamLock();
final RecursiveLock bUpstreamLock = b.getUpstreamLock();
aUpstreamLock.lock();
bUpstreamLock.lock();
try {
final NativeSurface aSurface = a.getNativeSurface();
final boolean aSurfaceLocked = NativeSurface.LOCK_SURFACE_NOT_READY < aSurface.lockSurface();
if( a.isRealized() && !aSurfaceLocked ) {
throw new GLException("Could not lock realized a surface "+a);
}
final NativeSurface bSurface = b.getNativeSurface();
final boolean bSurfaceLocked = NativeSurface.LOCK_SURFACE_NOT_READY < bSurface.lockSurface();
if( b.isRealized() && !bSurfaceLocked ) {
throw new GLException("Could not lock realized b surface "+b);
}
try {
for(int i = a.getGLEventListenerCount() - 1; 0 <= i; i--) {
a.disposeGLEventListener(a.getGLEventListener(i), false);
}
for(int i = b.getGLEventListenerCount() - 1; 0 <= i; i--) {
b.disposeGLEventListener(b.getGLEventListener(i), false);
}
b.setContext( a.setContext( b.getContext(), false ), false );
} finally {
if( bSurfaceLocked ) {
bSurface.unlockSurface();
}
if( aSurfaceLocked ) {
aSurface.unlockSurface();
}
}
} finally {
bUpstreamLock.unlock();
aUpstreamLock.unlock();
}
a.invoke(true, setViewport);
b.invoke(true, setViewport);
if(aIsPaused) { aAnim.resume(); }
if(bIsPaused) { bAnim.resume(); }
}
private static final GLRunnable setViewport = new GLRunnable() {
@Override
public boolean run(final GLAutoDrawable drawable) {
drawable.getGL().glViewport(0, 0, drawable.getSurfaceWidth(), drawable.getSurfaceHeight());
return false; // issue re-display w/ new viewport!
}
};
/**
* Determines whether the chosen {@link GLCapabilitiesImmutable}
* requires a {@link GLDrawable#swapBuffers() swap-buffers}
* before reading pixels.
* <p>
* Usually one uses the {@link GLBase#getDefaultReadBuffer() default-read-buffer}
* in which case {@link GLDrawable#swapBuffers() swap-buffers} shall happen <b>after</b> calling reading pixels, the default.
* </p>
* <p>
* However, <i>multisampling</i> offscreen {@link com.jogamp.opengl.GLFBODrawable}s
* utilize {@link GLDrawable#swapBuffers() swap-buffers} to <i>downsample</i>
* the multisamples into the readable sampling sink.
* In this case, we require {@link GLDrawable#swapBuffers() swap-buffers} <b>before</b> reading pixels.
* </p>
* @return chosenCaps.isFBO() && chosenCaps.getSampleBuffers()
*/
public static final boolean swapBuffersBeforeRead(final GLCapabilitiesImmutable chosenCaps) {
return chosenCaps.isFBO() && chosenCaps.getSampleBuffers();
}
}