org.j3d.aviatrix3d
Class TextureUnit

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.NodeComponent
          org.j3d.aviatrix3d.TextureUnit

All Implemented Interfaces:

java.lang.Comparable, ComponentRenderable, Renderable, TextureRenderable, TransparentRenderable

public class TextureUnit
extends NodeComponent
implements TextureRenderable

Describes a texture stage and its associated texture and attributes.

The external data passed to the ComponentRenderable calls shall be an Integer instance that represents the GL texture unit of the this instance is working with. If the value is -1, then only a single texture is being used, so the class does not need to make use of the glActiveTexture() call.

Internationalisation Resource Names

• noMultiTextureMsg: Somehow we found a video card that doesn't suppory multitexturing. What is this? A card from 1992?

Version:

$Revision: 1.52 $

Author:

Justin Couch, Alan Hudson

Field Summary

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

Constructor Summary

TextureUnit()
Constructs a Texture Unit with default values.

TextureUnit(Texture t, TextureAttributes attrs, TexCoordGeneration tcg)
Construct a Texture Unit with the specified texture, attributes and coordinate generation.

Method Summary

void	activateTexture(javax.media.opengl.GL gl, java.lang.Object stageId) Activate the texture now.
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(java.lang.Object o) Compares this object with the specified object for order.
int	compareTo(TextureUnit tu) Compares this object with the specified object for order.
void	deactivateTexture(javax.media.opengl.GL gl, java.lang.Object stageId) Deactivate the texture now so that it is no longer a valid rendering target.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
boolean	equals(TextureUnit tu) Compares this object with the specified object to check for equivalence.
OffscreenBufferDescriptor	getBuffer(javax.media.opengl.GLContext context) Fetch the underlying source buffer for the offscreen rendering that relates to this particular texture.
OffscreenCullable	getOffscreenSource() Fetch the offscreen texture source that this renderable holds on to.
TexCoordGeneration	getTexCoordGeneration() Get the currently set texture.
Texture	getTexture() Get the currently set texture.
TextureAttributes	getTextureAttributes() Get the currently set texture attributes.
void	getTextureTransform(javax.vecmath.Matrix4f mat) Get the current local texture transformation maxtix.
boolean	hasTransparency() Ask the texture if it has any transparency values.
boolean	isMultiTextureAllowed() Convenience method to check if this code has detected the prescense of multitexture extensions.
boolean	isOffscreenBuffer() Check to see if this is an offscreen buffer that is separately rendered rather than using explicit image data.
boolean	isOffscreenSource() Check to see if the contained texture is an offscreen renderable such as OffscreenTexture2D or MRTOffscreenTexture2D that contains a subscene graph to be rendered.
void	postRender(javax.media.opengl.GL gl, java.lang.Object stageId) Restore all openGL state to the given drawable.
void	render(javax.media.opengl.GL gl, java.lang.Object stageId) Issue ogl commands needed for this component
protected void	setLive(boolean state) Notification that this object is live now.
void	setTexCoordGeneration(TexCoordGeneration tcg) Set the texture coordinate generation for this stage.
void	setTexture(Texture tex) Set the texture for this stage.
void	setTextureAttributes(TextureAttributes attrs) Set the texture attributes for this stage.
void	setTextureTransform(javax.vecmath.Matrix4f mat) Set the current texture transform matrix.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.

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

Constructor Detail

TextureUnit

public TextureUnit()

Constructs a Texture Unit with default values.

TextureUnit

public TextureUnit(Texture t,
                   TextureAttributes attrs,
                   TexCoordGeneration tcg)

Construct a Texture Unit with the specified texture, attributes and coordinate generation.

Parameters:

t - The texture instance to use

attrs - Attributes used to control the visual appearance

tcg - Automated texture coordinate generation, if needed

Method Detail

checkForCyclicChild

protected void checkForCyclicChild(SceneGraphObject parent)
                            throws 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

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 SceneGraphObject

Parameters:

handler - The instance to use as a handler

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 SceneGraphObject

Parameters:

state - true if this should be marked as live now

hasTransparency

public boolean hasTransparency()

Ask the texture if it has any transparency values. The implementation should determine this from it's internal set of state, such as looking at the texture formats etc to see if they include an alpha channel

Specified by:

hasTransparency in interface TransparentRenderable

Returns:

true if any form of non-opaque rendering is defined

isOffscreenSource

public boolean isOffscreenSource()

Check to see if the contained texture is an offscreen renderable such as OffscreenTexture2D or MRTOffscreenTexture2D that contains a subscene graph to be rendered. If is is, then the getOffscreenSource() method will return the contained cullable.

Specified by:

isOffscreenSource in interface TextureRenderable

Returns:

true if the texture contains an offscreen source

getOffscreenSource

public OffscreenCullable getOffscreenSource()

Fetch the offscreen texture source that this renderable holds on to. If this node does not contain an offscreen texture then return null.

Specified by:

getOffscreenSource in interface TextureRenderable

