org.j3d.aviatrix3d
Class MRTOffscreenTexture2D

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.NodeComponent
          org.j3d.aviatrix3d.Texture
              org.j3d.aviatrix3d.MRTTexture2D
                  org.j3d.aviatrix3d.MRTOffscreenTexture2D

All Implemented Interfaces:

java.lang.Comparable, Cullable, DeletableRenderable, ObjectRenderable, OffscreenBufferRenderable, OffscreenCullable, OffscreenRenderTargetRenderable, Renderable, TransparentObjectRenderable, TransparentRenderable

public class MRTOffscreenTexture2D
extends MRTTexture2D
implements OffscreenBufferRenderable, OffscreenCullable

Describes the texture that is rendered to an offscreen buffer with the ability to have multiple render targets.

Due to the requirements for OpenGL 2.0, this will only work with frame buffer objects and not Pbuffers. Usage:

Since the format information is provided as part of the GLCapabilities instance, normally there is no need for it to be passed into the constructor like the other texture types do. The logic for determing the format is as follows using the depth bit values:

   if the alpha is non-zero
       if blue is non zero
           format = RGBA
       else if red is non-zero
           format = intensity-alpha
       else
           format = alpha
   else
       if blue is non-zero
           format = RGB
       else
           format = intensity
 

If this logic does not cover what you wish the texture to be, then there is an overloaded constructor that can take the explicit format definition that you wish to use. Note that if you wish to create a depth texture, this does not cover that case and you need to explicitly set the format to Texture.FORMAT_DEPTH_COMPONENT.

Since an offscreen rendering process has a completely different set of viewing parameters to the main scene, we have to include almost everything here as well. A complete viewing environment must be set up to deal with the texture rendering.

Note:

The current implementation does not work if you use this when using the null sort stage. A further limitation is that if this is used as part of a background (eg ShapeBackground) it will not be rendered correctly.

TODO:
If the scene is set but without root geometry, then the root geometry added later, then the update handler is not correctly dealt with. It never gets set. To overcome this, make sure you set a root group node before setting the scene, even if it is just a proxy value.

Internationalisation Resource Names

• capsReqdMsg: Error message when attempting to construct an instance of this object without GLCapabilities.
• nullLayersArrayMsg: Error message when the (internal) caller tries to call getParents() with a null array reference.
• invalidNumTargetsMsg: The number of render targets supplied is less than one.
• invalidTargetRangeMsg: Request for a target index that is negative or greater than the number of targets.
• invalidDimensionMsg Either the width or height value given to the class is not positive

Version:

$Revision: 2.14 $

Author:

Justin Couch

Field Summary

Fields inherited from class org.j3d.aviatrix3d.MRTTexture2D

bufferData, height

Fields inherited from class org.j3d.aviatrix3d.Texture

ANISOTROPIC_MODE_NONE, ANISOTROPIC_MODE_SINGLE, anisotropicDegree, anisotropicMode, BM_CLAMP, BM_CLAMP_TO_BOUNDARY, BM_CLAMP_TO_EDGE, BM_MIRRORED_REPEAT, BM_WRAP, borderColor, boundaryModeS, COMPARE_FUNCTION_GEQUAL, COMPARE_FUNCTION_LEQUAL, COMPARE_MODE_NONE, COMPARE_MODE_R2TEX, compareFunction, compareMode, depthComponentMode, format, FORMAT_ALPHA, FORMAT_DEPTH_COMPONENT, FORMAT_INTENSITY, FORMAT_INTENSITY_ALPHA, FORMAT_LUMINANCE, FORMAT_LUMINANCE_ALPHA, FORMAT_RGB, FORMAT_RGBA, GENERATE_MIPMAP, GENERATE_MIPMAP_DONT_CARE, GENERATE_MIPMAP_FASTEST, GENERATE_MIPMAP_HINT, GENERATE_MIPMAP_NICEST, generateMipMap, generateMipMapHint, imageChanged, magFilter, MAGFILTER_BASE_LEVEL_LINEAR, MAGFILTER_BASE_LEVEL_POINT, MAGFILTER_FASTEST, MAGFILTER_LINEAR_DETAIL, MAGFILTER_LINEAR_DETAIL_ALPHA, MAGFILTER_LINEAR_DETAIL_RGB, MAGFILTER_NICEST, minFilter, MINFILTER_BASE_LEVEL_LINEAR, MINFILTER_BASE_LEVEL_POINT, MINFILTER_FASTEST, MINFILTER_MULTI_LEVEL_LINEAR, MINFILTER_MULTI_LEVEL_POINT, MINFILTER_NICEST, mipMapMode, MODE_BASE_LEVEL, MODE_MIPMAP, numSources, priority, sources, stateChanged, textureIdMap, textureType, UPDATE_BUFFER_ALL, UPDATE_BUFFER_LAST, UPDATE_DISCARD_OVERWRITES, updateManagers, updateStrategy, width

