Package com.jogamp.opengl

Class FBObject

java.lang.Object

com.jogamp.opengl.FBObject

public class FBObject
extends Object

Core utility class simplifying usage of framebuffer objects (FBO) with all GLProfiles.

Supports on-the-fly reconfiguration of dimension and multisample buffers via #reset(GL, int, int, int, boolean) while preserving the FBObject.Attachment references.

Integrates default read/write framebuffers via GLContext.getDefaultReadFramebuffer() and GLContext.getDefaultReadFramebuffer(), which is being hooked at GL.glBindFramebuffer(int, int) when the default (zero) framebuffer is selected.

FIXME: Implement support for FBObject.Attachment.Type.DEPTH_TEXTURE, FBObject.Attachment.Type.STENCIL_TEXTURE .

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FBObject.Attachment	Common super class of all FBO attachments
static class	FBObject.ColorAttachment	Color render buffer FBO attachment
static interface	FBObject.Colorbuffer	Generic color buffer FBO attachment, either of type FBObject.ColorAttachment or FBObject.TextureAttachment.
static class	FBObject.RenderAttachment	Other renderbuffer attachment which maybe a colorbuffer, depth or stencil.
static class	FBObject.TextureAttachment	Texture FBO attachment

Field Summary

Fields

Modifier and Type	Field	Description
static int	CHOSEN_BITS	Request current context drawable's chosen depth- or stencil-bits; value -2
static int	DEFAULT_BITS	Request default bit count for depth- or stencil buffer (depth 24 bits, stencil 8 bits), value 0
static int	MAXIMUM_BITS	Request maximum bit count for depth- or stencil buffer (depth 32 bits, stencil 16 bits), value -3
static int	REQUESTED_BITS	Request current context drawable's requested depth- or stencil-bits; value -1

Constructor Summary

Constructors

Constructor	Description
FBObject()	Creates an uninitialized FBObject instance.

Method Summary

