Aviatrix3D
2.1.0

org.j3d.aviatrix3d
Class Appearance

java.lang.Object
  extended by org.j3d.aviatrix3d.SceneGraphObject
      extended by org.j3d.aviatrix3d.NodeComponent
          extended by 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

Aviatrix3D
2.1.0

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