Skip to content

Time and State ​

A node's time field tells Caddis what its output depends on, so it can cache, scrub and replay correctly.

timeOutput depends on
static (default)inputs and params only. Rendered once, then cached until something changes.
animatedalso the frame (iTime / iFrame).
historyinputs at other frames.
statefulits own previous output (feedback).

A node with a trigger param is treated as animated at least.

Reading other frames ​

json
"time": "history",
"maxLookback": 2,
"passes": [{ "shader": "echo.wgsl",
  "reads": ["src", { "input": "src", "frame": -1, "as": "prev1" }, { "input": "src", "frame": -2, "as": "prev2" }],
  "writes": "out" }]

Caddis re-renders just the input's upstream graph at those frames. maxLookback caps how far back reads go (at most 64), which keeps the cost predictable.

State: feedback that survives scrubbing ​

A stateful node declares state textures. Each frame, its passes read last frame's state and write the new one. Within one frame, a pass that reads @state.x after an earlier pass wrote it sees this frame's value: until a pass writes it, @state.x is last frame's; from then on it is the new one. A pass that both reads and writes it reads the value from before its own write. What the next frame starts from is the last value written this frame (or, if nothing wrote it, the one before):

json
"time": "stateful",
"state": { "trail": { "size": { "of": "src" } } },
"passes": [
  { "shader": "decay.wgsl", "reads": ["@state.trail", "src"], "writes": "@state.trail" },
  { "shader": "show.wgsl", "reads": ["@state.trail"], "writes": "out" }
]

On the layer's first frame the state is transparent. Nothing is ever "whatever the last rendered frame was": the state at frame N is defined as the result of running your passes from the layer's first frame to N. Caddis makes that cheap:

  • sequential playback steps once per frame;
  • jumping to a frame replays from the nearest snapshot, taken every 16 frames;
  • changing anything upstream, any param or the plugin itself discards the snapshots.

So any frame renders the same whether you played to it, scrubbed to it or exported it. Reset Simulation clears the snapshots.

Triggers ​

A trigger param is a row of keyframes. In shaders it reads as the number of frames since the latest key, or −1 before the first. params.reset == 0.0 means "a key is on this frame":

json
{ "id": "clean", "type": "trigger", "label": "Clean Frame" }
wgsl
if (params.clean == 0.0 || builtins.iLayerFrame < 0.5) {
  return textureSample(src, samp, uv);   // restart from the footage
}

Users drop keys with the Fire Here button in Properties.

Restart points ​

Add "restarts": true to a trigger on a stateful node to make each of its keys restart the simulation: on a key's frame the state starts fresh (transparent textures, zeroed state buffers, no logic state), exactly as on the layer's first frame, and Caddis replays from the latest key instead of the layer start. Jumping to a frame long after the layer starts then only replays back to the last key, and so does every change you make:

json
{ "id": "clean", "type": "trigger", "label": "Clean Frame", "restarts": true }

Your shader can still read the trigger (to show the source on a clean frame, say); Caddis does the state restart either way. Use it for anything shaped like "emit a burst", "clear" or "start over".

Use a trigger for "from now on", not a toggle ​

Because frame N is defined by replaying from the start, a param's value at each frame is what the replay sees, never "what it was when I clicked". A bool that is on means on for every frame it covers. A "Freeze" checkbox that latches the current image therefore latches the layer's first frame (the replay turns it on there). For anything that should happen at a moment, a freeze, a burst, a clear, use a trigger and test params.freeze == 0.0 on the frame its key sits on, or params.freeze >= 0.0 for "since the latest key".

Motion: reading Optical Flow ​

Caddis's Optical Flow node measures motion for you. Wire its Flow output into one of your image inputs and read it like any image: R and G are the horizontal and vertical motion in fractions of the image per frame. It works in a stateful node's replay too: every replayed frame gets that frame's real motion, so a scrubbed render matches playback. Inside a replay the flow is unsmoothed; ask your users to set the node's Temporal Smoothing to 0 if the Viewer must match exactly.

Example: datamosh ​

examples/datamosh in the Plugin Kit is a complete stateful node:

  1. a block-matching pass estimates motion between src and src one frame back;
  2. a warp pass drags last frame's result (@state.mosh) along that motion, adds a share of the frame's real change, and restarts on a Clean Frame key;
  3. a final pass shows the state.

It scrubs and exports exactly like playback.

Motion blur ​

Motion-blur samples between frames see the state of the frame they fall in. History reads at fractional frames are evaluated at that exact time.