Modifier and Type	Method	Description
FBObject.ColorAttachment	attachColorbuffer(GL gl, int attachmentPoint, boolean alpha)	Attaches a newly created and initialized FBObject.Colorbuffer, i.e.
FBObject.ColorAttachment	attachColorbuffer(GL gl, int attachmentPoint, int internalFormat)	Attaches a newly created and initialized FBObject.Colorbuffer, i.e.
FBObject.Colorbuffer	attachColorbuffer(GL gl, int attachmentPoint, FBObject.Colorbuffer colbuf)	Attaches a FBObject.Colorbuffer at the given attachment point and initializes it, if not done yet.
void	attachRenderbuffer(GL gl, int internalFormat)	Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, depending on the internalFormat.
void	attachRenderbuffer(GL gl, FBObject.Attachment.Type atype, int reqBits)	Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, selecting the internalFormat automatically.
FBObject.TextureAttachment	attachTexture2D(GL gl, int attachmentPoint, boolean alpha)	Attaches a FBObject.Colorbuffer, i.e.
FBObject.TextureAttachment	attachTexture2D(GL gl, int attachmentPoint, boolean alpha, int magFilter, int minFilter, int wrapS, int wrapT)	Attaches a FBObject.Colorbuffer, i.e.
FBObject.TextureAttachment	attachTexture2D(GL gl, int attachmentPoint, int internalFormat, int dataFormat, int dataType, int magFilter, int minFilter, int wrapS, int wrapT)	Attaches a FBObject.Colorbuffer, i.e.
void	bind(GL gl)	Bind this FBO, i.e.
FBObject.ColorAttachment	createColorAttachment(boolean alpha)	Creates a FBObject.ColorAttachment, selecting the format automatically.
static FBObject.ColorAttachment	createColorAttachment(int internalFormat, int samples, int width, int height)	Creates a FBObject.ColorAttachment, selecting the format automatically.
static FBObject.TextureAttachment	createColorTextureAttachment(int internalFormat, int width, int height, int dataFormat, int dataType, int magFilter, int minFilter, int wrapS, int wrapT)	Creates a color FBObject.TextureAttachment, i.e.
static FBObject.TextureAttachment	createColorTextureAttachment(GL gl, boolean alpha, int width, int height)	Creates a color FBObject.TextureAttachment, i.e.
static FBObject.TextureAttachment	createColorTextureAttachment(GL gl, boolean alpha, int width, int height, int magFilter, int minFilter, int wrapS, int wrapT)	Creates a color FBObject.TextureAttachment, i.e.
static FBObject.TextureAttachment	createColorTextureAttachment(GL gl, int internalFormat, int width, int height, int magFilter, int minFilter, int wrapS, int wrapT)
static FBObject.RenderAttachment	createRenderAttachment(FBObject.Attachment.Type type, int internalFormat, int samples, int width, int height)
void	destroy(GL gl)
void	detachAll(GL gl)	Detaches all FBObject.ColorAttachments, FBObject.TextureAttachments and FBObject.RenderAttachments and disposes them.
void	detachAllColorbuffer(GL gl)	Detaches all FBObject.ColorAttachments and FBObject.TextureAttachments and disposes them.
void	detachAllRenderbuffer(GL gl)
void	detachAllTexturebuffer(GL gl)	Detaches all FBObject.TextureAttachments and disposes them.
FBObject.Colorbuffer	detachColorbuffer(GL gl, int attachmentPoint, boolean dispose)	Detaches a FBObject.Colorbuffer, i.e.
void	detachRenderbuffer(GL gl, FBObject.Attachment.Type atype, boolean dispose)
void	formatToGLCapabilities(GLCapabilities caps)	Writes the internal format of the attachments to the given GLCapabilities object.
FBObject.Colorbuffer	getColorbuffer(int attachmentPoint)	Return the FBObject.Colorbuffer attachment at attachmentPoint if it is attached to this FBO, otherwise null.
FBObject.Colorbuffer	getColorbuffer(FBObject.Colorbuffer ca)	Returns the passed FBObject.Colorbuffer if it is attached to this FBO, otherwise null.
int	getColorbufferAttachmentPoint(FBObject.Colorbuffer ca)	Finds the passed FBObject.Colorbuffer within the valid range of attachment points using reference comparison only.
int	getColorbufferCount()	Return the number of attached FBObject.Colorbuffers
int	getDefaultReadBuffer()
FBObject.RenderAttachment	getDepthAttachment()	Return the depth FBObject.RenderAttachment attachment.
int	getHeight()	Returns the height
int	getMaxColorAttachments()	Returns the maximum number of colorbuffer attachments.
int	getMaxRenderbufferSize()
int	getMaxSamples()
int	getMaxTextureSize()
int	getNumSamples()	Returns the number of samples for multisampling (MSAA).
int	getReadFramebuffer()	Returns the framebuffer name to read from.
FBObject.Colorbuffer	getSamplingSink()	Return the multisampling FBObject.Colorbuffer sink, if using multisampling.
FBObject	getSamplingSinkFBO()	Return the complete multisampling FBObject sink, if using multisampling.
int	getStatus()	Note that the status may reflect an incomplete state during transition of attachments.
String	getStatusString()	return the getStatus() as a string.
static String	getStatusString(int fbStatus)
FBObject.RenderAttachment	getStencilAttachment()	Return the stencil FBObject.RenderAttachment attachment, if exist.
int	getTextureAttachmentCount()	Return the number of attached FBObject.TextureAttachments
int	getWidth()	Returns the width
int	getWriteFramebuffer()	Returns the framebuffer name to render to.
boolean	hasAttachmentUsingAlpha()	Returns true if any attached FBObject.Colorbuffer uses alpha, otherwise false.
boolean	hasFullFBOSupport()
void	init(GL gl, int newWidth, int newHeight, int newSamples)	Initializes this FBO's instance.
boolean	isBound()	Returns true if framebuffer object is bound via bind(GL), otherwise false.
boolean	isBound(GL gl)	Returns true if framebuffer object is bound via bind(GL), otherwise false.
boolean	isDepthStencilPackedFormat()
boolean	isInitialized()	Returns true if this instance has been initialized with #reset(GL, int, int) or #reset(GL, int, int, int, boolean), otherwise false
boolean	isModified()	Returns true if size, sample-count or any attachment of this instance or its sampling-sink has been modified since last sync, use, reset or resetSamplingSink.
boolean	isSamplingBufferDirty()	Returns true if the multisampling colorbuffer (msaa-buffer) has been flagged dirty by a previous call of bind(GL), otherwise false.
boolean	isStatusValid()	The status may even be valid if incomplete during transition of attachments.
void	markUnbound()	Method simply marks this FBO unbound w/o interfering w/ the bound framebuffer as perfomed by unbind(GL).
boolean	reset(GL gl, int newWidth, int newHeight, int newSamples)	Resets this FBO's instance.
boolean	resetSamplingSink(GL gl)	Manually validates the MSAA sampling sink, if used.
FBObject	setSamplingSink(FBObject newSamplingSink)	Setting this FBO sampling sink.
boolean	supportsDepth(int bits)	Returns true if GL.GL_DEPTH_COMPONENT16, GL.GL_DEPTH_COMPONENT24 or GL.GL_DEPTH_COMPONENT32 is supported, otherwise false.
boolean	supportsPackedDepthStencil()	Returns true if GL.GL_DEPTH24_STENCIL8 is supported, otherwise false.
boolean	supportsRGBA8()	Returns true if renderbuffer accepts internal format GL.GL_RGB8 and GL.GL_RGBA8, otherwise false.
boolean	supportsStencil(int bits)	Returns true if GL.GL_STENCIL_INDEX1, GL.GL_STENCIL_INDEX4, GL.GL_STENCIL_INDEX8 or GL2GL3.GL_STENCIL_INDEX16 is supported, otherwise false.
void	syncSamplingSink(GL gl)	If multisampling is being used and flagged dirty by a previous call of bind(GL) or after initialization, the msaa-buffers are sampled to it's sink #getSamplingTextureSink().
String	toString()
void	unbind(GL gl)	Unbind this FBO, i.e.
void	unuse(GL gl)	Unbind texture, ie bind 'non' texture 0
void	use(GL gl, FBObject.TextureAttachment ta)	Synchronize the sampling sink and bind the given FBObject.TextureAttachment, if not null.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_BITS

