Contents Previous Next

Java 3D API Specification


C H A P T E R10
Behaviors, Interpolators, and Picking




Behavior nodes provide the means for animating objects, processing keyboard and mouse inputs, reacting to movement, and enabling and processing pick events. Behavior nodes contain Java code and state variables. A Behavior's Java code can interact with Java objects, change node values within a Java 3D scene graph, change the behavior's internal state: in general perform any computation it wishes.

Simple behaviors can add surprisingly interesting effects to a scene graph. For example, we can animate a rigid object by using a behavior node to repetitively modify the TransformGroup node that points to the object we wish to animate. Alternatively, a behavior node can track the current position of a mouse and modify portions of the scene graph in response.

10.1 Behavior Object

A Behavior leaf node object contains a scheduling region and two methods: 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 object also contains the state information needed by its initilization and processStimulus methods.

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 a ViewPlatform's activation volume intersects a Behavior object's scheduling region. Only active behaviors can receive stimuli.

The initialization method allows a behavior object to initialize its internal state and specify its initial wakeup condition(s). Java 3D invokes a behavior's initialization code when the behavior's containing BranchGroup node is added to the virtual universe. Java 3D does not invoke the initialization method in a new thread. Thus, for Java 3D to regain control, the initialization method must not execute an infinite loop. It must return.

The processStimulus method receives and processes a behaviors' ongoing messages. The Java 3D behavior scheduler invokes a behavior node's processStimulus-method when a 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.

10.1.1 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 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 initialization behavior or each time Java 3D invokes its processStimulus behavior.

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:

10.1.2 WakeupCondition

A WakeupCondition object is an abstract class specialized to ten different WakeupCriterion objects and to four combining objects containing multiple WakeupCriterion objects. The four combining objects are WakeupOr, WakeupAnd, WakeupOrOfAnds, and WakeupAndOfOrs 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.

10.1.3 WakeupCriterion

Java 3D provides a rich set of wakeup criteria that Behavior objects can use in specifying a complex WakeupCondition. These wakeup criterion 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 a viewplatform enters.

10.1.4 Composing WakeupCriterion Objects

A Behavior object can combine multiple WakeupCriterion objects into a more powerful, composite WakeupCondition. Java 3D behaviors construct a composite WakeupCondition in one of the following ways: 

        WakeupCriterion && WakeupCriterion && ...

        WakeupCriterion || WakeupCriterion || ...

        WakeupOr && WakeupOr && ...

        WakeupAnd || WakeupAnd || ...

10.2 Composing Behaviors

Behavior objects can condition themselves to awaken only when signaled by a behavior node. The WakeupOnBehaviorPost WakeupCriterion takes as arguments a reference to a Behavior node reference and an integer. These two arguments allow a behavior to limit its wakeup criterion to a specific post by a specific behavior.

The WakeupOnBehaviorPost WakeupCriterion permits behaviors to chain their computations allowing parenthetical computations-one behavior opens a door and the second closes the same door or one behavior highlights an object and the second unhighlights the same object.

10.3 Scheduling

As a virtual universe grows large, Java 3D must carefully husband its resources to ensure adequate performance. In a 10,000-object virtual universe with 400 or so behavior nodes, a naive implementation of Java 3D could easily end up consuming the majority of its compute cycles executing the behaviors associated with the 400 behavior objects before it draws a frame. In such a situation, the frame rate could easily drop to unacceptable levels.

Behavior objects are usually associated with geometric objects in the virtual universe. In our example of 400 Behavior objects scattered throughout a 10,000-object virtual universe, only a few of these associated geometric objects would be visible at a given time. A sizeable fraction of the Behavior nodes-those associated with non-visible objects-need not execute. Only those relatively few Behavior objects that are associated with visible objects must execute.

Java 3D mitigates the problem of a large number of Behavior nodes in a high-population virtual universe through execution culling-choosing only to invoke those behaviors that have high relevance.

Java 3D requires each behavior to have a scheduling region and to post a wakeup condition. Together a behavior's scheduling region and wakeup criterion, provide Java 3D's behavior scheduler with sufficient domain knowledge to selectively prune behavior invocations and only invoke those behaviors that absolutely need to execute.

10.4 How Java 3D Performs Execution Culling

Java 3D finds all scheduling regions associated with Behavior nodes and constructs a scheduling-volume tree. It also creates an AND-OR tree containing all the Behavior node wakeup criterion. These two data structures provide the domain knowledge Java 3D needs to prune unneeded behavior execution (to perform "execution triage").

Java 3D must track a behavior's wakeup conditions only if a ViewPlatform object's activation volume intersects with that Behavior object's scheduling region. If the ViewPlatform object's activation volume does not intersect with a behavior's scheduling region, Java 3D can safely ignore that behavior's wakeup criterion.

In essence, the Java 3D scheduler performs the following checks:

Java 3D's behavior scheduler executes those Behavior objects that have been scheduled by calling the behavior's processStimulus method.

10.5 The Behavior API

The Java 3D behavior API spreads its functionality across three objects: the Behavior Leaf node, the WakeupCondition object, and the WakeupCriterion objects.

10.5.1 The Behavior Node
Methods

The Behavior Leaf node class defines the following methods. 

public abstract void initialize()

This method, invoked by Java 3D's behavior scheduler, is used to initialize the behavior's state variables and to establishes its WakeupConditions. Classes that extend Behavior must provide their own initialize method. 

public abstract void processStimulus(Enumeration criteria)

This method processes stimuli destined for this behavior. The behavior scheduler invokes this method if its WakeupCondition is satisfied. Classes that extend Behavior must provide their own processStimulus method. 

public final void setSchedulingBounds(Bounds region)
public final Bounds getSchedulingBounds()

These methods allow the user both to specify and retrieve this behavior's scheduling bounds. 

public final void setSchedulingBoundingLeaf(BoundingLeaf region)
public final BoundingLeaf getSchedulingBoundingLeaf()

These methods set and retrieve the Behavior node's scheduling region. When set to a value other than null, this overrides the scheduling bounds object. 

public void wakeupOn(WakeupCondition criteria)

