Skip to content

Porting Shaders ​

How to bring an existing GLSL effect (from Shadertoy, After Effects, OFX, TouchDesigner or your own library) into Caddis. It's written so you can follow it by hand, or hand it to a translation script or an AI model as its rules.

A port produces two things:

  1. plugin.json: the node's ports, settings and list of passes.
  2. One shader file per pass, holding only the body of the shader. Caddis writes the rest.

The GLSL Starter example (examples/glsl-starter in the Plugin Kit) is a working version of everything below: a one-pass Duotone, a Soft Glow built on a reusable blur module, an Ordered Dither reading a bundled texture, a Histogram counted with GPU atomics, and a Spotlight with viewer handles.

The rules ​

1. Write only the body ​

Remove from the originalBecause
#version, precisionCaddis compiles GLSL 4.50 for you.
uniform declarationsEach setting is declared in plugin.json and arrives under its own name.
in/out variables, gl_FragColor, fragColorYou return the color instead.
void main() / mainImage(...)Replace with vec4 shade(vec2 uv) (fragment) or void kernel(ivec2 p) (compute).
layout(binding = …) on texturesEvery texture you read is already a sampler2D named after its port or texture.

Helper functions, #defines and consts in the file stay as they are.

2. Coordinates ​

Caddis
uv0–1 across the texture this pass writes. Origin top-left, +y down.
Pixel position in render pixelsuv * iTarget
Pixel position in composition pixelsuv * iResolution
A distance of d composition pixels, as uvd / iResolution
Size of one texel of a full-size image input1.0 / iTarget

Shadertoy and OpenGL put the origin at the bottom left. Texture reads need no change, because texture(src, uv) reads the same pixel the source would. Only flip when the code means a direction on screen ("up", gravity, a gradient that starts at the bottom): use vec2(uv.x, 1.0 - uv.y) for those calculations.

Use composition pixels for every size a user sets. Caddis renders at Draft (¼), Preview (½) and Full resolution, and adds overscan canvas around layers that grow. A radius divided by iResolution looks identical at every quality level. A radius in raw texels gets four times smaller at Draft.

3. Color and alpha ​

Images come in and must go out as linear light, 16-bit float, straight (unpremultiplied) alpha. Values above 1 are allowed.

  • After Effects 8/16-bit, most OFX hosts, and TouchDesigner usually hand you premultiplied, often gamma-encoded, pixels. If your maths assumes premultiplied, convert on the way in and back on the way out:

    glsl
    vec4 c = texture(src, uv);
    c.rgb *= c.a;                          // premultiply
    // ... your premultiplied maths ...
    return c.a > 0.0 ? vec4(c.rgb / c.a, c.a) : vec4(0.0);   // back to straight
  • Blurs, warps and anything that averages pixels must average premultiplied color, or edges go dark.

  • Looks tuned in gamma space (a threshold at 0.5, a "screen" blend that feels right in AE 8-bit) behave differently in linear light. If the look matters more than physical correctness, convert around that one step: pow(c.rgb, vec3(1.0 / 2.2)) in, pow(x, vec3(2.2)) out.

  • Intermediate textures (ones you declare under textures) hold whatever you write, such as flow vectors, masks or premultiplied color. Only the node's outputs have to be straight alpha.

4. Uniforms → settings ​

Every uniform the user controls becomes a params entry. Its id becomes the variable name in your shader, so keep the original uniform's name unless it collides (see rule 7).

Original uniformplugin.json typeArrives in GLSL as
float sliderfloat (add min/max or softMin/softMax, unit)float
whole numberintint
angleangle (users type degrees)float, radians
checkboxboolint, 0 or 1 (test == 1)
popup / menuenum with optionsint, the option's index
vec2vec2vec2
a position the user dragspoint (gets an on-screen handle)vec2, composition pixels from the center
vec3vec3vec3
colorcolorvec4, linear, straight alpha
gradient / curve lookupgradient or curvesample @param.<id> as a 256×1 texture

Uniforms the host fills in map to built-in values instead:

Shadertoy / host valueCaddis
iResolution.xyiTarget for this pass's pixels, iResolution for composition pixels
iTimeiTime (composition time, seconds). For "seconds since the layer started", iLayerFrame / iFps.
iFrameiFrame (composition frame), or iLayerFrame
fragCoorduv * iTarget (remember the y flip for directions)
fragCoord / iResolution.xyuv
iChannel0an image input, e.g. src, declared in inputs
iChannel0 set to "Buffer A"a declared texture written by an earlier pass
iMousea point param (it gets a handle in the viewer)
random seediSeed (stable 0–1 per node), or a float param

Mark a setting "expose": true and users can drive it from a wire as well as the slider. Put settings in groups (which can start collapsed, nest, and hide with a mode menu), and add label rows for short explanations. See the Manifest Reference.

5. Multiple passes ​