public static final int DEFAULT_BITS

Request default bit count for depth- or stencil buffer (depth 24 bits, stencil 8 bits), value 0

See Also:

Constant Field Values

REQUESTED_BITS

public static final int REQUESTED_BITS

Request current context drawable's requested depth- or stencil-bits; value -1

See Also:

Constant Field Values

CHOSEN_BITS

public static final int CHOSEN_BITS

Request current context drawable's chosen depth- or stencil-bits; value -2

See Also:

Constant Field Values

MAXIMUM_BITS

public static final int MAXIMUM_BITS

Request maximum bit count for depth- or stencil buffer (depth 32 bits, stencil 16 bits), value -3

See Also:

Constant Field Values

Constructor Detail

FBObject

public FBObject()

Creates an uninitialized FBObject instance.

Call init(GL, int, int, int) .. etc to use it.

Method Detail

createColorTextureAttachment

public static final FBObject.TextureAttachment createColorTextureAttachment(GL gl,
                                                                            boolean alpha,
                                                                            int width,
                                                                            int height)

Creates a color FBObject.TextureAttachment, i.e. type FBObject.Attachment.Type.COLOR_TEXTURE, selecting the texture data type and format automatically.

Using default min/mag filter GL.GL_NEAREST and default wrapS/wrapT GL.GL_CLAMP_TO_EDGE.

Parameters:

gl - the used GLContext's GL object

alpha - set to true if you request alpha channel, otherwise false;

width - texture width

height - texture height

Returns:

the created and uninitialized color FBObject.TextureAttachment

createColorTextureAttachment

public static final FBObject.TextureAttachment createColorTextureAttachment(GL gl,
                                                                            boolean alpha,
                                                                            int width,
                                                                            int height,
                                                                            int magFilter,
                                                                            int minFilter,
                                                                            int wrapS,
                                                                            int wrapT)

Creates a color FBObject.TextureAttachment, i.e. type FBObject.Attachment.Type.COLOR_TEXTURE, selecting the texture data type and format automatically.

For GLES3, sampling-sink format must be equal w/ the sampling-source FBObject.Colorbuffer, see details below. Implementation aligns w/ createColorAttachment(boolean) and is enforced via sampleSinkExFormatMismatch(GL).

ES3 BlitFramebuffer Requirements: OpenGL ES 3.0.2 p194: 4.3.2 Copying Pixels

 If SAMPLE_BUFFERS for the read framebuffer is greater than zero, no copy
 is performed and an INVALID_OPERATION error is generated if the formats of
 the read and draw framebuffers are not identical or if the source and destination
 rectangles are not defined with the same (X0, Y 0) and (X1, Y 1) bounds.
 

Texture and Renderbuffer format details:

 ES2 Base iFormat: OpenGL ES 2.0.24 p66: 3.7.1 Texture Image Specification, Table 3.8
   ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA

 ES3 Base iFormat: OpenGL ES 3.0.2 p125: 3.8.3 Texture Image Specification, Table 3.11
   ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA
   DEPTH_COMPONENT, STENCIL_COMPONENT, RED, RG

 ES3 Required Texture and Renderbuffer iFormat: OpenGL ES 3.0.2 p126: 3.8.3 Texture Image Specification
   - RGBA32I, RGBA32UI, RGBA16I, RGBA16UI, RGBA8, RGBA8I,
     RGBA8UI, SRGB8_ALPHA8, RGB10_A2, RGB10_A2UI, RGBA4, and
     RGB5_A1.
   - RGB8 and RGB565.
   - RG32I, RG32UI, RG16I, RG16UI, RG8, RG8I, and RG8UI.
   - R32I, R32UI, R16I, R16UI, R8, R8I, and R8UI.
 

Parameters:

gl - the used GLContext's GL object

alpha - set to true if you request alpha channel, otherwise false;

width - texture width

height - texture height

magFilter - if > 0 value for GL.GL_TEXTURE_MAG_FILTER

minFilter - if > 0 value for GL.GL_TEXTURE_MIN_FILTER

wrapS - if > 0 value for GL.GL_TEXTURE_WRAP_S

wrapT - if > 0 value for GL.GL_TEXTURE_WRAP_T

Returns:

the created and uninitialized color FBObject.TextureAttachment

createColorTextureAttachment

public static final FBObject.TextureAttachment createColorTextureAttachment(GL gl,
                                                                            int internalFormat,
                                                                            int width,
                                                                            int height,
                                                                            int magFilter,
                                                                            int minFilter,
                                                                            int wrapS,
                                                                            int wrapT)

