org.j3d.aviatrix3d
Class Appearance

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

All Implemented Interfaces:

java.lang.Comparable, AppearanceRenderable, ObjectRenderable, Renderable

public class Appearance
extends NodeComponent
implements AppearanceRenderable

Describes the appearance of an object.

Attribute classes are used to control various visual details about the object being rendered. Although a single instance of this class can take all the attribute types at once, you'll need to consider what this object is being used for. Most of the time you should only ever need to use one of Point/Line/Polygon attributes.

Note: If you have semi-transparent objects that need blending, you do not need provide an instance of BlendAttributes. Aviatrix3D will internally handle the correct settings that you need, so there is no need to provide your own. Only use it when you want to blend objects with something different than the standard blending setup for non-transparent and transparent objects as it will remove this object from the normal transparency sorting processing and into a separate state.

Version:

$Revision: 1.46 $

Author:

Alan Hudson, Justin Couch

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

Appearance()
The default constructor.

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(Appearance app) 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(Appearance app) 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.
AlphaAttributes	getAlphaAttributes() Get the current alpha rendering attributes in use.
AppearanceAttributeRenderable	getAttributeRenderable(int attrib) Fetch the sub-renderable for the given type.
BlendAttributes	getBlendAttributes() Get the current blend rendering attributes in use.
DepthAttributes	getDepthAttributes() Get the current depth buffer attributes in use.
LineAttributes	getLineAttributes() Get the current line rendering attributes in use.
Material	getMaterial() Get the current material in use.
TransparentObjectRenderable	getMaterialRenderable() Fetch the renderable that corresponds to material properties.
PointAttributes	getPointAttributes() Get the current pointgon rendering attributes in use.
PolygonAttributes	getPolygonAttributes() Get the current polygon rendering attributes in use.
Shader	getShader() Get the current shader in use.
ShaderRenderable	getShaderRenderable() Fetch the renderable that corresponds to the set programmable shader.
StencilAttributes	getStencilAttributes() Get the current stencil buffer attributes in use.
TextureRenderable	getTextureRenderable(int unitNumber) Request the renderable for the given texture unit number.
void	getTextureUnits(TextureUnit[] texUnits) Get the texture units used by the material.
boolean	hasTransparency() Ask the appearance if it has any transparency values.
boolean	hasTransparencyInfo() Additional state information to supplement hasTransparency() by stating whether we have any set of sub-renderables that even define transparency information.
boolean	isVisible() Check to see if this appearance is making the geometry visible or not.
int	numTextureRenderables() Request the number of texture renderables that are available to process in this node.
int	numTextureUnits() Get the current number of texture units that are valid
void	postRender(javax.media.opengl.GL gl) Restore all openGL state.
void	render(javax.media.opengl.GL gl) Issue ogl commands needed for this component.
void	setAlphaAttributes(AlphaAttributes attr) Set the alpha rendering attributes to use.
void	setBlendAttributes(BlendAttributes attr) Set the blend rendering attributes to use.
void	setDepthAttributes(DepthAttributes attr) Set the depth buffer attributes to use.
void	setLineAttributes(LineAttributes attr) Set the line rendering attributes to use.
protected void	setLive(boolean state) Notification that this object is live now.
void	setMaterial(Material mat) Set the material to use.
void	setPointAttributes(PointAttributes attr) Set the point rendering attributes to use.
void	setPolygonAttributes(PolygonAttributes attr) Set the polygon rendering attributes to use.
void	setShader(Shader s) Set the shader to use.
void	setStencilAttributes(StencilAttributes attr) Set the stencil buffer attributes to use.
void	setTextureUnits(TextureUnit[] texUnits, int num) Set the texture units to use.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.
void	setVisible(boolean state) Set the visibility state of any geometry associated with this instance.

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

Appearance

public Appearance()

The default constructor.

Method Detail

isVisible

public boolean isVisible()

Check to see if this appearance is making the geometry visible or not.

Specified by:

isVisible in interface AppearanceRenderable

Returns:

true when the geometry is visible

hasTransparency

public boolean hasTransparency()

Ask the appearance if it has any transparency values. The implementation should determine this from it's internal set of state, such as looking at material properties, texture formats etc.

Specified by:

hasTransparency in interface AppearanceRenderable

Returns:

true if any form of non-opaque rendering is defined

hasTransparencyInfo

public boolean hasTransparencyInfo()

Additional state information to supplement hasTransparency() by stating whether we have any set of sub-renderables that even define transparency information. This is used for when an appearance renderable defines, say, polygon attributes, but no material or blend attributes at all. In this case you want to know about the 2-sided rendering but need to later check the geometry for colour with alpha being used.

Specified by:

hasTransparencyInfo in interface AppearanceRenderable

Returns:

true if We can categorically state that no transparency should be considered in this rendering

getAttributeRenderable

public AppearanceAttributeRenderable getAttributeRenderable(int attrib)

Fetch the sub-renderable for the given type. This can then be cast up to the appropriate extended Renderable type.

Specified by:

getAttributeRenderable in interface AppearanceRenderable

Parameters:

attrib - The attribute type identifier from AppearanceAttributeRenderable

Returns:

A renderable for that attribute if one is set, or null

numTextureRenderables

public int numTextureRenderables()

Request the number of texture renderables that are available to process in this node. OpenGL allows a maximum of 32 textures to be defined.

Specified by:

numTextureRenderables in interface AppearanceRenderable

Returns:

A number between 0 and 32

getTextureRenderable