Fields inherited from class org.j3d.aviatrix3d.NodeComponent

lastParent, liveCount, parentList

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.rendering.OffscreenBufferRenderable

FORMAT_ALPHA, FORMAT_DEPTH_COMPONENT, FORMAT_INTENSITY, FORMAT_LUMINANCE, FORMAT_LUMINANCE_ALPHA, FORMAT_RGB, FORMAT_RGBA

Constructor Summary

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, boolean unclampColorRange, int width, int height, int numTargets)
Constructs an offscreen texture that fits the given setup.

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, boolean unclampColorRange, int width, int height, int numTargets, boolean separateDepthTexture)
Constructs an offscreen texture that fits the given setup.

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, boolean unclampColorRange, int width, int height, int fmt, int numTargets, boolean separateDepthTexture)
Constructs an offscreen texture that fits the given setup and provides a specific format that overrides the automatic determination.

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, int width, int height, int numTargets)
Constructs an offscreen texture that fits the given setup.

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, int width, int height, int numTargets, boolean separateDepthTexture)
Constructs an offscreen texture that fits the given setup.

MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps, int width, int height, int format, int numTargets)
Constructs an offscreen texture that fits the given setup and provides a specific format that overrides the automatic determination.

Method Summary

protected void	checkForCyclicChild(SceneGraphObject parent) Check to see if this node is the same reference as the passed node that is a parent of this node.
int	compareTo(Texture tex) Compares this object with the specified object for order.
boolean	equals(Texture tex) Compares this object with the specified object to check for equivalence.
void	getClearColor(float[] col) Set the background colour that this surface should be cleared to before the drawing step.
LayerCullable	getCullableLayer(int layerIndex) Get the cullable layer child that for the given layer index.
OffscreenRenderTargetRenderable	getDepthRenderable() If a separate depth render target has been requested, return the renderable for that object now.
MRTTexture2D	getDepthRenderTarget() If the texture was configured with a separate offscreen depth texture from the colour texture, get that texture representation.
int	getFormat(int level) Get the format for this texture.
javax.media.opengl.GLCapabilities	getGLSetup() Deprecated. Use MRTTexture2D.getBufferSetup() Always returns null
void	getLayers(Layer[] layers) Fetch the current layers that are set.
int	getNumRenderTargets() Get the number of render targets that this offscreen renderable manages.
OffscreenBufferRenderable	getOffscreenRenderable() Fetch the renderable that this offscreen cullable will draw to.
MRTTexture2D	getRenderTarget(int index) Get the numbered render target.
OffscreenRenderTargetRenderable	getRenderTargetRenderable(int index) Get the child render target at the given index.
boolean	hasBufferResized() Check to see if this buffer has resized since the last time it was used.
boolean	hasSeparateDepthRenderable() Check to see if the depth buffer has its own separate renderable object.
boolean	isChildRenderTarget() Check to see if this is a child render target of a parent multiple render target offscreen buffer.
boolean	isRepaintRequired() Get the current state of the repainting enabled flag.
int	numCullableChildren() Returns the number of valid cullable children to process.
int	numLayers() Get the number of layers that are currently set.
void	resize(int w, int h) Resize this buffer to a new window.
void	setClearColor(float r, float g, float b, float a) Set the background colour that this surface should be cleared to before the drawing step.
void	setLayers(Layer[] layers, int numLayers) Set the collection of geometry that should be rendered to this texture.
protected void	setLive(boolean state) Notification that this object is live now.
void	setRepaintRequired(boolean enable) Set this texture as requiring a repaint for the next frame.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.

