Aviatrix3D
2.0

org.j3d.aviatrix3d
Class OffscreenTexture2D

java.lang.Object
  extended by org.j3d.aviatrix3d.SceneGraphObject
      extended by org.j3d.aviatrix3d.NodeComponent
          extended by org.j3d.aviatrix3d.Texture
              extended by org.j3d.aviatrix3d.OffscreenTexture2D
All Implemented Interfaces:
java.lang.Comparable, OffscreenTextureSource, PBufferTextureSource, Cullable, DeletableRenderable, ObjectRenderable, OffscreenCullable, Renderable, TextureSource

public class OffscreenTexture2D
extends Texture
implements PBufferTextureSource, OffscreenCullable

Describes the texture that is rendered to an offscreen buffer, using OpenGL pBuffers.

Since the format information is provided as part of the GLCapabilities instance, there is no need for it to be passed into the constructor like the other texture types do.

This implementation is somewhat shaky right now as the documentation on how to use the GLPbuffer class is very poor. The class may change drastically once we really work out what is going on.

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.

For repainting updates, the logic is as-follows. On the first time this 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.

Version:
$Revision: 1.29 $
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_RGB, FORMAT_RGBA, 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_NOT_LIVE_MESSAGE, updateHandler, WRITE_TIMING_MSG
 
Fields inherited from interface org.j3d.aviatrix3d.TextureSource
FORMAT_BGR, FORMAT_BGRA, FORMAT_INTENSITY_ALPHA, FORMAT_RGB, FORMAT_RGBA, FORMAT_SINGLE_COMPONENT
 
Constructor Summary
OffscreenTexture2D(javax.media.opengl.GLCapabilities caps, int width, int height)
          Constructs an offscreen texture that fits the given setup.
 
Method Summary
 void bindBuffer(javax.media.opengl.GLContext context)
          Bind the underlying source buffer for the offscreen rendering.
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.
 javax.media.opengl.GLPbuffer getBuffer(java.lang.Object obj)
          Get the currently registered pBuffer for the given key object.
 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.
 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 getNumLevels()
          Get the number of levels for the mipmapping in this source.
 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, javax.media.opengl.GLPbuffer 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 unbindBuffer(javax.media.opengl.GLContext context)
          Unbind the underlying source buffer for the offscreen rendering.
 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, getMagFilter, getMinFilter, getPriority, getTextureType, getUpdateStrategy, getWidth, setAnisotropicFilterDegree, setAnisotropicFilterMode, setBorderColor, setBoundaryModeS, setCompareFunction, setCompareMode, setDepthFormat, setMagFilter, setMinFilter, setPriority, setUpdateStrategy
 
Methods inherited from class org.j3d.aviatrix3d.NodeComponent
addParent, getParents, hasChanged, numParents, removeParent
 
Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject
checkForCyclicParent, dataChanged, 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.TextureSource
getWidth
 

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.

Method Detail

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

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

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.

Specified by:
getFormat in interface TextureSource
Parameters:
level - The mipmap level to get the format for
Returns:
The format.

getNumLevels

public int getNumLevels()
Get the number of levels for the mipmapping in this source.

Specified by:
getNumLevels in interface TextureSource
Returns:
The number of levels.

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

getGLSetup

public javax.media.opengl.GLCapabilities getGLSetup()
Get the requested buffer setup that describes this offscreen texture.

Specified by:
getGLSetup in interface PBufferTextureSource
Returns:
The defined capabilities setup for the texture

getBuffer

public javax.media.opengl.GLPbuffer 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 PBufferTextureSource
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,
                           javax.media.opengl.GLPbuffer buffer)
Register a pBuffer for a given key object.

Specified by:
registerBuffer in interface PBufferTextureSource
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 PBufferTextureSource
Parameters:
obj - The key used to register the buffer with

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

Specified by:
setLayers in interface PBufferTextureSource
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 callback method

bindBuffer

public void bindBuffer(javax.media.opengl.GLContext context)
Bind the underlying source buffer for the offscreen rendering.

Specified by:
bindBuffer in interface PBufferTextureSource
Parameters:
context - The containing context to bind from

unbindBuffer

public void unbindBuffer(javax.media.opengl.GLContext context)
Unbind the underlying source buffer for the offscreen rendering.

Specified by:
unbindBuffer in interface PBufferTextureSource
Parameters:
context - The containing context to bind from

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.

Specified by:
numLayers in interface PBufferTextureSource
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).

Specified by:
getLayers in interface PBufferTextureSource
Parameters:
layers - An array to copy the values into
Throws:
java.lang.IllegalArgumentException - The array provided is too small or null

isRepaintRequired

public boolean isRepaintRequired()
Get the current state of the repainting enabled flag.

Specified by:
isRepaintRequired in interface OffscreenTextureSource
Specified by:
isRepaintRequired in interface OffscreenCullable
Returns:
true when the texture requires re-drawing

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 OffscreenTextureSource
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 OffscreenTextureSource
Parameters:
col - An array of at least length 4 to copy values into

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

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

Aviatrix3D
2.0

Latest Info from http://aviatrix3d.j3d.org/
Copyright © 2003 - 2008 j3d.org