Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.media.j3d
Class Behavior

java.lang.Object
  |
  +--javax.media.j3d.SceneGraphObject
        |
        +--javax.media.j3d.Node
              |
              +--javax.media.j3d.Leaf
                    |
                    +--javax.media.j3d.Behavior
Direct Known Subclasses:
Billboard, Interpolator, KeyNavigatorBehavior, LOD, Mouse6DPointerBehavior, MouseBehavior, PickMouseBehavior, PickMouseBehavior, UnresolvedBehavior, ViewPlatformBehavior
public abstract class Behavior
extends Leaf

The Behavior leaf node provides a framework for adding user-defined actions into the scene graph. Behavior is an abstract class that defines two methods that must be overridden by a subclass: An 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.

The 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.

The 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:

  1. All modifications to scene graph objects (not including geometry by-reference or texture by-reference) made from the processStimulus method of a single behavior instance are guaranteed to take effect in the same rendering frame.
  2. All modifications to scene graph objects (not including geometry by-reference or texture by-reference) made from the 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.
Note that modifications to geometry by-reference or texture by-reference are not guaranteed to show up in the same frame as other scene graph changes.

Code Structure

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:

WakeupCondition Object

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 enumeration.

WakeupCriterion Object

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.

See Also:
WakeupCondition

Field Summary
 
Fields inherited from class javax.media.j3d.Node
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_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING
 
Constructor Summary
Behavior()
          Constructs a Behavior node with default parameters.
 
Method Summary
 boolean getEnable()
          Retrieves the state of the Behavior enable flag.
static int getNumSchedulingIntervals()
          Returns the number of scheduling intervals supported by this implementation of Java 3D.
 BoundingLeaf getSchedulingBoundingLeaf()
          Retrieves the Behavior node's scheduling bounding leaf.
 Bounds getSchedulingBounds()
          Retrieves the Behavior node's scheduling bounds.
 int getSchedulingInterval()
          Retrieves the current scheduling interval of this Behavior node.
protected  View getView()
          Returns the primary view associated with this behavior.
protected  WakeupCondition getWakeupCondition()
          Retrieves this behavior's current wakeup condition as set by the wakeupOn method.
abstract  void initialize()
          Initialize this behavior.
 void postId(int postId)
          Posts the specified postId to the Behavior Scheduler.
abstract  void processStimulus(java.util.Enumeration criteria)
          Process a stimulus meant for this behavior.
 void setEnable(boolean state)
          Enables or disables this Behavior.
 void setSchedulingBoundingLeaf(BoundingLeaf region)
          Set the Behavior's scheduling region to the specified bounding leaf.
 void setSchedulingBounds(Bounds region)
          Set the Behavior's scheduling region to the specified bounds.
 void setSchedulingInterval(int schedulingInterval)
          Sets the scheduling interval of this Behavior node to the specified value.
 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.
protected  void wakeupOn(WakeupCondition criteria)
          Defines this behavior's wakeup criteria.
 
Methods inherited from class javax.media.j3d.Node
cloneNode, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, duplicateNode, getBounds, getBoundsAutoCompute, getCollidable, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable
 
Methods inherited from class javax.media.j3d.SceneGraphObject
clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setUserData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Behavior

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

Method Detail

initialize

public abstract void initialize()
Initialize this behavior. Classes that extend Behavior must provide their own initialize method.
NOTE: Applications should not call this method. It is called by the Java 3D behavior scheduler.

processStimulus

public abstract void processStimulus(java.util.Enumeration criteria)
Process a stimulus meant for this behavior. This method is invoked if the Behavior's wakeup criteria are satisfied and an active ViewPlatform's activation volume intersects with the Behavior's scheduling region. Classes that extend Behavior must provide their own processStimulus method.
NOTE: Applications should not call this method. It is called by the Java 3D behavior scheduler.

Parameters:
criteria - an enumeration of triggered wakeup criteria for this behavior

setSchedulingBounds