This method, invoked by the behavior, informs Java 3D's scheduler to wake up this Behavior object whenever the specified WakeupCondition is satisfied. 

public void postId(int postId)

This method, when invoked by a behavior, informs Java 3D's scheduler of the identified event. The scheduler will schedule other behavior objects that have registered interest in this posting.

10.5.2 WakeupCondition Object

A WakeupCondition object is a superclass, and thus a container for a WakeupCriterion object or some combination of WakeupCriterion objects made using WakeupOr, WakeupAnd, WakeupOrOfAnds, or WakeupAndOfOr objects. A Behavior node hands a WakeupCondition to the behavior scheduler and the behavior scheduler hands back an enumeration of that WakeupCondition.

Methods

The Java 3D API provides two methods for constructing WakeupCondition enumerations: 

public Enumeration allElements()
public Enumeration triggeredElements()

These two methods create enumerators that sequentially access this WakeupCondition's WakeupCriteria. The first method creates an enumerator that sequentially provides a call to the WakeupCriteria. The second method creates an enumerator that sequentially presents only those WakeupCriteria that have been satisfied.

10.5.2.1 The WakeupCriterion Objects

The WakeupCriterion object class consists of several subclasses. Each subclass specifies one particular wakeup criteria, that criteria's associated arguments (if any), and either a flag that indicates whether this criteria caused a behavior object to awaken or a return field containing the information that caused the Behavior object to awaken.

Methods
public boolean hasTriggered()

This predicate method returns true if this WakeupCriterion contributed to waking a Behavior object.

10.5.2.2 WakeupOnAWTEvent

This WakeupCriterion object specifies that Java 3D should awaken a behavior when the specified AWT event occurs.

Constructors
public WakeupOnAWTEvent(int AwtId)
public WakeupOnAWTEvent(long EventMask)

The first constructor creates a WakeupOnAWTEvent object that informs Java 3D's scheduler to wake up the specified Behavior object whenever the AWT event specified by AwtId occurs. The second constructor creates a WakeupOnAWTEvent object that informs Java 3D's scheduler to wake up the specified Behavior object whenever any of the specified AWT EVENT_MASK events occur. EventMask consists of a ORed collection of EVENT_MASK values.

Methods
public AWTEvent[] getAWTEvent()

This method returns the array of consecutive AWTevents that triggered this WakeupCriterion to awaken the Behavior object. The Behavior object can retrieve the AWTEvent array and process it in any way it wishes.

10.5.2.3 WakeupOnActivation

The WakeupOnActivation object specifies a wakeup the first time the ViewPlatform's activation region intersects with this objects scheduling region.

Constructors
public WakeupOnActivation()

This constructor creates a WakeupOnActivation criterion.

10.5.2.4 WakeupOnBehaviorPost

This WakeupCriterion object specifies that Java 3D should awaken this behavior when the specified behavior posts the specified Id. A PostId of 0 specifies that this behavior should awaken on any post from the specified behavior. Specifying a null behavior implies this behavior should awaken whenever any behavior posts the specified PostID.

Constructors
public WakeupOnBehaviorPost(Behavior behavior, int postId)

This constructor creates a WakeupOnBehaviorPost object that informs Java 3D's scheduler to wake up this Behavior object whenever the specified behavior posts the specified postId. Specifying a null behavior represents any Behavior node that posts postId to wake this behavior. Specifying a postId of 0 implies that all posts from the specified behavior will awake this behavior.

Methods
public int getPostId()

This method returns the postId used in creating this WakeupCriterion.

10.5.2.5 WakeupOnDeactivation

The WakeupOnDeactivation object specifies a wakeup on the first detection of a ViewPlatform's activation region no longer intersecting with this object's scheduling region.

Constructors
public WakeupOnDeactivation(Bounds region)

This constructor creates a new WakeupOnDeactivation criterion.

10.5.2.6 WakeupOnElapsedFrames

This WakeupCriterion object specifies that Java 3D should awaken this behavior after it has rendered the specified number of frames. A value of zero implies that Java 3D will awaken this behavior at the next frame.

Constructors
public WakeupOnElapsedFrames(int frameCount)

This constructor creates a WakeupOnElapsedFrames object that informs Java 3D's scheduler to wake up the specified Behavior object after it has drawn frameCount frames. A frameCount value of zero means wake up at the next frame.

Methods
public int getElapsedFrameCount()

This method returns the frame count used in creating this WakeupCriterion.

10.5.2.7 WakeupOnElapsedTime

This WakeupCriterion object specifies that Java 3D should awaken this behavior after an elapsed number of milliseconds.

Constructors
public WakeupOnElapsedTime(long milliseconds)

This constructor creates a WakeupOnElapsedTime object that informs Java 3D's scheduler to wake up the specified Behavior object after the specified number of milliseconds.

Note: The scheduler will schedule the object after the specified number of milliseconds have elapsed, not before; however, the elapsed time may actually be slightly greater than the time specified.
Methods
public long getElapsedFrameTime()

This method returns the millisecond count used in creating this WakeupCriterion.

10.5.2.8 WakeupOnSensorEntry

This WakeupCriterion object specifies that Java 3D should awaken this behavior when any sensor enters the specified region.

Note: There can be situations where a Sensor may enter and then exit an armed region so rapidly that neither the Entry nor Exit conditions get engaged.
Constructors
public WakeupOnSensorEntry(Bounds region)

This constructor creates a WakeupOnSensorEntry object that informs Java 3D's scheduler to wake up the specified Behavior object whenever it detects a sensor within the specified region for the first time.

Methods
public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.2.9 WakeupOnSensorExit

This WakeupCriterion object specifies that Java 3D should awaken this behavior when any sensor already marked as within the region is no longer in that region.

Note: This semantic guarantees that an Exit condition gets engaged if its corresponding Entry condition was engaged.
Constructors
public WakeupOnSensorExit(Bounds region)

This constructor creates a WakeupOnSensorExit object that informs Java 3D's scheduler to wake up the specified Behavior object the first time it detects that a sensor has left the specified region.

Methods
public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.2.10 WakeupOnCollisionEntry

This WakeupCriterion object specifies that Java 3D should awaken this behavior when the specified object collides with any other object in the scene graph.

