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.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$

Author:

C. Fong, Steve Neuendorffer, Contributor: Christopher Hylands

See Also:

GRReceiver, GRActor

Pt.AcceptedRating:

yellow (vogel)

Pt.ProposedRating:

yellow (chf)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
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, _prefire

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _aspectForActor, _aspectsPresent, _defaultMicrostep, _executionAspects, _finishRequested, _initializables, _nextScheduleTime, _stopRequested, _tokenSentToCommunicationAspect, _zeroTime, localClock, startTime, stopTime

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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, int microstep) 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, resumeActor, setScheduler

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelStartTime, getModelStopTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, stop, stopFire, suggestedModalModelDirectors, supportMultirateFiring, suspend, terminate, transferInputs, transferOutputs, 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, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, 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, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeHierarchyListener, 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.

Constructor Detail

GRDirector

public GRDirector()
           throws IllegalActionException,
                  NameDuplicationException

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.

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

GRDirector

public GRDirector(Workspace workspace)
           throws IllegalActionException,
                  NameDuplicationException

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.

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

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,
                   int microstep)
            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.

microstep - The microstep.

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), Director.fireContainerAt(Time)

getCurrentTime

@Deprecated
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 StaticSchedulingDirector

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