msim.trajectory

Class SequenceDriver

java.lang.Object

msim.trajectory.TrajectoryActor

msim.trajectory.TrajectoryDriver

msim.trajectory.SequenceDriver

@ThreadSafe
public class SequenceDriver
extends TrajectoryDriver

Interpolates waypoints along a trajectory.

Copyright (C) 2009 Marsette A. Vona, III

Author:

Marsette A. Vona, III

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SequenceDriver.AdvanceHook interface for callback on advance to next waypoint
static class	SequenceDriver.ApplyingAdvanceHook Generic SequenceDriver.AdvanceHook impl that delegates to an object implementing an apply(Object[]) method.
static class	SequenceDriver.State playback state machine states
protected static class	SequenceDriver.Waypoint collection of data for a waypoint

Field Summary

Fields

Modifier and Type	Field and Description
protected SequenceDriver.AdvanceHook	advanceHook see setAdvanceHook(msim.trajectory.SequenceDriver.AdvanceHook)
protected vona.math.RXSInterpolator.InterpolationType	constrainedInterpolationType (un)constrained interpolation type
private static java.lang.String	cvsid
protected double	interpolationStart start/duration of current interpolation
protected double	interpolationTime start/duration of current interpolation
protected vona.math.RXSInterpolator[]	interpolator interpolators for each bound transform
protected boolean	loop whether playback is set to cycle
protected int	nextWaypoint Index of the next SequenceDriver.Waypoint in waypoints that will be played back, or equal to waypoints.size() if none.
protected double	pauseTime TrajectoryActor.clock time when SequenceDriver.State.PAUSE began
protected SequenceDriver.State	state current playback state
protected vona.math.RXSInterpolator.InterpolationType	unconstrainedInterpolationType (un)constrained interpolation type
protected java.util.Iterator<SequenceDriver.Waypoint>	waypointIterator current iterator on waypoints during playback
protected java.util.LinkedList<SequenceDriver.Waypoint>	waypoints The current list of waypoints.

Fields inherited from class msim.trajectory.TrajectoryDriver

lastUpdateTime

Fields inherited from class msim.trajectory.TrajectoryActor

active, clock, joint, slackID, wasOnlySetChangedGoalComponents, xform, xformID

Constructor Summary

Constructors

Constructor and Description
SequenceDriver() covers superclass impl
SequenceDriver(vona.time.Clock clock) covers superclass impl

Method Summary

Methods

Modifier and Type	Method and Description
protected void	advance() Advance interpolators to the next waypoint.
void	appendWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, double... waypoint) Inserts at end of sequence
void	appendWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, vona.math.RX... waypoint) Inserts at end of sequence
int	bind(java.lang.Object... specs) Fill the set of transforms which this TrajectoryActor reads/writes, in order.
void	clearWaypoints() Remove all current waypoints.
vona.math.RXSInterpolator.InterpolationType	getConstrainedInterpolationType() get the interpolation type for constrained transforms
protected double	getInterpolationCoordinate() Get the current normalized interpolation coordinate in [0.0, 1.0].
int	getNextWaypoint() get the index of the next waypoint that will be played back
int	getNumWaypoints() get the current number of waypoints in the sequence
SequenceDriver.State	getState() get the current playback SequenceDriver.State
vona.math.RXSInterpolator.InterpolationType	getUnconstrainedInterpolationType() get the interpolation type for unconstrained transforms
boolean	insertWaypoint(int index, vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, double... waypoint) Interprets waypoint as a packed TXEM DoF vector.
boolean	insertWaypoint(int index, vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, vona.math.RX... waypoint) Insert a new waypoint.
boolean	isLoop() Check whether playback cycles back to the waypoint sequence start after attaining the last waypoint.
boolean	needsUpdate() Called by the update thread when this TrajectoryActor is active to check whether TrajectoryActor.update() needs to be called soon.
void	pause() Pause any ongoing sequence playback.
void	play() Begin or resume sequence playback.
void	prependWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, double... waypoint) Inserts at start of sequence.
void	prependWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile, double interpolationTime, vona.math.RX... waypoint) Inserts at start of sequence.
void	removeWaypoint(int index) Remove an existing waypoint from the sequence.
void	rewind() convenience to setNextWaypoint(int) to 0
SequenceDriver.AdvanceHook	setAdvanceHook(SequenceDriver.AdvanceHook hook) Register a hook to be called after advancing to each waypoint.
void	setConstrainedInterpolationType(vona.math.RXSInterpolator.InterpolationType interpolationType) set the interpolation type for constrained transforms
void	setLoop(boolean loop) Set whether playback cycles back to the waypoint sequence start after attaining the last waypoint.
void	setNextWaypoint(int index) Set the index of the first waypoint to be played back.
void	setUnconstrainedInterpolationType(vona.math.RXSInterpolator.InterpolationType interpolationType) set the interpolation type for unconstrained transforms
void	stop() Stop any ongoing sequence playback.
void	unbind() Clear the set of transforms which this TrajectoryActor reads/writes.
void	update() Read/write transform state from/to model.
protected void	updateXForms() Update the TrajectoryActor.xform values from their driving source.
protected void	updateXForms(double interpolationCoordinate) Updates TrajectoryActor.xforms from interpolators given interpolationCoordinate.

