javax.media.opengl.GLFBODrawable Maven / Gradle / Ivy
/**
* 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 javax.media.opengl;
import javax.media.nativewindow.NativeWindowException;
import com.jogamp.opengl.FBObject;
import com.jogamp.opengl.FBObject.TextureAttachment;
/**
* Platform-independent {@link GLDrawable} specialization,
* exposing {@link FBObject} functionality.
*
*
* A {@link GLFBODrawable} is uninitialized until a {@link GLContext} is bound
* and made current the first time, hence only then it's capabilities fully reflect expectations,
* i.e. color, depth, stencil and MSAA bits will be valid only after the first {@link GLContext#makeCurrent() makeCurrent()} call.
* On-/offscreen bits are valid after {@link #setRealized(boolean) setRealized(true)}.
*
*
*
* MSAA is used if {@link GLCapabilitiesImmutable#getNumSamples() requested}.
*
*
* Double buffering is used if {@link GLCapabilitiesImmutable#getDoubleBuffered() requested}.
*
*
* In MSAA mode, it always uses the implicit 2nd {@link FBObject framebuffer} {@link FBObject#getSamplingSinkFBO() sink}.
* Hence double buffering is always the case w/ MSAA.
*
*
* In non MSAA a second explicit {@link FBObject framebuffer} is being used.
* This method allows compliance w/ the spec, i.e. read and draw framebuffer selection
* and double buffer usage for e.g. {@link GL#glReadPixels(int, int, int, int, int, int, java.nio.Buffer) glReadPixels(..)}.
* This method also allows usage of both textures seperately.
*
*
* It would be possible to implement double buffering simply using
* {@link TextureAttachment}s with one {@link FBObject framebuffer}.
* This would require mode selection and hence complicate the API. Besides, it would
* not support differentiation of read and write framebuffer and hence not be spec compliant.
*
*
* Actual swapping of the {@link TextureAttachment texture}s and/or {@link FBObject framebuffer}
* is performed either in the {@link jogamp.opengl.GLContextImpl#contextMadeCurrent(boolean) context current hook}
* or when {@link jogamp.opengl.GLDrawableImpl#swapBuffersImpl(boolean) swapping buffers}, whatever comes first.
*
*/
public interface GLFBODrawable extends GLDrawable {
// public enum DoubleBufferMode { NONE, TEXTURE, FBO }; // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
/**
* @return true if initialized, i.e. a {@link GLContext} is bound and made current once, otherwise false.
*/
public boolean isInitialized();
/**
* Notify this instance about upstream size change
* to reconfigure the {@link FBObject}.
* @param gl GL context object bound to this drawable, will be made current during operation.
* A prev. current context will be make current after operation.
* @throws GLException if resize operation failed
*/
void resetSize(GL gl) throws GLException;
/**
* @return the used texture unit
*/
int getTextureUnit();
/**
*
* @param unit the texture unit to be used
*/
void setTextureUnit(int unit);
/**
* Set the number of sample buffers if using MSAA
*
* @param gl GL context object bound to this drawable, will be made current during operation.
* A prev. current context will be make current after operation.
* @param newSamples new sample size
* @throws GLException if resetting the FBO failed
*/
void setNumSamples(GL gl, int newSamples) throws GLException;
/**
* @return the number of sample buffers if using MSAA, otherwise 0
*/
int getNumSamples();
/**
* Sets the number of buffers (FBO) being used if using {@link GLCapabilities#getDoubleBuffered() double buffering}.
*
* If {@link GLCapabilities#getDoubleBuffered() double buffering} is not chosen, this is a NOP.
*
*
* Must be called before {@link #isInitialized() initialization}, otherwise an exception is thrown.
*
* @return the new number of buffers (FBO) used, maybe different than the requested bufferCount (see above)
* @throws GLException if already initialized, see {@link #isInitialized()}.
*/
int setNumBuffers(int bufferCount) throws GLException;
/**
* @return the number of buffers (FBO) being used. 1 if not using {@link GLCapabilities#getDoubleBuffered() double buffering},
* otherwise ≥ 2, depending on {@link #setNumBuffers(int)}.
*/
int getNumBuffers();
/**
* @return the used {@link DoubleBufferMode}
*/
// DoubleBufferMode getDoubleBufferMode(); // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
/**
* Sets the {@link DoubleBufferMode}. Must be called before {@link #isInitialized() initialization},
* otherwise an exception is thrown.
*
* This call has no effect is MSAA is selected, since MSAA always forces the mode to {@link DoubleBufferMode#FBO FBO}.
* Also setting the mode to {@link DoubleBufferMode#NONE NONE} where double buffering is {@link GLCapabilitiesImmutable#getDoubleBuffered() requested}
* or setting a double buffering mode w/o {@link GLCapabilitiesImmutable#getDoubleBuffered() request} will be ignored.
*
*
* Since {@link DoubleBufferMode#TEXTURE TEXTURE} mode is currently not implemented, this method has no effect.
*
* @throws GLException if already initialized, see {@link #isInitialized()}.
*/
// void setDoubleBufferMode(DoubleBufferMode mode) throws GLException; // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
/**
* If MSAA is being used and {@link GL#GL_FRONT} is requested,
* the internal {@link FBObject} {@link FBObject#getSamplingSinkFBO() sample sink} is being returned.
*
* @param bufferName {@link GL#GL_FRONT} and {@link GL#GL_BACK} are valid buffer names
* @return the named {@link FBObject}
* @throws IllegalArgumentException if an illegal buffer name is being used
*/
FBObject getFBObject(int bufferName) throws IllegalArgumentException;
/**
* Returns the named texture buffer.
*
* If MSAA is being used, only the {@link GL#GL_FRONT} buffer is accessible
* and an exception is being thrown if {@link GL#GL_BACK} is being requested.
*
* @param bufferName {@link GL#GL_FRONT} and {@link GL#GL_BACK} are valid buffer names
* @return the named {@link TextureAttachment}
* @throws IllegalArgumentException if using MSAA and {@link GL#GL_BACK} is requested or an illegal buffer name is being used
*/
FBObject.TextureAttachment getTextureBuffer(int bufferName) throws IllegalArgumentException;
/** Resizeable {@link GLFBODrawable} specialization */
public interface Resizeable extends GLFBODrawable {
/**
* Resize this drawable.
*
* This drawable is being locked during operation.
*
* @param context the {@link GLContext} bound to this drawable, will be made current during operation
* A prev. current context will be make current after operation.
* @param newWidth
* @param newHeight
* @throws NativeWindowException in case the surface could no be locked
* @throws GLException in case an error during the resize operation occurred
*/
void setSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException;
}
}