createColorTextureAttachment

public static final FBObject.TextureAttachment createColorTextureAttachment(int internalFormat,
                                                                            int width,
                                                                            int height,
                                                                            int dataFormat,
                                                                            int dataType,
                                                                            int magFilter,
                                                                            int minFilter,
                                                                            int wrapS,
                                                                            int wrapT)

Creates a color FBObject.TextureAttachment, i.e. type FBObject.Attachment.Type.COLOR_TEXTURE.

Parameters:

internalFormat - internalFormat parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

width - texture width

height - texture height

dataFormat - format parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

dataType - type parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

magFilter - if > 0 value for GL.GL_TEXTURE_MAG_FILTER

minFilter - if > 0 value for GL.GL_TEXTURE_MIN_FILTER

wrapS - if > 0 value for GL.GL_TEXTURE_WRAP_S

wrapT - if > 0 value for GL.GL_TEXTURE_WRAP_T

Returns:

the created and uninitialized color FBObject.TextureAttachment

getColorbuffer

public final FBObject.Colorbuffer getColorbuffer(int attachmentPoint)

Return the FBObject.Colorbuffer attachment at attachmentPoint if it is attached to this FBO, otherwise null.

See Also:

#attachColorbuffer(GL, boolean), #attachColorbuffer(GL, boolean), attachTexture2D(GL, int, boolean, int, int, int, int), attachTexture2D(GL, int, int, int, int, int, int, int, int)

getColorbufferAttachmentPoint

public final int getColorbufferAttachmentPoint(FBObject.Colorbuffer ca)

Finds the passed FBObject.Colorbuffer within the valid range of attachment points using reference comparison only.

Note: Slow. Implementation uses a logN array search to save resources, i.e. not using a HashMap.

Parameters:

ca - the FBObject.Colorbuffer to look for.

Returns:

-1 if the FBObject.Colorbuffer could not be found, otherwise [0..getMaxColorAttachments()-1]

getColorbuffer

public final FBObject.Colorbuffer getColorbuffer(FBObject.Colorbuffer ca)

Returns the passed FBObject.Colorbuffer if it is attached to this FBO, otherwise null. Implementation compares the reference only.

Note: Slow. Uses getColorbufferAttachmentPoint(Colorbuffer) to determine it's attachment point to be used for getColorbuffer(int)

See Also:

#attachColorbuffer(GL, boolean), #attachColorbuffer(GL, boolean), attachTexture2D(GL, int, boolean, int, int, int, int), attachTexture2D(GL, int, int, int, int, int, int, int, int)

hasAttachmentUsingAlpha

public final boolean hasAttachmentUsingAlpha()

Returns true if any attached FBObject.Colorbuffer uses alpha, otherwise false.

init

public void init(GL gl,
                 int newWidth,
                 int newHeight,
                 int newSamples)
          throws IllegalStateException,
                 GLException

Initializes this FBO's instance.

The sampling sink is not initializes, allowing manual assignment via setSamplingSink(FBObject) if newSamples > 0.

Leaves the FBO bound

Parameters:

gl - the current GL context

newWidth - the initial width, it's minimum is capped to 1

newHeight - the initial height, it's minimum is capped to 1

newSamples - if > 0, MSAA will be used, otherwise no multisampling. Will be capped to getMaxSamples().

Throws:

IllegalStateException - if already initialized

GLException - in case of an error, i.e. size too big, etc ..

reset

public final boolean reset(GL gl,
                           int newWidth,
                           int newHeight,
                           int newSamples)
                    throws GLException,
                           IllegalStateException

Resets this FBO's instance.

In case the new parameters are compatible with the current ones no action will be performed and method returns immediately.
Otherwise all attachments will be recreated to match the new given parameters.

resetSamplingSink(GL) is being issued immediately to match the new configuration.

Leaves the FBO bound state untouched

Parameters:

gl - the current GL context

newWidth - the new width, it's minimum is capped to 1

newHeight - the new height, it's minimum is capped to 1

newSamples - if > 0, MSAA will be used, otherwise no multisampling. Will be capped to getMaxSamples().

Returns:

true if this instance has been modified, otherwise false.

Throws:

IllegalStateException - if not initialized via init(GL, int, int, int).

GLException - in case of an error, i.e. size too big, etc ..

formatToGLCapabilities

public final void formatToGLCapabilities(GLCapabilities caps)

Writes the internal format of the attachments to the given GLCapabilities object.

Parameters:

caps - the destination for format bits

getStatus

public final int getStatus()

Note that the status may reflect an incomplete state during transition of attachments.

Returns:

The FB status. GL.GL_FRAMEBUFFER_COMPLETE if ok, otherwise return GL FBO error state or -1

See Also:

#validateStatus()

getStatusString

public final String getStatusString()

return the getStatus() as a string.

getStatusString

public static final String getStatusString(int fbStatus)

isStatusValid

public final boolean isStatusValid()

The status may even be valid if incomplete during transition of attachments.

See Also:

getStatus()

attachTexture2D

public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                        int attachmentPoint,
                                                        boolean alpha)
                                                 throws GLException

Attaches a FBObject.Colorbuffer, i.e. FBObject.TextureAttachment, to this FBO's instance at the given attachment point, selecting the texture data type and format automatically.

Using default min/mag filter GL.GL_NEAREST and default wrapS/wrapT GL.GL_CLAMP_TO_EDGE.

Leaves the FBO bound.

Parameters:

gl - the current GL context

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

alpha - set to true if you request alpha channel, otherwise false;

Returns:

TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen

See Also:

#createColorTextureAttachment(GLProfile, boolean, int, int)

attachTexture2D

public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                        int attachmentPoint,
                                                        boolean alpha,
                                                        int magFilter,
                                                        int minFilter,
                                                        int wrapS,
                                                        int wrapT)
                                                 throws GLException

Attaches a FBObject.Colorbuffer, i.e. FBObject.TextureAttachment, to this FBO's instance at the given attachment point, selecting the texture data type and format automatically.

Leaves the FBO bound.

Parameters:

gl - the current GL context

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

alpha - set to true if you request alpha channel, otherwise false;

magFilter - if > 0 value for GL.GL_TEXTURE_MAG_FILTER

minFilter - if > 0 value for GL.GL_TEXTURE_MIN_FILTER

wrapS - if > 0 value for GL.GL_TEXTURE_WRAP_S

wrapT - if > 0 value for GL.GL_TEXTURE_WRAP_T

Returns:

TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen

See Also:

#createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int)

attachTexture2D

public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                        int attachmentPoint,
                                                        int internalFormat,
                                                        int dataFormat,
                                                        int dataType,
                                                        int magFilter,
                                                        int minFilter,
                                                        int wrapS,
                                                        int wrapT)
                                                 throws GLException

Attaches a FBObject.Colorbuffer, i.e. FBObject.TextureAttachment, to this FBO's instance at the given attachment point.

Leaves the FBO bound.

Parameters:

gl - the current GL context

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

internalFormat - internalFormat parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

dataFormat - format parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

dataType - type parameter to GL.glTexImage2D(int, int, int, int, int, int, int, int, long)

magFilter - if > 0 value for GL.GL_TEXTURE_MAG_FILTER

minFilter - if > 0 value for GL.GL_TEXTURE_MIN_FILTER

wrapS - if > 0 value for GL.GL_TEXTURE_WRAP_S

wrapT - if > 0 value for GL.GL_TEXTURE_WRAP_T

Returns:

TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen

See Also:

createColorTextureAttachment(int, int, int, int, int, int, int, int, int)

createColorAttachment

public final FBObject.ColorAttachment createColorAttachment(boolean alpha)

Creates a FBObject.ColorAttachment, selecting the format automatically.

For GLES3, sampling-sink FBObject.Colorbuffer format must be equal w/ the sampling-source FBObject.Colorbuffer. Implementation aligns w/ #createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int) and is enforced via sampleSinkExFormatMismatch(GL).

Parameters:

alpha - set to true if you request alpha channel, otherwise false;

Returns:

uninitialized ColorAttachment instance describing the new attached colorbuffer

createColorAttachment

public static final FBObject.ColorAttachment createColorAttachment(int internalFormat,
                                                                   int samples,
                                                                   int width,
                                                                   int height)

Creates a FBObject.ColorAttachment, selecting the format automatically.

For GLES3, sampling-sink FBObject.Colorbuffer format must be equal w/ the sampling-source FBObject.Colorbuffer. Implementation aligns w/ #createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int) and is enforced via sampleSinkExFormatMismatch(GL).

Parameters:

alpha - set to true if you request alpha channel, otherwise false;

Returns:

uninitialized ColorAttachment instance describing the new attached colorbuffer

createRenderAttachment

public static final FBObject.RenderAttachment createRenderAttachment(FBObject.Attachment.Type type,
                                                                     int internalFormat,
                                                                     int samples,
                                                                     int width,
                                                                     int height)

attachColorbuffer

public final FBObject.ColorAttachment attachColorbuffer(GL gl,
                                                        int attachmentPoint,
                                                        boolean alpha)
                                                 throws GLException

Attaches a newly created and initialized FBObject.Colorbuffer, i.e. a FBObject.ColorAttachment, at the given attachment point.

The FBObject.ColorAttachment is created using alpha if true and current sample count and size.

Leaves the FBO bound.

Parameters:

gl - the current GL context

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

alpha - set to true if you request alpha channel, otherwise false;

Returns:

ColorAttachment instance describing the new attached colorbuffer if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the colorbuffer couldn't be allocated

See Also:

createColorAttachment(boolean)

attachColorbuffer

public final FBObject.ColorAttachment attachColorbuffer(GL gl,
                                                        int attachmentPoint,
                                                        int internalFormat)
                                                 throws GLException,
                                                        IllegalArgumentException

