org.j3d.aviatrix3d
Class OffscreenTexture2D

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.NodeComponent
          org.j3d.aviatrix3d.Texture
              org.j3d.aviatrix3d.OffscreenTexture2D

All Implemented Interfaces:

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

public class OffscreenTexture2D
extends Texture
implements OffscreenCullable, OffscreenBufferRenderable

Describes the texture that is rendered to an offscreen buffer, using OpenGL frame buffer objects or pbuffers, depending on system capability.

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.

Version:

$Revision: 1.45 $

Author:

Justin Couch

Field Summary

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

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

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

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

OffscreenTexture2D(javax.media.opengl.GLCapabilities caps, int width, int height, int format)
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.
int	getBoundaryModeT() Get the current boundary handling for the S parameter.
OffscreenBufferDescriptor	getBuffer(java.lang.Object obj) Get the currently registered pBuffer for the given key object.
BufferSetupData	getBufferSetup() Get the requested buffer setup that describes this offscreen buffer.
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.
int	getFormat(int level) Get the format for this texture.
javax.media.opengl.GLCapabilities	getGLSetup() Get the requested buffer setup that describes this offscreen texture.
int	getHeight() Get the height of the texture in pixels.
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.
OffscreenRenderTargetRenderable	getOwnerOffscreenRenderable() If this is a child render target, return the owner renderable.
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	postRender(javax.media.opengl.GL gl) Restore all openGL state to the given drawable
void	registerBuffer(java.lang.Object obj, OffscreenBufferDescriptor buffer) Register a pBuffer for a given key object.
void	render(javax.media.opengl.GL gl) Issue ogl commands needed for this component
void	setBoundaryModeT(int mode) Set the boundary handling for the T parameter.
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.
void	setSources(int mipMapMode, int format, TextureSource[] texSources, int num) Set the images for this texture, overridden to provide an empty implementation as this is handled by the pBuffer directly.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.
void	unregisterBuffer(java.lang.Object obj) Remove an already registered pBuffer for a given key object.

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

getWidth

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

equals

Methods inherited from interface java.lang.Comparable

compareTo

Constructor Detail

OffscreenTexture2D

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

Constructs an offscreen texture that fits the given setup. 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

OffscreenTexture2D

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

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

OffscreenTexture2D

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

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

OffscreenTexture2D

public OffscreenTexture2D(javax.media.opengl.GLCapabilities caps,
                          boolean unclampColorRange,
                          int width,
                          int height,
                          int format)

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

format - The format to associate with this texture

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

setSources

public void setSources(int mipMapMode,
                       int format,
                       TextureSource[] texSources,
                       int num)
                throws InvalidWriteTimingException

Set the images for this texture, overridden to provide an empty implementation as this is handled by the pBuffer directly.

Overrides:

setSources in class Texture

Parameters:

mipMapMode - Flag stating the type of texture mode to use

format - Image format to use for grayscale images

texSources - The source data to use, single for base level

num - The valid number of images to use from the array

Throws:

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

equals

public boolean equals(Texture tex)

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

Overrides:

equals in class Texture

Parameters:

tex - The texture instance to be compared

Returns:

true if the objects represent identical values

getHeight

public int getHeight()

Get the height of the texture in pixels. If no image is set, this returns -1.

Specified by:

getHeight in interface OffscreenRenderTargetRenderable

Returns:

a number >= -1

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()

Get the requested buffer setup that describes this offscreen texture.

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

getBufferSetup

public BufferSetupData getBufferSetup()

Get the requested buffer setup that describes this offscreen buffer. Only called once when the buffer is first constructed.

Specified by:

getBufferSetup in interface OffscreenRenderTargetRenderable

Returns:

The requested capabilities of the buffer that needs to be created

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, and the getOwnerOffscreenRenderable() method will return the parent of this class.

Specified by:

isChildRenderTarget in interface OffscreenRenderTargetRenderable

Returns:

false always

getOwnerOffscreenRenderable

public OffscreenRenderTargetRenderable getOwnerOffscreenRenderable()

If this is a child render target, return the owner renderable. If it is not a child, this returns null.

Returns:

null always

getBuffer

public OffscreenBufferDescriptor getBuffer(java.lang.Object obj)

Get the currently registered pBuffer for the given key object. If there is no buffer registered for the current context, return null.

Specified by:

getBuffer in interface OffscreenRenderTargetRenderable

Parameters:

obj - The key used to register the buffer with

Returns:

buffer The buffer instance to use here.

registerBuffer

public void registerBuffer(java.lang.Object obj,
                           OffscreenBufferDescriptor buffer)

Register a pBuffer for a given key object.

Specified by:

registerBuffer in interface OffscreenRenderTargetRenderable

Parameters:

obj - The key used to register the buffer with

buffer - The buffer instance to use here.

unregisterBuffer

public void unregisterBuffer(java.lang.Object obj)

Remove an already registered pBuffer for a given key object.

Specified by:

unregisterBuffer in interface OffscreenRenderTargetRenderable

Parameters:

obj - The key used to register the buffer with

render

public void render(javax.media.opengl.GL gl)

Issue ogl commands needed for this component

Specified by:

render in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

postRender

public void postRender(javax.media.opengl.GL gl)

Restore all openGL state to the given drawable

Specified by:

postRender in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

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

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

setBoundaryModeT

public void setBoundaryModeT(int mode)
                      throws InvalidWriteTimingException

Set the boundary handling for the T parameter.

Parameters:

mode - The new mode.

Throws:

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

getBoundaryModeT

public int getBoundaryModeT()

Get the current boundary handling for the S parameter.

Returns:

The current mode.

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

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 Texture

Parameters:

tex - The texture instance to be compared

Returns:

-1, 0 or 1 depending on order