Skip to content

Writing Shaders ​

Each pass is one shader file. You write only the body: Caddis generates the bindings, uniforms, defines and entry point around it, so your bindings can never drift from the pipeline.

Fragment passes ​

Write a shade function that returns the color at uv (0–1 across the texture the pass writes, origin top-left).

wgsl
fn shade(uv: vec2<f32>) -> vec4<f32> {
  let c = textureSample(src, samp, uv);
  return vec4<f32>(c.rgb * params.gain, c.a);
}
glsl
vec4 shade(vec2 uv) {
    vec4 c = texture(src, uv);
    return vec4(c.rgb * gain, c.a);
}

The language comes from the file extension: .wgsl, or .glsl / .frag / .comp. GLSL is GLSL 4.50, converted to WGSL when the plugin loads. Most fragment and compute code works unchanged. Report anything that doesn't convert to us. Don't write #version, uniforms or main.

What's available ​

WGSLGLSL
Your paramsparams.<id><id>
Textures you readby their binding nameby name, already a sampler2D: texture(src, uv), texelFetch(src, p, 0)
Linear / nearest samplerssamp, samp_point(chosen for you)
Canvas size, comp pxbuiltins.iResolutioniResolution
Composition sizebuiltins.iCompiComp
This pass's target size, pxbuiltins.iTargetiTarget
Seconds / framebuiltins.iTime, builtins.iFrameiTime, iFrame
Frames since the layer startedbuiltins.iLayerFrameiLayerFrame
Render px per comp pxbuiltins.iScaleiScale
Repeat iteration / countbuiltins.iIteration, builtins.iIterationsiIteration, iIterations
Frame ratebuiltins.iFpsiFps
Stable per-node random 0–1builtins.iSeediSeed
Index dispatch size ("count")builtins.iCountiCount
Comp px (center origin) → canvas uvcaddis_to_uv(p)caddis_to_uv(p)

iResolution is the canvas, which is larger than the comp when the layer has overscan. uv * iResolution gives composition pixels at every quality level, so effects look the same at Draft, Preview and Full. Multiply pixel distances by iScale when you need render pixels.

Curves, Levels and range settings ​

These settings reach a shader as a 256-wide lookup texture read through @param.<id> (binding <id>_lut). Sample it at the value you want to remap:

glsl
// curves / levels: per-channel remap, the master curve already applied
vec3 graded = vec3(texture(tone_lut, vec2(c.r, 0.5)).r,
                   texture(tone_lut, vec2(c.g, 0.5)).g,
                   texture(tone_lut, vec2(c.b, 0.5)).b);
// range: how selected this brightness is (0–1)
float luma = dot(c.rgb, vec3(0.2126, 0.7152, 0.0722));
float w = texture(pick_lut, vec2(luma, 0.5)).r;

A toneRange setting is also a vec4 param: pick.x start, .y end, .z softness, .w the channel the user picked (0 Luma, 1 Red, 2 Green, 3 Blue), so you can choose what to measure before sampling. Each of these editors draws your node's first image input as a histogram.

Shared code: #include ​

Put helper functions in their own files and include them, in WGSL or GLSL:

glsl
#include "lib/noise.glsl"

Paths are looked up next to the including file first, then from the bundle root. Each file is included once per pass, however many files ask for it, so helper libraries can include each other freely. Errors point at the real file and line.

Bundled textures ​

A read of @asset.<name> binds the texture under its name. In GLSL, texture(blueNoise, uv) uses the asset's own filter and wrap (say repeat + nearest). In WGSL, sample with its own sampler: textureSample(blueNoise, blueNoise_samp, uv). To tile a texture in pixels, scale uv: texture(blueNoise, uv * iTarget / 64.0) repeats every 64 render pixels.

Color and alpha ​

Images are linear light, 16-bit float, with straight (unpremultiplied) alpha, both coming in and going out. Values above 1 are fine (HDR). Intermediate textures hold whatever you write. Use them for data such as flow vectors and masks.

Names to avoid ​

