Skip to content
RESONON

std/visuals

Import: use "std/visuals";

GPU visual operators — generators, filters, and the raw-shader Visual. Wire nodes with >> (primary input; route to screen to display) and bind parameters or texture inputs with node.parameter("name") << signal. screen is the global output sink, like master.

Generators (Noise, Ramp) have no primary input; filters take one via src >> op; 2-in filters (Composite, Displace, Lookup) take a second via a named slot, op.parameter("slot") << node. Every pass clamps its output to [0, 1]. Vector parameters (key, color0…, translate, scale, pivot) bind from a 2–4-element array, e.g. t.parameter("scale") << #[1.5, 1.5].

Screen

Section titled “Screen”

The display output sink. screen is a global (like master): route a visual with v >> screen, then adjust presentation via its methods.

set_quality

Section titled “set_quality”
fn set_quality(n: Number) -> Screen

Sets the supersampling (SSAA) quality — the internal render resolution as a multiple of the presented window. Higher is smoother but costs ~n² GPU work; clamped to the renderer’s supported range. Takes effect live — including on a playing sequenced screen lane, whose spans are rescaled where they are (the cuts stay put and nothing recompiles).

Parameters:

  • n (Number) — render-scale multiple (≥ 1)

Returns: Screen — the sink, for chaining

show_window

Section titled “show_window”
fn show_window() -> Screen

Opens the native live-rendering window for the routed visual, rendered on the GPU in-process from the routed graph and transport (audio meter feeds read as zero for now). A no-op if the window is already open.

Returns: Screen — the sink, for chaining

snap

Section titled “snap”
fn snap(path: String) -> Screen

Renders the routed visual off-screen on the GPU and writes it to a PNG at the given path. An absolute path is taken as typed; a relative one lands under the project the piece belongs to, not beside whichever shell started resonon, and any directory it names is created. Works headless, so it also runs in an offline render of a file in a project. Rendered at the export resolution (independent of the live window) with the SSAA set by set_quality.

Parameters:

  • path (String) — output PNG path

Returns: Screen — the sink, for chaining

Visual

Section titled “Visual”

A node in the GPU visual graph: a built-in operator (Noise, Blur, Displace, …) or a compiled shader (Visual(name, source)). Bind uniforms and wire input slots with v.parameter("name") << …, and route to the display with v >> screen.

Built-in uniforms are always supplied without binding (declare and use them):

  • iTime — playhead position in seconds, not wall time: holds on a pause, follows a seek, rewinds to 0 on a stop
  • iResolution — canvas size in pixels (vec2)
  • iBeat — playhead position in beats
  • iCycle — playhead position in cycles

These names are reserved and cannot be bound.

Custom shaders compiled with Visual(name, source) expose their own uniforms; any name is accepted. Live audio meter feeds are bindable: v.parameter("kick") << drums.rms, v.parameter("level") << master.peak (each track and the master expose .rms / .peak).

Constructor

Section titled “Constructor”
fn Visual(name: String, source: String) -> Visual

Compiles a fragment-shader source string into a Visual. Share GLSL between shaders by composing source strings in resonon, e.g. Visual("plasma", load_file("shaders/lib.glsl") + frag). Re-running the line with an edited source hot-swaps the operator, keeping its wiring and bindings.

Example:

let v = Visual("plasma", frag);

Parameters:

  • name (String) — the operator’s name; its identity on screen
  • source (String) — GLSL-ES fragment shader source (non-empty)

Returns: Visual — a compiled visual, bindable with << and routable with >>

parameter

Section titled “parameter”
fn parameter(name: String) -> VisualParam

Binds a uniform to a signal or value (v.parameter("period") << sig), or wires a texture input slot with a node (c.parameter("b") << node on Composite, d.parameter("by") << field on Displace, l.parameter("gradient") << ramp on Lookup). Each built-in operator lists its uniforms and slots on its constructor; a Visual(name, source) shader accepts any uniform it declares.

Parameters:

  • name (String) — a uniform or texture-slot name

Returns: VisualParam — a parameter reference, bound with <<

reset

Section titled “reset”
fn reset() -> Visual

Clears the operator’s render state on the next frame — TouchDesigner’s Reset pulse. On the node a feedback closure returns, the trail starts over from black and keeps building from there. Nothing else in the graph changes and nothing recompiles; on an operator that feeds nothing back it has no visible effect.

Example:

look.reset();

Returns: Visual — the operator, for chaining

VisualParam

Section titled “VisualParam”

A reference to a visual operator’s parameter, produced by node.parameter("name") and consumed by << (v.parameter("period") << sig). Not used on its own.

Blur

Section titled “Blur”
fn Blur(name: String) -> Visual

A blur visual: a TouchDesigner-style Blur TOP that softens its primary input (set via src >> Blur("…")) with a 5×5 box kernel whose spacing scales with radius, so it blurs at large radii too.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • radius — blur radius in pixels

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Composite

Section titled “Composite”
fn Composite(name: String) -> Visual

A composite visual: a TouchDesigner-style Composite TOP that blends its primary input A (set via src >> Composite("…")) with a second input B (set via c.parameter("b") << node, where node may be a forward node or prev inside feedback(...)). Bind operand to pick the blend (rounded to nearest): 0 over, 1 add, 2 subtract, 3 multiply, 4 difference, 5 subtractive, 6 max/lighten, 7 min/darken, 8 screen. Results are clamped to [0,1].

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • operand — blend-mode selector (see list above)

Inputs:

  • b — second input B, blended with the primary input A

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Displace

Section titled “Displace”
fn Displace(name: String) -> Visual

A displace visual: offsets each pixel lookup of its primary input (set via src >> Displace("…")) by a displacement field fed into the by slot (d.parameter("by") << field or d.parameter("by") << prev inside feedback(...)).

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • amount — displacement strength