Constants
public static final int USE_GEOMETRY
public static final int USE_BOUNDS

These constants specify whether collision against a Shape or Morph node is done using the actual geometry or whether the geometric bounds is used as an approximation.

Constructors
public WakeupOnCollisionEntry(SceneGraphPath armingPath)
public WakeupOnCollisionEntry(SceneGraphPath armingPath,
       int speedHint)
public WakeupOnCollisionEntry(Node armingNode)
public WakeupOnCollisionEntry(Node armingNode, int speedHint)
public WakeupOnCollisionEntry(Bounds armingBounds)

This constructor creates a WakeupOnCollisionEntry object that informs Java 3D's scheduler to wake up the specified Behavior object if the specified node's geometry or the specified bounds collides with any other object in the scene graph. The speedHint flag is one of: USE_GEOMETRY or USE_BOUNDS.

Methods
public SceneGraphPath getArmingPath()
public Bounds getArmingBounds()

These methods return the "collideable" path or bounds object used in specifying the collision detection. 

public SceneGraphPath getTriggeringPath()
public Bounds getTriggeringBounds()

This method returns the path or bounds object that caused the collision.

10.5.2.11 WakeupOnCollisionExit

This WakeupCriterion object specifies that Java 3D should awaken this behavior when the specified object no longer collides with any other object in the scene graph.

Constants
public static final int USE_GEOMETRY
public static final int USE_BOUNDS

These constants specify whether collision against a Shape or Morph node is done using the actual geometry or whether the geometric bounds is used as an approximation.

Constructors
public WakeupOnCollisionExit(SceneGraphPath armingPath)
public WakeupOnCollisionExit(SceneGraphPath armingPath,
       int speedHint)
public WakeupOnCollisionExit(Node armingNode)
public WakeupOnCollisionExit(Node armingNode, int speedHint)
public WakeupOnCollisionExit(Bounds armingBounds)

This constructor creates a WakeupOnCollisionExit object that informs Java 3D's scheduler to wake up the specified Behavior object if the specified node's geometry or the specified bounds collides with any other object in the scene graph. The speedHint flag is one of: USE_GEOMETRY or USE_BOUNDS.

Methods
public SceneGraphPath getArmingPath()
public Bounds getArmingBounds()

These methods return the "collideable" path or bounds object used in specifying the collision detection. 

public SceneGraphPath getTriggeringPath()
public Bounds getTriggeringBounds()

This method returns the path or bounds object that caused the collision.

10.5.2.12 WakeupOnCollisionMovement

This WakeupCriterion object specifies that Java 3D should awaken this behavior when the specified object moves while in a state of collision with any other object in the scene graph.

Constants
public static final int USE_GEOMETRY
public static final int USE_BOUNDS

These constants specify whether collision against a Shape or Morph node is done using the actual geometry or whether the geometric bounds is used as an approximation.

Constructors
public WakeupOnCollisionMovement(SceneGraphPath armingPath)
public WakeupOnCollisionMovement(SceneGraphPath armingPath,
       int speedHint)
public WakeupOnCollisionMovement(Node armingNode)
public WakeupOnCollisionMovement(Node armingNode, int speedHint)
public WakeupOnCollisionMovement(Bounds armingBounds)

This constructor creates a WakeupOnCollisionMovement object that informs Java 3D's scheduler to wake up the specified Behavior object if the specified node's geometry or the specified bounds collides with any other object in the scene graph. The speedHint flag is one of: USE_GEOMETRY or USE_BOUNDS.

Methods
public SceneGraphPath getArmingPath()
public Bounds getArmingBounds()

These methods return the "collideable" path or bounds object used in specifying the collision detection. 

public SceneGraphPath getTriggeringPath()
public Bounds getTriggeringBounds()

This method returns the path or bounds object that caused the collision.

10.5.2.13 WakeupOnViewPlatformEntry

This WakeupCriterion object specifies that Java 3D should awaken this behavior when any ViewPlatform enters the specified region.

Note: There can be situations where a ViewPlatform may enter and then exit an armed region so rapidly that neither the Entry nor Exit conditions get engaged.
Constructors
public WakeupOnViewPlatformEntry(Bounds region)

This constructor creates a WakeupOnViewPlatformEntry object that informs Java 3D's scheduler to wake up the specified Behavior object whenever it detects a ViewPlatform within the specified region for the first time.

Methods
public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.2.14 WakeupOnViewPlatformExit

This WakeupCriterion object specifies that Java 3D should awaken this Behavior when any ViewPlatform already marked as within the region is no longer in that region.

Note: This semantic guarantees that an Exit condition gets engaged if its corresponding Entry condition was engaged.
Constructors
public WakeupOnViewPlatformExit(Bounds region)

This constructor creates a WakeupOnViewPlatformExit object that informs Java 3D's scheduler to wake up the specified Behavior object the first time it detects a ViewPlatform has left the specified region.

Methods
public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.2.15 WakeupAnd

The WakeupAnd class specifies any number of wakeup conditions ANDed together. This WakeupCondition object specifies that Java 3D should awaken this Behavior when all of the WakeupCondition's constituent WakeupCriterion become valid.

Constructors
public WakeupAnd(WakeupCriterion conditions[])

This constructor creates a WakeupAnd object that informs Java 3D's scheduler to wake up this Behavior object when all the conditions specified in the array of WakeupCriterion have become valid.

10.5.2.16 WakeupOr

The WakeupOr class specifies any number of wakeup conditions ORed together. This WakeupCondition object specifies that Java 3D should awaken this Behavior when any of the WakeupCondition's constituent WakeupCriterion become valid.

Constructors
public WakeupOr(WakeupCriterion conditions[])

This constructor creates a WakeupOr object that informs Java 3D's scheduler to wake up this Behavior object when any condition specified in the array of WakeupCriterion become valid.

10.5.2.17 WakeupAndOfOrs

The WakeupAndOfOrs class specifies any number of OR wakeup conditions ANDed together. This WakeupCondition object specifies that Java 3D should awaken this Behavior when all of the WakeupCondition's constituent WakeupOr conditions become valid.

