Timer Class Reference

Timer emits timing information to control cyclic animation, one-shot timing, media playback, or simulation. More...

Inheritance diagram for Timer:

List of all members.

Public Member Functions
virtual bool	handleEvent (const Event &event)
	Callback function that is implemented by the callee.

---

Detailed Description

Timer emits timing information to control cyclic animation, one-shot timing, media playback, or simulation.

All time field values are specified in decimal seconds, except where otherwise noted.

Authoring Interface:

        Timer {
            field   SFDouble    startTime       0
            field   SFDouble    stopTime        0
            field   SFDouble    playTime        0
            field   SFDouble    mediaTime       0
            field   SFDouble    mediaStartTime  0
            field   SFDouble    mediaStopTime   0
            field   SFBoolean   loop            false
            field   SFFloat     rate            1
            field   SFDouble    interval        -1 XXX
            
            eventOut    SFDouble    duration
            eventOut    SFBoolean   isActive
            eventOut    SFDouble    cycleTime
            eventOut    SFDouble    time
            eventOut    SFFloat     fraction
        }

Parameters:

	startTime	controls when mediaTime starts advancing. With stopTime, mediaTime is first reset to mediaStartTime, restarting playback from the beginning. Default value: 0
	stopTime	controls when mediaTime ceases advancing. Default value: 0
	playTime	controls playback the same as startTime, except with playTime, mediaTime resumes advancing from its previous value, restarting playback from where it last stopped. Default value: 0
	mediaTime	generates timing events as the activated Timer advances. Default value: 0
	mediaStartTime	specifies the initial value of mediaTime. Note that a non-zero value here "trims" off a leading segment of the media playback being controlled. Default value: 0
	mediaStopTime	specifies the final value of mediaTime. Note that a mediaStopTime less than the value of interval "trims" off a trailing segment of the media playback being controlled. Default value: 0
	loop	specifies whether mediaTime should reset and repeat advancing when it reaches mediaStopTime. Default value: false
	rate	specifies the rate mediaTime advances. With a rate of 1, mediaTime advances one second for each second of wall clock time. rate multiplies mediaTime's advance, where a negative rate reverses the direction of playback. Default value: 1
	interval	specifies the playback interval (in seconds) over which this Timer runs. Default value: -1 XXX Timer used as IntervalSensor requires this to default to 1
	duration	generates an event when all clients of this Timer have determined their duration; its value is the same as its clients' longest duration.
	isActive	generates a TRUE event when the Timer becomes active, and a FALSE event when the Timer becomes inactive.
	cycleTime	generates an event each time the Timer completes one full interval.
	time	emits the current wall clock time whenever mediaTime advances.
	fraction	emits the current progress over the Timer's interval, as a fraction running from 0 to 1.

Functionality:

If startTime is greater than or equal to stopTime, the Timer runs. If loop is true, it runs continuously, emitting fraction, time, and mediaTime. Also, every interval seconds it emits cycleTime. If loop is false, the Timer completes one cycle of interval seconds and then stops. If this interval completes conceptually before the Timer is created, no events fire on startup. So, with the default parameters, the Timer is created running (startTime >= stopTime), but already completed (loop==false).

When the Timer is quiescent (isActive== false) sending a startTime which is >= stopTime will start the Timer at the given startTime. If that time is in the past and the current time is less than startTime+interval, the first event emitted will be as though the Timer had started at that startTime. For instance, if interval is 5 and you send a startTime 1 second in the past, the first event emitted by fraction will be 0.2. If startTime is set to a time in the future, the Timer will start at that time. If stopTime is set to a value greater than startTime, the Timer will stop either at that stopTime or when the interval is reached, whichever is first. If that stopTime is in the past, the Timer will stop immediately. If it is in the future, but is set to a value that is less than startTime+interval, the Timer will stop when that time is reached.

The playTime field behaves similarly to startTime except that the fraction and mediaTime values are not reset to 0. They continue from where they left off when the last stopTime caused the Timer to stop. If the Timer had completed (it stopped because startTime+interval had been reached) playTime behaves like startTime. If a playTime in the past is given, the Timer continues as if it had been restarted at the given playTime, even if that playTime is before the current startTime. If a playTime in the future is given the Timer continues operation at that time. For instance, if the interval is 5 and startTime is sent the current time, two seconds later, fraction will be 0.4. If you then send a stopTime of the current time, the Timer stops and fraction remains at 0.4. If you then send a playTime of the current time, the fraction continues from 0.4. If instead you give a playTime 1 second in the past, the Timer immediately sends a fraction of 0.6 an continues from there.

