Reference

Effect language builtins

View on GitHub

Every builtin function, context value and signal method of the effect language. A call takes a signature its arguments fit exactly, and otherwise one they fit with int arguments widened to floats, so an int is accepted wherever a float is expected and signatures with int forms keep ints as ints when every argument is an int.

Context values

NameTypeMeaning
timefloatSeconds since the effect's clip started; in an operator, since the sequence started.
durationfloatThe clip's duration in seconds; in an operator, the sequence's.
progressfloattime / duration, in 0..1.
frameintFrames since the effect's clip started, the nearest frame to time; in an operator, since the sequence started.
frame_ratefloatThe sequence's frames per second.
frames_elapsedintFrames since the frame shown before: one in steady playback, more after skipped frames, one after a seek, and zero when a console command re-renders the same frame.
previouscolorThis pixel last frame: an operator's own output, or an effect's layer. previous.at(i) reads another pixel of the fixture and around previous its neighbors. Black until the first frame and for a clip previewed alone; kept as it was after a seek.
pixel.indexintThe pixel's zero-based index within the target; in an operator, within its fixture instance.
pixel.fractionfloatThe pixel's index scaled to 0..1 across the target; in an operator, across its fixture instance.
pixel.xfloatThe pixel's layout x coordinate in meters, after fixture transforms.
pixel.yfloatThe pixel's layout y coordinate in meters.
target.countintHow many pixels the target has; in an operator, its fixture instance.
target.min_xfloatThe smallest x coordinate of the target's pixels.
target.min_yfloatThe smallest y coordinate of the target's pixels.
target.max_xfloatThe largest x coordinate of the target's pixels.
target.max_yfloatThe largest y coordinate of the target's pixels.
PIfloatπ, half a turn in radians.
TAUfloat2π, a full turn in radians.

Signal methods

Operator inputs and previous are signals.

at(pixel: int) -> color

The signal at another pixel of this fixture, at this frame; pixel is a zero-based index within the fixture.

Math

sin

sin(x: float) -> float

Sine of an angle in radians. NaN gives NaN. Never folded at compile time, so host and device agree.

let wave = sin(time * TAU);

cos

cos(x: float) -> float

Cosine of an angle in radians. NaN gives NaN.

let wave = cos(pixel.fraction * PI);

tan

tan(x: float) -> float

Tangent of an angle in radians. Grows without bound near odd multiples of PI / 2. NaN gives NaN.

let slope = tan(angle);

atan2

atan2(y: float, x: float) -> float

Angle of the point (x, y) from the positive x axis, in radians from -PI to PI. Note the argument order: y first.

let angle = atan2(pixel.y - 1.0, pixel.x - 1.0);

sqrt

sqrt(x: float) -> float

Square root. Negative numbers and NaN give NaN.

let distance = sqrt(dx * dx + dy * dy);

exp

exp(x: float) -> float

e raised to x. Large inputs give infinity. NaN gives NaN.

let decay = exp(-age * 4.0);

log

log(x: float) -> float

Natural logarithm. Zero gives negative infinity; negative numbers and NaN give NaN.

let octave = log(frequency / 440.0) / log(2.0);

pow

pow(base: float, exponent: int) -> float
pow(base: float, exponent: float) -> float

base raised to exponent. An int exponent that the compiler can bound to 0..10,000 multiplies base into one that many times, exactly. Any other exponent, including negative ints, uses the general power function: pow(2, -1) is 0.5. A negative base with a fractional exponent is NaN.

let falloff = pow(1.0 - progress, 3);

abs

abs(x: int) -> int
abs(x: float) -> float

Absolute value; an int stays an int. The int minimum wraps to itself, like negation.

let distance = abs(pixel.index - center);

sign

sign(x: int) -> int
sign(x: float) -> float

-1, 0 or 1 by the sign of x; an int stays an int. A float zero keeps its sign and NaN stays NaN.

let direction = sign(velocity);

min

min(a: int, b: int) -> int
min(a: float, b: float) -> float

