Appearance
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:
plugin.json: the node's ports, settings and list of passes.- 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 original | Because |
|---|---|
#version, precision | Caddis compiles GLSL 4.50 for you. |
uniform declarations | Each setting is declared in plugin.json and arrives under its own name. |
in/out variables, gl_FragColor, fragColor | You return the color instead. |
void main() / mainImage(...) | Replace with vec4 shade(vec2 uv) (fragment) or void kernel(ivec2 p) (compute). |
layout(binding = …) on textures | Every 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 | |
|---|---|
uv | 0–1 across the texture this pass writes. Origin top-left, +y down. |
| Pixel position in render pixels | uv * iTarget |
| Pixel position in composition pixels | uv * iResolution |
A distance of d composition pixels, as uv | d / iResolution |
| Size of one texel of a full-size image input | 1.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:
glslvec4 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 straightBlurs, 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 uniform | plugin.json type | Arrives in GLSL as |
|---|---|---|
float slider | float (add min/max or softMin/softMax, unit) | float |
| whole number | int | int |
| angle | angle (users type degrees) | float, radians |
| checkbox | bool | int, 0 or 1 (test == 1) |
| popup / menu | enum with options | int, the option's index |
vec2 | vec2 | vec2 |
| a position the user drags | point (gets an on-screen handle) | vec2, composition pixels from the center |
vec3 | vec3 | vec3 |
| color | color | vec4, linear, straight alpha |
| gradient / curve lookup | gradient or curve | sample @param.<id> as a 256×1 texture |
Uniforms the host fills in map to built-in values instead:
| Shadertoy / host value | Caddis |
|---|---|
iResolution.xy | iTarget for this pass's pixels, iResolution for composition pixels |
iTime | iTime (composition time, seconds). For "seconds since the layer started", iLayerFrame / iFps. |
iFrame | iFrame (composition frame), or iLayerFrame |
fragCoord | uv * iTarget (remember the y flip for directions) |
fragCoord / iResolution.xy | uv |
iChannel0 | an image input, e.g. src, declared in inputs |
iChannel0 set to "Buffer A" | a declared texture written by an earlier pass |
iMouse | a point param (it gets a handle in the viewer) |
| random seed | iSeed (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#definefor 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 astatetexture. 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". iChanneltextures that are files (noise, LUTs, grain plates) become bundled textures:"assets"inplugin.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
| Original | In Caddis |
|---|---|
texture2D(t, uv) | texture(t, uv) |
textureSize(t, 0) | iTarget (full-size inputs) or iResolution * iScale |
gl_FragCoord | uv * iTarget |
discard | return vec4(0.0); |
| reading a sampler declared as a uniform | it's already declared; just use its name |
bool uniforms in conditions | if (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-pluginThis 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
boundsis set. - [ ] Animated effects scrub backwards correctly.