Attaches a newly created and initialized FBObject.Colorbuffer, i.e. a FBObject.ColorAttachment, at the given attachment point.

The FBObject.ColorAttachment is created using the given internalFormat and current sample count and size.

Leaves the FBO bound.

Parameters:

gl - the current GL context

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

internalFormat - usually GL.GL_RGBA4, GL.GL_RGB5_A1, GL.GL_RGB565, GL.GL_RGB8 or GL.GL_RGBA8

Returns:

ColorAttachment instance describing the new attached colorbuffer if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the colorbuffer couldn't be allocated

IllegalArgumentException - if internalFormat doesn't reflect a colorbuffer

attachColorbuffer

public final FBObject.Colorbuffer attachColorbuffer(GL gl,
                                                    int attachmentPoint,
                                                    FBObject.Colorbuffer colbuf)
                                             throws GLException

Attaches a FBObject.Colorbuffer at the given attachment point and initializes it, if not done yet.

FBObject.Colorbuffer may be a FBObject.ColorAttachment or FBObject.TextureAttachment.

If FBObject.Colorbuffer is a FBObject.TextureAttachment and is uninitialized, i.e. it's texture name is zero, a new texture name is generated and setup w/ the texture parameter.
Otherwise, i.e. texture name is not zero, the passed TextureAttachment texA is considered complete and assumed matching this FBO requirement. A GL error may occur is the latter is untrue.

Leaves the FBO bound.

Parameters:

gl -

attachmentPoint - the color attachment point ranging from [0..getMaxColorAttachments()-1]

colbuf - the to be attached FBObject.Colorbuffer

Returns:

given FBObject.Colorbuffer instance if bound and configured successfully, otherwise GLException is thrown

Throws:

GLException - in case the colorbuffer couldn't be allocated or MSAA has been chosen in case of a FBObject.TextureAttachment

attachRenderbuffer

public final void attachRenderbuffer(GL gl,
                                     FBObject.Attachment.Type atype,
                                     int reqBits)
                              throws GLException,
                                     IllegalArgumentException

Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, selecting the internalFormat automatically.

Stencil and depth buffer can be attached only once.

In case the bit-count is not supported, the next available one is chosen, i.e. next higher (preferred) or lower bit-count.

Use getDepthAttachment() and/or getStencilAttachment() to retrieve details about the attached buffer. The details cannot be returned, since it's possible 2 buffers are being created, depth and stencil.

Leaves the FBO bound.

Parameters:

gl -

atype - either FBObject.Attachment.Type.DEPTH, FBObject.Attachment.Type.STENCIL or FBObject.Attachment.Type.DEPTH_STENCIL

reqBits - desired bits for depth or stencil, may use generic values DEFAULT_BITS, REQUESTED_BITS, CHOSEN_BITS or MAXIMUM_BITS.

Throws:

GLException - in case the renderbuffer couldn't be allocated or one is already attached.

IllegalArgumentException

See Also:

getDepthAttachment(), getStencilAttachment()

attachRenderbuffer

public final void attachRenderbuffer(GL gl,
                                     int internalFormat)
                              throws GLException,
                                     IllegalArgumentException

Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, depending on the internalFormat.

Stencil and depth buffer can be attached only once.

Use getDepthAttachment() and/or getStencilAttachment() to retrieve details about the attached buffer. The details cannot be returned, since it's possible 2 buffers are being created, depth and stencil.

Leaves the FBO bound.

Parameters:

gl - the current GL context

internalFormat - GL.GL_DEPTH_COMPONENT16, GL.GL_DEPTH_COMPONENT24, GL.GL_DEPTH_COMPONENT32, GL.GL_STENCIL_INDEX1, GL.GL_STENCIL_INDEX4, GL.GL_STENCIL_INDEX8 or GL.GL_DEPTH24_STENCIL8

Throws:

GLException - in case the renderbuffer couldn't be allocated or one is already attached.

IllegalArgumentException

See Also:

getDepthAttachment(), getStencilAttachment()

detachColorbuffer

public final FBObject.Colorbuffer detachColorbuffer(GL gl,
                                                    int attachmentPoint,
                                                    boolean dispose)
                                             throws IllegalArgumentException

Detaches a FBObject.Colorbuffer, i.e. FBObject.ColorAttachment or FBObject.TextureAttachment.

Leaves the FBO bound!

Parameters:

gl -

attachmentPoint -

dispose - true if the Colorbuffer shall be disposed

Returns:

the detached Colorbuffer

Throws:

IllegalArgumentException

detachRenderbuffer

public final void detachRenderbuffer(GL gl,
                                     FBObject.Attachment.Type atype,
                                     boolean dispose)
                              throws IllegalArgumentException

Parameters:

gl -

dispose - true if the Colorbuffer shall be disposed

reqAType - FBObject.Attachment.Type.DEPTH, FBObject.Attachment.Type.DEPTH or FBObject.Attachment.Type.DEPTH_STENCIL

Throws:

IllegalArgumentException

isDepthStencilPackedFormat

