SimpleSceneChanger Base

Quick start #

1. Add scenes: wire scene COMPs into the input connectors, or reference COMPs or TOPs in the Inputs sequence at the bottom of the Custom page.
2. Pick a Switch Mode and set Select (or Select Menu) to the scene you want.
3. On the Cooking page turn on Control Cook so idle scenes stop cooking, and Unload so their memory is released. Add Pre-Roll or Outro if a scene needs time before or after its switch.

The output is the changer's out1 TOP, at the resolution set by Res. The same manual is inside the component: About page, Open Documentation.

Adding scenes #

Each scene has an index, counting from 0. Use either way, or both:

• Wired connectors. Connect a scene COMP to an input connector. TouchDesigner only offers a COMP-level TOP connector when the COMP contains an Out TOP, so wired scenes need one. The COMP on the other end of the wire is the scene.
• Inputs sequence. Each block's TOP parameter takes a COMP or a TOP. A TOP is used as it is. A COMP resolves to the Out TOP behind its first TOP output, otherwise a TOP inside it whose display flag is on, otherwise its right-most TOP. A referenced COMP is the scene for cook control whichever TOP is shown. A block reference takes precedence over a wire on the same index.

Add sequence blocks for more scenes. A bare TOP that is not inside a scene COMP is shown but never uncooked or unloaded.

A scene's name is its COMP's name, or the TOP's name for a bare TOP scene. Select Menu, the Python API and the Pro cue table all use it.

Switching scenes #

Select takes a scene index from a constant, an expression, a bind or an exported CHOP channel, and a change is seen the frame it happens, even mid-transition. Loop Type decides out-of-range values: Clamp holds at the ends, Loop wraps around, Zigzag bounces back and forth.

Switch Mode:

• Crossfade blends from the current scene to the target over Crossfade Length, with Easing.
• Fade Through Black fades the current scene out over Fade Out Time, then the target in over Fade In Time. Fade Style decides what black means: To Black drives RGB to black and keeps alpha, To Transparent fades opacity.
• Cut switches instantly.
• A/B Fader Crossfade and A/B Fader Through Black are driven by the A/B Fader, see The A/B fader.

Changing Select during a timed transition restarts it toward the new scene, snapping back to the scene that was fully visible. Choosing the visible scene again cancels it. Finish Transition completes whatever is under way right now: a running fade lands, a Pre-Roll cuts straight to the scene it was warming, a half-moved fader completes.

The A/B fader #

The two A/B Fader modes work like a DJ crossfader:

• Whichever end the Fader rests at (0 or 1) is the current scene.
• Set Select to the next scene. Nothing changes yet.
• Move the Fader toward the opposite end: the blend (or the fade through black) follows it. Arriving at the far end completes the switch, and that end becomes the new resting end. Push up to switch, pick the next scene, pull down to switch again, so a physical fader never needs resetting.
• Turning back before arriving cancels and leaves the current scene untouched. Changing Select while the Fader is mid-way re-targets without a jump.

In A/B Fader Through Black the first half of the travel fades the current scene to black and the second half fades the target up. Fade Style applies, Easing does not.

With Auto Advance on and Advance On set to A/B Fader, Select lines up the next scene after every completed switch: just push and pull the Fader to walk through the scenes.

Cooking and memory #

With Control Cook on, after every change the changer recomputes which scene COMPs may cook: the visible scene, the incoming scene while a transition runs, a scene warming up for its Pre-Roll, and scenes still inside their Outro. Everything else has cooking disabled and, with Unload on, is unloaded a few frames later. The set is recomputed from scratch every time, so an interrupted, restarted or dropped transition can never leave a scene cooking forever, and a scene selected again before its unload lands simply keeps its memory.

• Pre-Roll: on a Select change the target COMP is allowed to cook right away and the switch is delayed by this much, so feedback loops, movies or particles are warm when they appear. In the A/B Fader modes any value above 0 warms the chosen scene as soon as Select changes; the Fader still decides when it shows.
• Outro: the outgoing scene keeps cooking for this long after the switch, so an exit animation can finish off-screen.
• Unload Method: Progressive uses COMP.progressiveUnload() paced by Unload Budget and covers every node type, POP buffers included. Immediate unloads each unlocked TOP in one frame. Locked operators are never unloaded.

Auto Advance #

Auto Advance switches to the next scene on its own.

• Advance On: Timer switches every Interval (the transition included). A/B Fader has no countdown: each completed A/B Fader switch lines up the next scene in Select. A/B Fader modes only.
• Order: Sequential steps through the scenes in Direction, and Loop Type decides the ends (Clamp stops, Loop wraps, Zigzag turns round). Random shows every other scene once, in a shuffled order, before any repeats, and never switches to the scene already visible. Random Seed makes the sequence reproducible.
• Turning Auto Advance off pauses the countdown where it is. Choosing a scene by hand restarts the countdown from that scene. Next Switch In counts down.

Per-scene times and curves #

A scene COMP can carry its own custom parameters, which override the changer's for that scene:

• Fadeintime and Fadeouttime: seconds (Fadeintime also overrides Crossfade Length).
• Fadeincurve (arriving: the crossfade, or the fade-up half) and Fadeoutcurve (leaving: the fade-to-black half): an Easing curve name such as OutBounce. Unknown names are ignored.

SimpleSceneChanger Pro puts these, and more, on every Inputs block: see per-scene settings.

Python #

changer = op('SimpleSceneChanger1')

changer.Switch(2)                                   # by index
changer.Switch('intro')                             # by scene name
changer.Switch(op('scene_intro'), mode='fade',      # by operator, with per-call overrides
               fadeouttime=0.5, fadeintime=1.5, easingout='InOutSine', easingin='OutBounce')
changer.Next()                                      # and Previous(): Loop wraps, Clamp stops, Zigzag turns back
changer.FinishTransition()

Switch(target, mode=None, fadeouttime=None, fadeintime=None, easingout=None, easingin=None) requests a scene change and returns right away. target is a scene index, a scene name, or the scene COMP / TOP; a string that is no scene name is tried as an operator path. mode is 'cross', 'fade', 'cut', 'manual' or 'manualfade' (None follows Switch Mode). The times are seconds (in 'cross', fadeintime is the crossfade length) and the easings are curve names from the Easing menu. Pre-Roll and Outro apply as usual. Raises ValueError for a target, mode or easing it cannot resolve.

Next(**overrides) and Previous(**overrides) switch to the neighbouring scene (from the incoming one while a switch runs), take Switch()'s overrides and return the index switched to, or None.

FinishTransition() completes the switch under way, like the Finish Transition pulse.

SceneName(index), SceneIndex(name) and Scene(target) look scenes up: the name of an index (None for an empty slot), the first index with a name, and the scene operator for an index, name or operator.

These properties are read-only and dependable: a parameter expression that reads one, such as op('SimpleSceneChanger1').CurrentName, updates by itself when it changes.

Property	Value
CurrentIndex	The visible scene's index (the outgoing one during a switch).
CurrentName, CurrentScene	Its name and its operator.
IncomingIndex	The target of a running switch, or None.
IncomingName, IncomingScene	Its name and its operator.
IsSwitching	True while a switch runs.
SceneNames	Every scene's name by index ('' for an empty slot).

Setting the Select parameter from Python is equivalent to using the dialog.

Callbacks #

On the Callbacks page, Create Callbacks makes an editable callbacks DAT next to the changer, with every callback documented inside. Every callback is optional.

Callback	When
onPrerollStart(target, current, seconds)	A scene starts its Pre-Roll warm-up (only when Pre-Roll is above 0).
onTransitionStart(target, current, mode)	A switch has begun: after any Pre-Roll, for cuts, when the A/B Fader leaves home, and again when a running switch is redirected.
onTransitionCancel(target, current)	A pre-rolling or running switch was abandoned (Select back or elsewhere, Fader home, Active off): the target will not arrive.
onSelectionChange(selected_ops, unselected_ops)	A switch completed; the lists hold the TOPs shown. The leaving scene's Outro starts here.
onCookingChange(cooked_comps, uncooked_comps)	Control Cook enabled or disabled scene COMPs; only changes are reported.

target and current are the scene COMPs (or TOPs for bare TOP scenes). A typical pair: start a scene's animation in onPrerollStart or onTransitionStart, and undo it in onTransitionCancel.

Every callback can also take an info dict with scene names and indices. It is passed only when the function declares an info parameter (or **kwargs), so callbacks DATs written before it existed keep working:

def onTransitionStart(target, current, mode, info=None):
    if info and info['name'] == 'intro':
        info['scene'].par.Play = True

Callback	info keys
onPrerollStart	index, name, scene, currentIndex, currentName, current, seconds
onTransitionStart	index, name, scene, currentIndex, currentName, current, mode
onTransitionCancel	index, name, scene, currentIndex, currentName, current
onSelectionChange	index, name, scene, previousIndex, previousName, previous
onCookingChange	cookedNames, uncookedNames

Troubleshooting #

• Nothing switches when I change Select Menu: Select is driven by an expression or export. Select Menu only works while Select is a constant or bind; drive Select directly instead.
• A scene never stops cooking: it is a bare TOP (not a COMP), or Control Cook is off, or Active is off. Bare TOPs are shown but never controlled.
• A scene keeps cooking for a while after switching: that is Outro. Set it to 0 for an immediate stop.
• Fade times or curves feel wrong for one scene: check that scene COMP for Fadeintime, Fadeouttime, Fadeincurve or Fadeoutcurve custom parameters, which override the changer's.
• Use Loop Type = Zigzag with a counter or LFO to ping-pong through the scenes.
• Unload never touches locked operators, so a frozen (locked) TOP inside a scene survives.