Constructors
public WakeupAndOfOrs(WakeupOr conditions[])

This constructor creates a WakeupAndOfOrs object that informs Java 3D's scheduler to wake up this Behavior object when all of the WakeupOr conditions specified in the array of WakeupOrs become valid.

10.5.2.18 WakeupOrOfAnds

The WakeupOrOfAnds class specifies any number of AND wakeup conditions ORed together. This WakeupCondition object specifies that Java 3D should awaken this Behavior when any of the WakeupCondition's constituent WakeupAnd conditions become valid.

Constructors
public WakeupOrOfAnds(WakeupAnd conditions[])

This constructor creates a WakeupOrOfAnds object that informs Java 3D's scheduler to wake up this Behavior object when any of the WakeupAnd conditions specified in the array of WakeupAnds become valid.

10.6 Predefined Behaviors

This section describes Java 3D's predefined behaviors, or Interpolators. Interpolators perform simple behavioral acts yet they provide broad functionality.

The Java 3D API provides interpolators for a number of functions: for manipulating transforms within a TransformGroup, for modifying the values of a Switch node, and for modifying Material attributes such as color and transparency.

The predefined behavior consist of two portions, a generic portion that all Interpolators share and a domain specific portion. The generic portion maps time onto an value in the range [0.0, 1.0] inclusive. The domain-specific portions map an alpha value in the range [0.0, 1.0] onto a value appropriate to the predefined behavior's range of outputs.

10.6.1 Interpolators

We call the Java 3D API's predefined behaviors interpolators because they smoothly interpolate among the two extreme values that an interpolator can produce. An alpha value of 0.0 results in generating an interpolator's minimal value. An alpha value of 1.0 results in generating an interpolator's maximal value. While an alpha value somewhere in between, generates a value proportionally in between the minimal and maximal value.

All behaviors share the same mechanism for specifying and later for converting a temporal value into an alpha value.

10.6.1.1 Mapping Time to Alpha

Several parameters control the mapping of time onto an alpha value. That mapping is deterministic as long as its parameters do not change. Thus two different interpolators with the same parameters will generate the same alpha value given the same time value. This means that two interpolators that do not communicate can still precisely coordinate their activities, even if they reside in different threads or even different processors-as long as those processors have consistent clocks.

Figure 10-1 shows the components of an Interpolator's time-to-alpha mapping. Time is represented on the horizontal axis. Alpha is represented on the vertical axis. As we move from left to right, we see alpha's value start at 0.0, rise to 1.0, and then decline back to 0.0 on the right hand side.

On the left hand side, Trigger time defines when this Interpolator's waveform begins. The region directly to the right of Trigger time, labeled Phase delay, defines a time period where the waveform does not change. Phase delays provide an important means for offsetting multiple interpolators from one another, especially where the interpolators have all the same parameters. The next four regions, labeled increasing, at one, decreasing, and at zero, all specify duration for the corresponding values of alpha.

Additionally, interpolators have a loop count that determines how many times to repeat the increasing, at one, decreasing, and at zero sequence; they also have associated mode flags that enable one, the other, or both portions of the waveform.

Developers can use the loop count in conjunction with the mode flags to generate various kinds of actions. Specifying a loop count of one and enabling the mode flag that enables only the increasing and at one portion of the waveform, we would get the waveform shown in Figure 10-2.

In Figure 10-2, alpha's value is zero before the combination of trigger time plus the phase delay duration. Alpha's value changes from zero to one over a specified interval of time and thereafter alpha's value remains one. (Subject to the reprogramming of the Interpolator's parameters.) A possible use of a single -increasing value might be to combine it with a rotation interpolator to program a door opening.

Similarly, by specifying a loop count of one and a mode flag that enables only the decreasing and at zero portion of the waveform, we would get the waveform shown in Figure 10-3.

In Figure 10-3, alpha's value is one before the combination of trigger time plus the phase delay duration. Alpha's value changes from one to zero over a specified interval and thereafter alpha's value remains zero. (Subject to the reprogramming of the Interpolator's parameters.) A possible use of a single -decreasing value might be to combine it with a rotation interpolator to program a door closing.

We can combine both of the above waveforms by specifying a loop count of one and setting the mode flag to enable both the -increasing and -at-one portion of the waveform as well as the -decreasing and -at-zero portion of the waveform. This combination would result in the waveform shown in Figure 10-4.

In Figure 10-4, alpha's value is zero before the combination of trigger time plus the phase delay duration. Alpha's value changes from zero to one over a specified period of time, it remains at one for another specified period of time, it then changes from one to zero over a third specified period of time, and thereafter alpha's value remains zero. (Subject to the reprogramming of the interpolator's parameters.) A possible use of an -increasing followed by an -decreasing value might be to combine it with a rotation interpolator to program a door swinging open and then closing.

By increasing the loop count, we can get repetitive behavior, such as a door swinging open and closed some number of times. At the extreme, we can specify a loop count of -1 or infinity.

We can construct looped versions of the waveforms shown in Figure 10-2, Figure 10-3, and Figure 10-4. Figure 10-5 shows a looping interpolator with mode flags set to enable only the -increasing and -at-one portion of the waveform.

In Figure 10-5, Alpha goes from zero to one over a fixed duration of time, it stays at one for another fixed duration of time, and then repeats.

Similarly, Figure 10-6 shows a looping interpolator with mode flags set to enable only the -decreasing and -at-zero portion of the waveform.

Lastly, Figure 10-7 shows a looping interpolator with both the increasing and decreasing portions of the waveform enabled.

In all three cases shown by Figure 10-5, Figure 10-6, and Figure 10-7, we can compute the exact value of alpha at any point in time.

Java 3D's preprogrammed behaviors permit other behaviors to change their parameters. When such a change occurs, alpha's value changes to match the state of the newly parameterized interpolator.

10.6.1.2 Acceleration of Alpha

Commonly, developers want alpha to change slowly at first and to speed up until the change in alpha reaches some appropriate rate. This is analogous to accelerating your car up to the speed limit-it does not start off immediately at the speed limit. Developers specify this "ease-in, ease-out" behavior through two additional parameters, the increasingAlphaRampDuration and the decreasingAlphaRampDuration.

