DirectX Media for Animation Java Reference

Previous

Classes

Index

Next

Behavior Class

public class Behavior extends java.lang.Object {
    // Methods
    public Behavior bvrHook(BvrCallback callback);
    public Behavior debug();
    public Behavior debug(String name);
    public Behavior debug(String name, boolean onStart);
    public Behavior debug(String name, boolean onStart, PrintStream std);
    public void init(Behavior a);
    public Behavior run(double startTime, BehaviorCtx ctx);
    public Behavior runOnce();
    public Behavior snapshot(double time, BehaviorCtx ctx);
    public Behavior substituteTime(NumberBvr a);
    
    public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b);
    public static Behavior until(Behavior a, DXMEvent e);
    public static Behavior until(Behavior a, DXMEvent e, Behavior b);
    public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier);
}

All behaviors are potentially time-varying and/or reactive values such as colors, numbers and images. They can be used to construct animated objects. All behavior subclasses inherit the methods of this class.

Because all behaviors are potentially time-varying and/or reactive, their values can change as a function of time or as the result of user input. Time-varying behaviors are created by combining time-based default behaviors (such a localTime) with other behaviors. Reactive behaviors are created using the until and untilNotify methods and specifying input events, such as mouse clicks. You can build up complex behaviors by combining existing behaviors. The value of a complex behavior always depends on the values of the behaviors that comprise it.

A behavior is "running" if it has been created using the run method with a specified start time. Ordinarily, the system runs behaviors as it needs them, so applications rarely use the run method directly. When a behavior runs, its time-varying and reactive qualities are active. This means the user can experience any changes that occur in the behavior as time passes or events occur. You can determine the value of a running behavior at a specific time by using the snapshot method. (This method cannot take snapshots of behaviors that are not running.)

In order to type-check behaviors, all behavior types must be known at construction time. This is why there is no Behavior.newUninitBvr() method included in the Behavior class.

Methods

bvrHook

public Behavior BvrHook(BvrCallback callback);

Allows a running behavior to be sampled.

Return Value:

Returns the Behavior object that is the value of the running behavior at the time it was sampled.

Parameter	Description
callback	The BvrCallback interface containing the notify method.

See Also: BvrCallback

debug

public Behavior debug();

Give the following information about a running behavior:

• An integer number (the ID), which distinguishes each instance of the behavior.
• The global time that the behavior was started.
• The value of the behavior at the time it was started.

The method assumes the following defaults:

• The behavior is unnamed.
• The information is displayed each time an instance of the behavior is started.
• The information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior was started at a global time of 39.66 seconds, and had a value of 0.5:

2 started at 39.66 result = 0.5

Remarks:

This method is unavailable to viewers that don't display the standard output.

debug

public Behavior debug(String name);

Give the following information about a running behavior:

• The name of the behavior.
• An integer number (the ID), which distinguishes each instance of the behavior.
• The global time that the behavior was started.
• The value of the behavior at the time it was started.

The method assumes the following defaults:

• The information is displayed each time an instance of the behavior is started.
• The information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

