javax.media.j3d
Class SceneGraphObject

java.lang.Object
  extended by javax.media.j3d.SceneGraphObject
Direct Known Subclasses:
Node, NodeComponent

public abstract class SceneGraphObject
extends java.lang.Object

SceneGraphObject is the common superclass for all scene graph objects. Scene graph objects are classified into two main types: nodes and node components. The Node object is the common superclass of all nodes, which includes TransformGroup, Shape3D, etc. The NodeComponent object is the common superclass of all node components, which includes Geometry, Appearance, etc.

All scene graph objects have a name, a user data object, a set of capability bits, and a set of capabilityIsFrequent bits.

Capability bits control whether a particular attribute in a node or node component is readable or writable. For live or compiled scene graphs, only those attributes whose capabilities are set before the scene graph is compiled or made live may be read or written. The default value for all read capability bits is true, meaning that all attributes may be read by default. The default value for all write capability bits is false, meaning that no attributes may be written by default. Read capability bits are defined as those capability bits of the form ALLOW_*_READ, plus the ALLOW_INTERSECT capability bit. Write capability bits are defined as those capability bits of the form ALLOW_*_WRITE, plus the ALLOW_CHILDREN_EXTEND and ALLOW_DETACH capability bits.

NOTE that the ENABLE_COLLISION_REPORTING and ENABLE_PICK_REPORTING bits are not really capability bits, although they are set with the setCapability method. The default value for each of the ENABLE_*_REPORTING bits is false.

For more information, see the Introduction to the Java 3D API.


Field Summary
private  long capabilityBits
           
private  long capabilityIsFrequentBits
           
private  boolean compiled
           
private  boolean live
           
private  boolean liveOrCompiled
           
(package private)  java.util.Hashtable nodeHashtable
           
private  java.lang.String objectName
           
(package private)  SceneGraphObjectRetained retained
           
private  java.lang.Object userData
           
 
Constructor Summary
SceneGraphObject()
          Constructs a SceneGraphObject with default parameters.
 
Method Summary
(package private)  boolean capabilityBitsEmpty()
           
(package private)  void checkForLiveOrCompiled()
           
 void clearCapability(int bit)
          Clear the specified capability bit.
 void clearCapabilityIsFrequent(int bit)
          Clears the isFrequent bit associated with the specified capability bit.
(package private)  void clearLive()
          Clears an internal flag which indicates that this scene graph object is no longer part of a live scene graph.
(package private)  void createRetained()
          Creates the retained mode object that this scene graph object will point to.
protected  void duplicateSceneGraphObject(SceneGraphObject originalNode)
          Copies all SceneGraphObject information from originalNode into the current node.
 boolean getCapability(int bit)
          Retrieves the specified capability bit.
 boolean getCapabilityIsFrequent(int bit)
          Retrieves the isFrequent bit associated with the specified capability bit.
 java.lang.String getName()
          Returns the name of this object.
(package private)  java.lang.String getNamePrefix()
           
(package private)  NodeComponent getNodeComponent(NodeComponent originalNodeComponent, boolean forceDuplicate, java.util.Hashtable hashtable)
          If forceDuplicate is true or duplicateOnCloneTree flag is true.
 java.lang.Object getUserData()
          Retrieves the userData field from this scene graph object.
 boolean isCompiled()
          Returns a flag indicating whether the node is part of a scene graph that has been compiled.
 boolean isLive()
          Returns a flag indicating whether the node is part of a live scene graph.
(package private)  boolean isLiveOrCompiled()
          Returns a flag indicating whether the node is part of a live scene graph or a compiled scene graph.
 void setCapability(int bit)
          Sets the specified capability bit.
 void setCapabilityIsFrequent(int bit)
          Sets the isFrequent bit associated with the specified capability bit.
(package private)  void setCompiled()
          Sets an internal flag which indicates that this scene graph object has been compiled.
(package private)  void setDefaultReadCapabilities(int[] bits)
          Method to set default read capability bits to true
