Platform-independent GLDrawable specialization, exposing FBObject functionality.

A GLFBODrawable is uninitialized until a 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 makeCurrent() call. On-/offscreen bits are valid after setRealized(true).

MSAA is used if requested.

Double buffering is used if requested.

In MSAA mode, it always uses the implicit 2nd framebuffer sink. Hence double buffering is always the case w/ MSAA.

In non MSAA a second explicit 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. glReadPixels(..). This method also allows usage of both textures seperately.

It would be possible to implement double buffering simply using Colorbuffers with one 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 Colorbuffers and/or framebuffer is performed either in the context current hook or when swapping buffers, whatever comes first.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	GLFBODrawable.Resizeable Resizeable `GLFBODrawable` specialization

Field Summary

Modifier and Type	Field and Description
public static final int	FBOMODE_USE_TEXTURE FBO Mode Bit: Use a `TextureAttachment` for the `render colorbuffer`, see `setFBOMode(int)`.

Method Summary

Modifier and Type	Method and Description
public FBObject.Colorbuffer	Returns: the named `Colorbuffer` getColorbuffer(final int `GL#GL_FRONT` and `GL#GL_BACK` are valid buffer names bufferName) Returns the named `Colorbuffer` instance.
public FBObject	Returns: the named `FBObject` getFBObject(final int `GL#GL_FRONT` and `GL#GL_BACK` are valid buffer names bufferName) If MSAA is being used and `GL#GL_FRONT` is requested, the internal `FBObject` `sample sink` is being returned.
public int	Returns: the used FBO mode bits, mutable via `setFBOMode(int)` getFBOMode()
public int	Returns: the number of buffers (FBO) being used. 1 if not using `double buffering`, otherwise ≥ 2, depending on `setNumBuffers(int)`. getNumBuffers()
public int	Returns: the number of sample buffers if using MSAA, otherwise 0 getNumSamples()
public int	Returns: the used texture unit getTextureUnit()
public boolean	Returns: `true` if initialized, i.e. a `GLContext` is bound and made current once, otherwise `false`. isInitialized()
public void	resetSize(final GL GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation. gl) Notify this instance about upstream size change to reconfigure the `FBObject`.
public void	setFBOMode(final int custom FBO mode bits like `FBOMODE_USE_TEXTURE`. modeBits) Set the FBO mode bits used for FBO creation.
public int	Returns: the new number of buffers (FBO) used, maybe different than the requested `bufferCount` (see above) setNumBuffers(final int bufferCount) Sets the number of buffers (FBO) being used if using `double buffering`.
public void	setNumSamples(final GL GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation. gl, final int new sample size newSamples) Set the number of sample buffers if using MSAA
public void	setTextureUnit(final int the texture unit to be used unit)

Inherited from com.jogamp.opengl.GLDrawable:: createContext getChosenGLCapabilities getFactory getGLProfile getHandle getNativeSurface getRequestedGLCapabilities getSurfaceHeight getSurfaceWidth isGLOriented isRealized setRealized swapBuffers toString

Field Detail

FBOMODE_USE_TEXTURE	back to summary
public static final int FBOMODE_USE_TEXTURE FBO Mode Bit: Use a `TextureAttachment` for the `render colorbuffer`, see `setFBOMode(int)`.

Method Detail

getColorbuffer back to summary

getColorbuffer	back to summary
public FBObject.Colorbuffer getColorbuffer(final int bufferName) throws IllegalArgumentException Returns the named `Colorbuffer` instance. If MSAA is being used, only the `GL#GL_FRONT` buffer is accessible and an exception is being thrown if `GL#GL_BACK` is being requested. Depending on the `fbo mode` the resulting `Colorbuffer` is either a `TextureAttachment` if `FBOMODE_USE_TEXTURE` is set, otherwise a `ColorAttachment`. See `Colorbuffer#isTextureAttachment()`. Parameters bufferName:int `GL#GL_FRONT` and `GL#GL_BACK` are valid buffer names Returns:FBObject.Colorbuffer the named `Colorbuffer` Exceptions IllegalArgumentException: if using MSAA and `GL#GL_BACK` is requested or an illegal buffer name is being used

public FBObject.Colorbuffer getColorbuffer(final int bufferName) throws IllegalArgumentException

Returns the named Colorbuffer instance.

If MSAA is being used, only the GL#GL_FRONT buffer is accessible and an exception is being thrown if GL#GL_BACK is being requested.

Depending on the fbo mode the resulting Colorbuffer is either a TextureAttachment if FBOMODE_USE_TEXTURE is set, otherwise a ColorAttachment. See Colorbuffer#isTextureAttachment().

Parameters

bufferName:int: GL#GL_FRONT and GL#GL_BACK are valid buffer names

Returns:FBObject.Colorbuffer

the named Colorbuffer

Exceptions

IllegalArgumentException:: if using MSAA and GL#GL_BACK is requested or an illegal buffer name is being used

getFBObject back to summary

getFBObject	back to summary
public FBObject getFBObject(final int bufferName) throws IllegalArgumentException If MSAA is being used and `GL#GL_FRONT` is requested, the internal `FBObject` `sample sink` is being returned. Parameters bufferName:int `GL#GL_FRONT` and `GL#GL_BACK` are valid buffer names Returns:FBObject the named `FBObject` Exceptions IllegalArgumentException: if an illegal buffer name is being used

public FBObject getFBObject(final int bufferName) throws IllegalArgumentException

If MSAA is being used and GL#GL_FRONT is requested, the internal FBObject sample sink is being returned.

Parameters

bufferName:int: GL#GL_FRONT and GL#GL_BACK are valid buffer names

