Appearance
Manifest Reference
plugin.json describes the plugin and every node it adds.
Plugin
| Field | ||
|---|---|---|
sdk | required | SDK version the plugin targets. Currently 1. A plugin asking for a newer SDK than the installed Caddis supports won't load, and says so. |
id | required | Lowercase reverse-DNS, unique to you: com.yourname.glowpack. |
name | required | Shown in Manage Plugins and on hover. |
version | required | Semver (1.2.0). The major number is part of every node's identity — see Versions below. |
vendor | Shown on the node's pill. | |
description, website | Shown in Manage Plugins. | |
wasm | Path of the WebAssembly module, for nodes with logic. | |
license | Paid plugins: see Selling Plugins. | |
assets | Textures shipped in the bundle (below). | |
modules | Reusable blocks of passes (below). | |
nodes | required | The nodes (below). |
Versions
A node saved in a project is identified by plugin id, node id and major version (plugin:com.yourname.glowpack/softGlow@1). Minor and patch releases replace the installed version in place: keep param ids stable and add new params with defaults that preserve old looks. Nodes already in a project follow the update straight away, including a live-reloaded dev folder: a param keeps its value while its id and type stay the same, picks up a new label, starts at its default if its type changed, and disappears if you removed it; inputs and outputs are rebuilt, and a wire into a port you removed is disconnected. So never reuse a removed id for something new. A major version is a new node type, so old projects keep using the old one while it stays installed.
Node
| Field | ||
|---|---|---|
id | required | Identifier, unique in the plugin. |
label | required | The node's name in the graph and menus. |
description | Shown in search and the fallback help page. | |
category | The built-in category it's closest to (Effects, Shapes…). Used for search; plugin nodes are listed under Plugins. | |
inputs, outputs | Ports (below). | |
params | Settings (below). | |
time | static (default), animated, history or stateful — see Time and State. | |
maxLookback | History / stateful nodes: how many frames back any pass reads (max 64). | |
bounds | How the output extent relates to the input's (below). | |
textures | Intermediate textures by name (below). | |
state | Textures kept between frames (stateful nodes). | |
buffers | GPU storage buffers by name (below). | |
groups | Sections in Properties (below). | |
gizmos | Handles drawn in the viewer (below). | |
passes | GPU passes, run in order (below). | |
logic | Name of the WebAssembly export that computes the node's points / shapes / values. | |
docs | Help page path (default docs/<id>.md). |
Ports
json
{ "id": "src", "type": "image", "label": "Source" }type is one of image, mask, points, shape, text, string, scalar, vec2, vec3, color. Port ids are identifiers. Your shaders use them by name, so pick something other than reserved words (in is a GLSL keyword; prefer src).
Image ports go to and from passes. Points, shapes and values go to and from logic, and passes can read points too (see Writing Shaders).
Params
json
{ "id": "radius", "type": "float", "label": "Radius", "default": 20,
"min": 0, "softMax": 200, "unit": "px", "group": "Glow", "expose": true }type | Stored as | In shaders | Properties control |
|---|---|---|---|
float | number | f32 | number field |
int | number | i32 | whole-number field |
angle | degrees | f32 radians | number field with ° and a dial |
bool | bool | i32 0 / 1 | checkbox |
enum | the option's text | i32 index into options | menu |
vec2 | x, y | vec2<f32> | linked pair |
point | x, y | vec2<f32> | pair, plus a handle in the viewer |
vec3 | x, y, z | vec3<f32> | triple |
color | r, g, b, a | vec4<f32>, linear, straight alpha | color picker |
string, text, file | text | — (logic only) | field / multi-line / file picker |
gradient, curve | ramp | a 256×1 lookup texture via @param.<id> | gradient / curve editor |
colorCurves | four curves (master, R, G, B) | @param.<id>: each channel's curve applied after the master in .rgb, the master alone in .a | the Curves editor, with the input's histogram |
levels | the Levels values | @param.<id>, laid out like colorCurves | the Levels editor, with the input's histogram |
toneRange | start, end, softness, channel | vec4(start, end, softness, channel), channel 0–3 = Luma / Red / Green / Blue; @param.<id> is the selection weight (0–1) by brightness | range selector over the input's histogram |
trigger | keyframes | f32 frames since the latest key, −1 if none | Fire Here button |
custom | text, in a format you choose | with "bake": a lookup via @param.<id> | a control your plugin draws (optionally over the input's histogram), see Custom Controls |
button | — | — | a button: runs "action" (a WebAssembly export) or "resets" settings to their defaults |
label | — | — | a line of text ("text") |
divider | — | — | a hairline between rows |
Other fields:
| Field | |
|---|---|
label | Defaults to the id, split into words. |
default | A number, [x, y], [r, g, b, a], true / false or a string. Gradients take { "stops": [{ "position": 0, "color": [r,g,b,a] }, …], "interpolation": "linear" }, plus an optional "blendSpace" — the gradient editor's Color Blend: "linearLight" (the default), "srgb", "oklab", "oklch" or "oklchLong"; @param.<id> is baked in it — curves { "points": [{ "position": 0, "value": 1 }, …], "interpolation": "smooth" }, ranges { "lo": 0.5, "hi": 1, "soft": 0.1, "channel": "Luma" }. |
min, max | Hard limits. Values past them are clamped. |
softMin, softMax | Slider range only. Typing past it is allowed. |
step | Drag step. |
unit | Shown after the label: px, %, Hz. |
options | enum choices, in menu order. |
group | The section the row sits in: a declared group's id (see Groups), or any name for a plain section. Rows without a group sit at the top level. Properties keeps your order. |
visibleWhen | An expression (below). The row hides while it's false. |
expose | Adds an E port (<id>_in) so a wire can drive the setting. |
keyframeable | false hides the keyframe diamond. |
tooltip | Hover text. |
extensions | file params: allowed file extensions. |
row | Settings with the same row id, next to each other, share one row in Properties under the first one's label, with one keyframe diamond for all of them. Numbers, angles, toggles and menus only. |
short | In a row: the tag before this field (1–2 characters; default the label's first letter). |
text | label rows: the text. |
action | button: the WebAssembly export to run when pressed (see CPU Logic). |
resets | button: setting ids or group ids to put back to their defaults when pressed, e.g. ["edges"]. No code needed. |
restarts | trigger params on a stateful node: each key restarts the node's state and its replay (see Time and State). |
palettes | gradient params: palettes your plugin ships, listed first in the gradient editor's palette button. Each is shaped like a gradient default: { "stops": [{ "position": 0, "color": [r, g, b, a] }, …], "interpolation": "smooth" }, optionally with a "blendSpace" (see default). |
Point coordinates are composition pixels with the origin at the center of the comp, +y down.
Groups
Sections in Properties. Declare them to fold, nest or hide them; a param's group names one by id.
json
"groups": [
{ "id": "glow", "label": "Glow" },
{ "id": "edges", "label": "Edges", "parent": "glow", "collapsed": true },
{ "id": "grain", "label": "Grain", "visibleWhen": "params.mode == 'Grain'" }
]| Field | |
|---|---|
id | Required. What params' group refers to. |
label | Header text (defaults to the id). |
collapsed | Starts folded. A section opens by itself when a setting inside it changes or is wired, until the user folds it. |
parent | Nests the section inside another. |
visibleWhen | An expression; the whole section hides while it's false. |
label and divider entries in params lay out the panel (a line of help text, a hairline). They have no value and aren't saved with the node, but take group and visibleWhen like any row.
Viewer handles
Every point param gets a draggable handle in the viewer while its node is selected. gizmos add guides tied to params:
json
"gizmos": [
{ "type": "line", "from": "start", "to": "end" },
{ "type": "circle", "center": "center", "radius": "radius" },
{ "type": "angle", "center": "center", "angle": "direction", "length": 80 },
{ "type": "box", "min": "topLeft", "max": "bottomRight" },
{ "type": "custom", "draw": "light_draw", "event": "light_event" }
]| Type | Draws | Drags |
|---|---|---|
line | a line between two point (or vec2) params | both ends |
circle | a circle of a float radius (comp px) around a point | the center; the rim sets the radius |
angle | a dial at a point | the tip sets an angle param (degrees, 0 = right, clockwise). Shift snaps to 15°. length is in screen pixels. |
box | a rectangle between two corner points | both corners |
custom | whatever your draw export returns, see Custom Controls | handles you draw; your event export sets params |
Handle drags keyframe like any edit and are one undo step. A param driven by a wire has no handle.
Textures
json
"textures": {
"half": { "size": { "of": "src", "scale": 0.5 } },
"flow": { "size": { "of": "src", "scale": 0.125 }, "format": "rgba32f" },
"lut": { "size": { "width": 256, "height": 1 }, "format": "r32f" }
}size is relative (of an image input, another texture, or "canvas" — the default — times scale, at most 4), or fixed width/height in pixels. Relative sizes follow quality level and overscan automatically. Add "ignoreQuality": true to a relative size to measure it in composition pixels instead, so it is the same size at Draft, Preview, Full and export: use it for a simulation that steps a fixed number of pixels per frame, so it finishes at the same time at every quality (it costs more at Draft, since the texture doesn't shrink).
format: rgba16f (default, the working format), rgba32f, r32f. 32-bit textures can't be filtered: sample them with samp_point or textureLoad.
Bundled textures (assets)
Images shipped inside the plugin: blue noise, dither matrices, grain plates, lookup tables. Declared once for the whole plugin, read by any pass as @asset.<name>.
json
"assets": {
"blueNoise": { "file": "textures/bluenoise64.png", "filter": "nearest", "wrap": "repeat", "colorSpace": "data" }
}| Field | |
|---|---|
file | PNG, JPEG, TIFF or EXR in the bundle. |
filter | linear (default) or nearest. |
wrap | clamp (default), repeat or mirror. |
colorSpace | srgb (default for 8- and 16-bit images): decoded to linear light like footage. linear: already linear (the default for EXR). data: used exactly as stored, for noise, matrices and lookup tables. |
Assets load as 16-bit float. --protect encrypts them along with your shaders. In GLSL, texture(blueNoise, uv) uses the asset's own filter and wrap. In WGSL, sample with blueNoise_samp.
Buffers
GPU storage buffers, for work that doesn't fit in a texture: histograms, sorting, particle state, counters.
json
"buffers": {
"bins": { "elements": 256, "type": "uint", "atomic": true },
"parts": { "elements": "params.maxParticles", "type": "vec4", "state": true }
}| Field | |
|---|---|
elements | Capacity: a number or an expression. |
type | float, int, uint, vec2 or vec4. |
atomic | int / uint only: the items and the count are atomics, so many invocations can add to them at once. |
state | Kept from frame to frame (stateful nodes), replayed and checkpointed like state textures, so it scrubs correctly. |
A buffer starts each frame zeroed (or, with state, as last frame left it). Each has a count alongside its items, which you can use as an append counter. Passes name buffers as @buffer.<name> in reads or writes. See Writing Shaders for the shader side.
Modules
A module is a block of passes written once and called from any node's pass list, like a function: a blur, a bloom, a sort.
json
"modules": {
"gaussian": {
"params": [{ "id": "radius", "type": "float", "default": 10 }],
"textures": { "across": { "size": { "of": "@in" } } },
"passes": [
{ "shader": "shaders/blur.glsl", "reads": [{ "input": "@in", "as": "img" }], "writes": "across", "defines": { "AXIS": 0 } },
{ "shader": "shaders/blur.glsl", "reads": [{ "input": "across", "as": "img" }], "writes": "@out", "defines": { "AXIS": 1 } }
]
}
}Call it from a node's passes:
json
{ "module": "gaussian", "reads": ["bright"], "writes": "blurred",
"params": { "radius": "params.glowRadius * 0.5" }, "when": "params.glowRadius > 0" }@inis the call's first read (@in.1,@in.2… the others). Unless you rename it withas, its binding name issrc(src1,src2…).@outis what the call writes.- A module's
texturesare private to each call, so two calls never share them."of": "@in"sizes one like the call's input. - Each module param binds to an expression in the caller's scope.
params.<id>alone passes the caller's param whole, including vectors and colors. An unbound param takes its default. - Module params are the value types: numbers, bools, enums, angles, vectors, points and colors. Inside the module's shaders they're the params; the node's own params aren't visible.
- Modules can call other modules, up to 8 deep. They can't use state, buffers,
@paramlookups or the node's textures yet.
Passes
json
"passes": [
{ "shader": "shaders/threshold.wgsl", "reads": ["src"], "writes": "half" },
{ "repeat": "params.iterations", "pingPong": ["half", "half2"], "passes": [
{ "shader": "shaders/blur.wgsl", "reads": [{ "input": "@prev", "as": "prev" }], "writes": "@next",
"defines": { "AXIS": 1 } }
]},
{ "shader": "shaders/composite.wgsl", "reads": ["src", "@last"], "writes": "out" }
]| Field | |
|---|---|
shader | A .wgsl or .glsl file in the bundle. |
kind | fragment (default) or compute. |
reads | Textures the pass samples, in order. Each is a name, or { "input": …, "frame": …, "as": …, "attributes": […] }. |
writes | An image output, a texture, @state.<name>, @next, or (compute) @buffer.<name>. |
defines | Compile-time constants: one shader file, several variants. |
when | An expression. The pass is skipped while it's false. |
workgroup | Compute: workgroup size, default [8, 8]. |
dispatch | Compute: what one invocation is for (below). |
Compute dispatch:
dispatch | Runs | Entry |
|---|---|---|
| (absent) | once per texel of the target, or, for a pass that writes only a buffer, of its first texture read | kernel(p) |
{ "over": "<texture>" } | once per texel of an input, texture, @state.x or @asset.x | kernel(p) |
"<points binding>" | once per point of a @points read | kernel_point(i) |
{ "count": "<expr>" } | i = 0 … count−1 (up to about 4 million) | kernel_index(i) |
{ "countFrom": "@buffer.x" } | i = 0 … x.count−1, read on the GPU (at most the buffer's capacity) | kernel_index(i) |
What a pass can read:
| Name | |
|---|---|
| an image input or texture name | by itself |
{ "input": "src", "frame": -1 } | the input one frame back (history / stateful nodes) |
@state.<name> | last frame's state texture |
@prev | inside a pingPong repeat: the texture the previous iteration wrote (the first one before the loop starts) |
@last | after a pingPong repeat: what its last iteration wrote |
@param.<id> | a gradient, curve, curves, levels or range param as a 256×1 texture (binding <id>_lut) |
@points.<port> | a points / shape input (or logic output) as a storage buffer |
@asset.<name> | a bundled texture |
@buffer.<name> | a storage buffer (compute passes can write it too) |
A pass can't sample the texture it writes. Use a second texture, or pingPong. State is the exception: reading and writing @state.x in one pass is the normal feedback step.
repeat takes an expression (capped at 1,024 iterations). pingPong names two textures. If the second isn't declared, it copies the first's size and format.
Bounds
Caddis sizes each layer's canvas before rendering, so it needs to know whether your node grows its content:
bounds | |
|---|---|
"passthrough" | Output sits where the input does (color effects, distortions within the image). The default for nodes with an image input. |
{ "expand": "params.radius * 3" } | Output can extend this many composition pixels beyond the input on every side (glows, blurs, drop shadows). |
"generator" / "full" | Output fills the comp. The default for nodes with no image input. |
Points and shapes your logic outputs are measured automatically.
Expressions
repeat, when, bounds.expand and visibleWhen use a small expression language: numbers, 'strings', + - * / %, == != < <= > >=, && || !, a ? b : c, and min max clamp floor ceil round abs sqrt pow log2 exp.
Names: params.<id> (vectors also as params.<id>.x / .y / .z / .w or .r / .g / .b / .a; enums as their option text), scale (render pixels per comp pixel), frame, time (seconds), fps (the composition's frame rate, so a per-second rate becomes a count: "repeat": "round(params.stepsPerSecond / fps)"), width, height (comp size), and iteration inside a repeat. frame, time and fps are known to repeat and when; bounds.expand and visibleWhen see only params.
json
"visibleWhen": "params.mode == 'Glow' && params.radius > 0"