Rings, Pips, and Fields

The model#

A Base (exactly one) encodes the value: a filled arc, discrete zones, or a color morph. Overlays (any number) sit on top, and there are only two kinds: a Pip, one positioned element, and a Field, a brightness texture across a lit region. Everything that looks like a different animation (a cursor, a comet, a ping, a shimmer) is a parameterization of those two. The catch pip for pot catch paints last within a declarative ring: a Custom ring gets none, and overdraw callbacks, OnRender, and the param-lock overlay all paint after it.

Consider some of these best practices, but do as you please:

Two ways to author a ring. Declarative: pick a ring style on the knob and the SDK renders it. Compositional: take the ring over with a callback and stack the primitives yourself. Both run on the same rendering core, so a firmware can mix them per ring.

Ring styles#

The declarative catalog: each style is one .Ring(...) call on a VirtualKnob.

Level

Basic, but beautiful. A filled arc grows from the ring's edge: the standard "how much" bar.

/* Plain level, no motion. */
static VirtualKnob mix   = VirtualKnob(0, "Mix")
    .Ring(Level(kAmber));

/* Pulsing fill over a faint unfilled region, 60% depth. */
static VirtualKnob decay = VirtualKnob(1, "Decay")
    .Ring(Level(kViolet, FillAnim::Pulse)
              .Passive({0x14, 0x08, 0x1C})
              .Depth(0.6f));

Bipolar

A two-color fan for signed values: one arm color above the pivot, another below. Boost/cut gains and pan positions live here.

/* Boost / cut around center detent. */
static VirtualKnob gain = VirtualKnob(2, "Gain")
    .Ring(Bipolar(kBoostGreen, kCutBlue, kCenterGrey));

/* Asymmetric range: pivot at 25% of travel. */
static VirtualKnob env  = VirtualKnob(3, "Env Amt")
    .Ring(Bipolar(kPos, kNeg, kZero).Pivot(0.25f));

Selector

Discrete zones for mode knobs: the active zone lights in the selected color, the other zones stay dark. ZoneGeometry chooses whether zones spread across the whole arc or light as contiguous regions.

static const char* kModes[3] = {"Series", "Parallel", "Spectral"};

static VirtualKnob mode = VirtualKnob(4, "Routing")
    .Selector(3)
    .Ring(SelectorRing(kActive, kOff, 3, ZoneGeometry::Region))
    .Labels(kModes, 3);          /* names surface in the web editor */

Gradient

A filled arc whose color morphs between snap points as the knob sweeps: the fill saturates toward each snap's color as the value approaches it, and dim markers sit at the snap positions so you can find them by feel. Built for engine and model pickers that morph rather than switch. Pair it with GradientSnapPip for a lit confirmation when the value lands on a snap.

static constexpr MorphSnapPoint kEngines[4] = {
    {0.f,      kDigiTeal},
    {1.f / 3,  kBbdAmber},
    {2.f / 3,  kTapeRust},
    {1.f,      kVinylViolet},
};

static VirtualKnob engine = VirtualKnob(0, "Engine")
    .Ring(Gradient(kEngines, 4))
    .Pip(GradientSnapPip());     /* lights in the morph color on a snap */

GradientFill

A plain level fill that wears a sibling knob's gradient color. The classic use: a depth or amount knob tinted by its companion's engine, so related controls read as one voice.

/* Depth's fill color follows the Engine knob (pot 0). */
static VirtualKnob depth = VirtualKnob(3, "Depth")
    .Ring(GradientFill(kEngines, 4, /*src_pot=*/0, kFallback));

Pips on any ring#

Independent of the arc style, every knob can paint the off-arc bottom LED as a marker. SolidPip is a fixed indicator; ThresholdSnapPip watches the value and switches color inside a window, the natural unity-gain or detent marker.

/* White at the 12 o'clock detent window, red when pushed past. */
static VirtualKnob drive = VirtualKnob(5, "Drive")
    .Ring(Level(kDriveOrange))
    .Pip(ThresholdSnapPip(kWhite, 0.45f, 0.55f, kRed));

