Skip to content

Stage 7 The UI

Radu Mailat edited this page Nov 3, 2026 · 1 revision

How a 240×240 screen with no frame buffer, 14 buttons, 7 encoders and 27 keys become a tracker: the frame, drawing in bands, input as edges and holds, the views, the keys as a mono synth, editing safely while the song plays, undo and the clipboard. Files: firmware/src/app/ui.c (all of it), firmware/src/app/ui_pat.c (all of it), and in firmware/src/app/ui_views.c: the top (song_loaded, save_song), ord_input, ins_input, songs_input, stage_log, and the shared input at the end (views_input, views_draw). firmware/src/gfx.c for the drawing primitives.

By the end you should be able to organise an embedded UI as state + input dispatch + pure drawing, and draw a rich screen with little RAM.

1. The shape of the UI

Read the header comment of ui.c. The UI is:

  • One state struct, ui, with everything the UI knows: the view, the cursor (order, row, channel), the instrument the keys play, edit mode, the block selection, each view's own cursor, the message line, button timings, the keys held, the stage view's history.
  • Input: input() reads the panel and dispatches to the current view's *_input() function.
  • Drawing: views_draw() dispatches to the current view's *_draw() function. Drawing never changes state.
  • A frame: ui_frame() = input, then (every 33 ms) draw, then LEDs.
enum { V_PAT, V_STAGE, V_ORD, V_SONG, V_INS, V_LIB, V_SONGS, V_SETUP, V_INTRO, NVIEW };

Nine views, each a pair of functions, and two switch statements to dispatch them. Navigation is go(v), which runs the old view's view_leave() (save the settings when leaving SETUP, end an audition when leaving the library), sets the view and starts a wipe. A button pressed twice toggles between paired views (HOME: pattern ↔ stage, SEQ: orders ↔ song, GLO: songs ↔ setup).

This is a small state machine plus immediate-mode drawing: every frame redraws the whole screen from state, so there's no "update this label" code and no way for the screen to drift from the state.

2. Drawing with no frame buffer

A 240×240 RGB565 frame buffer is 115 KB. The FM-1 can't spare it. So gfx.c draws into a canvas of 240×80 pixels (a third of the screen, 38 KB), sends it to the LCD by DMA, and draws the next third. ui.c wraps that into bands:

static void draw_all(void)
{
    for (y = 0; y < 240; y += 80) {
        band_begin(y);                 /* a canvas for rows y .. y+79 */
        if (ui.view != V_INTRO) draw_header();
        views_draw();                  /* the whole view, in screen coordinates */
        wipe_mask();
        if (set.crt) crt_lines();
        cv_blit(0, (uint32_t)y);       /* DMA it out */
    }
}

Every view draws itself three times per frame, in screen coordinates, and the canvas clips what falls outside the current band. band_begin sets the canvas's vertical offset (cv_oy = -y0) so drawing code never needs to know which band it's in. To save time, drawing functions skip work that can't touch the band:

static int band_has(int32_t y, int32_t h) { return y + h > band_y0 && y < band_y0 + 80; }
static void rect(int32_t x, int32_t y, int32_t w, int32_t h, uint16_t c)
{
    if (band_has(y, h))
        cv_rect(x, y, w, h, c);
}

This is why the header comment says a view "must not change anything while drawing": it's called three times, and anything it changed would change three times.

Two canvases, used in turn. cv_begin() flips between cv_buf[0] and cv_buf[1]. While the DMA sends one band, the CPU draws the next into the other. lcd_blit() only waits for the previous transfer before starting a new one. That's double buffering at the band level, and it's why the UI is smooth despite drawing everything every frame.

The tradeoff to notice: 76 KB of canvases instead of 115 KB of frame buffer, at the cost of running the drawing code three times. CPU for RAM. On a device with spare RAM and a slow CPU, you'd choose the opposite.

Pixels and colours

RGB(r, g, b) packs 8-bit components into RGB565 (5 bits red, 6 green, 5 blue: the eye is most sensitive to green). The canvas stores pixels byte-swapped (swap16) because the LCD takes them big-endian and the DMA sends bytes in memory order. mixc(a, b, t) blends two RGB565 colours by unpacking the components, interpolating and repacking, which is how every gradient, glow and highlight is made.

