Timer CHOP

From TouchDesigner 088 Wiki


Summary

The Timer CHOP is an engine for running timed processes. It outputs channels such as timing fractions, counters, pulses and timer states, and it calls python functions (callbacks) when various timing events occur.

Examples using the Timer CHOP include triggering multiple timed cues, running playlists, timelines, state machines, and driving pre-animated animation components in 3D scenes. See Help -> Operator Snippets for numerous examples.

You set a timer to a number of seconds, frames or samples, and trigger it to start via the Start parameter or the second input CHOP. The Timer CHOP outputs in seconds, frames, samples, fraction and on-off states as it’s counting, including a done channel that goes on when it is complete. When it reaches certain states like end-of-cycles or when it’s done, various python callbacks are called allowing you to customize its behavior.

The Timer CHOP gets triggered by events (via pulsing its parameters or driving its two inputs). It takes events in, counts time, changes state. Via its python callback functions, you can send events out to other nodes, set parameters, get/set values in DATs, CHOPs and storage, restart itself, or trigger other nodes. As such, it can operate as a state machine.

It has play/pause, plus a speed control to slow down or speed up the timer.

It can also cycle indefinitely and then can be signaled to end immediately or at the end of the current cycle.

One Timer CHOP can also have multiple timers within it. By attaching a Table DAT you can define one timer (segment) per row. In Serial Timers mode it allows for one time segment followed by another. In Parallel Timers mode, the timers all run in parallel, each with its own begin time and length, and its own set of output channels.

Timer CHOP.2.png

The Timer CHOP can be Locked to Timeline in a deterministic way, or run more freely in Sequential Mode. When run independently from the timeline, you can jump ahead, break out of cycles, pause, goTo() exact position or timecode in the timer, and dynamically adjust the speed.

The Timer CHOPs can be chained together, so that when one ends, the next can begin. They just need to all be Initialized together, where the ready_pulse channel of one Timer CHOP is exported to the Initialize parameter of the next Timer CHOP. Then they can be run in sequence, where the output of one Timer CHOP’s done_pulse channel is wired to the Start input (or exported to the Start parameter) of the next Timer CHOP. You start the chain of timers by starting the first Timer CHOP. By using some Timer CHOPs to loop awaiting input or response, or by adding logic to decide which CHOP to start next, state machines can be implemented.

Before a cycle or segment ends, an onCycleEndAlert() callback based on the Cycle End Alert parameter can be called to allow you to prepare for the next cycle, segment or Timer CHOP.

Attach an Info DAT to see the timecodes, or use the .timecode members. Custom text strings can be placed in the Info DAT for each segment, and custom animated channels can be created.

To make the entire CHOP loop after the last segment, put a timerOp.goTo(seconds=0) in onDone().

Recommended: the OP Snippets for Timer CHOP

See also: Trigger CHOP, Event CHOP, Speed CHOP, Count CHOP, Beat CHOP, Event CHOP, Clock CHOP, Delay CHOP, CHOP Execute DAT, LFO CHOP.

PythonIcon.png timerCHOP_Class

Parameters - Timer Page

Play Mode menu - Sequential (timeline-independent) or Locked to Timeline. In Locked to Timeline, non-deterministic features are disabled.

Initialize - (pulse parameter) Initialize is the signal to get the timer ready: sets the counters to zero (delay, timer, cycle, segment), set the output channels in the proper state, done to be off, the onInitialize() callback is run, and when initialize is complete, it indicates it’s ready by turning on the ready channel, awaiting a Start pulse.

Start (pulse) Start is the signal to commence the timers counting. It will count through the delay first, then the timer length. It does an Initialize if it is not already initialized, and then starts counting.

Length (float) the time-length of the timer. Set the Units menu to Seconds, Frames or Samples.

Delay (float) after Start, the delay before the timer begins counting.

Play (onoff) Pauses the timer. It is basically a 0 or 1 multiplier on the Speed.

Speed (default 1) Slows down or speeds up the timer.

Cue freezes playing at the Cue Point.

Cue Point time (Seconds, Frames or Fraction) which the cue point is frozen to.

Cycle (default Off) causes the timer to loop back to 0 when it reaches the end of the cycle.

Cycle Limit When the Cycle parameter is On, this determines if it will cycle indefinitely or cycle some maximum number of cycles.

Maximum Cycles When Cycle is on and Cycle Limit is on, this sets the maximum number of cycles.

Cycle End Alert – the number of seconds, frames or samples before a cycle, segment or done state is reached that the onCycleEndAlert() callback is called. This allows you to prepare for the next cycle, segment or timer.

Exit Segment at End of Cycle - When pulsed, it will exit the cycle (and segment) at the end of the currently-playing cycle.

Go to End of Cycle - When pulsed, it will exit the cycle (and segment) immediately.

Go to Done - will immediately go to the Done state.

Script DAT - the name of the DAT containing all the callbacks for this Timer CHOP. See timerCHOP_Class for usage

Lingo

  • Ready – the state after Initialize has occurred. ready is a channel you can output via the Outputs page. Note: The user can wait until initialization is complete without stalling the timeline by returning an integer greater than 0 in the callback onInitialize(). The return value is the number of frames to wait before onInitialize() gets called again. It goes to the Ready state when onInitialize() returns 0.
  • Running - This is on (1) after the timer has been started, and is not yet done.
  • Timer Active - This is on (1) while the timer is counting its time-length.
  • Done – This is on (1) when the timer has finished counting.

