Skip to content

Custom Controls ​

When none of the built-in controls fits, a plugin can draw its own: a control in Properties, a handle in the viewer, or both. You write two WebAssembly exports, one that draws and one that handles events, and Caddis does the rest. It frames the control like every other setting (label, keyframe diamond, resize grip), stores the value, keyframes it, and folds a whole drag into one undo step.

examples/custom-ui in the Plugin Kit is a complete example: a Bands control (edge bars, a draggable middle, the input's histogram) and a spotlight handle in the viewer.

Caddis colors only ​

A plugin never picks a color. Every shape is painted with one of Caddis's theme tokens, so plugin controls look like the rest of the app (and follow it if the theme changes):

TokenFor
Textprimary text and strokes
Mutedsecondary text, histograms, inactive marks
Subtletertiary text, grid lines
Edgeborders and dividers
Accentselection and active marks
Keyframeemphasis
Gizmoviewer handles and guides
Insetthe control's sunken background

Every paint also takes an opacity, so you can still build up depth.

A control in Properties ​

json
{
  "id": "bands", "type": "custom", "label": "Bands", "default": "0.4,0.8",
  "draw": "bands_draw", "event": "bands_event", "bake": "bands_bake",
  "height": 96, "resizable": true
}
Field
drawExport that draws the control. Required.
eventExport that handles presses, drags and clicks. Required.
bakeOptional. Export that turns the value into a lookup shaders read through @param.<id>, like a curve.
bakeSizeLookup width in entries (default 256, max 4096).
heightControl height in pixels (default 120).
resizableShows a grip under the control so the user can make it taller.
histogramtrue sends the node's input histogram with every call, so the control can draw it behind its graph (see below).
keysThe keys the control answers while it has keyboard focus, such as ["delete", "left", "right"] (see Keys).

The value is text, and its format is yours: "0.4,0.8", JSON, anything. Caddis stores it and keyframes it (text keys hold until the next key). Read it in your exports with req.param_str("bands", "0.4,0.8") (the second value is the fallback).

rust
use caddis_plugin::*;

fn bands_draw(req: &Request) -> Result<Response, String> {
    let [w, h] = req.ui_size();
    let mut d = DrawList::new();
    d.rect([0.0, 0.0, w, h], 3.0, Paint::fill(Token::Inset));
    d.line([w / 2.0, 0.0], [w / 2.0, h], Paint::stroke(Token::Accent, 1.0));
    d.handle([w / 2.0, 8.0], 5.0, "split");
    Ok(Response::new().draw(d))
}

fn bands_event(req: &Request) -> Result<Response, String> {
    match req.event() {
        Some(Event::Drag { handle, pos, .. }) if handle == "split" => {
            let x = (pos[0] / req.ui_size()[0]).clamp(0.0, 1.0);
            Ok(Response::new().value(&format!("{x:.4}")))
        }
        _ => Ok(Response::new()),
    }
}

Coordinates are control pixels from the top-left. An event can return a new drawing along with the new value, which saves a round trip while dragging. Otherwise Caddis calls draw again once the value changes.

Baking for shaders ​

With bake, shaders read the setting as a lookup texture, the same way they read a curve:

rust
fn bands_bake(req: &Request) -> Result<Response, String> {
    let mut rgba = Vec::with_capacity(256 * 4);
    for i in 0..256 {
        let w = /* your weight for i / 255 */ 0.0;
        rgba.extend_from_slice(&[w, w, w, 1.0]);
    }
    Ok(Response::new().bake(rgba))
}

bake must return exactly bakeSize × 4 numbers (RGBA per entry). In the shader, list "@param.bands" in the pass's reads and sample bands_lut.

Drawing the histogram ​

With "histogram": true, place the node's input histogram behind your graph and Caddis draws it, in the same look as its own Levels, Curves and Range editors:

rust
d.histogram([x, y, w, h], HistogramChannel::Luma);
HistogramChannelDraws
Masterluminance, with red, green and blue as thin lines over it
Lumaluminance alone
Red, Green, Blueone channel, tinted

Nothing is drawn until Caddis has rendered the node once, and it isn't updated during playback. Add it before the marks that should sit on top of it.

For numbers rather than a picture, req.ui_histogram() returns the raw data: 256 bins each of red, green, blue and luminance, normalized 0–1 (None until there is one). The custom-ui example uses it to show how much of the image falls inside its band.

A handle in the viewer ​

json
"gizmos": [{ "type": "custom", "draw": "light_draw", "event": "light_event" }]

This works the same way, but in composition pixels with the origin at the comp center (+y down), which is the space point params use. A handle can't hold a value of its own. Its events set your node's params instead:

rust
fn light_event(req: &Request) -> Result<Response, String> {
    let Some(Event::Drag { handle, pos, .. }) = req.event() else {
        return Ok(Response::new());
    };
    Ok(match handle.as_str() {
        "center" => Response::new().set("center", Value::Vec2(pos)),
        _ => Response::new(),
    })
}

req.ui_scale() is composition pixels per screen pixel. Multiply stroke widths and handle sizes by it so they stay the same size on screen at any zoom.

A node with a custom gizmo owns its viewer handles, so Caddis doesn't add its automatic point handles. Draw a handle for each point you want draggable.

Draw list ​

BuilderDraws
rect(rect, radius, paint)rectangle [x, y, w, h], corner radius
line(a, b, paint)line
polyline(points, closed, paint) / polygon(points, paint)open or closed path
ellipse(center, radii, paint)ellipse
text(pos, text, size, align, paint)text in Caddis's interface font; Align::Left, Center or Right
handle(pos, radius, id)a draggable handle in Caddis's own handle style (a round point)
handle_styled(pos, radius, id, style)a draggable handle that shows what it is (below)
histogram(rect, channel)the node's input histogram, drawn by Caddis (see above)
handle_area(rect, id)an invisible rectangle you can drag by, e.g. the middle of a range to move it whole. Add it before the handles inside it so they stay on top

Handle styles ​

Caddis draws every handle, so plugin graphs match its own editors. Pick the style that says what the handle does:

HandleStyleUse it forIn the viewer
Dota point on a graph (the default)circle
Squarea curve's end points, anchorssquare
Tangenta bezier tangent handlesmall circle
BarVan edge you drag left and righttall bar
BarHan edge you drag up and downwide bar
Hiddena grab area over a mark you draw yourselfnothing drawn

Don't draw your own mark under a visible handle: Caddis's handle covers it. Every style has a grab area of at least 7 px around its center.

Paints: Paint::fill(Token::Accent), Paint::stroke(Token::Muted, 1.0), and .alpha(0.5) on either.

Events ​

EventWhen
Drag { handle, pos, step, phase, mods }a handle is dragged (handle is its id), or the background is (handle is ""). phase is Begin, Move or End; step is the motion since your last event.
Click { pos, mods }a press that didn't move
DoubleClick { pos, mods }a double-click
Wheel { pos, delta, mods }the wheel with ⌥ or ⌘ held (a plain wheel scrolls Properties)
Key { key, handle, pos, mods }a key the setting lists in keys, pressed while the control has focus (see Keys)

mods has shift, alt and command (⌘ on macOS, Ctrl elsewhere).

Caddis may add kinds of event later, so keep a _ => arm in your match.

Keys ​

List the keys your control acts on in its manifest entry:

json
{ "id": "bands", "type": "custom", "draw": "bands_draw", "event": "bands_event",
  "keys": ["left", "right"] }

The keys are delete (Delete and Backspace), escape, enter, left, right, up and down. A control that lists keys takes keyboard focus when the user presses it, and from then on each listed key arrives as an Event::Key. While the control has focus those keys go to your plugin and to nothing else in Caddis, so list only the ones you act on; a key you leave out keeps its usual meaning. A control that lists no keys is never sent one.

Your exports keep nothing between calls, so the event tells you what the key is about:

  • handle is the id of the handle the user last pressed, or "" when the last press was on the background.
  • pos is where the pointer last was with a button down. After a click that added something, that is where the new thing is.
rust
Some(Event::Key { key: Key::Delete, handle, pos, .. }) => {
    // The handle that was pressed, or else whatever was just made at `pos`.
    let index = point_for_handle(&handle).or_else(|| point_near(&points, pos));
    if let Some(i) = index {
        points.remove(i);
    }
    Ok(Response::new().value(&encode(&points)))
}

After a delete, Caddis forgets the handle: if your handle ids are positions in a list, the id that was just deleted may now name the next item, and a second press must not remove that one too. The next key arrives with handle empty and the same pos.

Each key is one undo step. Viewer handles do not take keys.

Moving something by the pointer's motion ​

pos says where the pointer is. To move a value by how far the pointer moved, such as a whole range dragged by its middle, add the drag event's step: the motion since the last event your plugin received. The settings in the request already include every earlier step, so adding the step each time is exactly right, even when Caddis skips moves while the engine is busy.

rust
Some(Event::Drag { handle, step, .. }) if handle == "band" => {
    let dv = step[0] / graph_width;
    let shift = dv.clamp(-lo, 1.0 - hi); // keep the width at the ends
    Ok(Response::new().value(&format!("{},{}", lo + shift, hi + shift)))
}

Good to know ​

  • Calls run in the engine, next to your other logic, so protected plugins stay protected. Only the exports your manifest names can be called.
  • While a drag outruns the engine, Caddis skips intermediate moves and sends only the latest. Begin and End are always delivered, in order.
  • While a control is dragged, the viewer previews at reduced quality (as it does for every built-in slider), so a drag never waits behind a full-quality render.
  • Return the new drawing with an event's value (Response::draw + value): Caddis then skips the redraw call the value change would otherwise make.
  • A drawing holds up to 4,096 items. Text is capped at 200 characters and sizes 4–64 px.