org.j3d.aviatrix3d
Class AppearanceOverride

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.Node
          org.j3d.aviatrix3d.Leaf
              org.j3d.aviatrix3d.AppearanceOverride

All Implemented Interfaces:

java.lang.Comparable, CascadeRenderable, Cullable, LeafCullable, OverrideRenderable, Renderable

public class AppearanceOverride
extends Leaf
implements LeafCullable, OverrideRenderable

An appearance that can be placed higher in the tree other than the Appearance node and overrides the appearance of all objects lower in the tree.

This class can be used to override the appearance of everything in the tree, for example, to highlight a sub section of parts of a greater assembly. Two different types of behaviours are allowed: it can be used to always override everything below, or if can be provided as a backup if there is no appearance provided at the leaf nodes.

An additional configuration option is available in either mode. When the local appearance option is false it will add any missing appearance items from the leaf node Appearance class instance that it does not have locally specified. This allows you to, for example, provide a global shader, but leave the definition of the material and normal map textures to the individual shape node instances, without having to cart the shader around everywhere. Another way of thinking about this, is that content loaded from external sources that have colours and normal maps defined, don't have to worry about loading in the root shader to change rendering styles as part of the loader process. So long as your loader is consistent about which index each texture goes in, you don't have to care about what rendering style is applied globally (ie, normal texture is always texture unit 0, colour texture always texture unit 1 etc etc).

Version:

$Revision: 2.5 $

Author:

Justin Couch

Field Summary

Fields inherited from class org.j3d.aviatrix3d.Node

bounds, implicitBounds, INVALID_BOUNDS, parent

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

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

AUDIO_CULLABLE, CLIP_CULLABLE, FOG_CULLABLE, GEOMETRY_CULLABLE, LIGHT_CULLABLE, OVERRIDE_CULLABLE

Constructor Summary

AppearanceOverride()
Creates an override that is disabled by default and does not override the lower items on the tree.

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(AppearanceOverride sh) Compares this object with the specified object for order.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
boolean	equals(AppearanceOverride sh) Compares this object with the specified object to check for equivalence.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
Appearance	getAppearance() Get the current appearance associated with this shape.
AppearanceRenderable	getAppearanceRenderable() Fetch the renderable that represents the visual appearance modifiers of this shape.
int	getCullableType() Get the type that this cullable represents.
Renderable	getRenderable() Get the child renderable of this object.
boolean	isEnabled() Get the current enabled state of the light.
boolean	isLocalAppearanceOnly() Check whether the override shoudl include from the leaf Appearance nodes any missing definitions.
boolean	isOverridingLower() Check which direction has preference for the appearance handling.
boolean	overrideLower() Check which direction has preference for the appearance handling.
void	setAppearance(Appearance newApp) Set the appearance for this shape.
void	setEnabled(boolean state) Set the enabled state of this override.
protected void	setLive(boolean state) Notification that this object is live now.
void	setLocalAppearanceOnly(boolean state) Set the override function to determine whether we should override also include any missing appearance options that are defined in leaf Appearance nodes on the Shape nodes.
void	setOverrideLower(boolean state) Set the override function to determine whether we should override lower appearances or not.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.
boolean	useLocalOnlyAppearance() Check to see if this is a local appearance only or it should accumulate the leaf node colours/textures.

Methods inherited from class org.j3d.aviatrix3d.Node

boundsChanged, checkForCyclicParent, getBounds, getParent, markBoundsDirty, recomputeBounds, removeParent, requestBoundsUpdate, setBounds, setParent, updateBounds, updateParentBounds

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

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

getBounds

Constructor Detail

AppearanceOverride

public AppearanceOverride()

Creates an override that is disabled by default and does not override the lower items on the tree.

Method Detail

getCullableType

public int getCullableType()

Get the type that this cullable represents.

Specified by:

getCullableType in interface LeafCullable

Returns:

One of the _CULLABLE constants

getRenderable

public Renderable getRenderable()

Get the child renderable of this object.

Specified by:

getRenderable in interface LeafCullable

Returns:

an array of nodes

overrideLower

public boolean overrideLower()

Check which direction has preference for the appearance handling. If this is true then this instance will override those lower down the scene graph. If false, then those lower on the tree override this instance.

Specified by:

overrideLower in interface OverrideRenderable

Returns:

true if this overrides instances lower

useLocalOnlyAppearance

public boolean useLocalOnlyAppearance()

Check to see if this is a local appearance only or it should accumulate the leaf node colours/textures.

Specified by:

useLocalOnlyAppearance in interface OverrideRenderable

Returns:

true if we should only use the appearance node details from here

getAppearanceRenderable

public AppearanceRenderable getAppearanceRenderable()

Fetch the renderable that represents the visual appearance modifiers of this shape.

Specified by:

getAppearanceRenderable in interface OverrideRenderable

Returns:

The current appearance renderable or null if none

isEnabled

public boolean isEnabled()

Get the current enabled state of the light.

Specified by:

isEnabled in interface CascadeRenderable

Returns:

The current state

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

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

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

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

setEnabled

public void setEnabled(boolean state)
                throws InvalidWriteTimingException

Set the enabled state of this override. Can use this to turn it on and off in a general fashion.

Parameters:

state - The new state of the override

Throws:

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

setOverrideLower

public void setOverrideLower(boolean state)
                      throws InvalidWriteTimingException

Set the override function to determine whether we should override lower appearances or not.

Parameters:

state - Set true if this should trump lower instances in the tree

Throws:

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

isOverridingLower

public boolean isOverridingLower()

Check which direction has preference for the appearance handling. If this is true then this instance will override those lower down the scene graph. If false, then those lower on the tree override this instance.

Returns:

true if this overrides instances lower

setLocalAppearanceOnly

public void setLocalAppearanceOnly(boolean state)
                            throws InvalidWriteTimingException

Set the override function to determine whether we should override also include any missing appearance options that are defined in leaf Appearance nodes on the Shape nodes. This will not include any lower override appearance instances in the tree, only the leaf nodes. Default is to not use this ability.

Parameters:

state - Set true if this should trump lower instances in the tree

Throws:

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

isLocalAppearanceOnly

public boolean isLocalAppearanceOnly()

Check whether the override shoudl include from the leaf Appearance nodes any missing definitions.

Returns:

true if this overrides instances lower

getAppearance

public Appearance getAppearance()

Get the current appearance associated with this shape.

Returns:

the current instance

setAppearance

public void setAppearance(Appearance newApp)
                   throws InvalidWriteTimingException

Set the appearance for this shape.

Parameters:

newApp - The appearance

Throws:

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

compareTo

public int compareTo(AppearanceOverride sh)

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:

sh - The argument instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(AppearanceOverride sh)

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

Parameters:

sh - The shape instance to be compared

Returns:

true if the objects represent identical values