Methods inherited from class org.j3d.aviatrix3d.MRTTexture2D

getBoundaryModeT, getBuffer, getBufferSetup, getHeight, getRenderTargetIndex, postRender, registerBuffer, render, setBoundaryModeT, setSources, unregisterBuffer

Methods inherited from class org.j3d.aviatrix3d.Texture

cleanup, compareTo, equals, getAnisotropicFilterDegree, getAnisotropicFilterMode, getBorderColor, getBoundaryModeS, getCompareFunction, getCompareMode, getDepthFormat, getFormat, getGenerateMipMap, getGenerateMipMapHint, getMagFilter, getMinFilter, getPriority, getTextureType, getUpdateStrategy, getWidth, hasTransparency, setAnisotropicFilterDegree, setAnisotropicFilterMode, setBorderColor, setBoundaryModeS, setCompareFunction, setCompareMode, setDepthFormat, setGenerateMipMap, setGenerateMipMapHint, setMagFilter, setMinFilter, setPriority, setUpdateStrategy

Methods inherited from class org.j3d.aviatrix3d.NodeComponent

addParent, getParents, numParents, removeParent

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicParent, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setUserData

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.j3d.aviatrix3d.rendering.OffscreenBufferRenderable

getFormat

Methods inherited from interface org.j3d.aviatrix3d.rendering.OffscreenRenderTargetRenderable

getBuffer, getBufferSetup, getHeight, getWidth, registerBuffer, unregisterBuffer

Methods inherited from interface org.j3d.aviatrix3d.rendering.Renderable

equals

Methods inherited from interface java.lang.Comparable

compareTo

Constructor Detail

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             int width,
                             int height,
                             int numTargets)

Constructs an offscreen texture that fits the given setup. All values must be valid and non-negative. Floating point colour buffers are disabled and no seperate depth target is generated.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

width - The width of the texture in pixels

height - The height of the texture in pixels

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             int width,
                             int height,
                             int numTargets,
                             boolean separateDepthTexture)

Constructs an offscreen texture that fits the given setup. All values must be valid and non-negative. Floating point colour buffers are disabled and no seperate depth target is generated.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

width - The width of the texture in pixels

height - The height of the texture in pixels

separateDepthTexture - True is a separate depth texture render target should be created

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             boolean unclampColorRange,
                             int width,
                             int height,
                             int numTargets)

Constructs an offscreen texture that fits the given setup. All values must be valid and non-negative.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

unclampColorRange - true to make use of vendor-specific extensions for floating point colour buffers

width - The width of the texture in pixels

height - The height of the texture in pixels

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             boolean unclampColorRange,
                             int width,
                             int height,
                             int numTargets,
                             boolean separateDepthTexture)

Constructs an offscreen texture that fits the given setup. All values must be valid and non-negative.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

unclampColorRange - true to make use of vendor-specific extensions for floating point colour buffers

width - The width of the texture in pixels

height - The height of the texture in pixels

separateDepthTexture - True is a separate depth texture render target should be created

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             int width,
                             int height,
                             int format,
                             int numTargets)

Constructs an offscreen texture that fits the given setup and provides a specific format that overrides the automatic determination. All values must be valid and non-negative. Floating point colour buffers are disabled.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

width - The width of the texture in pixels

height - The height of the texture in pixels

format - The format to associate with this texture

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

MRTOffscreenTexture2D

public MRTOffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                             boolean unclampColorRange,
                             int width,
                             int height,
                             int fmt,
                             int numTargets,
                             boolean separateDepthTexture)

Constructs an offscreen texture that fits the given setup and provides a specific format that overrides the automatic determination. All values must be valid and non-negative.

Parameters:

caps - The capabilities needed to generate the Pbuffer with

unclampColorRange - true to make use of vendor-specific extensions for floating point colour buffers

width - The width of the texture in pixels

height - The height of the texture in pixels

fmt - The format to associate with this texture

separateDepthTexture - True is a separate depth texture render target should be created

Throws:

java.lang.IllegalArgumentException - The capabilities parameter is null or the number of targets is less than one

Method Detail

isRepaintRequired

public boolean isRepaintRequired()

Get the current state of the repainting enabled flag.

Specified by:

isRepaintRequired in interface OffscreenCullable

Returns:

true when the texture requires re-drawing

getCullableLayer

public LayerCullable getCullableLayer(int layerIndex)

Get the cullable layer child that for the given layer index.

Specified by:

getCullableLayer in interface OffscreenCullable

Returns:

The layer cullable at the given index or null

numCullableChildren

public int numCullableChildren()

Returns the number of valid cullable children to process. If there are no valid renderable children return -1.

Specified by:

numCullableChildren in interface OffscreenCullable

Returns:

A number greater than or equal to zero or -1

getOffscreenRenderable

public OffscreenBufferRenderable getOffscreenRenderable()

Fetch the renderable that this offscreen cullable will draw to.

Specified by:

getOffscreenRenderable in interface OffscreenCullable

Returns:

The renderable instance that we deposit pixels to

getClearColor

public void getClearColor(float[] col)

Set the background colour that this surface should be cleared to before the drawing step. Colours range from 0 to 1 in the normal manner.

Specified by:

getClearColor in interface OffscreenBufferRenderable

Parameters:

col - An array of at least length 4 to copy values into

getGLSetup

public javax.media.opengl.GLCapabilities getGLSetup()

Deprecated. Use MRTTexture2D.getBufferSetup() Always returns null

Get the requested buffer setup that describes this offscreen buffer.

Specified by:

getGLSetup in interface OffscreenBufferRenderable

Returns:

The defined capabilities setup for the texture

getFormat

public int getFormat(int level)

Get the format for this texture. As this is a single pBuffer texture, there is only ever one level, so the argument is ignored.

Parameters:

level - The mipmap level to get the format for

Returns:

The format.

getNumRenderTargets

public int getNumRenderTargets()

Get the number of render targets that this offscreen renderable manages. This should always return at least 1, being itself.

Specified by:

getNumRenderTargets in interface OffscreenBufferRenderable

Returns:

A value greater than zero

getRenderTargetRenderable

public OffscreenRenderTargetRenderable getRenderTargetRenderable(int index)

Get the child render target at the given index. If the index 0 is given, this will return a reference to ourselves.

Specified by:

getRenderTargetRenderable in interface OffscreenBufferRenderable

Parameters:

index - The index of the target to fetch

Returns:

The render target at the given index

hasSeparateDepthRenderable

public boolean hasSeparateDepthRenderable()

Check to see if the depth buffer has its own separate renderable object. Used when the offscreen needs to create the depth buffer separately as a texture to use in shading.

Specified by:

hasSeparateDepthRenderable in interface OffscreenBufferRenderable

Returns:

True if a separate depth texture is wanted

getDepthRenderable

public OffscreenRenderTargetRenderable getDepthRenderable()

If a separate depth render target has been requested, return the renderable for that object now. If not requested, this returns null.

Specified by:

getDepthRenderable in interface OffscreenBufferRenderable

Returns:

The depth target renderable or null

hasBufferResized

public boolean hasBufferResized()

Check to see if this buffer has resized since the last time it was used. If so, recreate the underlying setup, but keep everything else the same. Will reset the flag on read.

Specified by:

hasBufferResized in interface OffscreenBufferRenderable

Returns:

true if the buffer has resized, requiring reallocation of the underlying buffer objects

isChildRenderTarget

public boolean isChildRenderTarget()

Check to see if this is a child render target of a parent multiple render target offscreen buffer. Returns true if it is.

Specified by:

isChildRenderTarget in interface OffscreenRenderTargetRenderable

Overrides:

isChildRenderTarget in class MRTTexture2D

Returns:

true if this is a child, false if the parent

compareTo

public int compareTo(Texture tex)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. Derived instances should override this to add texture-specific extensions.

Overrides:

compareTo in class MRTTexture2D

Parameters:

tex - The texture instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(Texture tex)

Compares this object with the specified object to check for equivalence.

Overrides:

equals in class MRTTexture2D

Parameters:

tex - The texture instance to be compared