(package private)  void setLive()
          Sets an internal flag which indicates that this scene graph object is part of a live scene graph.
 void setName(java.lang.String name)
          Sets the name of this object.
 void setUserData(java.lang.Object userData)
          Sets the userData field associated with this scene graph object.
 java.lang.String toString()
          Returns a String representation of this SceneGraphObject.
 void updateNodeReferences(NodeReferenceTable referenceTable)
          Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to cloneTree.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

retained

SceneGraphObjectRetained retained

capabilityBits

private long capabilityBits

capabilityIsFrequentBits

private long capabilityIsFrequentBits

compiled

private boolean compiled

live

private boolean live

liveOrCompiled

private boolean liveOrCompiled

userData

private java.lang.Object userData

objectName

private java.lang.String objectName

nodeHashtable

java.util.Hashtable nodeHashtable
Constructor Detail

SceneGraphObject

public SceneGraphObject()
Constructs a SceneGraphObject with default parameters. The default values are as follows:

Method Detail

createRetained

void createRetained()
Creates the retained mode object that this scene graph object will point to. This should be overridden by those classes that have a specific retained mode object.


setDefaultReadCapabilities

void setDefaultReadCapabilities(int[] bits)
Method to set default read capability bits to true


getCapability

public final boolean getCapability(int bit)
Retrieves the specified capability bit. Note that only one capability bit may be retrieved per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the bit whose value is returned
Returns:
true if the bit is set, false if the bit is clear

setCapability

public final void setCapability(int bit)
Sets the specified capability bit. Note that only one capability bit may be set per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the bit to set
Throws:
RestrictedAccessException - if this object is part of live or compiled scene graph

clearCapability

public final void clearCapability(int bit)
Clear the specified capability bit. Note that only one capability bit may be cleared per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the bit to clear
Throws:
RestrictedAccessException - if this object is part of live or compiled scene graph

capabilityBitsEmpty

final boolean capabilityBitsEmpty()

getCapabilityIsFrequent

public final boolean getCapabilityIsFrequent(int bit)
Retrieves the isFrequent bit associated with the specified capability bit. Note that only one isFrequent bit, for a single capability bit, may be retrieved per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the bit whose value is returned
Returns:
true if the isFrequent bit is set, false if the isFrequent bit is clear
Since:
Java 3D 1.3

setCapabilityIsFrequent

public final void setCapabilityIsFrequent(int bit)
Sets the isFrequent bit associated with the specified capability bit. Setting the isFrequent bit indicates that the application may frequently access or modify those attributes permitted by the associated capability bit. This can be used by Java 3D as a hint to avoid certain optimizations that could cause those accesses or modifications to be expensive. By default the isFrequent bit associated with each capability bit is set.

Unlike setCapability, this method may be called on a live scene graph object (but not on a compiled object).

Note that only one isFrequent bit, for a single capability bit, may be set per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the capability bit for which to set the associated isFrequent bit
Throws:
RestrictedAccessException - if this object is part of a compiled scene graph
Since:
Java 3D 1.3

clearCapabilityIsFrequent

public final void clearCapabilityIsFrequent(int bit)
Clears the isFrequent bit associated with the specified capability bit. Clearing the isFrequent bit indicates that the application will infrequently access or modify those attributes permitted by the associated capability bit. This can be used by Java 3D as a hint to enable certain optimizations that it might otherwise avoid, for example, optimizations that could cause those accesses or modifications to be expensive.

Unlike clearCapability, this method may be called on a live scene graph object (but not on a compiled object).

Note that only one isFrequent bit, for a single capability bit, may be cleared per method invocation--capability bits cannot be ORed together.

Parameters:
bit - the capability bit for which to clear the associated isFrequent bit
Throws:
RestrictedAccessException - if this object is part of a compiled scene graph
Since:
Java 3D 1.3

setCompiled

final void setCompiled()
Sets an internal flag which indicates that this scene graph object has been compiled.


