public abstract class Behavior extends Leaf
initialization method, called once when the behavior
becomes "live," and a
processStimulus method called
whenever appropriate by the Java 3D behavior scheduler. The
Behavior node also contains an enable flag, a scheduling region,
a scheduling interval, and a wakeup condition.
The scheduling region defines a spatial volume that serves to enable the scheduling of Behavior nodes. A Behavior node is active (can receive stimuli) whenever an active ViewPlatform's activation volume intersects a Behavior object's scheduling region. Only active behaviors can receive stimuli.
The scheduling interval defines a partial order of execution for behaviors that wake up in response to the same wakeup condition (that is, those behaviors that are processed at the same "time"). Given a set of behaviors whose wakeup conditions are satisfied at the same time, the behavior scheduler will execute all behaviors in a lower scheduling interval before executing any behavior in a higher scheduling interval. Within a scheduling interval, behaviors can be executed in any order, or in parallel. Note that this partial ordering is only guaranteed for those behaviors that wake up at the same time in response to the same wakeup condition, for example, the set of behaviors that wake up every frame in response to a WakeupOnElapsedFrames(0) wakeup condition.
initialize method allows a Behavior object to
initialize its internal state and specify its initial wakeup
condition(s). Java 3D invokes a behavior's initialize code when the
behavior's containing BranchGroup node is added to the virtual
universe. Java 3D does not invoke the initialize method in a new
thread. Thus, for Java 3D to regain control, the initialize method
must not execute an infinite loop; it must return. Furthermore, a
wakeup condition must be set or else the behavior's processStimulus
method is never executed.
processStimulus method receives and processes a
behavior's ongoing messages. The Java 3D behavior scheduler invokes
a Behavior node's processStimulus method when an active ViewPlatform's
activation volume intersects a Behavior object's scheduling region
and all of that behavior's wakeup criteria are satisfied. The
processStimulus method performs its computations and actions
(possibly including the registration of state change information
that could cause Java 3D to wake other Behavior objects),
establishes its next wakeup condition, and finally exits.
A typical behavior will modify one or more nodes or node components
in the scene graph. These modifications can happen in parallel
with rendering. In general, applications cannot count on behavior
execution being synchronized with rendering. There are two
exceptions to this general rule:
processStimulus method of a single behavior instance
are guaranteed to take effect in the same rendering frame.
processStimulus methods of the set of behaviors that
wake up in response to a WakeupOnElapsedFrames(0) wakeup condition
are guaranteed to take effect in the same rendering frame.
When the Java 3D behavior scheduler invokes a Behavior object's processStimulus method, that method may perform any computation it wishes. Usually, it will change its internal state and specify its new wakeup conditions. Most probably, it will manipulate scene graph elements. However, the behavior code can only change those aspects of a scene graph element permitted by the capabilities associated with that scene graph element. A scene graph's capabilities restrict behavioral manipulation to those manipulations explicitly allowed.
The application must provide the Behavior object with references to those scene graph elements that the Behavior object will manipulate. The application provides those references as arguments to the behavior's constructor when it creates the Behavior object. Alternatively, the Behavior object itself can obtain access to the relevant scene graph elements either when Java 3D invokes its initialize method or each time Java 3D invokes its processStimulus method.
Behavior methods have a very rigid structure. Java 3D assumes that they always run to completion (if needed, they can spawn threads). Each method's basic structure consists of the following:
A WakeupCondition object is an abstract class specialized to fourteen different WakeupCriterion objects and to four combining objects containing multiple WakeupCriterion objects. A Behavior node provides the Java 3D behavior scheduler with a WakeupCondition object. When that object's WakeupCondition has been satisfied, the behavior scheduler hands that same WakeupCondition back to the Behavior via an iterator.
Java 3D provides a rich set of wakeup criteria that Behavior objects can use in specifying a complex WakeupCondition. These wakeup criteria can cause Java 3D's behavior scheduler to invoke a behavior's processStimulus method whenever
A Behavior object constructs a WakeupCriterion by constructing the appropriate criterion object. The Behavior object must provide the appropriate arguments (usually a reference to some scene graph object and possibly a region of interest). Thus, to specify a WakeupOnViewPlatformEntry, a behavior would specify the region that will cause the behavior to execute if an active ViewPlatform enters it.
Note that a unique WakeupCriterion object must be used with each instance of a Behavior. Sharing wakeup criteria among different instances of a Behavior is illegal.
ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_LOCALE_READ, ALLOW_PARENT_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING
|Constructor and Description
Constructs a Behavior node with default parameters.
|Modifier and Type
|Method and Description
Retrieves the state of the Behavior enable flag.
Returns the number of scheduling intervals supported by this implementation of Java 3D.
Retrieves the Behavior node's scheduling bounding leaf.
Retrieves the Behavior node's scheduling bounds.
Retrieves the current scheduling interval of this Behavior node.
Initialize this behavior.
Posts the specified postId to the Behavior Scheduler.
Process a stimulus meant for this behavior.
Enables or disables this Behavior.
Set the Behavior's scheduling region to the specified bounding leaf.
Set the Behavior's scheduling region to the specified bounds.
Sets the scheduling interval of this Behavior node to the specified value.
Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to
cloneNode, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, duplicateNode, getBounds, getBoundsAutoCompute, getCollidable, getLocale, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable
clearCapability, clearCapabilityIsFrequent, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString
public abstract void initialize()
public abstract void processStimulus(java.util.Iterator<WakeupCriterion> criteria)
criteria - an iterator of triggered wakeup criteria for this
public void setSchedulingBounds(Bounds region)
region - the bounds that contains the Behavior's new scheduling
public Bounds getSchedulingBounds()
public void setSchedulingBoundingLeaf(BoundingLeaf region)
region - the bounding leaf node used to specify the Behavior
node's new scheduling region
public BoundingLeaf getSchedulingBoundingLeaf()
public void postId(int postId)
This feature allows applications to send arbitrary events into the behavior scheduler stream. It can be used as a notification scheme for communicating events to behaviors in the system.
postId - the Id being posted
public void setEnable(boolean state)
state - true or false to enable or disable this Behavior
public boolean getEnable()
public static int getNumSchedulingIntervals()
numSchedulingIntervals / 2.
public void setSchedulingInterval(int schedulingInterval)
numSchedulingIntervals / 2.
schedulingInterval - the new scheduling interval
java.lang.IllegalArgumentException - if
schedulingInterval < 0 or
public int getSchedulingInterval()
public void updateNodeReferences(NodeReferenceTable referenceTable)
This method is called by
cloneTree after all nodes in
the sub-graph have been duplicated. The cloned Leaf node's method
will be called and the Leaf node 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
NOTE: Applications should not call this method directly. It should only be called by the cloneTree method.