And one pip belongs to the system: the catch pip. After a page switch it marks where the stored value waits, painted by the declarative renderer as the last step of that ring. A Custom ring skips the renderer, so it gets no catch pip, and everything ControlLoop paints afterwards (overdraw callbacks, OnRender, the param-lock overlay) lands on top of it.

A Custom ring can still draw one: pass the Pager as the ring's ctx, ask it for State(page, pot), and either call DrawCatchPip(panel, pot, ps, geo, kWhite) or hand the same PotState to the three-argument RingFrame::Emit(panel, pot, ps), which paints it as the top layer.

Fields: brightness as motion#

A Field never adds an element. It modulates the brightness of an already-lit region: the LEDs keep their color while their level breathes, ripples, twinkles, stutters, or bands. The declarative FillAnim::Pulse and Ripple are presets over this same math; composition opens the full set.

Consider driving the amount with an envelope, not a constant. It's cool.

Composition: RingFrame#

When a ring needs a second signal, take it over. A Custom ring replaces the declarative render; an Overdraw layers after it. Either way you compose a RingFrame: begin, stamp a base, stack overlays, emit.

RingFrame f;
f.Begin(geo);
f.Base(fill, value);
f.Field(Region::Active, FieldShimmer(), wet_env, t_ms);
f.Pip(Region::Full, playhead, pos01);
f.Emit(panel, pot);

Overlays target regions the base stamped, in region-relative 0..1 positions, never LED indices, so a composition ports across ring geometries: Full (the whole arc), Active (the lit value region), Passive (tip to end), BottomPip, or a custom Span.

A pip's parameters are where the classic looks come from:

The shipped composition to copy is examples/ring_demo, a stereo tremolo whose rings render the LFO itself. The audio callback publishes the LFO phase once per block; the rate ring layers a bouncing comet over a dim value fill:

static void RateOverdraw(LedPanel& panel, uint8_t pot,
                         const ArcGeometry& geo, float norm,
                         uint32_t t_ms, void* /*ctx*/)
{
    RingFrame f;
    f.BeginOverlay(geo);

    FillDesc fill;                       /* re-draw the dim value fill:  */
    fill.color = LedPanel::Scale(kRateColor, 0.35f);
    f.Base(fill, norm, t_ms);            /* frames compose on contents   */

    PipDesc comet;
    comet.color          = kRateColor;
    comet.compose        = PipCompose::Add;
    comet.motion         = PipMotion::Bounce;
    comet.smooth         = true;
    comet.tail_intensity = 0.25f;
    f.Pip(Region::Full, comet, 2.0f * g_lfo_phase01);

    f.Emit(panel, pot);
}

static VirtualKnob rate = VirtualKnob(0, "Rate")
    .Ring(Level(LedPanel::Scale(kRateColor, 0.35f)))
    .Overdraw(RateOverdraw);

And the depth ring goes fully custom: a value fill, a Carve notch sweeping at the LFO phase, and a shimmer whose amount follows the depth, so the ring literally shows what the tremolo does to the signal.

static void DepthRing(LedPanel& panel, uint8_t pot,
                      const ArcGeometry& geo, float norm,
                      uint32_t t_ms, void* /*ctx*/)
{
    RingFrame f;
    f.Begin(geo);

    FillDesc fill;
    fill.color = kDepthColor;
    f.Base(fill, norm, t_ms);

    PipDesc notch;                       /* darkness as an element */
    notch.compose = PipCompose::Carve;
    notch.motion  = PipMotion::Bounce;
    notch.smooth  = true;
    f.Pip(Region::Active, notch, 2.0f * g_lfo_phase01, norm);

    f.Field(Region::Active, FieldShimmer(70u), 0.3f * norm, t_ms);

    f.Emit(panel, pot);
}

static VirtualKnob depth = VirtualKnob(1, "Depth")
    .Ring(Custom(DepthRing));

Stateful animators#

Two effects (as of now) need memory: Sparkle spawns and decays scattered sparks across a ring, suited to noise-like and granular states; BeatPip flashes the bottom pip in tempo. Both keep caller-owned state structs and compose alongside the normal stack.

The full parameter tables, region semantics, and migration notes live in ring-animations.md. For how rings slot into the frame and where Overdraw runs, Firmware Anatomy has the render order.