The next example displays a solid-colored image whose red and green components are 1, and whose blue component is time-varying. The NumberBvr x initially has a value of "b" (a value that varies over time) . When the left button of the mouse is pressed, "b" (and therefore, "x" starts all over again, with a value of 0.5.

The debugging information (shown in the previous example) is displayed each time the left mouse button is pressed.

import com.ms.dxmedia.*;

class DebugTestModel extends Model {
  public void createModel(double startTime, BehaviorCtx ctx) {
      NumberBvr b = (NumberBvr) add(localTime, toBvr(0.5)).Debug("b");

      NumberBvr x = NumberBvr.newUninitBvr();
      x.init(until(b, leftButtonDown, x));
      
      ImageBvr model = solidColorImage(colorRgb(toBvr(1), toBvr(1), x));

      setImage(model);
  }
}       

public class DebugTest extends DXMApplet {
    public void init() {
    // Always call the superclass's init() first to ensure codeBase is set
    super.init();
    // Now set the model
    setModel(new DebugTestModel()) ; 
    }
}

Return Value:

Returns the Behavior object.

Parameter	Description
name	The name of the behavior.

Remarks:

This method is unavailable to viewers that don't display the standard output.

debug

public Behavior debug(String name, boolean onStart);

Gives the following information about a running behavior:

• The name of the behavior.
• An integer number (the ID), which distinguishes each instance of the behavior.
• The global time that the behavior was started or sampled.
• The local time that the behavior was sampled. (If debug is being called when the behavior is started, then the local time is 0, which is not displayed.)
• The value of the behavior at the time it was started or sampled.

This method assumes the information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

Return Value:

Returns the Behavior object.

Parameter	Description
name	The name of the behavior.
onStart	If true, the debug method is called when the behavior is started. If false, the method is called whenever the behavior is sampled. The default is true.

Remarks:

This method is unavailable to viewers that don't display the standard output.

debug

public Behavior debug(String name, boolean onStart, PrintStream std);

Give the following information about a running behavior:

• The name of the behavior.
• An integer number (the ID), which distinguishes each instance of the behavior.
• The global time that the behavior was started or sampled.
• The local time that the behavior was sampled. (If debug is being called when the behavior is started, then the local time is 0, which is not displayed.)
• The value of the behavior at the time it was started or sampled.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

Return Value:

Returns the Behavior object.

Parameter	Description
name	The name of the behavior.
onStart	If true, the debug method is called when the behavior is started. If false, the method is called whenever the behavior is sampled. The default is true.
std	The output device. The default is the standard output.

Remarks:

This method is unavailable to viewers that don't display the standard output.

init

public void init(Behavior a)

Initializes a behavior created by the newUninit method.

Parameter	Description
a	The Behavior object to be initialized.

run

public Behavior run(double startTime, BehaviorCtx ctx);

Creates an instance of the behavior and maps it to the global time line. If the original behavior is already running, the startTime parameter is ignored.

Return Value:

Returns the Behavior object.

Parameter	Description
startTime	The time at which to start a behavior.
ctx	Contains state information (such as the view).

runOnce

public Behavior runOnce();

Used when applications must reference a running behavior once it starts running, but don't require the application to explicitly start that behavior. With the runOnce method, the run method is not called automatically. Also, subsequent invocations of run always refer to the initial instance of the behavior. No new running behaviors are created. The following example plays 2 movies. The first movie plays from the beginning for 10 seconds. It then fades, over a 2 second interval, into a second movie:

ImageBvr movie1Once = (ImageBvr)movie1.runOnce();
ImageBvr movie2Once = (ImageBvr)movie2.runOnce();
ImageBvr faderMovie = (ImageBvr)
	until(movie1Once, 
		timer(toBvr(10)),
		until(fade(div(localTime, toBvr(2)), movie1Once, movie2Once),
			timer(toBvr(2)),
			movie2Once);

snapshot

public Behavior snapshot(double time, BehaviorCtx ctx);

Creates a snapshot of a behavior. The snapshot's value, which does not change over time, is equal to the value of the original behavior at the time given by time.

Return Value:

Returns the Behavior object.

Parameter	Description
time	The simulation time.
ctx	Contains state information (such as the view).

substituteTime

public Behavior substituteTime(NumberBvr a);

Creates a new behavior from an existing Behavior and a NumberBvr. In the new behavior, the number behavior replaces all occurrences of localTime in the original behavior. (This includes behaviors where localTime is implicit, such as imported movies. The method can be used even if localTime isn't explicitly in the code.) This allows behaviors to be, for example, time-scaled to run faster or slower, time-shifted to start at a different time, or frozen at a particular point in time. Here are some examples:

//A point moving 1 unit in x/second, starting at 0	
	b0 = point2XY(localTime, toBvr(0));

    //Create new behavior moving 0.5 units/second, 
    //by replacing localTime with localTime/2
	b1 = origBvr.substituteTime(div(localTime, toBvr(2)));

    //Create new behavior moving 1 unit/second, 
    //starting at 33, by replacing localTime with localTime + 33
	b2 = origBvr.substituteTime(add(localTime, toBvr(33));

    //Create new behavior moving 2 units/second, starting at 33, 
    //by replacing localTime with (localTime *2) + 33
	b3 = origBvr.substituteTime(add(mul(localTime, toBvr(2)), toBvr(33));

    //Freeze the original behavior at time 77
	b4 = origBvr.substituteTime(toBvr(77));

    //Tie the new behavior to the x-component of the mouse
	b5 = origBvr.substituteTime(mousePosition.getX());

    //Show that replacements are cumulative. The following sequence:
	c0 = point2XY(localTime, toBvr(0));
	c1 = c0.substituteTime(add(localTime, toBvr(33)));
	c2 = c1.substituteTime(mul(localTime, toBvr(2)));

    //is equivalent to:
	c0.substituteTime(add(mul(localTime, toBvr(2))), toBvr(33));

Return Value:

Returns the Behavior object.

Parameter	Description
a	The NumberBvr object that replaces localTime.

cond

public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b);

Creates a new behavior from the BooleanBvr and two other behaviors. The value of the new behavior, at any point in time, is one of those two behaviors. Which of the behaviors chosen depends on the value of the BooleanBvr. Here is an example:

//Create a new behavior, y, which is either 1.0 if x > 1.0, or another behavior, x
	NumberBvr y = (NumberBvr)cond(gte(x, toBvr(1.0)), toBvr(1.0), x);

Return Value:

Returns the Behavior object.

Parameter	Description
bool	The BooleanBvr object that determines which of the two behaviors will become the value of the new behavior.
a	The first of the two possible values the new behavior can assume.
b	The second of the two possible values the new behavior can assume.

until

public static Behavior until(Behavior a, DXMEvent e);

When event e occurs, runs and switches to the behavior the event produced.

Return Value:

Returns the Behavior object caused by the event e.

Parameter	Description
a	The Behavior object that the behavior represents initially.
e	The DXMEvent object that triggers the switch and returns the new behavior.

until

public static Behavior until(Behavior a, DXMEvent e, Behavior b);

Creates a behavior that changes when a given event occurs. Up to and including the time the event occurs, the behavior is the same as a. After the event e occurs, the behavior changes to be the same as b. Because until takes behaviors and returns a behavior, it can be nested. Here are some examples:

//The ColorBvr col is initially red
//It turns blue when the left mouse button is pressed
ColorBvr c = (ColorBvr)until(red, leftButtonDown, blue);

//Example of nested behaviors
//The behavior is initially red
//It turns blue when the left mouse button is pressed
//And turns green when it is pressed again
ColorBvr c = (ColorBvr)until(red, leftButtonDown,
			until(blue, leftButtonDown, green));

Return Value:

Returns the Behavior object.

Parameter	Description
a	The Behavior object that the behavior represents initially.
e	A DXMEvent object specifying the event.
b	The Behavior object that the behavior represents after the event.

untilNotify

public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier);

Creates a behavior that changes upon a given event. Initially, the behavior is the same as a. When event e occurs, the behavior changes to the behavior returned by the event notifier notifier.

Return Value:

Returns the Behavior object.

Parameter	Description
a	The Behavior object that the behavior represents initially.
e	A DXMEvent object specifying the event.
b	The UntilNotifier object. The notify method of this object, called on the given event, returns the new behavior.