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 (translate, scale, pivot) bind from a 2–4-element array, e.g. t.parameter("scale") << #[1.5, 1.5], and a table parameter (Ramp’s keys) from an array of rows.

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

fn set_quality(n: Number) -> Screen

Sets the supersampling (SSAA) quality — the internal render resolution as a multiple of the composition size (default 1, one sample per pixel). 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

resolution

fn resolution(w: Number, h: Number) -> Screen

Sets the composition size in pixels (default 1920 × 1080). Every operator renders at this size, multiplied by set_quality for SSAA. The live window preserves its aspect ratio with black bars; snap and render(screen) use the composition size. Changing size reallocates targets and clears feedback trails, without recompiling shaders or moving sequenced cuts.

Parameters:

w (Number) — positive integer width, within the GPU texture limit including SSAA
h (Number) — positive integer height, within the GPU texture limit including SSAA

Returns: Screen — the sink, for chaining

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

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 composition 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

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.

Every input an operator reads must be wired: its primary input (>>) and each of its slots. As in TouchDesigner, an operator missing an input is not drawn: a graph that holds one is an error, and the picture on screen stays.

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 — size in pixels the shader draws at (vec2): the composition size times iRenderScale
iRenderScale — pixels drawn per composition pixel: the screen.set_quality value, rounded up to a whole number. Multiply a size in pixels by it to keep it the same size at every quality
iBeat — playhead position in beats
iCycle — playhead position in cycles
iStage — which of its passes a built-in operator draws (Blur draws three); always 0 in your own shader

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

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

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("table") << 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

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 the feedback’s seed 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

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.

BlurExtend

What a Blur sees beyond the image edges: TD’s Blur Extend menu.

BlurExtend.hold — The edge pixels.
BlurExtend.repeat — The image again.
BlurExtend.mirror — The image mirrored.

BlurMethod

The axes a Blur blurs along: TD’s Blur Method menu.

BlurMethod.horizontal_and_vertical — Both axes.
BlurMethod.horizontal — Across only.
BlurMethod.vertical — Up only.

BlurType

The kernel shape of a Blur: TD’s Blur Type menu.

BlurType.catmull_rom — Sharp.
BlurType.gaussian — Soft.
BlurType.box — Flat.
BlurType.bartlett — A triangle.
BlurType.sinc — Sharpens; as in TD it gains brightness and never goes negative.
BlurType.hanning — A Hanning window.
BlurType.blackman — A Blackman window.

Extend

What is read beyond the image edges: TD’s Extend menu.

Extend.hold — The edge pixels.
Extend.zero — Black.
Extend.repeat — The image again.
Extend.mirror — The image mirrored.

LookupChannel

How a Lookup index colour picks from the table: TD’s Lookup Index Channel menu. Every choice but rgba_independent gives each channel the same point.

LookupChannel.luminance — 0.3 R + 0.6 G + 0.1 B.
LookupChannel.red — Red.
LookupChannel.green — Green.
LookupChannel.blue — Blue.
LookupChannel.alpha — Alpha.
LookupChannel.rgb_average — The average of red, green and blue.
LookupChannel.rgba_average — The average of red, green, blue and alpha.
LookupChannel.rgb_maximum — The largest of red, green and blue.
LookupChannel.rgba_maximum — The largest of red, green, blue and alpha.
LookupChannel.rgba_independent — Red picks the table’s red, green its green and blue its blue.

Operand

How a Composite combines its inputs A and B: TD’s Composite Operation menu. As in TD, no result is clamped: subtract can go below 0 and add above 1.

Operand.add — A + B.
Operand.difference — |A − B|.
Operand.maximum — The larger of A and B.
Operand.minimum — The smaller of A and B.
Operand.multiply — A × B.
Operand.over — A over B; A is opaque, so A.
Operand.screen — 1 − (1 − A)(1 − B).
Operand.subtract — A − B.
Operand.subtractive — A − B, with B first clamped to 0..1.

RampExtend

What a Ramp draws below 0: TD’s Ramp Extend Left menu.

RampExtend.hold — The first colour.
RampExtend.black — Black.
RampExtend.zero — Zero.
RampExtend.repeat — The ramp again.
RampExtend.mirror — The ramp mirrored.

RampExtendRight

What a Ramp draws above 1: TD’s Ramp Extend Right menu.

RampExtendRight.same_as_left — What extend_left draws below 0.
RampExtendRight.hold — The last colour.
RampExtendRight.black — Black.
RampExtendRight.zero — Zero.
RampExtendRight.repeat — The ramp again.
RampExtendRight.mirror — The ramp mirrored.

RampFit

How a radial or circular Ramp fits a non-square image: TD’s Ramp Fit Aspect menu.

RampFit.fill — Stretched to each side.
RampFit.fit_horizontal — To the width.
RampFit.fit_vertical — To the height.
RampFit.fit_best — To the shorter side.

RampInterp

The curve between the keys of a Ramp: TD’s Ramp Interpolate Notches menu.

RampInterp.step — Each key holds until the next.
RampInterp.linear — A straight line.
RampInterp.ease_in_ease_out — Eases out of each key and into the next.
RampInterp.hermite — A smooth curve through the keys; tension 1 flattens it at each key, below 0 it overshoots more.

RampType

The shape of a Ramp: TD’s Ramp Type menu.

RampType.vertical — Bottom to top.
RampType.horizontal — Left to right.
RampType.radial — Around the centre, counterclockwise from the right.
RampType.circular — Out from the centre, reaching 1 half a width out.

RgbOutput

The colour an RgbKey draws: TD’s RGB Key RGB Output menu.

RgbOutput.multiply_alpha — The image times the key, which takes what is out of the key to black.
RgbOutput.new_alpha — The key itself, as a grey image.

Unit

The unit of a distance on an image: TouchDesigner’s Pixels, Fraction and Fraction Aspect.

Unit.pixels — Composition pixels.
Unit.fraction — Fractions of the width (across) and of the height (up).
Unit.fraction_aspect — Fractions of the width, both across and up.

Blur

fn Blur(name: String) -> Visual

A blur visual: TouchDesigner’s Blur TOP. It blurs its primary input (set via src >> Blur("…")), all four channels, with a kernel size pixels wide: one pass along each axis. As in TD, size is a whole number of taps; a fraction fades between the two sizes around it, so a modulated size moves smoothly. Sizes are in composition pixels, so a blur looks the same at every screen.set_quality.

preshrink blurs a smaller image, so a wide blur costs less: 2 halves the width and height with a 2×2 box, then the kernel runs over the small image, which makes it preshrink times wider. The size is limited to 4096 render pixels per pass; use preshrink for wider blurs. TD’s Dither is left out: it only matters for 8-bit images, and visuals are 16-bit float.

Parameters:

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

Uniforms:

method — the axes to blur, a BlurMethod (default horizontal_and_vertical)
type — the kernel shape, a BlurType (default catmull_rom)
extend — the edge condition, a BlurExtend (default hold)
preshrink — how many times smaller the blurred image is (default 1, none)
size — the kernel width in pixels (default 7)
sample_step — the distance between taps, in sample_step_units (default 1)
sample_step_unit — the unit of sample_step, a Unit (default pixels)
rotate — the kernel’s rotation in degrees, counterclockwise (default 0)

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

Composite

fn Composite(name: String) -> Visual

A composite visual: TouchDesigner’s Composite TOP. It combines its primary input A (TD’s input 1, set via src >> Composite("…")) with a second input B (TD’s input 2, set via c.parameter("b") << node, where node may be a forward node or prev inside feedback(...)) by the operand operation, e.g. c.parameter("operand") << Operand.subtract.

Parameters:

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

Uniforms:

operand — the operation, an Operand (default multiply)

Inputs:

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

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

Displace

fn Displace(name: String) -> Visual

A displace visual: TouchDesigner’s Displace TOP. Each pixel of its primary input (set via src >> Displace("…")) is read from another place, set by a displacement field fed into the by slot (d.parameter("by") << field, or d.parameter("by") << prev inside feedback(...)). As in TD, the field’s red moves the lookup across and its blue moves it up, so a Slope feeds it directly. Each pixel at uv reads the input at uv × uv_weight + offset × offset_weight + 2 × displace_weight × (field − midpoint), per axis, in fractions of the width and height: a field of 0.75 at weight 0.1 moves the lookup a twentieth of the image. extend sets what is read beyond the edges. Fixed at TD’s defaults: Horizontal Source red, Vertical Source blue. The alpha is 1.

Parameters:

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

Uniforms:

displace_weight_x — how far the field moves the lookup across (default 1)
displace_weight_y — how far the field moves the lookup up (default 1)
midpoint_x — the red value that does not move the lookup (default 0.5)
midpoint_y — the blue value that does not move the lookup (default 0.5)
uv_weight — weight of the pixel’s own position; at 0 every pixel starts from the offset (default 1)
offset_x — start of the lookup across, before offset_weight (default 0.5)
offset_y — start of the lookup up, before offset_weight (default 0.5)
offset_weight — weight of the offset (default 0)
extend — the edge condition, an Extend (default hold)

Inputs:

by — displacement field

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

Edge

fn Edge(name: String) -> Visual

An edge visual: TouchDesigner’s Edge TOP. It finds the edges in the luminance of its primary input (set via src >> Edge("…")), with a 3×3 Sobel whose taps are sample_step pixels apart, and draws them in white on black: the soft cells of a noise field become bright contour lines. As in TD, the edge is sqrt(strength × (1 − black_level) × gradient² / sample_step) − black_level, clamped to 0..1. Fixed at TD’s defaults: Select luminance (0.3 R + 0.6 G + 0.1 B), white edges, no comp over the input. The alpha is 1, not the edge. The step is in composition pixels, so the edges are the same at every quality.

Parameters:

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

Uniforms:

strength — edge gain; the edge grows with its square root (default 1)
black_level — taken off the edge, so weak edges go to black (default 0)
sample_step — distance from each pixel to its taps, in pixels (default 1)

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

Lookup

fn Lookup(name: String) -> Visual

A lookup visual: TouchDesigner’s Lookup TOP. It replaces the colours of its primary input (set via src >> Lookup("…"), the index) with colours from a lookup table: a line across the image in the table slot (l.parameter("table") << ramp), from dark_u, dark_v to light_u, light_v. By default the line runs across the middle of the table, so a Ramp("…") makes a palette: an index of 0 takes the colour at its left, 1 the colour at its right. As in TD, the index range maps index_start to the dark end and index_end to the light end and holds beyond them; reversed, it reverses the table. The table is the line read at as many points as the table image is pixels wide or high, whichever is more, and the lookup blends between neighbouring points. With output_lookup at 1 it draws the table itself, left to right. Checked against TD’s float exports: within one 8-bit filter step on every probe. The table image is the size of the screen, where TD’s has its own size. TD’s CHOP method is left out: visuals take no CHOPs. The alpha is 1, where TD’s is the table’s.

Parameters:

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

Uniforms:

index_channel — how the index picks from the table a LookupChannel (default rgba_independent)
index_start — the index at the dark end of the table (default 0)
index_end — the index at the light end of the table (default 1)
dark_u — the dark end across, in dark_units (default 0)
dark_v — the dark end up, in dark_units (default 0.5)
dark_unit — the unit of dark_u and dark_v, a Unit (default fraction)
light_u — the light end across, in light_units (default 1)
light_v — the light end up, in light_units (default 0.5)
light_unit — the unit of light_u and light_v, a Unit (default fraction)
output_lookup — 1 draws the table, 0 looks the image up in it (default 0)

Inputs:

table — the image to take the lookup table from, e.g. a Ramp("…")

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

LumaLevel

fn LumaLevel(name: String) -> Visual

A luma-level visual: TouchDesigner’s Luma Level TOP. It sets the levels of the luminance of its primary input (set via src >> LumaLevel("…")) and scales each pixel’s colour with it, so hue and saturation hold. As in TD, the luminance (0.3 R + 0.6 G + 0.1 B), clamped to 0..1, goes through invert, then black_level, then brightness (clamped to 1), then gamma, then contrast (not clamped). Black stays black. Fixed at TD’s defaults: Source luminance and the Range, Step and Post pages. The alpha is 1.

Parameters:

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

Uniforms:

invert — mix towards the inverted luminance, 0..1 (default 0)
black_level — luminance at or below this goes to black (default 0)
brightness — luminance gain (default 1)
gamma — gamma correction; above 1 lifts the dark tones (default 1)
contrast — gain about mid-grey (default 1)

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

Noise

fn Noise(name: String) -> Visual

A noise generator: TouchDesigner’s Noise TOP with type Simplex 3D, monochrome, aspect corrected, alpha one. The field is static; animate it by binding the translate, e.g. n.parameter("tz") << Time(0.2).set_timebase(seconds(1)). For the same coordinates it matches TD’s field; a seed picks a different field than the same seed does in TD.

Parameters:

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

Uniforms:

seed — which field; any number, each gives a different field
period — feature size; the longer image side spans 4 / period units, positive
harmonics — layers added on top of the base, 0–32, rounded down
spread — frequency factor from one layer to the next
gain — amplitude factor from one layer to the next
exponent — signed power on the sum; above 1 pulls values toward 0
amplitude — weight of the base layer, before the exponent
offset — added after the exponent; the midpoint of the output
tx — moves the field right, in noise units
ty — moves the field up, in noise units
tz — moves through the field’s third axis, in noise units

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

Ramp

fn Ramp(name: String) -> Visual

A ramp visual: TouchDesigner’s Ramp TOP. A generator (no input) that draws a gradient through keys, a table with a row per key, any number of them, as TD’s Ramp reads its DAT: #[pos, r, g, b, a], the position along the ramp and the key’s colour and alpha. As in TD, positions are clamped to 0..1 and the keys are taken in order of position, a tie in table order; where no key sits at 0 or 1, the ramp wraps around from its last key to its first. Bind a table of your own: r.parameter("keys") << #[#[0, 0, 0, 0, 1], #[0.5, 0.3, 0.4, 0.7, 1], #[1, 1, 1, 1, 1]].