These two parameters specify a period during which the "change in alpha" increases until it reaches its maximum per-unit-of-time step size. A value of 1/4 the increasing or decreasing duration means that changes during the first quarter of the increasing or decreasing period, stays constant for half the period, and decelerates for the remaining quarter of the period. A value of zero implies that changes at a constant rate. A value of 1/2 the associated duration or greater is clamped to 1/2 the associated duration and implies that the change in increases during the first half of the period and then decreases during the second half of the period. Figure 10-8 shows these three examples graphically.

10.6.2 The Alpha Class

The Alpha class provides common methods for convert a time value into an alpha value (a value in the range 0 to 1).

Constants
public static final int INCREASING_ENABLE
public static final int DECREASING_ENABLE

These flags specify that this alpha's mode is to use the increasing or decreasing component of the alpha.

Constructors
public Alpha(int loopCount, int mode, long triggerTime,
       long phaseDelayDuration, long increasingAlphaDuration,
       long increasingAlphaRampDuration, long alphaAtOneDuration, 
       long decreasingAlphaDuration, long decreasingAlphaRampDuration,
       long alphaAtZeroDuration)

Constructs a new Alpha object using the specified parameters.

Methods
public float value()
public float value(long atTime)

These methods return a value between 0.0 and 1.0 inclusive, based on the current time and the time-to-alpha parameters established for this interpolator. 

public void setStartTime(long startTime)
public long getStartTime()

These methods set and retrieve this alpha's startTime, the base for all relative time specifications. 

public void setLoopCount(int loopCount)
public int getLoopCount()

These methods set and retrieve this alpha's loopCount. 

public void setMode(int mode)
public int getMode()

These methods set and retrieve this alpha's mode. The mode is one of the following values: INCREASING_ENABLE or DECREASING_ENABLE. These values may be ORed together to specify that both are active.

The increasing alpha parameters are increasingAlphaDuration, increasingAlphaRampDuration, and alphaAtOneDuration. The decreasing alpha parameters are decreasingAlphaDuration, decreasingAlphaRampDuration, and alphaAtZeroDuration. 

public void setTriggerTime(long triggerTime)
public long getTriggerTime()

These methods set and retrieve this alpha's triggerTime. 

public void setPhaseDelayDuration(long phaseDelayDuration)
public long getPhaseDelayDuration()

These methods set and retrieve this alpha's phaseDelayDuration. 

public void setIncreasingAlphaDuration(long 
       increasingAlphaDuration)
public long getIncreasingAlphaDuration()

These methods set and retrieve this alpha's increasingAlphaDuration. 

public void setIncreasingAlphaRampDuration(long 
       increasingAlphaRampDuration)
public long getIncreasingAlphaRampDuration()

These methods set and retrieve this alpha's increasingAlphaRampDuration. 

public void setAlphAtOneDuration(long alphaAtOneDuration)
public long getAlphaAtOneDuration()

These methods set and retrieve this alpha's alphaAtOneDuration. 

public void setDecreasingAlphaDuration(long 
       decreasingAlphaDuration)
public long getDecreasingAlphaDuration()

These methods set and retrieve this alpha's decreasingAlphaDuration. 

public void setDecreasingAlphaRampDuration(long 
       decreasingAlphaRampDuration)
public long getDecreasingAlphaRampDuration()

These methods set and retrieve this alpha's decreasingAlphaRampDuration. 

public void setAlphAtZeroDuration(long alphaAtZeroDuration)
public long getAlphaAtZeroDuration()

These methods set and retrieve this alpha's alphaAtZeroDuration. 

public boolean finished()

This method tests if this alpha object is past its activity window - if it has finished all its looping activity.

10.6.3 The Interpolator Behavior Class

The Interpolator is a behavior class that provides the means for converting a time value into an alpha value (a value in the range [0.0, 1.0] inclusive). Its subclasses use these methods to further map time to some value in their range.

Constructors

The Interpolator behavior class has the following constructor. 

public Interpolator(Alpha alpha)

This constructor provides the common initialization code for all specializations of Interpolator.

Methods
public void setAlpha(Alpha alpha)
public Alpha getAlpha()

These methods set and retrieve this interpolator's alpha object. 

public long initialize()

This is the default Interpolator initialization behavior. It sets the Interpolator start time to the current time and schedules the behavior to awaken at the next frame.

10.6.4 PositionInterpolator

The PositionInterpolator object controls the translation component of its Transform3D Group.

Constructors

The PositionInterpolator object specifies the following constructors. 

public PositionInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial position interpolator with a specified target, an axisOfTranslation set to Identity, a startPosition of 0.0f, and an endPosition of 1.0f. 

public PositionInterpolator(Alpha alpha, TransformGroup target, 
       Transform3D axisOfTranslation, float startPosition,
       float endPosition)

Constructs and initializes a new PositionInterpolator that varies the target transform node's translation component (startPosition and endPosition). The axisOfRotation parameter specifies the transform that takes the axis of translation and makes it coincide with the X axis.

Methods

The PositionInterpolator object specifies the following methods. 

public void setStartPosition(float position)
public float getStartPosition()

These two methods get and set the Interpolator's start position. 

public void setEndPosition(float position)
public float getEndPosition()

These two methods get and set the Interpolator's end position. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup node. 

public void processStimulus(Enumeration criteria)

The PositionInterpolator behavior. The Translator Behavior responds to two stimuli: activate, which resets the Translator, caching the start time, etc., and update, which computes the elapsed time indexes into the spline information and computes a transformation component.

10.6.5 RotationInterpolator Object

The RotationInterpolator class extends the Interpolator class. The RotationInterpolator object varies the rotation component of its target TransformGroup.

Constructors
public RotationInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial rotation interpolator with a specified target, axisOfRotation set to identify, a minimum angle of 0.0f, and a maximum angle of 6.283185308f. 

public RotationInterpolator(Alpha alpha, TransformGroup target, 
       Transform3D axisOfRotation, float minimumAngle,
       float maximumAngle)

Constructs a new rotation interpolator that varies the target TransformGroup's rotation component. The minimumAngle parameter is the starting angle in radians, maximumAngle is the ending angle in radians.

Methods
public void setMinimumAngle(float angle)
public float getMinimumAngle()

These two methods get and set the Interpolator's minimum rotation angle. 

public void setMaximumAngle(float angle)
public float getMaximumAngle()

These two methods get and set the Interpolator's maximum rotation angle. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup node. 

public void processStimulus(Enumeration criteria)

The RotationInterpolator behavior.

10.6.6 ColorInterpolator Object

The ColorInterpolator class extends Interpolator. The ColorInterpolator object interpolates between the two colors specified changing the material property specified.

Constructors
public ColorInterpolator(Alpha alpha, Material target)

Constructs a trivial color interpolator with a specified target, a startColor of black, and an end color of white. 

public ColorInterpolator(Alpha alpha, Material target,
       Color3f startColor, color3f endColor)

Constructs a new ColorInterpolator object that varies the target material among two color values (startColor and endColor).

Methods
public void setStartColor(Color3f color)
public void getStartColor(Color3f color)

These two methods get and set the Interpolator's start color. 

public void setEndColor(Color3f color))
public void getEndColor(Color3f color)

These two methods get and set the Interpolator's end color. 

public void setTarget(Material target)
public Material getTarget()

These two methods get and set the Interpolator's target Material component object. 

public void processStimulus(Enumeration criteria)

The ColorInterpolator behavior.

10.6.7 ScaleInterpolator Object

The ScaleInterpolator class extends the Interpolator class. The ScaleInterpolator object varies the scale component of its target TransformGroup.

Constructors
public ScaleInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial scale interpolator that varies its target transform using the specified alpha, using an identity matrix, a minimum scale = 0.1f), and a maximum scale = 1.0f node among the two scale values. 

public ScaleInterpolator(Alpha alpha, TransformGroup target, 
       Transform3D axisOfScale, float minimumScale, 
       float  maximumScale)

Constructs a new ScaleInterpolator object that varies the target TransformGroup's transform node among the two scale values (minimumScale, the starting scale and maximumScale, the ending scale).

Methods
public void setMinimumScale(float scale)
public float getMinimumScale()

These two methods get and set the Interpolator's minimum scale. 

public void setMaximumScale(float scale)
public float getMaximumScale()

These two methods get and set the Interpolator's maximum scale. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup node. 

public void processStimulus(Enumeration criteria)

The ScaleInterpolator behavior.

10.6.8 SwitchValueInterpolator Object

The SwitchValueInterpolator class extends Interpolator. The SwitchValueInterpolator object cycles the Switch child selector of a Switch node.

Constructors
public SwitchValueInterpolator(Alpha alpha, Switch target)
public SwitchValueInterpolator(Alpha alpha, Switch target, 
       int  firstChildIndex, int lastChildIndex)

Constructs a new SwitchValueInterpolator object that varies the target Switch node's child index between the two values provided (firstChildIndex, the index of the first children in the Switch node to select and lastChildIndex, the index of the last children in the Switch node to select).

Methods
public void setFirstChildIndex(int firstIndex)
public int getFirstChildIndex()

These two methods get and set the Interpolator's first child index. 

public void setLastChildIndex(int lastIndex)
public int getLastChildIndex()

These two methods get and set the Interpolator's last child index. 

public void setTarget(Switch target)
public Switch getTarget()

These two methods get and set the Interpolator's target Switch node. 

public void processStimulus(Enumeration criteria)

The SwitchValueInterpolator behavior.

10.6.9 TransparencyInterpolator Object

The TransparencyInterpolator class extends Interpolator. The TransparencyInterpolator object interpolates between the two transparencies specified and changes the material property specified.

Constructors
public TransparencyInterpolator(Alpha alpha, 
       TransparencyAttributes target)

Constructs a trivial transparency interpolator with a specified target, a minimum transparency of 0.0f, and a maximum transparency of 1.0f. 

public TransparencyInterpolator(Alpha alpha, 
       TransparencyAttributes target, 
       float  minimumTransparency, float maximumTransparency)

Constructs a new TransparencyInterpolator object that varies the target material's transparency between the two transparency values (minimumTransparency, the starting transparency and maximumTransparency, the ending transparency).

Methods
public void setMinimumTransparency(float transparency)
public float getMinimumTransparency()

These two methods get and set the Interpolator's minimum transparency. 

public void setMaximumTransparency(float transparency)
public float getMaximumTransparency()

These two methods get and set the Interpolator's end transparency. 

public void setTarget(Material target)
public Material getTarget()

These two methods get and set the Interpolator's target Material component object. 

public void processStimulus(Enumeration criteria)

The TransparencyInterpolator behavior.

10.6.10 PositionPathInterpolator Object

The PositionPathInterpolator class extends Interpolator. The PositionPathInterpolator object varies the translational component of its target TransformGroup by interpolating among a series of predefined knot-position pairs.

The first knot must have a value of 0.0. The last knot must have a value 1.0. An intermediate knot with index k must have a value strictly greater than any knot with index less than k.

Constructors
public PositionPathInterpolator(Alpha alpha,
       TransformGroup target, Transform3D axisOfTranslation,
       float[] knots, Point3f[] positions)

Constructs a new PositionPathInterpolator that varies the translation of the target Transform3D Group's transform. The axisOfTranslation parameter specifies the transform that take the axis of translation and makes it coincide with the Z axis. The knots parameter specifies an array of knot values that specify a spline. The positions parameter specifies an array of position values at the knots.

Methods
public int arrayLengths()

Retrieves the length of the PositionPathInterpolator's knots and positions arrays. 

public void setPosition(int index, Point3f position)
public void getPosition(int index, Point3f position)

These two methods get and set the Interpolator's indexed position. 

public void setKnot(int index, float knot)
public float getKnot(int index)

These two methods get and set the Interpolator's indexed knot value. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup object. 

public void processStimulus(Enumeration criteria)

The PositionPathInterpolator behavior.

10.6.11 RotPosPathInterpolator Object

The RotPosPathInterpolator class extends Interpolator. The RotPosPathInterpolator object varies the rotational and translational component of its target TransformGroup by interpolating among a series of predefined knot-position pairs.

