ISF Shader Viewer

examples/isf-example loads any ISF (Interactive Shader Format) shader at runtime, parses its input declarations, and auto-generates the parameter UI — no Rust code required per shader.

cargo run -p isf-example

The engine starts immediately with the last-loaded shader. On first launch it defaults to the bundled ColorCycle.fs. Use the Load Shader... button inside the control window to pick any .fs or .frag file — the shader swaps within one frame and the control tab updates its name and sliders to match.

What is ISF?

ISF is an open standard that wraps a GLSL fragment shader in a JSON header declaring its inputs:

/*{
    "CREDIT": "by VIDVOX",
    "ISFVSN": "2",
    "CATEGORIES": ["Glitch", "Retro"],
    "INPUTS": [
        { "NAME": "inputImage", "TYPE": "image" },
        {
            "NAME": "noiseLevel",
            "TYPE": "float",
            "MIN": 0.0, "MAX": 1.0, "DEFAULT": 0.5
        },
        {
            "NAME": "rollAmount",
            "TYPE": "float",
            "MIN": -1.0, "MAX": 1.0, "DEFAULT": 0.0
        }
    ]
}*/

void main() {
    // ... GLSL fragment body ...
}

The JSON header is everything between /*{ and }*/. The rest is plain GLSL. ISF is supported natively by Resolume, VDMX, and many other VJ tools — there is a large community library at editor.isf.video.

Bundled shaders

The example ships with ~50 shaders in examples/isf-example/shaders/. They cover a range of styles: generative patterns, video processing, glitch, and feedback effects. Good ones to start with:

FileWhat it does
Bad TV.fsVHS noise, roll, and scan-line glitch (requires video input)
WarpTunnel.fsPsychedelic tunnel with speed and twist controls
GlitchBlocks.fsBlock-shift RGB glitch
FractalZoom.fsContinuous fractal zoom
AuroraWaves.fsFlowing aurora borealis effect
NeonPulse.fsNeon glow rings
CellularLife.fsConway-style cellular automata

How the viewer works

Startup

On launch the viewer:

  1. Reads ~/.config/rustjay/isf-last-shader.txt — if it exists and the file is still on disk, that shader is loaded
  2. Falls back to the bundled ColorCycle.fs on first launch or if the saved path is gone
  3. Parses the ISF JSON header with the isf crate
  4. Builds a Vec<ParameterDescriptor> from the declared inputs — these drive the auto-generated UI and the engine's LFO / MIDI / OSC systems
  5. Creates an IsfEffect that owns the parsed data and starts the engine

Switching shaders at runtime

The Load Shader... button at the top of the ISF tab opens a native file picker. Picking a new file writes the path into a shared Arc<Mutex<Option<PathBuf>>>. On the next prepare() call the effect picks up the path, rebuilds the pipeline, and signals the engine to refresh the parameter list via parameters_dirty(). The tab label hot-reloads to the new shader's filename within one frame.

The chosen path is saved to ~/.config/rustjay/isf-last-shader.txt so the next launch picks up where you left off.

File hot-reload

While the app is running, edit any .fs file in your editor and save. IsfEffect::prepare() polls the file's mtime each frame and re-transpiles automatically when it changes — no button press needed. Useful for iterating on shader code live.

Transpilation

GLSL can't run on wgpu directly — the engine compiles it to WGSL at startup inside IsfEffect::init(). The pipeline (rustjay_isf::compile):

  1. Generates a GLSL prelude that defines the ISF builtins: an IsfData uniform block (TIME, TIMEDELTA, FRAMEINDEX, RENDERSIZE, DATE, PASSINDEX), an IsfInputs block with one std140 field per typed input, a shared sampler, and one texture2D per image/audio input. IMG_* sampling macros are inlined as texture expressions; gl_FragColor and legacy texture2D() are adapted automatically.
  2. Compiles GLSL → SPIR-V with shaderc (Vulkan 1.2 target).
  3. Converts SPIR-V → WGSL with naga (spv-in → validate → wgsl-out), then re-parses and re-validates the WGSL so a broken shader fails at cargo test, not at GPU init.

Coordinate convention: ISF is bottom-left origin, so the vertex stage Y-flips isf_FragNormCoord (and gl_FragCoord), and texture sampling flips back — IMG_THIS_PIXEL(inputImage) reads the same physical pixel of the input frame.

Auto-generated parameters

Each ISF input type maps to a parameter kind:

ISF typeWidgetNotes
floatSliderUses MIN/MAX/DEFAULT from the header
boolCheckbox
long (int)Integer slider
image(none)Bound to the engine's live video input automatically (1×1 black when unconnected)
color(none yet)DEFAULT reaches the shader via state (name_r/g/b/a); no UI widget yet
point2D(none yet)DEFAULT reaches the shader via state (name_x/y); no UI widget yet