public final boolean isDepthStencilPackedFormat()

detachAll

public final void detachAll(GL gl)

Detaches all FBObject.ColorAttachments, FBObject.TextureAttachments and FBObject.RenderAttachments and disposes them.

Leaves the FBO bound, if initialized!

An attached sampling sink texture will be detached as well, see #getSamplingTextureSink().

Parameters:

gl - the current GL context

detachAllColorbuffer

public final void detachAllColorbuffer(GL gl)

Detaches all FBObject.ColorAttachments and FBObject.TextureAttachments and disposes them.

Leaves the FBO bound, if initialized!

An attached sampling sink texture will be detached as well, see #getSamplingTextureSink().

Parameters:

gl - the current GL context

detachAllTexturebuffer

public final void detachAllTexturebuffer(GL gl)

Detaches all FBObject.TextureAttachments and disposes them.

Leaves the FBO bound, if initialized!

An attached sampling sink texture will be detached as well, see #getSamplingTextureSink().

Parameters:

gl - the current GL context

detachAllRenderbuffer

public final void detachAllRenderbuffer(GL gl)

destroy

public final void destroy(GL gl)

Parameters:

gl - the current GL context

resetSamplingSink

public final boolean resetSamplingSink(GL gl)
                                throws GLException

Manually validates the MSAA sampling sink, if used.

If MSAA is being used and no sampling sink is attached via setSamplingSink(FBObject) a new sampling sink is being created.

If the sampling sink size or attributes differs from the source, its attachments are reset to match the source.

Automatically called by #reset(GL, int, int, int, boolean) and syncSamplingSink(GL).

It is recommended to call this method after initializing the FBO and attaching renderbuffer etc for the 1st time if access to sampling sink resources is required.

Leaves the FBO bound state untouched

Parameters:

gl - the current GL context

Returns:

true if this instance has been modified, otherwise false.

Throws:

GLException - in case of an error, i.e. size too big, etc ..

setSamplingSink

public FBObject setSamplingSink(FBObject newSamplingSink)
                         throws IllegalStateException,
                                GLException

Setting this FBO sampling sink.

Parameters:

newSamplingSink - the new and initialized FBO sampling sink to use, or null to remove current sampling sink

Returns:

the previous sampling sink or null if none was attached

Throws:

GLException - if this FBO doesn't use MSAA or the given sink uses MSAA itself

IllegalStateException - if the newSamplingSink is not null and not initialized

bind

public final void bind(GL gl)
                throws GLException

Bind this FBO, i.e. bind write framebuffer to getWriteFramebuffer().

If multisampling is used, it sets the read framebuffer to the sampling sink getWriteFramebuffer().

In case you have attached more than one color buffer, you may want to setup GL2ES2.glDrawBuffers(int, int[], int).

Parameters:

gl - the current GL context

Throws:

GLException

unbind

public final void unbind(GL gl)
                  throws GLException

Unbind this FBO, i.e. bind read and write framebuffer to default, see GLBase.getDefaultDrawFramebuffer().

If full FBO is supported, sets the read and write framebuffer individually to default, hence not disturbing an optional operating MSAA FBO, see GLBase.getDefaultReadFramebuffer() and GLBase.getDefaultDrawFramebuffer()

Parameters:

gl - the current GL context

Throws:

GLException

markUnbound

public final void markUnbound()

Method simply marks this FBO unbound w/o interfering w/ the bound framebuffer as perfomed by unbind(GL).

Only use this method if a subsequent unbind(GL), use(GL, TextureAttachment) or bind(GL) follows on any FBO.

isBound

public final boolean isBound(GL gl)

Returns true if framebuffer object is bound via bind(GL), otherwise false.

Method verifies the bound state via GLBase.getBoundFramebuffer(int).

Parameters:

gl - the current GL context

isBound

public final boolean isBound()

Returns true if framebuffer object is bound via bind(GL), otherwise false.

syncSamplingSink

public final void syncSamplingSink(GL gl)

If multisampling is being used and flagged dirty by a previous call of bind(GL) or after initialization, the msaa-buffers are sampled to it's sink #getSamplingTextureSink().

Method also resets the sampling sink configuration via resetSamplingSink(GL) if used and required.

Method is called automatically by use(GL, TextureAttachment).

Method always resets the framebuffer binding to default in the end. If full FBO is supported, sets the read and write framebuffer individually to default after sampling, hence not disturbing an optional operating MSAA FBO, see GLBase.getDefaultReadFramebuffer() and GLBase.getDefaultDrawFramebuffer()

In case you use this FBO w/o the GLFBODrawable and intend to employ glReadPixels(..) you may want to call glBindFramebuffer(GL.GL_READ_FRAMEBUFFER, getReadFramebuffer());

Leaves the FBO unbound.

Parameters:

gl - the current GL context

ta - FBObject.TextureAttachment to use, prev. attached w/ attachTexture2D(..)

Throws:

IllegalArgumentException

use

public final void use(GL gl,
                      FBObject.TextureAttachment ta)
               throws IllegalArgumentException

Synchronize the sampling sink and bind the given FBObject.TextureAttachment, if not null.

If using a FBObject.TextureAttachment and multiple texture units, ensure you call GL.glActiveTexture(int) first!

syncSamplingSink(GL) is being called

Leaves the FBO unbound!

Parameters:

gl - the current GL context

ta - FBObject.TextureAttachment to use, prev. attached w/ attachTexture2D(..), may be null in case no FBObject.TextureAttachment is used.

Throws:

IllegalArgumentException

unuse

public final void unuse(GL gl)

Unbind texture, ie bind 'non' texture 0

Leaves the FBO unbound.

hasFullFBOSupport

public final boolean hasFullFBOSupport()
                                throws GLException

Throws:

GLException

See Also:

GLBase.hasFullFBOSupport()

supportsRGBA8

public final boolean supportsRGBA8()
                            throws GLException

Returns true if renderbuffer accepts internal format GL.GL_RGB8 and GL.GL_RGBA8, otherwise false.

Throws:

GLException - if #init(GL) hasn't been called.

supportsDepth

public final boolean supportsDepth(int bits)
                            throws GLException

Returns true if GL.GL_DEPTH_COMPONENT16, GL.GL_DEPTH_COMPONENT24 or GL.GL_DEPTH_COMPONENT32 is supported, otherwise false.

Parameters:

bits - 16, 24 or 32 bits

Throws:

GLException - if #init(GL) hasn't been called.

supportsStencil

public final boolean supportsStencil(int bits)
                              throws GLException

Returns true if GL.GL_STENCIL_INDEX1, GL.GL_STENCIL_INDEX4, GL.GL_STENCIL_INDEX8 or GL2GL3.GL_STENCIL_INDEX16 is supported, otherwise false.

Parameters:

bits - 1, 4, 8 or 16 bits

Throws:

GLException - if #init(GL) hasn't been called.

supportsPackedDepthStencil

public final boolean supportsPackedDepthStencil()
                                         throws GLException

Returns true if GL.GL_DEPTH24_STENCIL8 is supported, otherwise false.

Throws:

GLException - if #init(GL) hasn't been called.

getMaxColorAttachments

public final int getMaxColorAttachments()
                                 throws GLException

Returns the maximum number of colorbuffer attachments.

Throws:

GLException - if #init(GL) hasn't been called.

getMaxTextureSize

public final int getMaxTextureSize()
                            throws GLException

Throws:

GLException

getMaxRenderbufferSize

public final int getMaxRenderbufferSize()
                                 throws GLException

Throws:

GLException

getMaxSamples

public final int getMaxSamples()
                        throws GLException

Throws:

GLException

See Also:

GLBase.getMaxRenderbufferSamples()

isInitialized

public final boolean isInitialized()

Returns true if this instance has been initialized with #reset(GL, int, int) or #reset(GL, int, int, int, boolean), otherwise false

getWidth

public final int getWidth()

Returns the width

getHeight

public final int getHeight()

Returns the height

getNumSamples

public final int getNumSamples()

Returns the number of samples for multisampling (MSAA). zero if no multisampling is used.

getWriteFramebuffer

public final int getWriteFramebuffer()

Returns the framebuffer name to render to.

getReadFramebuffer

public final int getReadFramebuffer()

Returns the framebuffer name to read from. Depending on multisampling, this may be a different framebuffer.

getDefaultReadBuffer

public final int getDefaultReadBuffer()

getColorbufferCount

public final int getColorbufferCount()

Return the number of attached FBObject.Colorbuffers

getTextureAttachmentCount

public final int getTextureAttachmentCount()

Return the number of attached FBObject.TextureAttachments

getStencilAttachment

public final FBObject.RenderAttachment getStencilAttachment()

Return the stencil FBObject.RenderAttachment attachment, if exist. Maybe share the same FBObject.Attachment.getName() as getDepthAttachment(), if packed depth-stencil is being used.

getDepthAttachment

public final FBObject.RenderAttachment getDepthAttachment()

Return the depth FBObject.RenderAttachment attachment. Maybe share the same FBObject.Attachment.getName() as getStencilAttachment(), if packed depth-stencil is being used.

getSamplingSinkFBO

public final FBObject getSamplingSinkFBO()

Return the complete multisampling FBObject sink, if using multisampling.

getSamplingSink

public final FBObject.Colorbuffer getSamplingSink()

Return the multisampling FBObject.Colorbuffer sink, if using multisampling.

isSamplingBufferDirty

public final boolean isSamplingBufferDirty()

Returns true if the multisampling colorbuffer (msaa-buffer) has been flagged dirty by a previous call of bind(GL), otherwise false.

isModified

public final boolean isModified()

Returns true if size, sample-count or any attachment of this instance or its sampling-sink has been modified since last sync, use, reset or resetSamplingSink.

Otherwise method returns false.

toString

public final String toString()

Overrides:

toString in class Object