Class SceneGraphObject
- java.lang.Object
-
- 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 theALLOW_INTERSECT
capability bit. Write capability bits are defined as those capability bits of the formALLOW_*_WRITE
, plus theALLOW_CHILDREN_EXTEND
andALLOW_DETACH
capability bits.NOTE that the
ENABLE_COLLISION_REPORTING
andENABLE_PICK_REPORTING
bits are not really capability bits, although they are set with the setCapability method. The default value for each of theENABLE_*_REPORTING bits
is false.For more information, see the Introduction to the Java 3D API.
-
-
Constructor Summary
Constructors Constructor Description SceneGraphObject()
Constructs a SceneGraphObject with default parameters.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clearCapability(int bit)
Clear the specified capability bit.void
clearCapabilityIsFrequent(int bit)
Clears the isFrequent bit associated with the specified capability bit.protected void
duplicateSceneGraphObject(SceneGraphObject originalNode)
Copies all SceneGraphObject information fromoriginalNode
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.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.void
setCapability(int bit)
Sets the specified capability bit.void
setCapabilityIsFrequent(int bit)
Sets the isFrequent bit associated with the specified capability bit.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 tocloneTree
.
-
-
-
Constructor Detail
-
SceneGraphObject
public SceneGraphObject()
Constructs a SceneGraphObject with default parameters. The default values are as follows:-
all read capability bits : set (true)
all write capability bits : clear (false)
all capabilityIsFrequent bits : set (true)
isLive : false
isCompiled : false
user data : null
name : null
-
-
Method Detail
-
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
-
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
-
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
-
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
-
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 tocloneTree
. This method is called bycloneTree
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 thegetNewObjectReference
method found in theNodeReferenceTable
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 theallowDanglingReferences
parameter passed in thecloneTree
call.NOTE: Applications should not call this method directly. It should only be called by the cloneTree method.
- Parameters:
referenceTable
- a NodeReferenceTableObject that contains thegetNewObjectReference
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 fromoriginalNode
into the current node. This method is called from thecloneNode
method which is, in turn, called by thecloneTree
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)
-
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 classjava.lang.Object
-
-