Parameters declared this way become full first-class engine parameters: they can be targeted by LFOs, mapped to MIDI CC, addressed over OSC, and saved in presets — without any extra code.

Custom pipeline

Because ISF's binding layout differs from the engine's standard layout, the viewer uses a custom render pipeline (see Frame History & Custom Pipelines for the general pattern):

  • shader_source() returns a minimal passthrough stub — the engine compiles it but never runs it
  • init() compiles the real compiled WGSL pipeline (vertex stage generated to match the fragment's declared inputs)
  • a companion .vs beside the shader becomes the vertex stage, if it is an ISF one — see below
  • render() std140-packs and uploads uniforms (real TIME, TIMEDELTA, FRAMEINDEX, DATE), then draws once per PASSES entry — each with its own PASSINDEX and bind group — and returns true

Companion vertex shaders

A shader may ship Whatever.vs beside Whatever.fs. The VIDVOX blur, sharpen and optical-flow families use it to precompute neighbour coordinates (left_coord, right_coord, …) once per vertex and read them back as varyings — without it those varyings are zero and every neighbour tap lands on the same texel.

The host supplies isf_vertShaderInit() (and its legacy vv_ spelling), which sets gl_Position and isf_FragNormCoord; the vertex stage also sees RENDERSIZE, PASSINDEX and the shader's inputs. Varying locations come from the fragment stage, so the two agree. A .vs that is not an ISF one, or that fails to compile, is ignored and the generated vertex stage is used — the shader still runs.

Multi-pass and PERSISTENT buffers

A pass with a TARGET renders into its own offscreen texture, which any pass can sample by that name. The last pass always reaches the engine's output: either it has no TARGET (the usual shape) or it has one and its buffer is copied to the output afterwards — which is what makes a one-pass feedback shader like Test-PersistentBuffer show anything at all.

WIDTH / HEIGHT size a target: numbers, $WIDTH, $HEIGHT, $someInput, arithmetic, and floor / min / max. Anything else falls back to the render size. RENDERSIZE inside a pass is that pass's own target, so a shader sampling a quarter-res buffer by pixel coordinate lands where it means to.

A PERSISTENT target is double-buffered: a pass writes this frame's half while every sample of that target reads last frame's. That is what makes feedback work, and it makes a delay line fall out for free — buf2 <- buf1, buf1 <- inputImage leaves buf2 two frames behind, whatever order the passes are in. A non-persistent target is a within-frame temporary instead: it reads back as whatever an earlier pass wrote this frame, and the pass that renders into it samples black (that would be a read of its own attachment).

The engine has a single video input, so every image input of a shader is bound to it — a two-input shader (a datamosh driven by a motionImage, a transition) would otherwise be dead in the water with a black second input.

shaders/Delta.fs is the worked example — four chained persistent buffers give it the RGB frame delays that the delta example gets from a Rust ring buffer.

Known limitations

The compiler handles the vast majority of stock ISF shaders (~96% of the VIDVOX test corpus compiles), but some won't load:

  • Array-typed varyings (e.g. convolution shaders declaring varying vec2 texOffsets[5]) — WGSL can't express array-typed stage IO; these fail at compile time.
  • IMPORTED images — declared and bound to a placeholder texture, but not loaded yet.
  • Pass FLOAT — every PASSES target is allocated in the engine's working format, so a shader asking for a float intermediate still runs, just not at the precision it asked for. WIDTH / HEIGHT are honoured.
  • MadMapper-dialect .vs files (in_Vertex, modelViewProjectionMatrix) — rejected, and the shader falls back to the generated vertex stage. ISF-dialect ones (isf_vertShaderInit()) are used.
  • audio / audioFFT inputs — placeholder-bound, no live audio data yet.
  • A small number of shaders with constructs glslang/naga reject (unguarded redefinitions of GLSL builtins like round, and 2 files hitting a naga SPIR-V frontend bug).

An ISF download unzips to a bundle folder named Whatever.fs, holding Whatever.fs.fs and often a .vs and sample images. Open either the folder or the .fs inside it.

If a shader fails, the output window shows black and the tab name displays the error message.

Getting more shaders

The ISF community library at editor.isf.video has hundreds of free shaders. Download any .fs file and open it with the file picker. Shaders tagged generator run without video input; shaders tagged filter or transition expect a live video source connected in the Input tab.

Shadertoy shaders often work too if they use the mainImage entry-point pattern — download the GLSL, add a minimal ISF header, and load it:

/*{
    "ISFVSN": "2",
    "INPUTS": []
}*/

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    // paste Shadertoy code here
    // iTime → TIME, iResolution → RENDERSIZE, iChannel0 → inputImage
}