Returns:

The Cullable instance for the offscreen, if available

isOffscreenBuffer

public boolean isOffscreenBuffer()

Check to see if this is an offscreen buffer that is separately rendered rather than using explicit image data. Offscreen buffers do not necessarily contain a sub scene graph. The isOffscreenSource() method is used to determine that.

Specified by:

isOffscreenBuffer in interface TextureRenderable

Returns:

true if this represents an offscreen buffer of some sort

getBuffer

public OffscreenBufferDescriptor getBuffer(javax.media.opengl.GLContext context)

Fetch the underlying source buffer for the offscreen rendering that relates to this particular texture. The buffer descriptor would be fetched from the matching offscreen texture source that was registered below this class.

Specified by:

getBuffer in interface TextureRenderable

Parameters:

context - The containing context to find the matching buffer for

Returns:

A buffer descriptor for that context, or null if none found

activateTexture

public void activateTexture(javax.media.opengl.GL gl,
                            java.lang.Object stageId)

Activate the texture now. This will be called before the render() method and is used to perform any enabling functionality for the given renderable.

Specified by:

activateTexture in interface TextureRenderable

Parameters:

gl - The GL context to render with

stageId - The ID of the texture stage we're reading

deactivateTexture

public void deactivateTexture(javax.media.opengl.GL gl,
                              java.lang.Object stageId)

Deactivate the texture now so that it is no longer a valid rendering target.

Specified by:

deactivateTexture in interface TextureRenderable

Parameters:

gl - The GL context to render with

stageId - The ID of the texture stage we're reading

render

public void render(javax.media.opengl.GL gl,
                   java.lang.Object stageId)

Issue ogl commands needed for this component

Specified by:

render in interface ComponentRenderable

Parameters:

gl - The gl context to draw with

stageId - The ID of the texture stage we're reading

postRender

public void postRender(javax.media.opengl.GL gl,
                       java.lang.Object stageId)

Restore all openGL state to the given drawable.

Specified by:

postRender in interface ComponentRenderable

Parameters:

gl - The gl context to draw with

stageId - The ID of the texture stage we're reading

compareTo

public int compareTo(java.lang.Object o)
              throws java.lang.ClassCastException

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.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - The object to be compared

Returns:

-1, 0 or 1 depending on order

Throws:

java.lang.ClassCastException - The specified object's type prevents it from being compared to this Object

equals

public boolean equals(java.lang.Object o)

Compare this object for equality to the given object.

Specified by:

equals in interface Renderable

Overrides:

equals in class java.lang.Object

Parameters:

o - The object to be compared

Returns:

True if these represent the same values

setTexture

public void setTexture(Texture tex)
                throws InvalidWriteTimingException

Set the texture for this stage. Passing a value of null will disable this stage from being passed to the rendering APIs.

Parameters:

tex - The texture to be used or null

Throws:

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

getTexture

public Texture getTexture()

Get the currently set texture. If none is set, return null.

Returns:

The current texture instance or null

setTextureAttributes

public void setTextureAttributes(TextureAttributes attrs)
                          throws InvalidWriteTimingException

Set the texture attributes for this stage.

Parameters:

attrs - The texture attributes. Null clears.

Throws:

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

getTextureAttributes

public TextureAttributes getTextureAttributes()

Get the currently set texture attributes. If none is set, return null.

Returns:

The current texture attributes instance or null

setTexCoordGeneration

public void setTexCoordGeneration(TexCoordGeneration tcg)
                           throws InvalidWriteTimingException

Set the texture coordinate generation for this stage.

Parameters:

tcg - The texture coordinate generation. Null clears.

Throws:

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

getTexCoordGeneration

public TexCoordGeneration getTexCoordGeneration()

Get the currently set texture. If none is set, return null.

Returns:

The current texture instance or null

setTextureTransform

public void setTextureTransform(javax.vecmath.Matrix4f mat)
                         throws InvalidWriteTimingException

Set the current texture transform matrix. A value of null will reset the matrix back to the default identity matrix. A copy of this matrix is made.

Parameters:

mat - The matrix to modify textures by, or null

Throws:

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

getTextureTransform

public void getTextureTransform(javax.vecmath.Matrix4f mat)

Get the current local texture transformation maxtix. If no matrix is currently set, it will set the value to an identity matrix.

Parameters:

mat - The matrix to copy the current values into

compareTo

public int compareTo(TextureUnit tu)

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.

Parameters:

tu - The texture unit instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(TextureUnit tu)

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

Parameters:

tu - The texture unit instance to be compared

Returns:

true if the objects represent identical values

isMultiTextureAllowed

public boolean isMultiTextureAllowed()

Convenience method to check if this code has detected the prescense of multitexture extensions. If none are found, this will return null. However, one node instance has to have passed through the rendering cycle for this to have detected it. A better option would be to make use of the appropriate callbacks on the GraphicsOutputDevice APIs to detect before you get to this point.

Returns:

true if multitexture is allowed