Returns:FBObject

the named FBObject

Exceptions

IllegalArgumentException:: if an illegal buffer name is being used

getFBOMode	back to summary
public int getFBOMode() Returns:int the used FBO mode bits, mutable via `setFBOMode(int)`

getNumBuffers	back to summary
public int getNumBuffers() Returns:int the number of buffers (FBO) being used. 1 if not using `double buffering`, otherwise ≥ 2, depending on `setNumBuffers(int)`.

getNumSamples	back to summary
public int getNumSamples() Returns:int the number of sample buffers if using MSAA, otherwise 0

getTextureUnit	back to summary
public int getTextureUnit() Returns:int the used texture unit

isInitialized	back to summary
public boolean isInitialized() Returns:boolean `true` if initialized, i.e. a `GLContext` is bound and made current once, otherwise `false`.

resetSize back to summary

resetSize	back to summary
public void resetSize(final GL gl) throws GLException Notify this instance about upstream size change to reconfigure the `FBObject`. Parameters gl:GL GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation. Exceptions GLException: if resize operation failed

public void resetSize(final GL gl) throws GLException

Notify this instance about upstream size change to reconfigure the FBObject.

Parameters

gl:GL: GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation.

Exceptions

GLException:: if resize operation failed

setFBOMode back to summary

setFBOMode	back to summary
public void setFBOMode(final int modeBits) throws IllegalStateException Set the FBO mode bits used for FBO creation. Default value is: `FBOMODE_USE_TEXTURE`. If `GLRendererQuirks#BuggyColorRenderbuffer` is set, `FBOMODE_USE_TEXTURE` is always added at initialization. Parameters modeBits:int custom FBO mode bits like `FBOMODE_USE_TEXTURE`. Exceptions IllegalStateException: if already initialized, see `isInitialized()`.

public void setFBOMode(final int modeBits) throws IllegalStateException

Set the FBO mode bits used for FBO creation.

Default value is: FBOMODE_USE_TEXTURE.

If GLRendererQuirks#BuggyColorRenderbuffer is set, FBOMODE_USE_TEXTURE is always added at initialization.

Parameters

modeBits:int: custom FBO mode bits like FBOMODE_USE_TEXTURE.

Exceptions

IllegalStateException:: if already initialized, see isInitialized().

setNumBuffers back to summary

setNumBuffers	back to summary
public int setNumBuffers(final int bufferCount) throws IllegalStateException, GLException Sets the number of buffers (FBO) being used if using `double buffering`. If `double buffering` is not chosen, this is a NOP. Must be called before `initialization`, otherwise an exception is thrown. Returns:int the new number of buffers (FBO) used, maybe different than the requested `bufferCount` (see above) Exceptions IllegalStateException: if already initialized, see `isInitialized()`.

public int setNumBuffers(final int bufferCount) throws IllegalStateException, GLException

Sets the number of buffers (FBO) being used if using double buffering.

If double buffering is not chosen, this is a NOP.

Must be called before initialization, otherwise an exception is thrown.

Returns:int

the new number of buffers (FBO) used, maybe different than the requested bufferCount (see above)

Exceptions

IllegalStateException:: if already initialized, see isInitialized().

setNumSamples	back to summary
public void setNumSamples(final GL gl, final int newSamples) throws GLException Set the number of sample buffers if using MSAA Parameters gl:GL GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation. newSamples:int new sample size Exceptions GLException: if resetting the FBO failed

setNumSamples

back to summary

public void setNumSamples(final GL gl, final int newSamples) throws GLException

Set the number of sample buffers if using MSAA

Parameters

gl:GL: GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation.
newSamples:int: new sample size

Exceptions

GLException:: if resetting the FBO failed

setTextureUnit	back to summary
public void setTextureUnit(final int unit) Parameters unit:int the texture unit to be used

com.jogamp.opengl back to summary

public Interface GLFBODrawable.Resizeable

Known Direct Implementers: jogamp.opengl.GLFBODrawableImpl.ResizeableImpl

Resizeable GLFBODrawable specialization

Field Summary

Inherited from com.jogamp.opengl.GLFBODrawable:: FBOMODE_USE_TEXTURE

Method Summary

Modifier and Type	Method and Description
public void	setSurfaceSize(GLContext the `GLContext` bound to this drawable, will be made current during operation A prev. current context will be make current after operation. context, int new width in pixel units newWidth, int new width in pixel units newHeight) Resize this `GLFBODrawable`'s surface.

Inherited from com.jogamp.opengl.GLFBODrawable:: getColorbuffer getFBObject getFBOMode getNumBuffers getNumSamples getTextureUnit isInitialized resetSize setFBOMode setNumBuffers setNumSamples setTextureUnit

Method Detail

setSurfaceSize back to summary

setSurfaceSize	back to summary
public void setSurfaceSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException Resize this `GLFBODrawable`'s surface. This drawable is being locked during operation. Parameters context:GLContext the `GLContext` bound to this drawable, will be made current during operation A prev. current context will be make current after operation. newWidth:int new width in pixel units newHeight:int new width in pixel units Exceptions NativeWindowException: in case the surface could no be locked GLException: in case an error during the resize operation occurred

public void setSurfaceSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException

Resize this GLFBODrawable's surface.

This drawable is being locked during operation.

Parameters

context:GLContext: the GLContext bound to this drawable, will be made current during operation A prev. current context will be make current after operation.
newWidth:int: new width in pixel units
newHeight:int: new width in pixel units

Exceptions

NativeWindowException:: in case the surface could no be locked
GLException:: in case an error during the resize operation occurred