Text uses fonts generated by tools/gen_font.py: proportional glyphs with 4-bit anti-aliasing, run-length packed. cv_text() blends each pixel's coverage over what's already on the canvas, so text on a coloured box has no dark fringe.

Themes

typedef struct {
    const char *name;
    uint16_t bg, panel, line, dim, text, acc, hi, sel, play, rec;
    uint16_t cu0, cu1;
    uint16_t chan[10];
} theme_t;

Every colour on screen comes from the current theme through a role name (th->acc, th->rec, th->chan[ch]), never a literal. Six themes, including high-contrast and Okabe–Ito colour-blind-safe ones. Name colours by role, not by hue, and accessibility becomes a table entry.

Eye candy, cheaply

The 16-bit-console look is built from a few tiny effects, each worth reading once:

  • copper(): a vertical gradient with three bright bars whose centres follow a sine table, the Amiga/Mega Drive "copper bars".
  • crt_lines(): after a band is drawn, every other row is darkened by 25 % with bit tricks on packed RGB565 (((c & 0xF7DE) >> 1) + ((c & 0xE79C) >> 2) is ½ + ¼ of each component without unpacking).
  • wipe_mask(): a view change paints the background over the part of the screen the wipe hasn't reached yet, with a rainbow edge.
  • rainbow(): a hue wheel from integer arithmetic, used for the cursor's colour cycling.

3. Input: edges, holds and acceleration

Hardware gives levels ("PLAY is down"). A UI needs events ("PLAY was pressed", "SEL was held for a second"). input() turns one into the other by keeping the previous state:

static uint32_t btn_now, btn_prev;
static int pressed(int b)  { return (btn_now >> b & 1u) && !(btn_prev >> b & 1u); }   /* rising edge */
static int released(int b) { return !(btn_now >> b & 1u) && (btn_prev >> b & 1u); }  /* falling edge */
static int held(int b)     { return (int)(btn_now >> b & 1u); }

and remembers when each button went down (ui.t_down[b]). On top of that, two patterns cover every multi-function button on the panel:

Hold once. An action that fires once when a button has been held for a time:

static int hold_once(int b, uint32_t ms)
{
    if (held(b) && !ui.hold_done[b] && held_ms(b) >= ms) {
        ui.hold_done[b] = 1;
        return 1;
    }
    return 0;
}

Tap versus hold. A button that does one thing on a tap and another on a hold acts on release for the tap, and only if the hold didn't fire:

if (hold_once(B_LFO, 600u)) {
    /* held: solo the channel */
} else if (released(B_LFO) && !ui.hold_done[B_LFO]) {
    /* tapped: mute the channel */
}

hold_done doubles as "this press was used for something else": the pattern view sets it when SEL is held while an encoder turns (marking a block), so releasing SEL afterwards doesn't also copy.

Press twice to confirm. Destructive actions (load over unsaved changes, overwrite a slot, delete) use confirm(): the first press shows a message and remembers the action for 2 s; a second press within that time does it. No dialog boxes, one line of code at each call site.

Encoder acceleration. enc() multiplies the detents by 4 when the turns come less than 25 ms apart, by 2 under 50 ms. Scrolling 128 rows or 256 slots stays quick, fine adjustment stays precise. The host's spin command turns it off (accel_off) so scripts are exact.

4. The keys: a mono synth

The 27 keys (and MIDI in) play the instrument on the cursor's channel. Each tracker channel is one chip voice, so a channel can play one note at a time. What should happen when you hold C, then press E, then let go of E? On a monophonic synth, C sounds again. ui.c does the same with a small stack of keys held:

static void key_down(int id)
{
    keys_held_drop(id);                         /* not twice */
    if (ui.keys_held_n == 16) keys_held_drop(ui.keys_held[0]);
    ui.keys_held[ui.keys_held_n++] = (int16_t)id;
    ui.jam_key = (int16_t)id;                   /* the one sounding */
}
static void key_up(int id)
{
    keys_held_drop(id);
    if (ui.jam_key == id)                       /* the sounding key went up: */
        jam_resume();                           /* the newest still held plays again, or silence */
}