Inputs:

  • by — displacement field

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Edge

Section titled “Edge”
fn Edge(name: String) -> Visual

An edge visual: a spatial filter that Sobel-detects the boundaries of its primary input (set via src >> Edge("…")), turning a soft noise/voronoi field into bright cell-contour lines.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • strength — edge gain

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Lookup

Section titled “Lookup”
fn Lookup(name: String) -> Visual

A lookup visual: a TouchDesigner-style Lookup TOP that colourises its primary input (set via src >> Lookup("…"), used as the index) by sampling a gradient fed into the gradient slot (l.parameter("gradient") << ramp) at the index’s luminance.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Inputs:

  • gradient — colour gradient to sample, e.g. a Ramp("…")

Returns: Visual — a filter node, routable with >> and bindable with .parameter

LumaLevel

Section titled “LumaLevel”
fn LumaLevel(name: String) -> Visual

A luma-level visual: a TouchDesigner-style Luma Level TOP over its primary input (set via src >> LumaLevel("…")). Brightness / black-level / gamma / invert controls, e.g. to lift a crushed image into a colour Lookup’s range.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • brightness — output gain
  • black — black-level offset
  • gamma — gamma exponent
  • invert — 0..1 invert mix

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Noise

Section titled “Noise”
fn Noise(name: String) -> Visual

A noise generator visual: an animated TouchDesigner-style fractal value-noise field, the green-TOP-style source of an operator chain. Bind its TD noise TOP parameters with .parameter("name") << ….

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • period — feature size; larger is bigger cells
  • harmonics — fbm octave count
  • gain — per-octave amplitude falloff
  • exponent — contrast shaping, pow
  • offset — brightness floor

Returns: Visual — a generator node, routable with >> and bindable with .parameter

Ramp

Section titled “Ramp”
fn Ramp(name: String) -> Visual

A ramp generator visual: a TouchDesigner-style Ramp TOP drawing a 4-key colour gradient (no input). The keys color0..color3 sit at 0, pos1, pos2, 1; type picks orientation (0 horizontal, 1 vertical, 2 radial). The defaults make a black→blue→light-blue→white palette for Lookup.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • type — orientation selector (0 horizontal, 1 vertical, 2 radial)
  • color0 — gradient key at position 0, a vec3
  • color1 — gradient key at pos1, a vec3
  • color2 — gradient key at pos2, a vec3
  • color3 — gradient key at position 1, a vec3
  • pos1 — second key position
  • pos2 — third key position

Returns: Visual — a generator node, routable with >> and bindable with .parameter

RgbKey

Section titled “RgbKey”
fn RgbKey(name: String) -> Visual

An RGB-key visual: a TouchDesigner-style RGB Key TOP that blacks out pixels of its primary input (set via src >> RgbKey("…")) within threshold of the key colour, passing the rest through. With the defaults (black key, threshold 0) it is a pass-through.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • key — colour to key out, a vec3
  • threshold — key range/softness

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Slope

Section titled “Slope”
fn Slope(name: String) -> Visual

A slope visual: a TouchDesigner-style Slope TOP that turns the luminance gradient of its primary input (set via src >> Slope("…")) into a signed RG displacement field, re-centred around offset for a downstream Displace.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • strength — gradient gain
  • offset — re-centre point

Returns: Visual — a filter node, routable with >> and bindable with .parameter

Transform

Section titled “Transform”
fn Transform(name: String) -> Visual

A transform visual: a TouchDesigner-style Transform TOP that translates, rotates and scales its primary input (set via src >> Transform("…")) about a pivot. Positive scale zooms in, positive rotate spins counter-clockwise; rotation is aspect-corrected so a wide canvas spins without shearing. extend picks how pixels outside the source are filled (rounded to nearest): 0 hold/clamp, 1 repeat, 2 mirror, 3 black. With the defaults it is a pass-through.

Parameters:

  • name (String) — the operator’s name; its identity on screen

Uniforms:

  • translate — uv-fraction offset (+x right, +y up), a vec2
  • rotate — rotation in degrees (positive is counter-clockwise)
  • scale — per-axis zoom, a vec2
  • pivot — centre of rotate/scale, a vec2
  • extend — outside-source fill mode (see list above)

Returns: Visual — a filter node, routable with >> and bindable with .parameter

feedback

Section titled “feedback”
fn feedback(build: Function) -> Visual

Builds a feedback group: the closure is called with prev — the group’s previous-frame output as a sampleable visual — and returns the group output. Wire prev into a slot (e.g. d.parameter("by") << prev) to close the loop; the renderer realizes it as a ping-pong buffer. Route the result with >> screen.

Example:

feedback(fn(prev) { let d = Displace("warp"); d.parameter("by") << prev; return Noise("field") >> d; })

Parameters:

  • build (Function) — fn(prev) { ... }, returning the group’s output Visual

Returns: Visual — the group output, routable with >> and reusable for fan-out

load_shader

Section titled “load_shader”
fn load_shader(name: String, path: String) -> Visual

Loads a fragment shader from an external .glsl file and compiles it. The path is resolved relative to the .non file being run, so existing shader tooling (highlighting, linting) can edit the .glsl directly. The file is read when this call runs, so re-run the line that loads it to pick up an edit: the operator hot-swaps, keeping its wiring and bindings. A compile error is reported in that .glsl, on the line you wrote it on.

Example:

let v = load_shader("plasma", "shaders/plasma.glsl");

Parameters:

  • name (String) — the operator’s name; its identity on screen
  • path (String) — shader file path, relative to the current .non file

Returns: Visual — a compiled visual, bindable with << and routable with >>