The first knot must have a value of 0.0. The last knot must have a value 1.0. An intermediate knot with index k must have a value strictly greater than any knot with index less than k.

Constructors
public RotPosPathInterpolator(Alpha alpha, TransformGroup target, 
       Transform3D  axisOfRotPos, float knots[], Quat4f  quats[], 
       Point3f  positions[])

Constructs a new RotPosPathInterpolator that varies the rotation and translation of the target Transform3D Group's transform. The axisOfRotation parameter specifies the transform that take the axis of rotation and makes it coincide with the Z axis. The knots parameter specifies an array of knot values that specify a spline. The quats parameter specifies an array of quaternion values at the knots. The positions parameter specifies an array of position values at the knots.

Methods
public int arrayLengths()

Retrieves the length of the RotPosPathInterpolator's knots, positions, and quats arrays. 

public void setQuat(int index, Quat4f quat)
public void getQuat(int index, Quat4f quat)

These two methods get and set the Interpolator's indexed quat. 

public void setPosition(int index, Point3f position)
public void getPosition(int index, Point3f position)

These two methods get and set the Interpolator's indexed position. 

public void setKnot(int index, float knot)
public float getKnot(int index)

These two methods get and set the Interpolator's indexed knot value. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup object. 

public void processStimulus(Enumeration criteria)

The RotPosPathInterpolator behavior.

10.6.12 RotPosScalePathInterpolator Object

The RotPosPathScaleInterpolator class extends Interpolator. The RotPosPathScaleInterpolator object varies the rotational, translational, and scale component of its target TransformGroup by interpolating among a series of predefined knot-position pairs.

The first knot must have a value of 0.0. The last knot must have a value 1.0. An intermediate knot with index k must have a value strictly greater than any knot with index less than k.

Constructors
public RotPosScalePathInterpolator(Alpha alpha,
       TransformGroup target, Transform3D  axisOfRotPosScale,
       float knots[], Quat4f  quats[], Point3f  positions[],
       float  scales[])

Constructs a new RotPosScalePathInterpolator that varies the rotation, translation, and scale of the target Transform3D Group's transform. The axisOfRotPosScale parameter specifies the transform that take the axis of rotation and makes it coincide with the Z axis. The knots parameter specifies an array of knot values that specify a spline. The quats parameter specifies an array of quaternion values at the knots. The positions parameter specifies an array of position values at the knots. The scale parameter specifies the scale component value.

Methods
public int arrayLengths()

Retrieves the length of the RotPosPathScaleInterpolator's knots and positions arrays. 

public void setScale(int index, float scale)
public float getScale(int index)

These two methods get and set the Interpolator's indexed scale value. 

public void setQuat(int index, Quat4f quat)
public void getQuat(int index, Quat4f quat)

These two methods get and set the Interpolator's indexed quat. 

public void setPosition(int index, Point3f position)
public void getPosition(int index, Point3f position)

These two methods get and set the Interpolator's indexed position. 

public void setKnot(int index, float knot)
public float getKnot(int index)

These two methods get and set the Interpolator's indexed knot value. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup object. 

public void processStimulus(Enumeration criteria)

The RotPosScalePathInterpolator behavior.

10.6.13 RotationPathInterpolator Object

The RotationPathInterpolator class extends the Interpolator class. The RotationPathInterpolator object varies the rotation component of its target TransformGroup by interpolating among a series of predefined knot-orientation pairs.

The first knot must have a value of 0.0. The last knot must have a value 1.0. An intermediate knot with index k must have a value strictly greater than any knot with index less than k.

Constructors
public RotationPathInterpolator(Alpha alpha,
       TransformGroup target, Transform3D  axisOfRotation,
       float knots[], Quat4f quats[])

Constructs a new RotationPathInterpolator object that varies the target TransformGroup node transform. The axisOfRotation parameter specifies the transform that take the axis of rotation and makes it coincide with the Z axis. The knots parameter specifies an array of knot values that specify a spline. The quats parameter specifies an array of quaternion values at the knots.

Methods
public int arrayLengths()

The length of the RotationPathInterpolator's knots and positions arrays. 

public void setQuat(int index, Quat4f quat)
public void getQuat(int index, Quat4f quat)

These two methods get and set the Interpolator's indexed quat. 

public void setKnot(int index, float knot)
public float getKnot(int index)

These two methods get and set the Interpolator's indexed knot value. 

public void setTarget(TransformGroup target)
public TransformGroup getTarget()

These two methods get and set the Interpolator's target TransformGroup object. 

public void processStimulus(Enumeration criteria)

The RotationPathInterpolator behavior.

10.7 LOD Behaviors

The LOD (level of detail) leaf node is an abstract behavior class that operates on a list of Switch group nodes to select one of the children of the Switch nodes. Specializations of the LOD abstract behavior node implement various level-of-detail policies.

Constructors
public LOD()

Constructs and initializes a new LOD node.

Methods

The LOD node class defines the following methods. 

public final void addSwitch(Switch switchNode)
public final void setSwitch(Switch switchNode, int index)
public final void insertSwitch(Switch switchNode, int index)
public final void removeSwitch(int index)
public final Switch getSwitch(int index)
public final int numSwitches()

The addSwitch method appends the specified switch node to this LOD's list of switches. The setSwitch method replaces the specified switch node with the switch node provided. The insertSwitch method inserts the specified switch node at the specified index. The removeSwitch method removes the switch node at specified index. The getSwitch method returns the switch node specified by the index. The numSwitches method returns a count of this LOD's switches. 

public final Enumeration getAllSwitches()

This method returns the enumeration object of all switches.

10.7.0.1 DistanceLOD

The DistanceLOD behavior node implements a distance-based LOD policy. The DistanceLOD behavior selects one of the Switch node's children based on distance from the viewer. For distances 0 through N-where distance[0] is most detail, N is least-the DistanceLOD selects child n when the viewer is > distance[n+1] and distance[n] from the center of the Bounds of the DistanceLOD node.

Constructors
public DistanceLOD()
public DistanceLOD(float[] distances)

