TouchDesigner Tutorial: Scripting Events with Callbacks

This tutorial covers how to use Python callbacks for event-driven programming in TouchDesigner, allowing you to execute code based on specific events from operators.

What Are Callbacks?

Callbacks are Python functions that run automatically based on events from a docked operator. When you add certain operators like a Timer CHOP to your network, you’ll notice a small purple square at the bottom right corner. Clicking on this reveals a docked DAT containing callback functions.

These callbacks include functions like:

• onInitialize - Runs when the timer is initialized
• onReady - Runs when the timer is ready to start
• onStart - Runs when the timer starts
• onCycle - Runs each time the timer completes a cycle

Whatever code you place inside these functions will execute when the corresponding event occurs.

Setting Up the Example

Creating the Network

1. Add a Timer CHOP - Use the Tab key to open the OP Create dialog and add a Timer CHOP
2. Add a Text TOP - Navigate to TOPs and add a Text TOP
3. Add a Noise TOP - Connect the Text TOP to a Noise TOP
4. Configure the Noise TOP - Turn off monochrome and set the period to 10 for broad color swaths

Editing Callbacks in a Text Port

To edit callbacks more conveniently without zooming into your network:

1. Split your view and change one pane to a Text Port
2. Drag the callback DAT (the docked operator) to the Text Port
3. Drop it where it says “textport” and select “Open the DAT”

Now you can edit all callbacks without making the operator viewer active.

Configuring the Timer

1. Turn on Cycle mode
2. Turn off Cycle Limit
3. Set the Length to about 2 seconds
4. Initialize and start the timer to verify it restarts every 2 seconds

Writing Callback Code

The onCycle Callback

Every time the timer completes a cycle, we can update operators in our network:

def onCycle(timerOp, cycle, interrupt):
    # Update the text display
    op('text1').par.text = 'The current cycle is ' + str(cycle)

    # Change the noise seed
    op('noise1').par.seed = cycle

Key points:

• Use op('operatorName') to reference operators in your network
• Access parameters with .par.parameterName
• The cycle variable is an integer, so use str() to convert it for string concatenation

The onReady Callback

Set up the initial state when the timer is ready:

def onReady(timerOp):
    op('text1').par.text = 'Ready'

The onStart Callback

Execute code when the timer starts:

def onStart(timerOp):
    op('text1').par.text = 'Start'

The onInitialize Callback

Reset everything to a clean state when initializing:

def onInitialize(timerOp):
    op('text1').par.text = 'Ready'
    op('noise1').par.seed = 0

This ensures consistent state every time you initialize the timer.

Why Use Callbacks Instead of Channel Outputs?

While you could use the Timer CHOP’s channel outputs directly, callbacks offer advantages:

• Event-driven logic - Code runs exactly when events occur, not continuously
• Cleaner state management - Set up initialization and reset conditions clearly
• Better organization - Separate code for different events (start, cycle, etc.)
• Consistent state - Ensure your project starts in a known state every time

Summary

Callbacks provide a powerful way to implement event-driven programming in TouchDesigner:

Callback	When It Runs
onInitialize	When the timer is initialized
onReady	When the timer is ready to start
onStart	When the timer begins running
onCycle	Each time the timer completes a cycle

This approach helps you think about setting up conditions for startup and cycling, ensuring your project’s state is consistent every time you run an operation. This is just the tip of the iceberg for what you can accomplish with callbacks in TouchDesigner.

def onCycle(timerOp, cycle, interrupt):
    # 更新文本显示
    op('text1').par.text = 'The current cycle is ' + str(cycle)

    # 更改噪声种子
    op('noise1').par.seed = cycle

def onReady(timerOp):
    op('text1').par.text = 'Ready'

def onStart(timerOp):
    op('text1').par.text = 'Start'

def onInitialize(timerOp):
    op('text1').par.text = 'Ready'
    op('noise1').par.seed = 0