DirectX Media for Animation Programmer's Guide

Previous

TOC

Index

Next

DXMApplet and DXMCanvas

Direct Animation for Java provide the DXMApplet and DXMCanvas classes which extend the standard AWT Applet and Canvas classes to provide applets and canvases specifically for displaying behaviors. Each of these require a Model upon construction, and they each override the necessary methods on Applet and Canvas in order to view that model. In the case of DXMApplet, start() and stop() methods are provided. For DXMCanvas, show() and hide() methods are provided.

Note that, by default, DXMApplet and DXMCanvas provide their own frame-loop so the application needn't provide one explicitly (though it may choose to do so by overriding this default behavior).

Here is an example of using the DXMApplet class to view the AllMediaTypes model defined above:

public class MyApplet 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 MyApplet());
    }
}

Given a model, this is all that is needed to construct an applet to view that model.

The use of DXMCanvas is identical, except, of course, you need to position the canvas inside of an application frame, just as you would any other canvas.

Dynamically Changing the Model

Note that these classes are defined such that once an applet or canvas is built, the model cannot be changed. This is intentional. If there is a need to change the model dynamically, this should be reflected in changes to the behaviors that make up the model, and not by switching to another model. If an application really needs to switch to an entirely different model, it can construct a new applet or canvas.

Advanced Topic: The Viewer interface

Direct Animation for Java provides a Java interface called Viewer that encapsulates operations common to all displayers of behaviors. Because it is an interface, it is not constructed directly by applications. Instead, it is provided through concrete classes such as the DXMApplet and DXMCanvas classes . However, it does have a set of methods that can be used by applications.

Most applications never need to call any of these methods or, for that matter, ever need know about the Viewer interface. This is only for more explicit control of the running of behaviors, and for non-default ways of dealing with error handling and preference establishment.

Here are the relevant portions:

public interface Viewer {
    public void startModel() throws QQException;
    public void tick(double timeToUse) throws QQException;
    public void tick() throws QQException;
    public double getCurrentTime();
    public double getCurrentTickTime();
    public void registerErrorAndWarningReceiver
                               (ErrorAndWarningReceiver w);
    public Preferences getPreferences();
    public void        setPreferences(Preferences p);
}

The viewer gets its model via a mechanism not shown here (it is not meant to be called by applications). The relevant methods are:

• The startModel() method which starts the behaviors associated with the model at global time 0. This is when the globalTime behavior starts. Incidentally, startModel() is also what causes the createModel() method on the model itself to get invoked.
• The tick(double timeToUse) method which explicitly does a single sampling and display of the model with timeToUse as the global time.
• The tick() method, which is shorthand for tick(getCurrentTime()), and is the easiest way to explicitly sample and display the model, thus providing a real-time clock for global time.
• The getCurrentTime()method returns the number of seconds since startModel was invoked.
• The getCurrentTickTime() method returns the time provided for the most recent call to tick, or 0 if it hasn't yet been called.
• The registerErrorAndWarningReceiver() method which allows the application to register an object that will have its methods invoked upon asynchronous errors encountered when Direct Animation is controlling the frame loop, or when recoverable warnings occur when sampling and displaying the model.
• The getPreferences()/setPreferences() methods which allow the application to dynamically modify the viewer preferences at arbitrary times (as opposed to the establishPreferences() method contained in the Model class, which only allows preferences to be established when the model is being constructed).

Explicit Control of the Frame Loop

The implementations of DXMApplet and DXMCanvas implement a thread that repeatedly calls the tick() method, and thus have a built-in frame loop. If an application wants to explicitly control the frame loop, it override these classes and providing different implementations that invoke tick() in their application-specific way.

Advanced Topic: Preferences

Occasionally, the programmer constructing the model, or the application controlling the viewer, will want to provide explicit rendering/viewing preference settings to Direct Animation. Such preferences can include texture mapping quality, output audio format, maximum frames per second, polygon fill mode, and so on.

The Preferences object is the means by which these settings are made. Asit was previously shown, the model can set these preferences upon model construction, and the application can set them at any time by querying the viewer for them, setting them, and then submitting them back to the viewer.

Note also that, through the system registry, the user has an opportunity to establish preferences that become the default set of preferences for viewing a model. Changes made by the model or the application override these defaults. Because of this, setting of preferences should be something that both the model and the application approach conservatively, and only do if it is truly appropriate for the situation.