isCompiled

public final boolean isCompiled()
Returns a flag indicating whether the node is part of a scene graph that has been compiled. If so, then only those capabilities explicitly allowed by the object's capability bits are allowed.

Returns:
true if node is part of a compiled scene graph, else false

setLive

final void setLive()
Sets an internal flag which indicates that this scene graph object is part of a live scene graph.


clearLive

final void clearLive()
Clears an internal flag which indicates that this scene graph object is no longer part of a live scene graph.


isLive

public final boolean isLive()
Returns a flag indicating whether the node is part of a live scene graph.

Returns:
true if node is part of a live scene graph, else false

isLiveOrCompiled

final boolean isLiveOrCompiled()
Returns a flag indicating whether the node is part of a live scene graph or a compiled scene graph.

Returns:
true if either live or compiled

checkForLiveOrCompiled

final void checkForLiveOrCompiled()

setUserData

public void setUserData(java.lang.Object userData)
Sets the userData field associated with this scene graph object. The userData field is a reference to an arbitrary object and may be used to store any user-specific data associated with this scene graph object--it is not used by the Java 3D API. If this object is cloned, the userData field is copied to the newly cloned object.

Parameters:
userData - a reference to the new userData field

getUserData

public java.lang.Object getUserData()
Retrieves the userData field from this scene graph object.

Returns:
the current userData field

updateNodeReferences

public void updateNodeReferences(NodeReferenceTable referenceTable)
Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to cloneTree. This method is called by cloneTree after all nodes in the sub-graph have been duplicated. The cloned Leaf node and cloned NodeComponent's method will be called and the Leaf node/NodeComponent can then look up any object references by using the getNewObjectReference method found in the NodeReferenceTable object. If a match is found, a reference to the corresponding object in the newly cloned sub-graph is returned. If no corresponding reference is found, either a DanglingReferenceException is thrown or a reference to the original object is returned depending on the value of the allowDanglingReferences parameter passed in the cloneTree call.

NOTE: Applications should not call this method directly. It should only be called by the cloneTree method.

Parameters:
referenceTable - a NodeReferenceTableObject that contains the getNewObjectReference method needed to search for new object instances.
See Also:
NodeReferenceTable, Node.cloneTree(), DanglingReferenceException

setName

public void setName(java.lang.String name)
Sets the name of this object. Object names are for information only.

Parameters:
name - the new name of this object
Since:
Java 3D 1.4

getName

public java.lang.String getName()
Returns the name of this object.

Returns:
the name of this object
Since:
Java 3D 1.4

duplicateSceneGraphObject

protected void duplicateSceneGraphObject(SceneGraphObject originalNode)
Copies all SceneGraphObject information from originalNode into the current node. This method is called from the cloneNode method which is, in turn, called by the cloneTree method.

NOTE: Applications should not call this method directly. It should only be called by the cloneNode method.

Parameters:
originalNode - the original node to duplicate.
See Also:
Group.cloneNode(boolean), Node.duplicateNode(javax.media.j3d.Node, boolean), Node.cloneTree(), NodeComponent.setDuplicateOnCloneTree(boolean)

getNodeComponent

NodeComponent getNodeComponent(NodeComponent originalNodeComponent,
                               boolean forceDuplicate,
                               java.util.Hashtable hashtable)
If forceDuplicate is true or duplicateOnCloneTree flag is true. This procedure will return a clone of originalNode or the value in in nodeHashtable if found. Otherwise return originalNode This method is called from the duplicateAttributes method during cloneNodeComponent.

Parameters:
originalNodeComponent - the original node to duplicate.
forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree variable determines whether NodeComponent data is duplicated or copied.
nodeHashtable - is used to keep track of mapping between old and new node references.

getNamePrefix

java.lang.String getNamePrefix()

toString

public java.lang.String toString()
Returns a String representation of this SceneGraphObject. If its name is non-null, then it is concatenated with super.toString().

Overrides:
toString in class java.lang.Object


Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.