Each Shadertoy buffer, AE render loop step or OFX intermediate becomes a pass:

json
"textures": {
  "bufferA": { "size": { "of": "canvas", "scale": 0.5 } }
},
"passes": [
  { "shader": "shaders/a.glsl", "reads": ["src"], "writes": "bufferA" },
  { "shader": "shaders/image.glsl", "reads": ["src", "bufferA"], "writes": "out" }
]
  • Passes run in order. A pass can't read the texture it writes; use a second texture.
  • One shader file can serve several passes: "defines": { "AXIS": 0 } sets a #define for that pass, and { "input": "bufferA", "as": "img" } renames what it reads.
  • Loops of the same pass (iterative blurs, relaxation) use repeat + pingPong. See the Manifest Reference.
  • A Shadertoy buffer that reads itself from last frame is feedback. Use "time": "stateful" and a state texture. See Time and State.
  • Steps you use in several effects (a blur, a bloom) become a module: written once, called from any node's pass list with its own settings. See the Manifest Reference.
  • Helper functions shared between shader files go in a file of their own, pulled in with #include "lib/helpers.glsl".
  • iChannel textures that are files (noise, LUTs, grain plates) become bundled textures: "assets" in plugin.json, read as @asset.<name>.
  • Histograms, sorts and particle buffers use storage buffers, with the usual GLSL atomicAdd / atomicMax. See Writing Shaders.

6. Bounds ​

If your effect draws outside the source (glows, blurs, shadows, displacements), add "bounds": { "expand": "<comp px>" }, e.g. "params.radius * 1.5". Without it, Caddis sizes the layer to the source and crops the outside. Color effects need nothing.

7. Names ​

Settings, ports and textures become identifiers in your shader. They can't be GLSL built-in names (mix, step, length, smooth…) or keywords (in, out, input…), and these are reserved: params, builtins, samp, samp_point, dst, uv, shade, kernel, anything starting with _caddis. Caddis refuses a clashing name and tells you which one. Prefer src for the main image input.

8. GLSL that needs changing ​

OriginalIn Caddis
texture2D(t, uv)texture(t, uv)
textureSize(t, 0)iTarget (full-size inputs) or iResolution * iScale
gl_FragCoorduv * iTarget
discardreturn vec4(0.0);
reading a sampler declared as a uniformit's already declared; just use its name
bool uniforms in conditionsif (flag == 1)

Before and after ​

A Shadertoy-style chromatic split:

glsl
// Original
uniform sampler2D iChannel0;
uniform vec3 iResolution;
uniform float amount;   // pixels
void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    vec2 uv = fragCoord / iResolution.xy;
    vec2 off = vec2(amount / iResolution.x, 0.0);
    float r = texture(iChannel0, uv + off).r;
    float g = texture(iChannel0, uv).g;
    float b = texture(iChannel0, uv - off).b;
    fragColor = vec4(r, g, b, 1.0);
}
glsl
// Caddis: shaders/split.glsl
vec4 shade(vec2 uv) {
    vec2 off = vec2(amount / iResolution.x, 0.0);   // comp px → uv, same at every quality
    vec4 c = texture(src, uv);
    float r = texture(src, uv + off).r;
    float b = texture(src, uv - off).b;
    return vec4(r, c.g, b, c.a);                     // keep the source's alpha
}
json
{
  "sdk": 1, "id": "com.you.split", "name": "Split", "version": "1.0.0", "vendor": "You",
  "nodes": [{
    "id": "split", "label": "Chromatic Split", "category": "Effects",
    "inputs":  [{ "id": "src", "type": "image", "label": "Source" }],
    "outputs": [{ "id": "out", "type": "image" }],
    "params":  [{ "id": "amount", "type": "float", "default": 8, "min": 0, "softMax": 100, "unit": "px", "expose": true }],
    "bounds":  { "expand": "params.amount" },
    "passes":  [{ "shader": "shaders/split.glsl", "reads": ["src"], "writes": "out" }]
  }]
}

What changed: the uniforms and mainImage are gone, iChannel0 became the src input, amount moved to params, the alpha now passes through instead of being forced to 1, and bounds lets the red and blue fringes spread past the source.

Checking a port ​

sh
cadmium-engine plugin check ./my-plugin

This compiles every shader and reports errors with the file, line and column of your source, with the same output as Manage Plugins. A translation script can run it after each conversion and feed the errors back to fix. For live tuning, add the folder with Plugins › Manage Plugins… › Developer › Add Development Folder…: Caddis reloads on every save.

Then check by eye, in Caddis:

  • [ ] Same look at Draft, Preview and Full quality.
  • [ ] Transparent edges stay clean (no dark fringe), so the alpha is straight on output.
  • [ ] Nothing is cropped when the effect spreads past the source, so bounds is set.
  • [ ] Animated effects scrub backwards correctly.