Returns:

true if the objects represent identical values

checkForCyclicChild

protected void checkForCyclicChild(SceneGraphObject parent)
                            throws InvalidWriteTimingException,
                                   CyclicSceneGraphStructureException

Check to see if this node is the same reference as the passed node that is a parent of this node. This is the downwards check to ensure that there is no cyclic scene graph structures at the point where someone adds a node to the scenegraph. When the reference and this are the same, an exception is generated. Since each class may have different lists of child node setups, this should be overriden by any class that can take children, and have the call passed along to the children.

Overrides:

checkForCyclicChild in class SceneGraphObject

Parameters:

parent - The reference to check against this class

Throws:

CyclicSceneGraphStructureException - Equal parent and child

InvalidWriteTimingException

setLive

protected void setLive(boolean state)

Notification that this object is live now. Overridden to make sure that the live state of the nodes represents the same state as the parent scene graph.

Overrides:

setLive in class Texture

Parameters:

state - true if this should be marked as live now

setUpdateHandler

protected void setUpdateHandler(NodeUpdateHandler handler)

Set the scenegraph update handler for this node. It will notify all its children of the value. A null value will clear the current handler.

Overrides:

setUpdateHandler in class Texture

Parameters:

handler - The instance to use as a handler

getRenderTarget

public MRTTexture2D getRenderTarget(int index)

Get the numbered render target. Using an index of 0 will return a reference to this class because this class is always considered to be render target 0. A number out of range will generate an exception.

Parameters:

index - The render target number to get the texture representation for

Returns:

The render target representation for that index

Throws:

java.lang.IllegalArgumentException - The index is out of range

getDepthRenderTarget

public MRTTexture2D getDepthRenderTarget()

If the texture was configured with a separate offscreen depth texture from the colour texture, get that texture representation.

Returns:

The render target representation for depth or null if not requested

resize

public void resize(int w,
                   int h)

Resize this buffer to a new window. Automatically sets the repaint required flag.

Parameters:

w - The new width of the buffer in pixels. Must be positive.

h - The new height of the buffer in pixels. Must be positive.

Throws:

java.lang.IllegalArgumentException - if the width or height <= 0

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

setLayers

public void setLayers(Layer[] layers,
                      int numLayers)
               throws InvalidWriteTimingException,
                      CyclicSceneGraphStructureException

Set the collection of geometry that should be rendered to this texture. The geometry is, in effect, a completely separate rendarable space, with it's own culling and sorting pass. In addition, a check is made to make sure that no cyclic scene graph structures are created, as this can create really major headachesfor nested surface rendering. A null value will clear the current geometry and result in only rendering the background, if set. if not set, then whatever the default colour is, is used (typically black).

Parameters:

layers - The collection of layers, in order, to render

numLayers - The number of valid layers to use

Throws:

CyclicSceneGraphStructureException - Equal parent and child

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

numLayers

public int numLayers()

Get the number of layers that are currently set. If no layers are set, or a scene is set, this will return zero.

Returns:

a value greater than or equal to zero

getLayers

public void getLayers(Layer[] layers)
               throws java.lang.IllegalArgumentException

Fetch the current layers that are set. The values will be copied into the user-provided array. That array must be at least numLayers() in length. If not, this method does nothing (the provided array will be unchanged).

Parameters:

layers - An array to copy the values into

Throws:

java.lang.IllegalArgumentException - The array provided is too small or null

setRepaintRequired

public void setRepaintRequired(boolean enable)

Set this texture as requiring a repaint for the next frame. If no repaint is required, reset this to null at the point where no repainting is required. The internal flag is a user-defined state, so For the first frame at least, this should be set to true so that the initial paint can be performed (assuming data is present, of course).

Parameters:

enable - true to have this repaint the next frame

setClearColor

public void setClearColor(float r,
                          float g,
                          float b,
                          float a)
                   throws InvalidWriteTimingException

Set the background colour that this surface should be cleared to before the drawing step. Colours range from 0 to 1 in the normal manner.

Parameters:

r - The red component of the background clear colour

g - The green component of the background clear colour

b - The blue component of the background clear colour

a - The alpha component of the background clear colour

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method