The duration field is emitted as soon as the Timer knows its duration. This is typically the same as interval. But if interval is < 0 (the default), the duration is determined elsewhere (e.g., when the Timer is controlling a MovieSurface or MeshAnimation) it does not fire until the duration is known from the controlled asset.

The isActive field fires a true event when the Timer starts and a false event when it stops. The fraction field emits a value linearly increasing from 0 to 1 over the interval. If loop is true the fraction returns to 0 and increases again when the interval is reached. At the end of this interval-long cycle, the cycleTime field emits the current time. If loop is false, this happens once at the end of the cycle. Otherwise, it happens at the end of every cycle. While running, the time field emits the current time on every behavior cycle.

The rate field continuously varies the Timer's progression over its interval. Normally, fraction will be incremented by (timeStep/interval) over each timeStep of elapsed wall clock time. However, rate multiplies this increment ((timeStep/interval)*rate), causing the fraction to increase more rapidly when rate > 1 and more slowly when rate < 1. A rate < 0 will cause fraction to start at 1 and linearly decrease towards 0 at an increment determined by (timeStep/interval)*rate . The rate field can be changed continuously to modify progression towards the interval while the Timer is running. For instance, if the interval is 5 seconds and rate is 1, the fraction will be at 0.2 after 1 second (0.0+1/5*1.0). If you then change rate to 2, the fraction will be at 0.6 after one more second (0.2+1/5*2). If you then change the rate to 0.5, the fraction will be 0.7 after one more second (0.6+1/5*0.5). If you then change rate to -1, the fraction will be 0.5 after one more second (0.7+1/5*-1).

The mediaTime field emits a time value that starts at 0 when the Timer starts and continues forward at 1 second per second of elapsed time. For instance, if the interval is 5, the fraction value will go from 0 to 1 over that 5 seconds, but mediaTime will go from 0 to 5. Setting mediaStartTime and mediaStopTime modifies this behavior. If the mediaStartTime field is set to a value > 0, but less than the interval the mediaTime field will start at that value. This also affects the fraction output and reduces the total running time of the Timer. Similarly, if mediaStopTime is set to a value > 0 and greater than mediaStartTime and less than the interval, the mediaTime field will stop at that value. For instance, if the interval is 5 seconds and mediaStartTime is set to 1 and mediaStopTime is set to 4, when startTime is set the current time, mediaTime will immediately emit 1 and fraction will emit 0.2. These will continue emitting increasing value for 3 seconds at which time mediaTime will emit 4, fraction will emit 0.8 and the Timer will stop. If loop is true, mediaTime will then emit a 1 again, fraction will emit a 0.2 again and the cycle will continue.

The Timer can be put to a variety of uses. If used as the contol timer for a media asset (e.g., MovieSurface or MeshAnimation), the media can be started and stopped with startTime and stopTime. And playTime be used for a pause and continue feature, resuming playback from the current value of mediaTime, without first resetting mediaTime to its initial value (mediaStartTime). A subset of the asset can be played using mediaStartTime and mediaStopTime. and a companion animation can be controlled with the fraction output. The Timer can also be used to control a one-shot event. If you set interval to the desired delay and then send a startTime event, when the interval is reached, cycleTime fires to signal the event. The Timer can also be used to wake-up an activity periodically. By setting interval to the wake-up period, and setting loop to true, cycleTime will fire whenever the activity should be executed.

---

Member Function Documentation

virtual bool handleEvent (  const Event &  event  )  [virtual]

Callback function that is implemented by the callee. Parameters: event  specifies the time of the event. Event time will be the same for events occurring in the same render phase For example, PREUPDATE, POSTUPDATE, PRERENDER and POSTRENDER event callbacks will all pass the same event time for the same frame. Returning stop Emma from calling the rest of the handlers for this event If you return true, Emma will keep on calling rest of the handlers for this event Implements EventHandler.

---