Methods inherited from class msim.trajectory.TrajectoryDriver

activate, compareXFormsInNeedsUpdate, deactivate, getMinUpdateTime, updateXFormsInNeedsUpdate

Methods inherited from class msim.trajectory.TrajectoryActor

checkBindings, clampXForms, compareXFormsToModel, getBoundJoint, getBoundXForm, getDefaultXForm, getNumBindings, getOriginalUnsetGoal, isActive, modelStateChanged, modelStructureChanged, onlySetChangedGoalComponents, readXFormsFromModel, writeXFormsToModel

Methods inherited from class java.lang.Object

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

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

state

protected SequenceDriver.State state

current playback state

waypoints

protected java.util.LinkedList<SequenceDriver.Waypoint> waypoints

The current list of waypoints.

This is only mutable when in playback state SequenceDriver.State.IDLE.

Any existing waypoints will be checked for compatiblity with a new bind(java.lang.Object...).

nextWaypoint

protected int nextWaypoint

Index of the next SequenceDriver.Waypoint in waypoints that will be played back, or equal to waypoints.size() if none.

waypointIterator

protected java.util.Iterator<SequenceDriver.Waypoint> waypointIterator

current iterator on waypoints during playback

interpolationStart

protected double interpolationStart

start/duration of current interpolation

interpolationTime

protected double interpolationTime

start/duration of current interpolation

pauseTime

protected double pauseTime

TrajectoryActor.clock time when SequenceDriver.State.PAUSE began

loop

protected boolean loop

whether playback is set to cycle

interpolator

protected vona.math.RXSInterpolator[] interpolator

interpolators for each bound transform

constrainedInterpolationType

protected vona.math.RXSInterpolator.InterpolationType constrainedInterpolationType

(un)constrained interpolation type

unconstrainedInterpolationType

protected vona.math.RXSInterpolator.InterpolationType unconstrainedInterpolationType

(un)constrained interpolation type

advanceHook

protected SequenceDriver.AdvanceHook advanceHook

see setAdvanceHook(msim.trajectory.SequenceDriver.AdvanceHook)

Constructor Detail

SequenceDriver

public SequenceDriver(vona.time.Clock clock)

covers superclass impl

SequenceDriver

public SequenceDriver()

covers superclass impl

Method Detail

play

public void play()

Begin or resume sequence playback.

This can be called from any state.

The state will automatically return to SequenceDriver.State.IDLE after the last waypoint (unless looping) or if there are no waypoints.

pause

public void pause()

Pause any ongoing sequence playback.

Interpolation stops immediately.

stop

public void stop()

Stop any ongoing sequence playback.

Interpolation continues until the current waypoint is attained.

rewind

public void rewind()

convenience to setNextWaypoint(int) to 0

getState

public SequenceDriver.State getState()

get the current playback SequenceDriver.State

setLoop

public void setLoop(boolean loop)

Set whether playback cycles back to the waypoint sequence start after attaining the last waypoint.

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

isLoop

public boolean isLoop()

Check whether playback cycles back to the waypoint sequence start after attaining the last waypoint.

setNextWaypoint

public void setNextWaypoint(int index)

Set the index of the first waypoint to be played back.

Parameters:

index - the index of the first waypoint to be played back, negative treated as 0, greater than or equal to waypoints.size() treated as waypoints.size()-1

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

getNextWaypoint

public int getNextWaypoint()

get the index of the next waypoint that will be played back

insertWaypoint

public boolean insertWaypoint(int index,
                     vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                     double interpolationTime,
                     vona.math.RX... waypoint)

Insert a new waypoint.

The passed transforms will be clamped to the current limits of the corresponding bound joints, where appliccable.

Parameters:

index - the index of the new waypoint (existing waypoints at this and hider indices will have their indices incremented), negative treated as 0, greater than waypoints.size() treated as waypoints.size()

interpolationTime - the time in seconds to spend interpolating to this waypoint, not NaN and not negative

Returns:

true if any transform was changed due to clamping

Throws:

java.lang.IllegalArgumentException - if the number of passed transforms does not equal the number of currently bound transforms

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

insertWaypoint

public boolean insertWaypoint(int index,
                     vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                     double interpolationTime,
                     double... waypoint)

Interprets waypoint as a packed TXEM DoF vector.

appendWaypoint

public void appendWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                  double interpolationTime,
                  vona.math.RX... waypoint)

Inserts at end of sequence

appendWaypoint