Panel keys have ids 0–26, MIDI notes are 100 + note, so both share the stack. Letting go of a key that isn't sounding does nothing, so overlapping notes neither cut each other off nor leave a held key silent. This last-note priority is the standard rule for mono synths.

A knob changing a cell's note previews it with jam_preview(): the note plays for 350 ms and stops by itself (JAM_TIMED), so nothing is left sounding with no key to release. The UI fuzzer (tests/ui_fuzz_test.mjs) hammers keys, MIDI and knobs in random orders and checks that once every key is up, nothing sounds. Hanging notes are the classic bug of this kind of code, so it gets its own test.

5. The pattern view

ui_pat.c is the tracker proper. Things to notice:

The lens. Six channels fit across. The cursor's channel shows its whole cell (note, instrument, volume, two effects) in a wide column; the five around it show only their notes in narrow columns. pat_draw() works out each visible column's x and width from ui.scroll and ui.ch every frame. A single row of numbers decides the whole layout.

Follow mode. While playing with follow on, view_ord() / view_row() return the player's position instead of the cursor's, and cursor_follow() moves the cursor along. Turning SELECT while playing re-posts PC_PLAY at the new row, so you scrub through the song.

Knobs edit the cell's fields side by side. pat_knob(k, d): KNOB 1 the note (an empty cell takes the last note entered), KNOB 2 the instrument (turning below 00 means "none"), KNOB 3 the volume, KNOB 4 effect 1's value. FX flips the four knobs to the two effect columns, where the command knob walks the effect list by name (fx_next). The footer always shows what each knob does now, in the quarter of the screen above it.

Entering notes live. With REC on and the song playing, a note is written to the row being played, quantised to the nearest row:

int o = player.ord, r = player.row;
uint32_t sp = player.speed[player.speed_i & 1u];
if (player.tick * 2u >= sp && ++r >= song.rows) {   /* past half the row: the next one */
    r = 0;
    o = o + 1 < song.nord ? o + 1 : song.loop;
}

The wrong instrument for a column is refused with a reason. ins_ch_say() says "DRUMS: FM6", "TONES: SQ1-SQ3" or "FM: FM1-FM6" rather than writing a note the channel would never play.

6. Editing a song that is playing

This is the subtle part, and it builds on Stage 3's rules.

static void lock(void) { player.lock = 1; }
static void unlock(void) { player.lock = 0; }

static cell_t *edit_cell(int ch, int pat, int row)
{
    cell_t *c;
    undo_mark(ch, pat);
    lock();
    c = song_cell_w(&song, ch, pat, row);      /* may allocate, may compact: memory moves */
    unlock();
    if (!c) ui_say("SONG FULL", "NO ROOM FOR ROWS");
    else ui.dirty = 1;
    return c;
}

Every write to a cell goes through edit_cell(). Getting the pointer is locked, because song_cell_w may move patterns. Writing the cell's bytes through the pointer is not locked: that's the cosmetic race Stage 3 accepted. Inserting or deleting an order position (ord_input) shifts the order list under lock(), while changing one order entry with a knob doesn't need it.

player.lock is a plain flag, not a mutex: the audio ISR checks it at the start of each block and, if set, renders the chips without running the driver. The main loop never waits for anything. A flag the real-time side checks and skips on is the right "lock" for a context that must never block.

Loading and saving take the lock for their whole duration (songs_input, save_song), because they rewrite the entire song. While locked, the chips keep running, so notes already playing ring out instead of stopping dead.

The dirty counter… as a flag

ui.dirty says "the song changed since it was loaded or saved"; the header shows the title in yellow with a *. Unlike FM1-GM's counter, FM1-TRAX uses a flag set by every edit path and cleared by load and save. Simple, and the price is that every edit path has to remember to set it. (Exercise 3.)

7. Undo: one pattern, swapped

static struct {
    int ch, pat, ok;
    uint32_t t;
    cell_t cells[MAX_ROWS];
} undo __attribute__((section(".pool")));

The undo buffer holds one pattern as it was before the last burst of edits. undo_mark() is called before every edit: if the same pattern was edited less than 1.5 s ago, it's the same burst and nothing is saved; otherwise the pattern is copied in. ARP (undo_swap) swaps the buffer with the pattern, so pressing it again is redo.

