Custom GLSL Shaders
Reference for the Custom GLSL node - built-in uniforms per shader format, parameter annotations, audio uniforms, and SSF scenes.
Reference for shaders that run in the Custom GLSL node.
- Formats — plain GLSL, Shadertoy-style code, ISF files, and SSF scenes
- Built-in uniforms — what each format gets without declaring it
- Parameters — every uniform you declare becomes a control
- Pointer uniforms — mouse position and buttons, in every format
- Audio uniforms — live audio values, available by name, plus four audio inputs you wire yourself
- SSF scenes — load a
.synScenefolder as one node
Formats
The node detects the format from the source.
| Format | Detected by | Entry point |
|---|---|---|
| Plain GLSL | default | void main() writing gl_FragColor |
| Shadertoy-style | mainImage, iTime or iResolution in the source | void mainImage(out vec4 fragColor, in vec2 fragCoord) |
| ISF | a /*{ … }*/ JSON header with INPUTS, DESCRIPTION, PASSES or ISFVSN at the top of the source | void main() writing gl_FragColor |
| SSF scene | vec4 renderMain(void) in the source, or a loaded .synScene | vec4 renderMain(void) |
Drop a .glsl, .frag, .fs or .isf file onto the node graph to create a Custom GLSL node from it.
Built-in uniforms
Do not declare these. The compiler injects them.
Plain GLSL
| Uniform | Type | Value |
|---|---|---|
uTime | float | Animation time in seconds |
uResolution | vec2 | Output size in pixels |
uMouse | vec2 | Mouse position, 0–1 |
uTexture | sampler2D | The texture wired into the Texture in input |
uTexture2, uTexture3 … | sampler2D | The textures wired into the added Texture in 2, 3 … inputs |
Shadertoy-style
| Name | Type | Value |
|---|---|---|
iTime | float | Animation time in seconds |
iResolution | vec3 | Output size in pixels (z = 1) |
iMouse | vec4 | Mouse position and last click, in pixels |
iFrame | int | Frame counter |
iChannel0 | sampler2D | The texture wired into the Texture in input |
iChannel1 | sampler2D | The texture wired into the added Texture in 2 input |
iChannel2 and iChannel3 read Texture in 3 and Texture in 4. A channel whose input the node does not have, or that has nothing wired, reads Texture in. Add texture inputs with + Texture in in the node's parameters.
ISF
| Name | Value |
|---|---|
TIME | Animation time in seconds |
RENDERSIZE | Output size in pixels |
isf_FragNormCoord | Pixel position, 0–1 |
FRAMEINDEX | Frame counter |
TIMEDELTA | Fixed at 1/60 |
IMG_NORM_PIXEL(tex, uv), IMG_PIXEL(tex, px), IMG_THIS_NORM_PIXEL(uv), IMG_THIS_PIXEL(px), IMG_SIZE(tex) | Texture lookups |
The first image input reads the Texture in input, the second Texture in 2, and so on. An audio or audioFFT input reads the audio spectrum texture. The shader renders in one pass; PASSINDEX is always 0.
SSF scene
| Name | Type | Value |
|---|---|---|
TIME | float | Animation time in seconds |
RENDERSIZE | vec2 | Size in pixels of the pass being rendered |
FRAMECOUNT | float | Frames rendered since the shader compiled |
PASSINDEX | int | Index of the pass being rendered |
_xy | vec2 | Pixel position |
_uv | vec2 | Pixel position, 0–1 |
_uvc | vec2 | Aspect-corrected position, (0,0) at the center |
PI | float | 3.14159265359 |
_mouse, _click, _muv, _muvc | The pointer uniforms | |
syn_Media | sampler2D | The texture wired into the Texture in input |
syn_MediaType | float | 1 when the Texture in input is wired, 0 otherwise |
uTexture2, uTexture3 … | sampler2D | The textures wired into the added Texture in inputs; iChannel1 to iChannel3 read them too |
syn_FinalPass | sampler2D | The scene's previous output frame |
Every pass TARGET and every image NAME from scene.json is a sampler2D of that name.
Pointer uniforms
Every format has these. Name one in the shader and it is declared for you.
| Name | Type | Value |
|---|---|---|
_mouse | vec4 | xy is the pointer position in pixels, origin at the bottom left. zw is the position where the button went down; both are negative while no button is held |
_click | vec3 | Left, right and middle button in x, y, z: 1 while held, 0 otherwise |
_muv | vec2 | Pointer position, 0–1 |
_muvc | vec2 | Pointer position, aspect-corrected with (0,0) at the center, the same space as _uvc |
- The pointer is read over the viewport, in the Node graph and in performMODE
uTexture2,uTexture3… read the node's added texture inputs; one the node does not have, or with nothing wired, reads Texture in
Parameters
Each uniform you declare becomes a control in Shader Parameters, stored on the node as uniform_<name>.
uniform float speed; // @range 0 5 @default 1 @label "Speed"
uniform int mode; // @options "Soft" "Hard"
uniform bool invert;
uniform vec2 center; // @range -1 1
uniform vec3 tint; // @color @default 1 0.5 0.2| Declaration | Control |
|---|---|
float, int | Slider, with the per-parameter animation bar |
int with @options | Dropdown; the value is the option index |
bool | Switch |
vec2 | X and Y sliders |
vec3 / vec4 with @color | Color swatch (vec4 adds an alpha slider) |
Annotations go in a // comment on the same line as the declaration.
@range <min> <max>— slider bounds. Without it a float runs -2 to 2 and an int 0 to 100@default <value>— starting value; give one number per component for vectors@label "Name"— display name@step <n>— slider step@color— show avec3orvec4as a color@options "A" "B" …— show anintas a dropdown
A vec3 or vec4 without @color compiles and works but gets no control.
Use the Expose button on a control to promote the uniform to a Base, a driver port, and the performMODE deck. Sliders can be animated, mapped to audio, and mapped to MIDI like any other parameter. See Parameters and Controls.
mat and sampler2D declarations are not turned into controls.Audio uniforms
Name an audio uniform in the shader and it is declared for you and updated every frame. No wiring is needed.
void main() {
vec2 uv = gl_FragCoord.xy / uResolution;
float spectrum = texture(audio_Spectrum, uv.x).g;
gl_FragColor = vec4(vec3(spectrum * audio_BassLevel), 1.0);
}The prefix is audio_ in plain GLSL, Shadertoy-style and ISF shaders. Inside an SSF scene the same names use syn_.
The Audio row appears in the editor once the shader names an audio uniform. It selects the source: the timeline's audio when a song is loaded, otherwise the input device, or a specific clip or file.
| Uniform | Value |
|---|---|
audio_Level, audio_BassLevel, audio_MidLevel, audio_MidHighLevel, audio_HighLevel | Smoothed loudness of the whole spectrum and of each band, 0–1 |
audio_Hits, audio_BassHits, audio_MidHits, audio_MidHighHits, audio_HighHits | Transients: rises fast on an isolated hit, falls back quickly, 0–1 |
audio_Presence, audio_BassPresence, audio_MidPresence, audio_MidHighPresence, audio_HighPresence | Slow rise and fall with the energy in the band, 0–1 |
audio_Time, audio_BassTime, audio_MidTime, audio_MidHighTime, audio_HighTime | Clocks that advance with loudness. Not normalised |
audio_CurvedTime | A clock that accelerates strongly with loudness |
audio_FadeInOut | Rises to 1 when sound starts, falls to 0 when it stops |
audio_Intensity | Builds toward 1 during loud passages, sinks in quiet ones |
audio_Spectrum | sampler2D, 512 × 1. .r raw FFT, .g conditioned FFT on a log frequency scale, .b the same at lower resolution, .a waveform (0.5 is silence) |
audio_LevelTrail | sampler2D, 256 × 1 history with the newest sample at x = 1. .r level, .g bass, .b mid, .a high |
Bands: Bass 30–250 Hz, Mid 250–2000 Hz, MidHigh 2–6 kHz, High 6–16 kHz.
Sample the two textures with a float or a vec2: texture(audio_Spectrum, 0.25) and texture(audio_Spectrum, vec2(0.25, 0.5)) read the same texel.
Audio inputs
Click + Audio in in the node's parameters to add an audio input. Audio in 1 is read as audio_In1, Audio in 2 as audio_In2, and so on (syn_In1 … in an SSF scene). Add as many as you need.
- The Sound node sets the frequency range and the response, so each input is an audio uniform of your own design
- Any modifier can drive an input, not only a Sound node
- An input with nothing wired, or a name the node has no input for, reads 0
- The × next to an input removes it; the others keep their numbers
#define kick audio_In1gives an input a name in the shader
#define kick audio_In1
void main() {
vec2 uv = gl_FragCoord.xy / uResolution;
gl_FragColor = vec4(vec3(step(length(uv - 0.5), 0.1 + 0.3 * kick)), 1.0);
}Beat uniforms
audio_BPM, audio_BPMConfidence, audio_OnBeat, audio_ToggleOnBeat, audio_RandomOnBeat, audio_BeatTime, audio_BPMTwitcher, audio_BPMSin, audio_BPMSin2, audio_BPMSin4, audio_BPMSin8, audio_BPMTri, audio_BPMTri2, audio_BPMTri4, audio_BPMTri8.
audio_BPMConfidence reads 0.Behaviour under pause
The level, hit and presence values and both textures keep following the audio while the app is paused. The time clocks and the beat clock hold until playback resumes.
An unknown name such as audio_Bass fails the compile and the error lists the valid names.
SSF scenes
An SSF scene is a folder ending in .synScene that holds main.glsl, scene.json, and optionally script.js and an images folder.
- Drop the folder, or a
.zipof it, onto the node graph - The scene loads as one Custom GLSL node named after the scene's
TITLE - Controls, passes, images, the script and the audio uniforms are set up from the scene's files
Controls
Each entry in CONTROLS becomes a control and a uniform of the same name.
Control TYPE | Uniform | Control |
|---|---|---|
slider, knob | float | Slider with MIN, MAX, DEFAULT |
toggle | float | Switch (0 or 1) |
bang | float | Button; 1 for the frame it is pressed |
bang counter | float | Button; counts presses |
xy | vec2 | X and Y sliders |
color | vec3 | Color swatch (DEF_COLOR) |
dropdown | float | Dropdown from LABELS and VALUES |
- A
smoothvariant eases toward the set value at the rate inPARAMS - A
speedvariant adds the set value to the uniform every second and holds while the app is paused - A
travelervariant is aspeedcontrol whose rate eases toward the set value at the rate inPARAMS - A control with no
TYPEis a slider UI_GROUPputs controls under a group headerHARD_TRANSITIONSandSMOOTH_TRANSITIONSentries become sliders in a Transitions group
scene.json can contain comments, trailing commas and numbers written as 1. or .5. A control or image listed twice is used once.
Passes
PASSES render in order before the final pass. renderMain runs once per pass with PASSINDEX set to the pass index; the final pass has the index after the last entry.
WIDTH/HEIGHT— pass size; the node's output size when omittedFLOAT— 32-bit float target (half float when the GPU cannot render to float)FILTER—linear,nearestormipmap;WRAP—repeat,clampormirror
A pass that samples its own TARGET reads its previous frame, so feedback works with or without DOUBLE_BUFFER. Passes and syn_FinalPass hold while the app is paused.
Images
IMAGES entries load from the scene's folder and bind to their NAME. The desktop app stores them in the resources vault; the browser build embeds them in the patch.
Scripts
script.js runs once per frame before the shader.
setup()runs once;update(dt)runs every frame- Every uniform is a global:
TIME, the audio values, the control names, and the pointer (_muvc.x,_click.x) setUniform(name, …)creates a shader uniform;setControl(name, value)writes a controluniforms.name = valuealso creates a uniform. An object assigned this way is read again every frame, souniforms.cam = camfollows later changes tocam- A uniform the script sets from a variable takes its size from the shader:
cam.zinmain.glslmakescamavec3 onChange,onOffToOn,onOnToOff,whileOn,whileOffregister handlersprint(…)writes to the script log shown under the code box
Edit script.js on the Script tab of the code box, which appears while an SSF scene is loaded. Click Run, or press Ctrl+Enter, to restart the script with the new text. Open in editor opens it in your own code editor instead, and each save there restarts the script. The shader compiles again at the same time, because the uniforms the script sets are part of the shader.
The script runs in an isolated sandbox with no network or file access. A script that does not return within 100 ms is stopped and the status row shows timed out; Reload script restarts it.
Helper functions
Scenes can call the scene library without declaring it: _rotate, _toPolar, _toRect, _hsv2rgb, _rgb2hsv, _noise, _fbm, _rand, the _hash family, _pulse, _mix3 to _mix5, _map, _mirror, _palette, _loadMedia, _textureMedia, _loadImage, _edgeDetect, _edgeDetectSobel, _hBlurTiltShift, _vBlurTiltShift, and the rest of the standard set. A function the scene defines itself replaces the library's.
Includes
#include reads from the bundled libraries:
#include "lygia/generative/snoise.glsl"
#include "hg_sdf.glsl"lygia/…— the lygia shader libraryhg_sdf.glsl— signed distance functionsdome_header.glsl— fulldome coordinate helpers
Scenes written for desktop GLSL
Auragen compiles a scene as GLSL ES 3.00. Scene code written for desktop GLSL is adapted when it compiles, and main.glsl in the editor stays as you wrote it.
- An integer in a float expression is converted:
float x = 1;,TIME * 2,pow(x, 2),uv *= 2; - An integer vector passed as a float vector is converted:
vec2 size = textureSize(tex, 0); - A global variable set from a uniform (
vec2 U = _xy;) gets its value at the start of each frame - Default parameter values (
float f(float a, float b = 1.0)) become overloads - A name that GLSL ES reserves (
sample, or a name with two underscores) is renamed FRAMECOUNTworks where an integer is necessary:int i = min(0, FRAMECOUNT),FRAMECOUNT % 2texelFetch(syn_Spectrum, index, 0)works with one integer index
The status row under the editor shows how many expressions were adapted. An error line number refers to main.glsl, or names the included file.
Limits
- One shader can read 16 textures on most GPUs, counting images, passes, the media input and the audio textures. A scene that reads more does not compile
CUBEMAPSsample blacktextureFinalPassin a script returns black- The beat uniforms use the fixed clock described under Beat uniforms
- The scene-wide color and media adjustments (
_Brightness,_Contrast,_Media_Scale, …) stay at their neutral values; use the node's own parameters and effect nodes instead
Editor
- ▾ next to the tabs — hide or show the code box, to show only the parameters
- Auto — recompile 500 ms after you stop typing; Compile or Ctrl+Enter compiles now
- Reset — restore the default shader
- Tab inserts four spaces
- GLSL and Script tabs — switch the code box between the shader and, with an SSF scene loaded, the scene's
script.js. Run, on the Script tab, applies an edit to the script - Open in editor — opens the code on the active tab in the app your computer uses for that file type, for example your code editor. Each save there updates the node. Desktop app only
Under the parameters, Built-in uniforms, Audio uniforms and SSF scenes open these reference sections, and Guide shows the shader authoring guide. An AI assistant connected to Auragen reads the same guide on its own, through the MCP server's getShaderGuide tool, so there is nothing to paste into it.
A compile error shows under the editor with its line. A node whose saved shader does not compile shows an error badge in the graph.