Construct and initialize a new DistanceLOD node. The distances parameter specifies a vector of doubles representing LOD cutoff distances.

Methods
public final int numDistances()
public final double getDistance(int whichLOD)
public final void setDistance(int whichLOD, double distance)

The numDistances method returns a count of the number of LOD distance cut-off parameters. The getDistance method returns a particular LOD cut-off distance. The setDistance method sets a particular LOD cut-off distance. 

public void initialize()

This method sets up the initial wakeup criteria. 

public void processStimulus(Enumeration criteria)

This method computes the appropriate level of detail.

10.8 Billboard Behavior

The Billboard behavior node operates on a TransformGroup node to specify a transform that always aligns itself perpendicular to a specified world-coordinate axis or to a viewer's view vector-regardless, in either case, of transforms above the specified transform node in the scene graph.

Billboard nodes provide the most benefit for complex, roughly-symmetric objects. A typical use might consist of a quadrilateral that contains a texture of a tree.

Constants

The Billboard class adds the following new constants. 

public static final int ROTATE_ABOUT_AXIS

Specifies that rotation should be about the specified axis. 

public static final int ROTATE_ABOUT_POINT

Specifies that rotation should be about the specified point and that the children's Y-axis should match the ViewPlatform's Y-axis.

Constructors

The Billboard class specifies the following constructors. 

public Billboard()

Constructs a Billboard behavior node with ROTATE_ABOUT_AXIS rotation with an axis pointing along the Y axis. 

public Billboard(TransformGroup tg)
public Billboard(TransformGroup tg, int mode, Vector3f axis)

The first constructor constructs a Billboard behavior node with default parameters that operates on the specified TransformGroup node. The default alignment mode is ROTATE_ABOUT_AXIS with the axis along the Y axis. The second constructor constructs a Billboard behavior node with the specified axis and mode that operates on the specified TransformGroup node. The axis parameter specifies the ray about which the billboard rotates. The mode parameter is the alignment mode and is one of ROTATE_ABOUT_AXIS, ROTATE_ABOUT_POINT.

Methods

The Billboard class defines the following methods. 

public final void setAlignmentMode(int mode)
public final int getAlignmentMode()

These methods, if enabled by the appropriate flag, permit an application to either retrieve or set the Billboard node's alignment mode, one of ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT. 

public final void setAlignmentAxis(Vector3f axis)
public final void setAlignmentAxis(float x, float y, float z)
public final void getAlignmentAxis(Vector3f axis)

These methods, if enabled by the appropriate flag, permit an application to set or retrieve the Billboard node's alignment axis. 

public void initialize()

This method sets up the initial wakeup criteria. 

public void processStimulus(Enumeration criteria)

This method computes the appropriate transform.

10.9 Picking
Note: This section is still under construction and does not reflect the final API for picking. It is intended to provide a flavor of the kind of picking interface that Java 3D will support.

Behavior nodes provide the means for building developer-specific picking semantics. An application developer can define custom picking semantics using Java 3D's behavior mechanism. The developer might wish to define pick semantics that use a mouse to shoot a ray into the virtual universe from the current viewpoint, find the first object along that ray, and highlight that object when the end-user releases the mouse button. A typical scenario follows:

Java 3D includes helping functions that aid in intersecting various geometric objects with objects in the virtual universe:

Picking functions return Path Objects.

Constants
public static final int XXXXX
public static final int YYYYY

These ...

Methods
public final SceneGraphPath closestRayIntersect(Point3f base, 
       Point3f head)
public final void allRayIntersects(Point3f base, Point3f head, 
       SceneGraphPath intersects[])
public final void sortedRayIntersects(Point3f base, Point3f head, 
       Path intersects[])

These methods find objects in the virtual world that intersect the specified ray. The first method returns one object (via the Path object), the object closest to the base. The remaining two methods return all objects intersected by the ray, first in any order, the second in sorted order closest to furthest. 

public final SceneGraphPath closestIntersect(Bounds object)
public final void allIntersecting(Bounds object)
public final void sortedRayIntersects(Bounds object)

These methods find objects in the virtual world that intersect the specified bounds. The first method returns one object (via the Path object), the object closes to the ViewPlatform and within the Bounds. If more than one object is closest, one is chosen. The remaining two methods return all objects intersected by the Bounds object, first in any order, the second in sorted order closest to furthest. Again, ties result in an indeterminate order.

10.9.1 SceneGraphPath Object

The SceneGraphPath object represents a path from a node to a Locale object, via link nodes.

Constructors
public SceneGraphPath(Locale root, Node object)
public SceneGraphPath(Locale root, Node object, Link links[])

These construct and initialize a new SceneGraphPath object. The first form specifies the path's Locale object and the object in question. The second form adds an array of links from Locale to object. The object parameter may be a Group node or it may be a Shape3D or a Morph leaf node. If any other type of Leaf node is specified, an IllegalArgumentException is thrown.

Methods
public final void set(SceneGraphPath newPath)
public final void setLocale(Locale newLocale)
public final void setObject(Node object)
public final void setLink(Link newLink, int index)
public final void setLinks(Link links[])

These methods set the path's values. The first method sets the path's interior values. The second method sets the path's locale to the specified locale. The third method sets the path's object to the specified object (a Group node or a Shape3D or Morph leaf node). The fourth method replaces the link node associated with the specified index with the specified newLink. The last method replaces all of the link nodes with the new list of link nodes. 

public final Locale getLocale()
public final Node getObject()

The first method returns the path's Locale. The second method returns the path's object. 

public final int linkCount()
public final Link getLink(int index)

The first method returns the number of link nodes in this path. The second method returns the link node associated with the specified index. 

public boolean equals(SceneGraphPath testPath)

This method returns true if all of the data members of path testPath are equal to the corresponding data members in this SceneGraphPath. 

public int hashCode()

This method returns a hash number based on the data values in this object. Two different SceneGraphPath objects with identical data values (i.e., returns true for trans.equals(SceneGraphPath)) will return the same hash number. Two paths with different data members may return the same hash value, although this is not likely.


Contents Previous Next

Java 3D API Specification


Copyright © 1997, Sun Microsystems, Inc. All rights reserved.