Compare with FM1-GM, which snapshots the whole song (two song copies in RAM). FM1-TRAX's song is 173 KB; a second copy wouldn't fit. A pattern is at most 128 × 7 = 896 bytes. Size undo to what you can afford, and group edits into bursts by time so one undo undoes what the user thinks of as one action.

The clipboard is similar: a block of up to 128 rows × 13 channels of cells, copied out of patterns and pasted into others through edit_cell (so a paste is undoable like any edit).

8. The other views, briefly

All follow the same pattern: an *_input() reading encoders and buttons, and a *_draw().

  • Orders (ord_input): SELECT the position, ALGORITHM the channel, KNOB 1 one pattern number, KNOB 2 all of the row's at once, KNOB 3 the song length, KNOB 4 the loop. LFO duplicates a position with new copies of its patterns (pat_unused finds a free pattern number), so you can vary the copy.

  • Instrument editor (ins_input): FM pages map the four knobs to the same parameter on the four operators, so an envelope is shaped like four faders on a mixer. op_field() returns a pointer to the field for a page and row, and op_max() its range: a small table-driven editor instead of 30 cases. Edits call ins_changed(), which posts PC_INS so the next note reloads the patch. The macro page writes past a macro's end to make it longer.

  • Library: browses presets and user slots by group, auditions an entry on a spare instrument slot (AUDITION_INS) and restores the song's own instrument afterwards (audition_end).

  • Songs: the 256 slots, with load, save, new, demo and delete, every destructive action behind confirm().

  • Stage: scopes, a piano roll and the YM2612's register map. The heat map uses the chips' log hook:

    static void stage_log(void *ctx, int kind, int port, uint8_t reg, uint8_t val)
    {
        if (kind == MD_LOG_FM && reg != 0x2A)       /* the DAC's stream would light one cell all the time */
            ui.heat[port & 1][reg] = 255;
    }

    The audio ISR calls it on every register write; stage_tick() fades the values once a frame. A UI feature built on a hook the engine already had for VGM export.

9. LEDs and messages

leds() lights the current view's button, PLAY (green, or red while recording), REC, FX, SEL with a block, the instrument editor's page, and the keys held. The device's plat_leds() builds the matrix picture off-line and copies it (Stage 1).

ui_say(a, b) puts a two-part message in the header for 1.4 s. It's the UI's only feedback channel besides the screen itself, and the tests read it indirectly through the state it describes.

10. What to take away

  • One state struct, per-view input and draw functions, two dispatch switches, and a go() with a leave hook.
  • Redraw everything from state every frame; never mutate state while drawing.
  • Without a frame buffer, draw in bands with clipping, and double-buffer the bands.
  • Turn levels into edges; build tap/hold/press-twice from pressed, released, hold_once and a hold_done flag.
  • Accelerate encoders by turn speed.
  • Mono key handling: a stack of held keys, last-note priority.
  • Lock only what moves memory; use a flag the real-time side skips on, never a blocking lock.
  • Size undo to your RAM; group edits into bursts by time; swap for redo.
  • Name colours by role; themes and accessibility become data.

11. Exercises

  1. Draw the frame timeline: ui_frame() every 16 ms, redraw every 33 ms, three bands each. While band 2 is being drawn, what is the DMA doing?
  2. Find every place that sets ui.dirty = 1. Is there an edit path that changes the song and forgets? (Look at the order view's knobs and the instrument editor.)
  3. Why does undo_swap() call song_cell_w (which allocates) and not song_cell?
  4. Hold C, press E, press G, release E, release G. Write down keys_held and what sounds after each step.
  5. pat_draw() is called three times per frame. Find a computation in it that's repeated each time, and decide whether it's worth caching.
  6. Add, on paper, a "transpose the whole pattern" action on a button hold. Which helpers would you reuse, and how would it interact with undo?
  7. Write a scenario that enters notes while playing with REC on and checks that they land on the expected rows.

Next stage: where the songs go when you press SAVE.


← Stage 6: The simulator and tests · Contents · Stage 8: The chunk store →

Clone this wiki locally