ptolemy.domains.gr.kernel
Class GRDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.actor.sched.StaticSchedulingDirector
                  ptolemy.domains.gr.kernel.GRDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class GRDirector
extends StaticSchedulingDirector

GR is a domain for displaying three-dimensional graphics in Ptolemy II. GR is an untimed domain in where actors are connected in an acyclic directed graph. Actors are fired according to a simple topological sort of the graph. Nodes in the graph that have no descendants are assumed to be consumers of data produced by the rest of the model.

The basic idea behind the GR domain is to arrange geometry and transform actors in a directed acyclic graph to represent the location and orientation of objects in a scene. This topology of connected GR actors form what is commonly called a scene graph in computer graphics literature. The GR director converts the GR scene graph into a Java3D representation for rendering on the computer screen.

Since:

Ptolemy II 1.0

Version:

$Id: GRDirector.java 57046 2010-01-27 23:35:53Z cxh $

Author:

C. Fong, Steve Neuendorffer, Contributor: Christopher Hylands

See Also:

GRReceiver, GRActor, Serialized Form

Accepted Rating:

yellow (vogel)

Proposed Rating:

yellow (chf)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private java.util.Set<Actor>	_disabledActors The set of actors that have returned false in their postfire() methods.
private Director	_insideDirector
private int	_iteration
private long	_lastIterationTime
private boolean	_pseudoTimeEnabled
Parameter	iterations A parameter representing the number of times that postfire() may be called before it returns false.
Parameter	iterationTimeLowerBound A parameter that indicates the time lower bound of each iteration.

Fields inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_postfireReturns

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

GRDirector()
Construct a director in the default workspace with an empty string as its name.

GRDirector(CompositeEntity container, java.lang.String name)
Construct a director in the given container with the given name.

GRDirector(Workspace workspace)
Construct a director in the workspace with an empty name.

Method Summary

private void	_buildActorTable() Create an actor table that caches all the actors directed by this director.
private void	_debugViewActorTable() For debugging purposes.
private void	_fire() Make sure that iterationLowerUpperBound milliseconds have elapsed since the last iteration.
private ViewScreenInterface	_getViewScreen() Return the one view screen in the model under the control of this director.
private void	_init() Most of the constructor initialization is relegated to this method.
private void	_reset()
java.lang.Object	clone(Workspace workspace) Clone the director into the specified workspace.
void	fire() Override the super class method.
Time	fireAt(Actor actor, Time time) Schedule a firing of the given actor at the given time.
double	getCurrentTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()
Time	getModelNextIterationTime() Return maximum value for type double.
Time	getModelTime() Return the current "time".
void	initialize() Initialize all the actors associated with this director.
void	invalidateSchedule() Process the mutation that occurred.
Receiver	newReceiver() Return a new receiver consistent with the GR domain.
boolean	postfire() Iterate all actors under control of this director and fire them.
boolean	prefire() Always return true.
void	preinitialize() Preinitialize the actors associated with this director and initialize the number of iterations to zero.
void	wrapup() Reset this director to an uninitialized state to prepare for the end of an execution.

Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_setScheduler, addDebugListener, getScheduler, isScheduleValid, removeDebugListener, setScheduler

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, finish, fireAt, fireAtCurrentTime, getCausalityInterface, getErrorTolerance, getGlobalTime, getModelStartTime, getModelStopTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isFireFunctional, isStopRequested, isStrict, iterate, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime, setModelTime, stop, stopFire, suggestedModalModelDirectors, supportMultirateFiring, terminate, transferInputs, transferOutputs

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

iterations

public Parameter iterations

A parameter representing the number of times that postfire() may be called before it returns false. If the value is less than or equal to zero, the execution will never return false in postfire(), and thus the execution continues indefinitely. This parameter must contain an IntToken. The default value is an IntToken with the value zero.

iterationTimeLowerBound

public Parameter iterationTimeLowerBound

A parameter that indicates the time lower bound of each iteration. This parameter is useful for guaranteeing that each frame of an animation takes at least a certain amount of time before proceeding to the next frame. This parameter is measured in milliseconds. This parameter must contain an IntToken. The default value is an IntToken with value the 33, which corresponds roughly to 30 frames per second.

_disabledActors

private java.util.Set<Actor> _disabledActors

The set of actors that have returned false in their postfire() methods. These actors will not be fired again.

_lastIterationTime

private long _lastIterationTime

_pseudoTimeEnabled

private boolean _pseudoTimeEnabled

_insideDirector

private Director _insideDirector

_iteration

private int _iteration

Constructor Detail

GRDirector

public GRDirector()

Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

GRDirector

public GRDirector(Workspace workspace)

Construct a director in the workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:

workspace - The workspace of this object.

GRDirector