public TextureRenderable getTextureRenderable(int unitNumber)

Request the renderable for the given texture unit number. If there is no renderable for that number, return null.

Specified by:

getTextureRenderable in interface AppearanceRenderable

Parameters:

unitNumber - The number of the texture unit to fetch

Returns:

The matching texture unit renderable or null if not available

getShaderRenderable

public ShaderRenderable getShaderRenderable()

Fetch the renderable that corresponds to the set programmable shader. If no shader is set, return null.

Specified by:

getShaderRenderable in interface AppearanceRenderable

Returns:

The current shader renderable or null

getMaterialRenderable

public TransparentObjectRenderable getMaterialRenderable()

Fetch the renderable that corresponds to material properties. If none is set or valid for this visual appearance, return null

Specified by:

getMaterialRenderable in interface AppearanceRenderable

Returns:

The current shader renderable or null

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.

Specified by:

postRender in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

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

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

setVisible

public void setVisible(boolean state)

Set the visibility state of any geometry associated with this instance. This can only be set during the data-changed callback as it only effects visual state and not rendering state. An object that is not visible is still valid for the bounds, which means it can be picked etc. That is, making something invisible does not effect the bounds of the parent objects.

Parameters:

state - true to make the object visible

Throws:

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

setMaterial

public void setMaterial(Material mat)
                 throws InvalidWriteTimingException

Set the material to use. Null will clear the material.

Parameters:

mat - The new material

Throws:

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

getMaterial

public Material getMaterial()

Get the current material in use.

Returns:

The current material instance or null

setPolygonAttributes

public void setPolygonAttributes(PolygonAttributes attr)
                          throws InvalidWriteTimingException

Set the polygon rendering attributes to use. Null will clear the current attributes.

Parameters:

attr - The new attributes or null

Throws:

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

getPolygonAttributes

public PolygonAttributes getPolygonAttributes()

Get the current polygon rendering attributes in use.

Returns:

The current attributes instance or null

setLineAttributes

public void setLineAttributes(LineAttributes attr)
                       throws InvalidWriteTimingException

Set the line rendering attributes to use. Null will clear the current attributes.

Parameters:

attr - The new attributes or null

Throws:

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

getLineAttributes

public LineAttributes getLineAttributes()

Get the current line rendering attributes in use.

Returns:

The current attributes instance or null

setPointAttributes

public void setPointAttributes(PointAttributes attr)
                        throws InvalidWriteTimingException

Set the point rendering attributes to use. Null will clear the current attributes.

Parameters:

attr - The new attributes or null

Throws:

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

getPointAttributes

public PointAttributes getPointAttributes()

Get the current pointgon rendering attributes in use.

Returns:

The current attributes instance or null

setBlendAttributes

public void setBlendAttributes(BlendAttributes attr)
                        throws InvalidWriteTimingException

Set the blend rendering attributes to use. Null will clear the current attributes.

Note Setting a value will disable state sorting for transparency on this object.

Parameters:

attr - The new attributes or null

Throws:

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

getBlendAttributes

public BlendAttributes getBlendAttributes()

Get the current blend rendering attributes in use.

Returns:

The current attributes instance or null

setAlphaAttributes

public void setAlphaAttributes(AlphaAttributes attr)
                        throws InvalidWriteTimingException

Set the alpha rendering attributes to use. Null will clear the current attributes.

Note Setting a value will disable state sorting for transparency on this object.

Parameters:

attr - The new attributes or null

Throws:

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

getAlphaAttributes

public AlphaAttributes getAlphaAttributes()

Get the current alpha rendering attributes in use.

Returns:

The current attributes instance or null

setDepthAttributes

public void setDepthAttributes(DepthAttributes attr)
                        throws InvalidWriteTimingException

Set the depth buffer attributes to use. Null will clear the current attributes.

Parameters:

attr - The new attributes or null

Throws:

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

getDepthAttributes

public DepthAttributes getDepthAttributes()

Get the current depth buffer attributes in use.

Returns:

The current attributes instance or null

setStencilAttributes

public void setStencilAttributes(StencilAttributes attr)
                          throws InvalidWriteTimingException

Set the stencil buffer attributes to use. Null will clear the current attributes.

Parameters:

attr - The new attributes or null

Throws:

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

getStencilAttributes

public StencilAttributes getStencilAttributes()

Get the current stencil buffer attributes in use.

Returns:

The current attributes instance or null

setShader

public void setShader(Shader s)
               throws InvalidWriteTimingException

Set the shader to use. Null will clear the current shader.

Parameters:

s - The new shader instance to use or null

Throws:

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

getShader

public Shader getShader()

Get the current shader in use.

Returns:

The current shader instance or null

setTextureUnits

public void setTextureUnits(TextureUnit[] texUnits,
                            int num)
                     throws InvalidWriteTimingException

Set the texture units to use. Null will disable texturing.

Parameters:

texUnits - The new Texture lists to set

num - The number of valid entries in the array

Throws:

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

numTextureUnits

public int numTextureUnits()

Get the current number of texture units that are valid

Returns:

a positive number

getTextureUnits

public void getTextureUnits(TextureUnit[] texUnits)

Get the texture units used by the material.

Parameters:

texUnits - An array to copy the texture units into

Throws:

java.lang.IllegalArgumentException - The provided array is not big enough to hold all the texture units

compareTo

public int compareTo(Appearance app)

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:

app - The argument instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(Appearance app)

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

Parameters:

app - The appearance instance to be compared

Returns:

true if the objects represent identical values