public void setSchedulingBounds(Bounds region)
Set the Behavior's scheduling region to the specified bounds. This is used when the scheduling bounding leaf is set to null.

Parameters:
region - the bounds that contains the Behavior's new scheduling region

getSchedulingBounds

public Bounds getSchedulingBounds()
Retrieves the Behavior node's scheduling bounds.

Returns:
this Behavior's scheduling bounds information

setSchedulingBoundingLeaf

public void setSchedulingBoundingLeaf(BoundingLeaf region)
Set the Behavior's scheduling region to the specified bounding leaf. When set to a value other than null, this overrides the scheduling bounds object.

Parameters:
region - the bounding leaf node used to specify the Behavior node's new scheduling region

getSchedulingBoundingLeaf

public BoundingLeaf getSchedulingBoundingLeaf()
Retrieves the Behavior node's scheduling bounding leaf.

Returns:
this Behavior's scheduling bounding leaf information

wakeupOn

protected void wakeupOn(WakeupCondition criteria)
Defines this behavior's wakeup criteria. This method may only be called from a Behavior object's initialize or processStimulus methods to (re)arm the next wakeup. It should be the last thing done by those methods.

Parameters:
criteria - the wakeup criteria for this behavior
Throws:
java.lang.IllegalStateException - if this method is called by a method other than initialize or processStimulus

getWakeupCondition

protected WakeupCondition getWakeupCondition()
Retrieves this behavior's current wakeup condition as set by the wakeupOn method. If no wakeup condition is currently active, null will be returned. In particular, this means that null will be returned if Java 3D is executing this behavior's processStimulus routine and wakeupOn has not yet been called to re-arm the wakeup condition for next time.

Returns:
the current wakeup condition for this behavior
Since:
Java 3D 1.3

postId

public void postId(int postId)
Posts the specified postId to the Behavior Scheduler. All behaviors that have registered WakeupOnBehaviorPost with this postId, or a postId of 0, and with this behavior, or a null behavior, will have that wakeup condition met.

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.

Parameters:
postId - the Id being posted
See Also:
WakeupOnBehaviorPost

setEnable

public void setEnable(boolean state)
Enables or disables this Behavior. The default state is enabled.

Parameters:
state - true or false to enable or disable this Behavior

getEnable

public boolean getEnable()
Retrieves the state of the Behavior enable flag.

Returns:
the Behavior enable state

getNumSchedulingIntervals

public static int getNumSchedulingIntervals()
Returns the number of scheduling intervals supported by this implementation of Java 3D. The minimum number of supported intervals must be at least 10. The default scheduling interval for each behavior instance is set to numSchedulingIntervals / 2.

Returns:
the number of supported scheduling intervals
Since:
Java 3D 1.3

setSchedulingInterval

public void setSchedulingInterval(int schedulingInterval)
Sets the scheduling interval of this Behavior node to the specified value. 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. The default value is numSchedulingIntervals / 2.

Parameters:
schedulingInterval - the new scheduling interval
Throws:
java.lang.IllegalArgumentException - if schedulingInterval < 0 or schedulingInterval >= numSchedulingIntervals
Since:
Java 3D 1.3

getSchedulingInterval

public int getSchedulingInterval()
Retrieves the current scheduling interval of this Behavior node.

Returns:
the current scheduling interval
Since:
Java 3D 1.3

getView

protected View getView()
Returns the primary view associated with this behavior. This method is useful with certain types of behaviors (e.g., Billboard, LOD) that rely on per-View information and with behaviors in general in regards to scheduling (the distance from the view platform determines the active behaviors). The "primary" view is defined to be the first View attached to a live ViewPlatform, if there is more than one active View. So, for instance, Billboard behaviors would be oriented toward this primary view, in the case of multiple active views into the same scene graph.

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'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 cloneTree call.

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

Overrides:
updateNodeReferences in class SceneGraphObject
Parameters:
referenceTable - a NodeReferenceTableObject that contains the getNewObjectReference method needed to search for new object instances.
See Also:
NodeReferenceTable, Node.cloneTree(), DanglingReferenceException
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD