StackSL cheatsheet

StackSL lowers to vec4 stack(vec4 stack_in). The usual input convention is vec4(x, y, z_or_hash, time), the stack starts with that input, and every word works with vec4 values.

Stack signatures use a b -- c, where the top of stack is on the right. If a word needs a missing value, the compiler fills by wrap/default convention and reports it in diagnostics.

How a program runs

The smallest complete program is one word and a clamp:

uv saturate

uv pushes vec4(uv.xy, 0, 1) and saturate clamps it. Whatever is on top of the stack at the end becomes the colour, so this frame is a red-green gradient. Every program below has the same shape: push something, transform it, and the top value is the colour.

Inputs and constants

uv runs 0..1 across the frame; p is the same coordinate centred on zero, which is the one to reach for whenever a figure has a middle.

p 4 * phacelle palette saturate

Worked: The input convention, and the whole rendered gallery opens on uv saturate.

Kotlin helpers

These helpers compile StackSL to GLSL and run it through a tiny on-demand compute shader. They need a running Renderer in context.

Stack words

All values are vec4. Swizzles turn selected channels back into a vec4: one channel is splatted, two channels become xy,0,1, three become xyz,1, and four stay four-wide. The dot prefix is optional.

These are how a program reaches a value it has already computed. Below, dup copies the polar coordinate, y takes the angle lane off the copy, 0.2t drifts it with time, and >y writes the result back into the lane it came from, so the angle turns while the radius is left alone:

p polar
dup y 0.2t + >y
cart
fbm
sigmoid
palette

Worked: Swizzles and constructors.

Number forms and suffixes

Suffixes let you write modulation where you are already thinking about a number. The same modifiers work as numeric literals, top-of-stack amplitude operators, and top-of-stack driver operators.

]sh10 below is the driver form: it consumes the scaled coordinate as its phase and holds a random value across each bucket of it, which is what turns a smooth gradient into blocks.

uv 6 * ]sh10 palette saturate

Worked: Modifiers, ranges, and memories.

Modifier alphabet

| keeps the default driver, usually time or input coordinates. ] changes the driver to the consumed top value.

]wr14 is a sine wave across radius at fourteen cycles, driven by the centred coordinate it consumes. That draws concentric rings with one token:

p ]wr14 palette saturate

Examples: 0.4c2, 0.4s3q8, p length |pulse8d0.15q4, p ]fbm5q8, prev xy ]c3p0.1.

Math and logic

Eighteen stripes: take the x lane, scale it, fold it through sin, then bring the -1..1 result back into 0..1 before colouring it.

uv x 18 * sin 0.5 + 0.5 * palette saturate

Arity variants use word.N for explicit consumption and word.all for stack blasts where supported. Examples: average.4, median.5, min.1, min.all, sort.all.

Reducers and geometry

A reducer collapses a vec4 to one number splatted across all four lanes, which is how a distance becomes a shape: length of the centred coordinate is the radius, and pulse keeps a soft band at one radius, so this is a ring.

p length 0.5 0.08 pulse white *

Worked: Pulses, rings, and FM.

Domain transforms

These change the coordinate before anything is read at it, so they compose: six mirrored sectors, then a twist that grows with radius, and only then the noise.

p 6 kaleido
1.7 twist
3.0 *
fbm
palette
saturate

Worked: Domain transforms and shapers.

Creative operators

The shapers you reach for once a field exists. Here a noise field is remapped onto 0.2..0.8, quantised to six levels, and pushed off centre before it is coloured.

uv 5 * fbm
0.2 0.8 ramp
6 posterize
0.62 bias
palette

Worked: Domain transforms and shapers.

Volumetric noise

noise and fbm above are two-dimensional. They read coord.xy + coord.zw * 0.07, so z barely changes the result: a volume seen along z shows the same pattern at every depth. Use these words when you need noise in three or four dimensions; they read input.xyz (or all of .xyzw).

They differ from the 2D words in two ways you will notice:

• Their range is exactly 0..1, for any octave count, lacunarity and gain. The 2D fbm peaks a little below 1, so fbm 0.5 - averages slightly below zero and a force built from it drifts.
• They cost more. curl3 evaluates fbm3 eighteen times, which is why its short form runs three octaves instead of five. Extra octaves in a curl add fine noise rather than larger structure.

Every word takes its coordinate first. The second slot is the word's own knob and the third is the octave count, so input 0.03 3 curl3.3 is "epsilon 0.03, three octaves".

Four lines, one per word, each a common use:

input 2.2 * curl3 xyz 0.4 *        # a divergence-free three-channel force
input 6 * worley3 z 1- 8 pow       # glowing cell walls
input 1.7 * warp3                  # filaments
input fbmd3 yzw normalize          # a surface normal from the noise field

Phase noise

These words make noise whose phase you can turn, separately for each frequency. Use them when you need several fields that belong together: two eyes of a stereo pair, three colour channels, species of particles, or one field at two moments. Turn the phase of every frequency and the second field correlates with the first by \( \cos(2\pi\cdot\mathrm{turns}) \): 0 gives the same field, 0.25 an uncorrelated partner with the same character, and 0.5 its negative. Turn only the fine frequencies and the two fields share their large forms exactly while their detail differs.

noise and fbm cannot do this, because value noise has no phase. These words sum small oriented waves (sparse Gabor noise) twice, once through cos and once through sin, so each returns a pair, vec4(c, s, envelope, 1). x is the field. y is the same field a quarter turn on. z is their length, which no phase change alters. c and s are signed with mean zero, and nearly all values fall inside -1..1. The words read coord.xy, and phase is measured in turns, as in phacelle (where rotate uses radians).

One field; three related colour channels from a single evaluation; and fine octaves that churn over time while the large forms hold still:

input 8 * qnoise x 0.5 * 0.5 +
input 8 * qnoise >n <n x <n 0.33 phrot x <n 0.67 phrot x vec3 0.5 * 0.5 +
input 8 * [0,0,0.1,0.3] t * phnoise x 0.5 * 0.5 +

The second line computes the noise once and rotates the mark three times, which is cheap. Two qnoise words with the same arguments are evaluated twice.

A phase response

For a curve of your own, write a definition that takes one value and leaves one, then pass it quoted to qnoise. The definition runs once per wave and its .x is added to that wave's phase, in turns. Its input describes the wave:

• .x is the wave's frequency, in cycles per unit of the coordinate qnoise was given;
• .y is its octave, 0 for the coarsest;
• .z is a random number in 0..1, fixed for that wave;
• .w is the coordinate's w, which is time by the usual input convention.

: fine >k 0.5 4 <k x smoothstep 0.5 * ;     # no turn at frequency 0.5, half a turn from 4 up
'fine input 8 * qnoise x

: churn >k <k z 0.5 - <k w * ;              # each wave drifts at its own speed
'churn input 8 * qnoise x 0.5 * 0.5 +       # noise that changes without sliding

Frequencies are measured in the coordinate the word receives, so input 8 * puts the coarsest octave near 8 cycles across the unit square, but a response sees it as about 1.

Color spaces

Colour offsets and contrast changes look more even in OKLab: convert with rgb2oklab, do the math, then convert back with oklab.

Definitions

Define reusable words with : name ... ;. A call consumes one input value, runs the definition with that value as its local stack/input, then pushes the result.

A definition must therefore be net zero on the stack: consume its input, leave its result. A called definition that is not is a compile error naming it. Open a definition with >name, which moves the top, and not =name, which copies it:

: half  >v  <v 0.5 *  ;      # right: consumes one, leaves one
: half  =v  <v 0.5 *  ;      # refused: leaves its input under its result, so every call pushes two

stack.auto reports this. A slot whose program has an unbalanced definition, or any warning at all, writes a card into the box's stack.auto output channel and closes it again once the program is clean. Ask directly with stackAutoShaderReport("…", "slotName"), which returns a StackAutoReport carrying problems, warnings and notes and renders itself as HTML for display().

Only definitions that something calls are checked. A root program may end with more than one value on the stack, because its stack starts with the program's input already on it (input x 12 * ends with two). The same goes for a definition used only as an entrypoint ({{ stack.auto.foo:tap }}), which runs as a root program.

: ring
  length 0.5 0.06 pulse
;

p ring white *

Definitions are inlined into GLSL, so shared math can still be optimized.

Word references

Prefix a word with ' to put a compile-time reference to that word on the stack. apply, call, and invoke consume a word reference and a value, inline the referenced word with that value as its input, and push the result. Both word value apply and value word apply work.

: pattern
  normalize
;

'pattern p apply

References can be passed through another definition, which is useful for shader helpers that need a pattern or sampling function.

: pattern
  xylen
;

: mapped
  apply
;

'pattern uv mapped

This is still static lowering: StackSL carries the word reference while compiling, then emits direct GLSL for the referenced word rather than a runtime function pointer.

phacelle / directional-noise uses this for directional phasor noise. It takes point frequency offset normalization -- noise, with defaults for everything after point. Add a quoted pattern definition before or after the arguments to orient the cells. The pattern receives each cell point as its input and may do normal StackSL work, including sampling.

: flowPattern
  input sample-abs
  normalize
;

'flowPattern p 100 * 1.5 0.2 1 phacelle.4

Local marks

Local marks name a stack value inside the current root program or definition. They are compile-time aliases, not mutable variables, so unused marked values are still pruned.

A mark cannot be called x, y, z or w, and the compiler says so when you try.

uv 8 * =coord
coord fbm
coord 0.2t + fbm
0.5 mix
palette

Use the explicit move/read form when you want to keep the working stack clean, and always inside a definition, where =name would leave the input on the stack and unbalance the call (see Definitions):

uv 8 * >coord
<coord fbm
<coord 0.2t + fbm
0.5 mix
palette

Feedback sampling, store, and host values

For long-term dynamics, think of RGBA as four memories. Use range vectors for rates, nearby sample offsets for diffusion, and explicit channel writes when you want separate state variables.

Copyable patterns

Centered soft ring:

p length 0.5 0.08 pulse white *

Drifting feedback with a pulsed injection:

0.004wx7 0.004wy5 vec2 sample.w
0.986 *
p length 0.42 0.035 pulse palette 0.05 *
+
saturate

Subroutine called twice with different coordinates:

: ridge
  fbm 0.45 0.08 pulse
;

p 5.0 * 0.2t + ridge
p 7.0 * 0.13t - ridge
0.5 * +
palette

Nearby samples plus four slow memory scales:

prev
dup xy 0.012 * sample.w
swap zw 0.009 * sample.w
+ 0.5 *
p ]wr9 0.006 * 0.004c0.17 +
p ]wa7 0.006 * 0.004s0.11 +
vec2 sample.w
0.65 * +
uv 5.0 * prev 0.4 * + 0.02t + fbm
dup 0.23 + dup 0.37 + dup 0.61 + vec4
0.08 * +
prev 0.006_0.09 ema
dup average 0.015pulse0.23d0.09 + +
mirror saturate

Channel gradient with sampler texel size:

uv texelSize gradient.r