public GRDirector(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException

Construct a director in the given container with the given name. If the container argument is null, a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:

container - Container of the director.

name - Name of this director.

Throws:

IllegalActionException - If the director is not compatible with the specified container.

NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity in the container.

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the director into the specified workspace. This calls the base class and then copies the parameter of this director. The new actor will have the same parameter values as the old.

Overrides:

clone in class StaticSchedulingDirector

Parameters:

workspace - The workspace for the new object.

Returns:

A new object.

Throws:

java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Override the super class method. This method does nothing and everything is postponed to the postfire() method. This assures that inputs are stable.

Specified by:

fire in interface Executable

Overrides:

fire in class StaticSchedulingDirector

Throws:

IllegalActionException - If any actor executed by this actor return false in prefire.

fireAt

public Time fireAt(Actor actor,
                   Time time)
            throws IllegalActionException

Schedule a firing of the given actor at the given time. If there is an executive director, this method delegates to it. Otherwise, it sets its own notion of current time to that specified in the argument. The reason for this is to enable GRDirector to be a top-level director and to support the design pattern where a director requests a refiring at the next time it wishes to be awakened, just prior to returning from fire(). DEDirector, for example, does that, as does the SDFDirector if the period parameter is set.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The scheduled time.

Returns:

The time returned by the executive director, or or the specified time if there isn't one.

Throws:

IllegalActionException - If by the executive director.

See Also:

Director.fireAtCurrentTime(Actor)

getCurrentTime

public double getCurrentTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()

Return the current "time". The GR domain is not a timed domain, so this method is semantically meaningless. However, this method is implemented in order to get timed domains to work inside the GR domain. In particular, this method will give actors a "fake" impression of advancement of time.

Overrides:

getCurrentTime in class Director

Returns:

The current "time"

See Also:

Director.setCurrentTime(double)

getModelTime

public Time getModelTime()

Return the current "time". The GR domain is not a timed domain, so this method is semantically meaningless. However, this method is implemented in order to get timed domains to work inside the GR domain. In particular, this method will give actors a "fake" impression of advancement of time.

Overrides:

getModelTime in class Director

Returns:

The current "time"

See Also:

Director.setModelTime(Time)

getModelNextIterationTime

public Time getModelNextIterationTime()

Return maximum value for type double. Since the GR domain is not a timed domain, so this method does not return any meaningful value. However, this method is implemented so that GR will work within timed domains.

Overrides:

getModelNextIterationTime in class Director

Returns:

The maximum value for type double.

See Also:

Director.getModelTime()

initialize

public void initialize()
                throws IllegalActionException

Initialize all the actors associated with this director. Perform some internal initialization for this director.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

IllegalActionException - If the initialize() method of one of the associated actors throws it.

invalidateSchedule

public void invalidateSchedule()

Process the mutation that occurred. Reset this director to an uninitialized state to prepare for rescheduling. Notify parent class about invalidated schedule.

Overrides:

invalidateSchedule in class StaticSchedulingDirector

See Also:

NamedObj.attributeChanged(ptolemy.kernel.util.Attribute), NamedObj.attributeTypeChanged(ptolemy.kernel.util.Attribute)

newReceiver

public Receiver newReceiver()

Return a new receiver consistent with the GR domain.

Overrides:

newReceiver in class Director

Returns:

A new GRReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Iterate all actors under control of this director and fire them. Return false if the system has finished executing. This happens when the iteration limit is reached. The iteration limit is specified by the iterations parameter. If the iterations parameter is set to zero, this method will always return true and the model will run indefinitely.

Specified by:

postfire in interface Executable

Overrides:

postfire in class StaticSchedulingDirector

Returns:

Return true if the iterations parameter is 0 or if the iteration limit has not been exceeded.

Throws:

IllegalActionException - If unable to get the parameter iterations.

prefire

public boolean prefire()
                throws IllegalActionException

Always return true. A GR composite actor will always be iterated. Note that this does not call prefire() on the contained actors.

Specified by:

prefire in interface Executable

Overrides:

prefire in class StaticSchedulingDirector

Returns:

Always returns True.

Throws:

IllegalActionException - Not thrown in this base class

preinitialize

public void preinitialize()
                   throws IllegalActionException

Preinitialize the actors associated with this director and initialize the number of iterations to zero. The order in which the actors are preinitialized is non-deterministic.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

wrapup

public void wrapup()
            throws IllegalActionException

Reset this director to an uninitialized state to prepare for the end of an execution.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class Director

Throws:

IllegalActionException - If the parent class throws it

_buildActorTable

private void _buildActorTable()
                       throws IllegalActionException

Create an actor table that caches all the actors directed by this director. This method is called once in initialize().

Throws:

IllegalActionException - If the scheduler is null.

_debugViewActorTable

private void _debugViewActorTable()
                           throws IllegalActionException

For debugging purposes. Display the list of contained actors and other pertinent information about them.

Throws:

IllegalActionException - If there is a problem in obtaining the number of initial token for delay actors

_fire

private void _fire()
            throws IllegalActionException

Make sure that iterationLowerUpperBound milliseconds have elapsed since the last iteration. Go through the schedule and iterate every actor. If an actor returns false in its prefire(), fire() and postfire() will not be called on it.

Throws:

IllegalActionException - If an actor executed by this director returns false in its prefire().

_getViewScreen

private ViewScreenInterface _getViewScreen()
                                    throws IllegalActionException

Return the one view screen in the model under the control of this director.

Returns:

The one view screen.

Throws:

IllegalActionException - If there is more than one view screen.

_init

private void _init()

Most of the constructor initialization is relegated to this method. Initialization process includes : - create a new actor table to cache all actors contained - create a new receiver table to cache all receivers contained - set default number of iterations - set period value

_reset

private void _reset()