behavior.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: Behavior.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.5 $
 * $Date: 2007/02/09 17:17:52 $
 * $State: Exp $
 */

package javax.media.j3d;


import java.util.Enumeration;

/**
 * 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
 * <code>initialization</code> method, called once when the behavior
 * becomes "live," and a <code>processStimulus</code> 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.
 *
 * <P>
 * The <i>scheduling region</i> defines a spatial volume that serves
 * to enable the scheduling of Behavior nodes. A Behavior node is
 * <i>active</i> (can receive stimuli) whenever an active ViewPlatform's
 * activation volume intersects a Behavior object's scheduling
 * region. Only active behaviors can receive stimuli.
 *
 * <P>
 * The <i>scheduling interval</i> 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.
 *
 * <P>
 * The <code>initialize</code> 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.
 *
 * <P>
 * The <code>processStimulus</code> 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:
 * <ol>
 * <li>All modifications to scene graph objects (not including geometry
 * by-reference or texture by-reference) made from the
 * <code>processStimulus</code> method of a single behavior instance
 * are guaranteed to take effect in the same rendering frame.</li>
 * <li>All modifications to scene graph objects (not including geometry
 * by-reference or texture by-reference) made from the
 * <code>processStimulus</code> 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.</li>
 * </ol>
 *
 * 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.
 *
 * <P>
 * <b>Code Structure</b>
 * <P>
 * 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.
 *
 * <P>
 * 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.
 *
 * <P>
 * 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:
 *
 * <P>
 * <UL>
 * <LI>Code to decode and extract references from the WakeupCondition
 * enumeration that caused the object's awakening.</LI>
 * <LI>Code to perform the manipulations associated with the
 * WakeupCondition</LI>
 * <LI>Code to establish this behavior's new WakeupCondition</LI>
 * <LI>A path to Exit (so that execution returns to the Java 3D
 * behavior scheduler)</LI>
 * </UL>
 *
 * <P>
 * <b>WakeupCondition Object</b>
 * <P>
 * 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.
 *
 * <P>
 * <b>WakeupCriterion Object</b>
 * <P>
 * 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
 *
 * <UL>
 * <LI>The center of a ViewPlatform enters a specified region</LI>
 * <LI>The center of a ViewPlatform exits a specified region</LI>
 * <LI>A behavior is activated</LI>
 * <LI>A behavior is deactivated</LI>
 * <LI>A specified TransformGroup node's transform changes</LI>
 * <LI>Collision is detected between a specified Shape3D node's
 * Geometry object and any other object</LI>
 * <LI>Movement occurs between a specified Shape3D node's Geometry
 * object and any other object with which it collides</LI>
 * <LI>A specified Shape3D node's Geometry object no longer collides
 * with any other object</LI>
 * <LI>A specified Behavior object posts a specific event</LI>
 * <LI>A specified AWT event occurs</LI>
 * <LI>A specified time interval elapses</LI>
 * <LI>A specified number of frames have been drawn</LI>
 * <LI>The center of a specified Sensor enters a specified region</LI>
 * <LI>The center of a specified Sensor exits a specified region</LI>
 * </UL>
 *
 * <p>
 * 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.
 *
 * <p>
 * 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.
 *
 * <p>
 * <b>Additional Information</b>
 * <p>
 * For more information, see the
 * <a href="doc-files/intro.html">Introduction to the Java 3D API</a> and
 * <a href="doc-files/Behaviors.html">Behaviors and Interpolators</a>
 * documents.
 *
 * @see WakeupCondition
 */

public abstract class Behavior extends Leaf {

    /**
     * Constructs a Behavior node with default parameters.  The default
     * values are as follows:
     * <ul>
     * enable flag : true<br>
     * scheduling bounds : null<br>
     * scheduling bounding leaf : null<br>
     * scheduling interval : numSchedulingIntervals / 2<br>
     * </ul>
     */
    public Behavior() {
    }

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

    /**
     * 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.
     * <br>
     * NOTE: Applications should <i>not</i> call this method.  It is called
     * by the Java 3D behavior scheduler.
     * @param criteria an enumeration of triggered wakeup criteria for this
     * behavior
     */
    public abstract void processStimulus(Enumeration criteria);

    /**
     * Set the Behavior's scheduling region to the specified bounds.
     * This is used when the scheduling bounding leaf is set to null.
     * @param region the bounds that contains the Behavior's new scheduling
     * region
     */  
    public void setSchedulingBounds(Bounds region) {
	((BehaviorRetained)this.retained).setSchedulingBounds(region);
    }

    /**  
     * Retrieves the Behavior node's scheduling bounds.
     * @return this Behavior's scheduling bounds information
     */  
    public Bounds getSchedulingBounds() {
	return ((BehaviorRetained)this.retained).getSchedulingBounds();
    }

    /**
     * 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.
     * @param region the bounding leaf node used to specify the Behavior
     * node's new scheduling region