As in TD, phase moves the start of the ramp and period sets its length: a vertical or horizontal ramp reads position (x − phase) ÷ period at x across the image (0 to 1), and a radial or circular ramp reads its angle or distance ÷ period − phase. position_x and position_y move the centre of a radial or circular ramp, in fractions of the image. Radial and circular ramps take antialias × antialias samples a pixel (1 to 4). With premultiply, the colour is multiplied by the alpha. Checked against TD’s float exports: exact to float32, except ease in ease out (within 1.5e-4) and hermite with no key at 0 or 1. TD’s Dither is left out: it only matters for 8-bit images, and visuals are 16-bit float. The alpha is 1, where TD’s is the ramp’s.

Parameters:

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

Uniforms:

keys — the keys, a table of #[pos, r, g, b, a] rows (default black at 0, white at 1)
type — the shape of the ramp, a RampType (default horizontal)
position_x — the centre of radial and circular across, from the image centre (default 0)
position_y — the centre of radial and circular up, from the image centre (default 0)
phase — where the ramp starts (default 0)
period — the length of the ramp (default 1)
extend_left — the ramp below 0, a RampExtend (default repeat)
extend_right — the ramp above 1, a RampExtendRight (default same_as_left)
interp — the curve between keys, a RampInterp (default linear)
tension — hermite’s flattening at each key (default 0)
antialias — samples per axis for radial and circular, 1 to 4 (default 4)
fit_aspect — how radial and circular fit the image, a RampFit (default fit_horizontal)
premultiply — 1 multiplies the colour by the alpha, 0 does not (default 1)

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

RgbKey

fn RgbKey(name: String) -> Visual

An RGB-key visual: TouchDesigner’s RGB Key TOP. It pulls a key from the red, green and blue of its primary input (set via src >> RgbKey("…")): a pixel whose every channel lies between that channel’s min and max is in the key (1), the rest is out (0). A soft low or soft high fades the key in below min or out above max over that distance, along a cosine; at 0 the edge is hard. As in TD, each channel is clamped to 0..1, as are min and max, and a min at or above its max keys nothing. The key is the product of the three channels, inverted by invert (0 to 1, a blend). rgb_output sets the colour: the image times the key, or the key itself. With TD’s defaults every pixel is in the key, so the image passes through. Fixed at TD’s default: Alpha Output new alpha. The alpha is 1.

Parameters:

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

Uniforms:

red_min — the lowest red in the key (default 0)
red_max — the highest red in the key (default 1)
red_soft_low — how far below red_min the key fades in (default 0)
red_soft_high — how far above red_max the key fades out (default 0)
green_min — the lowest green in the key (default 0)
green_max — the highest green in the key (default 1)
green_soft_low — how far below green_min the key fades in (default 0)
green_soft_high — how far above green_max the key fades out (default 0)
blue_min — the lowest blue in the key (default 0)
blue_max — the highest blue in the key (default 1)
blue_soft_low — how far below blue_min the key fades in (default 0)
blue_soft_high — how far above blue_max the key fades out (default 0)
invert — inverts the key; 1 keeps what is out of the range (default 0)
rgb_output — the colour, an RgbOutput (default multiply_alpha)

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

Slope

fn Slope(name: String) -> Visual

A slope visual: TouchDesigner’s Slope TOP. It measures how the luminance of its primary input (set via src >> Slope("…")) changes across and up, from taps sample_step pixels before and after each pixel, and writes it as a displacement field for Displace: red is the slope left to right, blue the slope bottom to top, each zero_point + strength × difference / (4 × sample_step). As in TD, green is the zero point, alpha is 1 and the result is not clamped. Fixed at TD’s defaults: luminance (0.3 R + 0.6 G + 0.1 B) and the previous and next pixels. The step is in composition pixels, so the field is the same at every quality.

Parameters:

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

Uniforms:

strength — slope gain (default 1)
zero_point — the value of a flat image (default 0.5)
sample_step — distance from each pixel to its taps, in pixels (default 1)

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

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. 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, an Extend (default hold)

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

feedback

fn feedback(seed: Visual, build: Function) -> Visual

Builds a feedback group: TouchDesigner’s Feedback TOP, with the group output as its Target TOP. The closure is called with prev and returns the group output. prev is the output’s previous frame, except on the output’s first frame and on the frame after a reset(), when it is the seed’s current frame. 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(Noise("seed"), fn(prev) { let d = Displace("warp"); d.parameter("by") << prev; return Noise("field") >> d; })

Parameters:

seed (Visual) — what prev is until the output has a frame of its own
build (Function) — fn(prev) { ... }, returning the group’s output Visual

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

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 >>