public void appendWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                  double interpolationTime,
                  double... waypoint)

Inserts at end of sequence

prependWaypoint

public void prependWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                   double interpolationTime,
                   vona.math.RX... waypoint)

Inserts at start of sequence.

prependWaypoint

public void prependWaypoint(vona.math.RXSInterpolator.InterpolationProfile interpolationProfile,
                   double interpolationTime,
                   double... waypoint)

Inserts at start of sequence.

removeWaypoint

public void removeWaypoint(int index)

Remove an existing waypoint from the sequence.

Parameters:

index - the index of the waypoint to remove, negative treated as 0, greater than or equal to waypoints.size() treated as waypoints.size()-1

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

clearWaypoints

public void clearWaypoints()

Remove all current waypoints.

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

getNumWaypoints

public int getNumWaypoints()

get the current number of waypoints in the sequence

setConstrainedInterpolationType

public void setConstrainedInterpolationType(vona.math.RXSInterpolator.InterpolationType interpolationType)

set the interpolation type for constrained transforms

getConstrainedInterpolationType

public vona.math.RXSInterpolator.InterpolationType getConstrainedInterpolationType()

get the interpolation type for constrained transforms

Overrides:

getConstrainedInterpolationType in class TrajectoryActor

setUnconstrainedInterpolationType

public void setUnconstrainedInterpolationType(vona.math.RXSInterpolator.InterpolationType interpolationType)

set the interpolation type for unconstrained transforms

getUnconstrainedInterpolationType

public vona.math.RXSInterpolator.InterpolationType getUnconstrainedInterpolationType()

get the interpolation type for unconstrained transforms

Overrides:

getUnconstrainedInterpolationType in class TrajectoryActor

bind

public int bind(java.lang.Object... specs)

Fill the set of transforms which this TrajectoryActor reads/writes, in order.

This impl extends superclass impl to allocate interpolator.

Overrides:

bind in class TrajectoryActor

Parameters:

specs - a set of Joint sub-transform specifiers, in order, each of the the form (joint, name, or path, sub-transform ID...). If no sub-transform IDs are given then TrajectoryActor.getDefaultXForm() is implied. If more than one sub-transform ID is given then more than one binding is specified.

Returns:

the number of transforms bound

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

java.lang.IllegalStateException - if there are existing waypoints and they are not compatible with the new bindings (the driver will be left unbound)

unbind

public void unbind()

Clear the set of transforms which this TrajectoryActor reads/writes.

This impl extends superclass impl to deallocate interpolator.

Overrides:

unbind in class TrajectoryActor

Throws:

java.lang.IllegalStateException - if called when not in SequenceDriver.State.IDLE

update

public void update()

Read/write transform state from/to model.

This is called automatically by the update thread whenever this TrajectoryActor is active. See class header doc for details.

This impl sets TrajectoryDriver.lastUpdateTime, TrajectoryDriver.updateXForms(), and then TrajectoryActor.writeXFormsToModel().

This impl marks TrajectoryDriver.lastUpdateTime, and then updateXForms() and TrajectoryActor.writeXFormsToModel() iff playback state is SequenceDriver.State.PLAY or SequenceDriver.State.STOPPING. Also handles advance()ing from waypoint to waypoint, and stopping playback when finished.

Overrides:

update in class TrajectoryDriver

needsUpdate

public boolean needsUpdate()

Called by the update thread when this TrajectoryActor is active to check whether TrajectoryActor.update() needs to be called soon.

This impl does TrajectoryDriver.updateXForms() then returns the opposite of TrajectoryActor.compareXFormsToModel() iff TrajectoryDriver.lastUpdateTime is NaN or is at least as long ago as TrajectoryDriver.getMinUpdateTime().

The comparison is skipped if not TrajectoryDriver.compareXFormsInNeedsUpdate(), and otherwise the update is skipped if not TrajectoryDriver.updateXFormsInNeedsUpdate().

This impl returns true if it's been at least TrajectoryDriver.getMinUpdateTime() since the last update() and playback state is SequenceDriver.State.PLAY or SequenceDriver.State.STOPPING.

Overrides:

needsUpdate in class TrajectoryDriver

setAdvanceHook

public SequenceDriver.AdvanceHook setAdvanceHook(SequenceDriver.AdvanceHook hook)

Register a hook to be called after advancing to each waypoint.

updateXForms

protected void updateXForms()

Update the TrajectoryActor.xform values from their driving source.

This impl calls updateXForms(double) with getInterpolationCoordinate().

Specified by:

updateXForms in class TrajectoryDriver

updateXForms

protected void updateXForms(double interpolationCoordinate)

Updates TrajectoryActor.xforms from interpolators given interpolationCoordinate.

getInterpolationCoordinate

protected double getInterpolationCoordinate()

Get the current normalized interpolation coordinate in [0.0, 1.0].

advance

protected void advance()

Advance interpolators to the next waypoint.