TimeSensors generate events as time passes. TimeSensors remains inactive until their startTime is reached. At the first simulation tick where real time >= startTime, the TimeSensor will begin generating time and alpha events, which may be routed to other nodes to drive continuous animation or simulated behaviors. The length of time a TimeSensor generates events is controlled using cycleInterval and cycleCount; a TimeSensor stops generating time events at time startTime+cycleInterval*cycleCount. cycleMethod controls the mapping of time to alpha values (which are typically used to drive Interpolators). It may be set to FORWARD, causing alpha to rise from 0.0 to 1.0 over each interval, BACK which is equal to 1-FORWARD, or it may be set to SWING, causing alpha to alternate 0.0 to 1.0, 1.0 to 0.0, on each successive interval, TICK will generate events only once per cycle, with alpha always set to 0.
pauseTime may be set to interrupt the progress of a TimeSensor. If pauseTime is greater than startTime, time and alpha events will not be generated after the pause time. pauseTime is ignored if it is less than or equal to startTime.
If cycleCount is <= 0, the TimeSensor will continue to tick continuously, without a cycle interval; in this case, cycleInterval and cycleMethod are ignored, and alpha events are not generated. This use of the TimeSensor should be used with caution, since it incurs continuous overhead on the simulation.
Setting cycleCount to 1 and cycleInterval to 0 will result in a single event being generated at startTime; this can be used to build alarms and timers that go off periodically.
No guarantees are made with respect to how often a TimeSensor will generate time events, but at least one event must be generated if it is later than startTime and startTime was set to a time in the future.
FILE FORMAT/DEFAULTS
TimeSensor {
startTime 0 # SFTime (double-precision seconds)
pauseTime 0 # SFTime
cycleInterval 1 # SFTime
cycleCount 1 # SFLong
cycleMethod FORWARD # SFEnum FORWARD | BACK | SWING | TICK
actionObject Parent # SFNode
actionMethod "Tick" # SFString
actionParameters SFNode Self # MFFields
# eventIn SFTime setStartTime
# eventIn SFTime setPauseTime
# eventIn SFTime setCycleInterval
# eventIn SFLong setCycleCount
# eventIn SFEnum setCycleMethod # FORWARD | BACK | SWING
# eventOut SFTime time
# eventOut SFFloat alpha
}
Oops, need to add a description of the SFTime field. We could use SFFloat's for time, except that if we expect to be dealing with absolute times( from Jan 1 1970 0:00 GMT perhaps) then 32-bit floats don't give enough precision. Inventor writes SFTime fields as 64-bit double-precision values, but stores time values internally as two 32-bit integers. The unit needs to be specified - if its a float, it could be seconds, if it is a Long then a second is too course.
Open issue: Do we use wall-clock, real-time, or simulation-time, or do we allow this to be selectable by the author, with a sensible default?