Parameters - Segments Page

You can specify multiple timers in one Timer CHOP. A "segment" acts as one timer, with its own length, delay time, number of cycles to repeat and other conditions.

Segments DAT - a table DAT that contains one row per timer (segment). The column headings can be delay or begin, length, cycle, cyclelimit, maxcycles and cycleendalert, which override the equivalent parameters. (These are the internal names for the corresponding parameters.) begin is unique as it replaces delay, and it represents the time from Start that the timer will begin counting, whether the CHOP is set to Serial Timers or Parallel Timers (see Segment Method).

The Segments DAT also can include any number of custom columns. See Columns to Custom Channels and Columns to Info DAT below.

Segment Method - (menu) If the Segment Method is Serial Timers, the timers will be played back-to-back. If the Segment Method is Parallel Timers, the timers can be played at the same time, and a set of channels will be output for each timer.

Segment Units - (menu) For the columns delay, begin, length and cycleendalert, you specify whether it’s seconds, frames or samples with this menu.

Columns to Custom Channels - Optional extra columns (any name) in the segments DAT can be output as extra channels (the columns must contain numbers). Specify their names in the Columns to Channels parameter. The channel name will be the column name. You can also output the length, delay, etc columns as channels.

Custom Channel Interpolation - By default, custom channels step to their new value at the begin of the segment. This menu lets you interpolate to the new value linearly, or any combination of ease-in and ease-out.

Columns to Info DAT - Optional extra columns (any name) in the segments DAT can be output to the Info DAT (attach an Info DAT to the Timer CHOP) if you specify their names in this parameter.

Info DAT Output During Delay - During the Delay periods and the Initialize/Ready states, the custom rows in the Info DAT will be blank by default. This option will put the custom strings in the Info DAT all the time, incuding when the CHOP is Initialized.

Previous Segment - (pulse) Jump to Previous Segment.

Next Segment - (pulse) Jump to Next Segment.

Lingo

  • Segment – each segment acts as one timer, with delay time, length, number of cycles to repeat and other conditions.
  • Begin – in Parallel Timers, the number of seconds after a Start (frames or samples) after which each timer starts counting up from zero.
  • Done – The state it goes into when all the timers has finished counting, whether they are in Parallel or Serial, Segments or not.
  • End – Cycle End is the end of each cycle, Segment End is the end of the segment.
  • Cumulative Time – Zero at Start, a count that is affected by speed and rises while timers are active (not during delays).
  • Running Time – Zero at Start, the wall-clock time since Start was called no matter what are the delays, speeds, cycles or premature clicking of Go To Segment End. It stops counting when Done has been reached.

Parameters - Output Page

Timer Fraction - Outputs outputs channel timer_fraction for each segment.

Timer Count - Outputs the elapsed Seconds channel as timer_seconds, Frames outputs channel as timer_frames, or Samples outputs channel as timer_samples. Because this is elapsed time, timer_frames starts at 0, as do the others.

Timer Active - Outputs channel timer_active which is on only while the timer fraction is counting (is non-zero).

Timer Pulse - Outputs outputs channel timer_pulse when the timer reaches its length.

Delay Fraction - Outputs a 0-1 fraction in delay_fraction while the delay occurs.

Delay Count - Outputs the delay count in seconds, frames or samples.

Initializing - Outputs channel initializing while the timer is initalizing (while the callback onInitialize() returns non-zero).

Ready - Outputs channel ready which is 1 after an Initialize and before a Start.

Ready Pulse - Outputs a pulse when initialization has finished and the timer is ready to start. It pulses even when the timer starts rights away after an initialization.

Running - Outputs outputs channel running which is 1 after a Start and before the Done.

Done - Outputs channel done when done or complete.

Done Pulse - Outputs outputs channel done when the all timers have reached their completion.

Cycles - Outputs channel cycles, starting with 0 for entire first cycle.

Cycle Pulse - Outputs a pulse at the end of every cycle, even on the first and only cycle.

Cycles + Fraction - Outputs channel cycle_plus_fraction, starting with 0 for entire first cycle.

Segment - Outputs outputs channel segment, starting with 0 for first segment.

Segment Pulse - Outputs channel segment_pulse which is a pulse at the end of each segment.

Segment + Fraction - Outputs channel segment_plus_fraction, starting with 0 for first segment ending at #segments at end.

Cumulative Timer Count - Outputs cumulative_seconds, cumulative_frames or cumulative_samples. It is a time count that adds up all the Timer Active times for all segments since Start: it is affected by "Speed", and counts up only while timer_active is on.

Running Time Count - Outputs the "wall-clock" time since Start occurred, no matter what are the delays, speeds, cycles or pre-mature clicking of Go To Segment End, etc. It stops counting when Done has been reached. running_seconds, running_frames, or running_samples. When CHOP is set to Parallel Timers, this will output a channel per segment plus one global running time channel.

Parameters - Channel Page

Sample Rate - The sample rate that the CHOP outputs at, which is also used when the units of Length, Delay and Cycle End Alert time are set to Samples. The default sample rate is 60 samples per second.

Inputs

Input 1 - sending a 0-to-1 step is the equivalent of clicking the Initialize parameter.

Input 2 - sending a 0-to-1 step is the equivalent of clicking the Start parameter.