The smaller argument. Two ints give an int; otherwise both are floats. NaN in either argument gives NaN.

let last = min(radius, target.count - 1 - pixel.index);

max

max(a: int, b: int) -> int
max(a: float, b: float) -> float
max(a: color, b: color) -> color

The larger argument. Two ints give an int; two colors take the larger of each channel. NaN in either float argument gives NaN.

let first = max(-radius, -pixel.index);

clamp

clamp(x: int, low: int, high: int) -> int
clamp(x: float, low: float, high: float) -> float

x limited to low..=high. Three ints give an int. Float clamping with low > high, or NaN in any argument, gives NaN. Int clamping applies low first, so low > high gives high.

let level = clamp(age / fade, 0.0, 1.0);

mix

mix(a: float, b: float, t: float) -> float
mix(a: color, b: color, t: float) -> color

Linear interpolation from a at t = 0 to b at t = 1. t outside 0..1 extrapolates. A NaN t gives NaN.

let color = mix(#ff0000, #0000ff, pixel.fraction);

smoothstep

smoothstep(low: float, high: float, x: float) -> float

0 below low, 1 above high, and a smooth cubic between. low == high divides by zero and gives NaN.

let edge = smoothstep(0.4, 0.6, pixel.fraction);

step

step(edge: float, x: float) -> float

0 when x < edge, otherwise 1. NaN in either argument gives NaN.

let on = step(0.5, progress);

integral

integral(parameter: float) -> float

A float parameter integrated over time, in its units times seconds. Integrates from the clip's start in an effect, or the sequence's start in an operator. A fixed value gives parameter * time; automation is integrated exactly, so a changing speed or rate never jumps. The argument must name a float parameter.

let phase = integral(speed) * TAU;

Rounding and conversion

floor

floor(x: float) -> float

The largest whole number at most x, as a float. Use x // 1 for the same value as an int when x is an int expression, or int(floor(x)) for a float.

let step = floor(time * 4.0);

ceil

ceil(x: float) -> float

The smallest whole number at least x, as a float. NaN gives NaN.

let bars = ceil(height / 3.0);

round

round(x: float) -> float

The nearest whole number, halves away from zero, as a float. round(2.5) is 3 and round(-2.5) is -3. NaN gives NaN.

let step = round(time * 40.0);

fract

fract(x: float) -> float

The fractional part x - floor(x), in [0, 1). Negative numbers wrap: fract(-0.25) is 0.75. Infinity and NaN give NaN.

let phase = fract(time * 0.5 + pixel.fraction);

int

int(x: float) -> int

A float converted to an int, truncating toward zero. Saturates at the int range and turns NaN into zero. Write int(floor(x)) to floor negative values.

let index = int(progress * len(colors));

Missing values

is_nan

is_nan(x: float) -> bool

Whether x is NaN, the missing value. Comparisons with NaN are always false, so test missing values with this.

guard !is_nan(last_beat);

value_or

value_or(x: float, replacement: float) -> float

x, or replacement when x is NaN. Both arguments are always computed; use an if when the replacement is expensive.

let age = value_or(time - mark_last(beats, time), 1000.0);

Color

rgb

rgb(red: float, green: float, blue: float) -> color

A color from channels in 0..1. Channels may lie outside 0..1 until the color is written, which clamps them; a NaN channel is written as zero.

let warm = rgb(1.0, 0.6, 0.2);

hsv

hsv(hue: float, saturation: float, value: float) -> color

A color from hue in turns, saturation and value in 0..1. Hue wraps in both directions, so 1.25 is 0.25.

let rainbow = hsv(pixel.fraction + time * 0.1, 1.0, 1.0);

hue

hue(color: color) -> float

A color's hue in turns, in [0, 1). Grays have hue zero.

let shifted = hsv(hue(source) + 0.5, saturation(source), intensity(source));

saturation

saturation(color: color) -> float

A color's HSV saturation in 0..1. Grays have saturation zero.

let pastel = saturation(source) < 0.5;

intensity

intensity(color: color) -> float

A color's HSV value: its brightest channel as a fraction of full brightness. Black is zero and any fully bright channel is one.

let masked = source * intensity(mask);

red

red(color: color) -> float

A color's red channel in 0..1, the scale rgb takes. rgb(red(c), green(c), blue(c)) is c again.

let warmth = red(source) - blue(source);

green

green(color: color) -> float

A color's green channel in 0..1.

let swapped = rgb(green(source), red(source), blue(source));

blue

blue(color: color) -> float

A color's blue channel in 0..1.

let gray = (red(source) + green(source) + blue(source)) / 3.0;

invert

invert(color: color) -> color

Each channel complemented: full brightness minus the channel. Inverting black gives white.

invert(input)

Curves and gradients

curve_clamped

curve_clamped(curve: curve, position: float, low: float, high: float) -> float

clamp(curve[position], low, high) as one operation. Indexing a curve, curve[position], samples it at a position in 0..1; an empty curve gives NaN.

let level = curve_clamped(envelope, progress, 0.0, 1.0);

curve_integral

curve_integral(curve: curve, position: float) -> float

The area under the curve from position 0 to position. End values are held beyond the authored points, so the area keeps growing past them; a negative position gives a negative area. Multiply by duration to integrate a rate over the clip's seconds. An empty curve or a NaN position gives NaN.

let spawned = curve_integral(rate, progress) * duration;

gradient_color_scaled

gradient_color_scaled(gradient: gradient, position: float, scale: float) -> color

gradient[position] * clamp(scale, 0, 1) as one operation. Indexing a gradient, gradient[position], samples its color at a position in 0..1; an empty gradient gives black.

gradient_color_scaled(colors, pixel.fraction, level)

Marks and crossings

mark_last

mark_last(marks: marks, time: float) -> float

The time in seconds of the last mark at or before time. NaN before the first mark.

let age = time - mark_last(beats, time);

mark_last_index

mark_last_index(marks: marks, time: float) -> int

The zero-based index of the last mark at or before time. -1 before the first mark.

let beat = mark_last_index(beats, time);

mark_at

mark_at(marks: marks, index: int) -> float

The time in seconds of the mark at index. NaN outside 0..mark_count(marks).

let next = mark_at(beats, beat + 1);

mark_count

mark_count(marks: marks) -> int

How many marks the collection holds; the same as len(marks).

guard mark_count(beats) > 0;

curve_first_crossing

curve_first_crossing(curve: curve, value: float) -> float

The first position in 0..1 where the curve reaches value. NaN when it never does, or for an empty curve.

let arrival = curve_first_crossing(chase, pixel.fraction);

curve_last_crossing

curve_last_crossing(curve: curve, value: float, before: float) -> float

The last position at or before before where the curve reaches value. NaN when there is none.

let left = curve_last_crossing(chase, pixel.fraction, progress);

Sections

section_count

section_count(width: int) -> int

How many runs of width pixels the target is split into. A per-fixture effect sections each fixture; a whole-target effect sections the target's fixtures in order. Widths below one count as one.

let sections = section_count(10);

section_index

section_index(width: int) -> int

The zero-based run of width pixels the current pixel is in.

let lit = section_index(10) % 2 == 0;

section_position

section_position(width: float) -> float

The current pixel's position within its run of width pixels, in [0, 1). Widths below one count as one.

let ramp = section_position(10.0);

Randomness

rand

rand(seed: float) -> float

A pseudo-random number in [0, 1) hashed from seed. Pure: the same seed always gives the same value, on every pixel, frame, controller and seek. Combine what identifies a decision (pixel, time bucket, mark) with a user seed parameter. Integer seeds above 2^24 lose precision. NaN gives NaN.

let twinkle = rand((seed * 31.0 + pixel.index) * 31.0 + floor(time * 8.0));

Collections

len

len(array: array<T>) -> int
len(marks: marks) -> int

How many items an array or marks collection holds. Indexing an array, array[i], clamps i to the first or last item and floors a float i; an empty array gives the item type's default.

let color = colors[pixel.index % len(colors)];