Params, textures and defines become identifiers in your shader. Caddis refuses names that collide with the language: a GLSL param called mix would hide mix(), and in is a keyword. It also reserves params, builtins, samp, samp_point, dst, uv, shade, kernel and anything starting with _caddis. Use "as" in reads to rename a texture.

Compute passes ​

"kind": "compute" runs once per texel of the target, which you write with textureStore:

wgsl
fn kernel(p: vec2<i32>) {
  let c = textureLoad(src, p, 0);
  textureStore(dst, p, c * params.gain);
}
glsl
void kernel(ivec2 p) {
    imageStore(dst, p, texelFetch(src, p, 0) * gain);
}

In compute passes, sample with textureSampleLevel / textureLoad (WGSL) or textureLod / texelFetch (GLSL).

Points in a pass ​

A pass can read a points or shape input — or points your node's own logic produced — as a buffer:

json
{ "shader": "splat.wgsl", "kind": "compute", "dispatch": "pts",
  "reads": [{ "input": "@points.particles", "as": "pts", "attributes": ["scale", "color"] }],
  "writes": "canvas" }

Each point has pos (composition pixels, center origin), id, index, and one vec4 per requested attribute (scalars in .x). Missing attributes read as scale / opacity = 1, color = white, and everything else 0.

wgsl
// Fragment: loop over the set.
for (var i = 0u; i < pts.count; i = i + 1u) {
  let q = pts.items[i];
  // ... caddis_to_uv(q.pos), q.color, q.scale.x
}

// Compute with "dispatch": once per point.
fn kernel_point(i: i32) {
  let q = pts.items[i];
  textureStore(dst, vec2<i32>(caddis_to_uv(q.pos) * builtins.iTarget), q.color);
}
glsl
// GLSL names the set's members pts_count and pts_items[i].
for (uint i = 0u; i < pts_count; i++) {
    vec2 uv2 = caddis_to_uv(pts_items[i].pos);
}

void kernel_point(int i) {
    imageStore(dst, ivec2(caddis_to_uv(pts_items[i].pos) * iTarget), pts_items[i].color);
}

Point reads are current-frame only.

Buffers ​

A pass that names @buffer.<name> binds it. A buffer is a count and an array of items:

WGSLGLSL
The itemshist.items[i]hist_items[i]
The counthist.counthist_count
Atomic add ("atomic": true)atomicAdd(&hist.items[i], 1u)atomicAdd(hist_items[i], 1u)

Compute passes can read and write buffers. Fragment passes read them as plain values, which is how you draw what a compute pass gathered.

With "atomic": true, GLSL's atomicAdd, atomicMin, atomicMax, atomicAnd, atomicOr, atomicXor and atomicExchange work on name_items[i] and name_count, and plain reads and writes stay atomic. In WGSL the items and count are atomic<u32> (or atomic<i32>): use atomicAdd(&b.items[i], v), atomicLoad(&b.count) and so on.

A complete histogram:

json
"buffers": { "bins": { "elements": 256, "type": "uint", "atomic": true } },
"passes": [
  { "shader": "count.glsl", "kind": "compute", "reads": ["src"], "writes": "@buffer.bins" },
  { "shader": "draw.glsl", "reads": ["src", "@buffer.bins"], "writes": "out" }
]
glsl
// count.glsl: once per texel of src (the pass writes only a buffer)
void kernel(ivec2 p) {
    float luma = dot(texelFetch(src, p, 0).rgb, vec3(0.2126, 0.7152, 0.0722));
    atomicAdd(bins_items[uint(clamp(luma, 0.0, 1.0) * 255.0)], 1u);
}

To run once per element, use "dispatch": { "count": "256" } or { "countFrom": "@buffer.parts" } with void kernel_index(int i). countFrom reads the count on the GPU, so a pass can append with atomicAdd(parts_count, 1u) and the next pass runs over exactly what was appended. The example plugin's Histogram node is all of this working together.

Errors ​

Every shader is compiled when the plugin loads. Errors show in Manage Plugins and in plugin check with the file, line and column of your source, never the generated parts. A shader the GPU driver rejects at render time is reported in the status console, and the node outputs nothing.