feat(bank_panel): audition, multi-select, and keyboard nav (M5 Wave B)

Pure bank_grid gains hit-test, selection-update, and arrow-nav math with
tests; the panel wires mouse multi-select, keyboard nav via an accelerator
hook, and stock PlayPreview/StopPreview audition with a leak-free preview
lifecycle. Read-only: no arrange insertion, no project/bank mutation.
This commit is contained in:
2026-07-22 21:55:16 -04:00
parent 322581227c
commit fc54472d3e
4 changed files with 789 additions and 8 deletions
+358 -8
View File
@@ -48,6 +48,9 @@
// WDL_DLGRET (the platform dialog-proc return type).
#ifdef _WIN32
#include <windows.h>
#include <windowsx.h> // GET_X_LPARAM / GET_Y_LPARAM (SWELL supplies them on mac/linux)
#else
#include <pthread.h>
#endif
#include "wdltypes.h"
#include "swell/swell.h"
@@ -55,6 +58,11 @@
#include "resource.h"
// reaper_plugin.h defines preview_register_t (the stock preview struct) and the
// REAPER_PLUGIN_HINSTANCE / registration types. main.cpp includes it with
// REAPERAPI_IMPLEMENT; here we only need the type declarations.
#include "reaper_plugin.h"
#define REAPERAPI_MINIMAL
#define REAPERAPI_WANT_DockWindowAddEx
#define REAPERAPI_WANT_DockWindowActivate
@@ -63,10 +71,17 @@
#define REAPERAPI_WANT_GetMainHwnd
#define REAPERAPI_WANT_PCM_Source_CreateFromFile
#define REAPERAPI_WANT_PCM_Source_Destroy
// Stock preview API (verified against reaper_plugin.h / reaper_plugin_functions.h):
// PlayPreview/StopPreview drive a caller-owned preview_register_t. These are the
// STOCK symbols (not SWS-only) — see the audition section below.
#define REAPERAPI_WANT_PlayPreview
#define REAPERAPI_WANT_StopPreview
#include "reaper_plugin_functions.h"
// main.cpp owns the module instance handle (needed to load the dialog resource).
// main.cpp owns the module instance handle (needed to load the dialog resource)
// and REAPER's dispatch struct (needed to register the keyboard accelerator hook).
extern REAPER_PLUGIN_HINSTANCE g_hInst;
extern reaper_plugin_info_t* g_rec;
namespace reasampler {
@@ -94,6 +109,12 @@ const LICE_pixel kColCellBorder = LICE_RGBA(70, 70, 76, 255);
const LICE_pixel kColWaveform = LICE_RGBA(120, 200, 160, 255);
const LICE_pixel kColMidline = LICE_RGBA(60, 60, 66, 255);
const LICE_pixel kColText = LICE_RGBA(200, 200, 205, 255);
// Selection chrome (Wave B). Selected cells get a tinted fill + brighter border;
// the focused cell (audition/nav target) gets a distinct accent border so it is
// distinguishable within a multi-selection.
const LICE_pixel kColSelBg = LICE_RGBA(38, 66, 58, 255); // selected fill tint
const LICE_pixel kColSelBorder = LICE_RGBA(120, 200, 160, 255);// selected border
const LICE_pixel kColFocusBorder = LICE_RGBA(210, 230, 220, 255);// focused-cell border
// --- Panel state --------------------------------------------------------------
@@ -122,10 +143,39 @@ struct PanelState {
// Entries for stale generations are lazily overwritten on next miss; a bank
// change also clears it wholesale (see refreshFingerprint) to bound memory.
std::unordered_map<std::string, CachedThumbnail> cache;
// --- Interaction (Wave B) -------------------------------------------------
// The current cell selection (indices into bank->all(), focus, anchor). Pure
// math lives in bank_grid; this holds the live state the pointer/keyboard
// mutate. A bank change (generation bump) resets it (indices could dangle).
Selection selection;
// The item count the selection was last validated against. On a bank change we
// clear the selection rather than risk indices pointing past the new count.
int selItemCount = 0;
// --- Audition preview (Wave B) --------------------------------------------
//
// The stock preview register we hand to PlayPreview/StopPreview. Its cs/mutex
// is initialized ONCE (initPreview) and destroyed ONCE (deinitPreview) across
// the panel's lifetime — NOT per playback — because REAPER's audio thread may
// touch the register's guarded fields. `previewSrc` is the PCM_source currently
// owned by `preview.src`; non-null exactly while auditioning. `previewActive`
// tracks whether PlayPreview succeeded and StopPreview is still owed.
preview_register_t preview{};
PCM_source* previewSrc = nullptr;
bool previewActive = false;
bool previewInited = false; // guards double init / deinit
};
PanelState g_panel;
// Forward declarations for the interaction/audition helpers defined lower down but
// referenced by earlier sections (e.g. refreshFingerprint stops audition on a bank
// change). Definitions live in the "Audition preview" / "Selection + input" blocks.
void stopAudition();
// --- Current-project directory (mirrors persist.cpp's derivation) -------------
//
// The index stores relative paths; resolving a bank file needs the current .rpp
@@ -228,9 +278,21 @@ const Envelope& thumbnailFor(const Sample& sample, int width,
// zero midline, and the min/max waveform. Multi-channel envelopes are stacked
// vertically (each channel gets an equal horizontal band) so a stereo sample shows
// both channels without folding (precision invariant: no stereo fold).
void drawThumbnail(LICE_IBitmap* bmp, const CellRect& rect, const Envelope& env) {
LICE_FillRect(bmp, rect.x, rect.y, rect.width, rect.height, kColCellBg, 1.0f, 0);
LICE_DrawRect(bmp, rect.x, rect.y, rect.width, rect.height, kColCellBorder, 1.0f, 0);
// `selected` tints the fill and brightens the border; `focused` overrides the
// border with the accent color so the caret cell reads within a multi-selection.
void drawThumbnail(LICE_IBitmap* bmp, const CellRect& rect, const Envelope& env,
bool selected, bool focused) {
const LICE_pixel bg = selected ? kColSelBg : kColCellBg;
LICE_pixel border = selected ? kColSelBorder : kColCellBorder;
if (focused) border = kColFocusBorder;
LICE_FillRect(bmp, rect.x, rect.y, rect.width, rect.height, bg, 1.0f, 0);
LICE_DrawRect(bmp, rect.x, rect.y, rect.width, rect.height, border, 1.0f, 0);
// The focused cell gets a second inset rectangle so it stays distinct even when
// its neighbors are also selected (double outline reads as "the active one").
if (focused)
LICE_DrawRect(bmp, rect.x + 1, rect.y + 1, rect.width - 2, rect.height - 2,
border, 1.0f, 0);
if (env.empty()) {
// Unreadable / empty sample: cell drawn, no waveform. A single midline
@@ -288,6 +350,21 @@ void drawEmptyState(HWND hwnd, LICE_IBitmap* bmp, int w, int h) {
DrawText(dc, msg, -1, &rc, DT_CENTER | DT_VCENTER | DT_SINGLELINE | DT_WORDBREAK);
}
// The cell rects for the panel's CURRENT client width and bank size. Both paint
// and mouse hit-testing call this so they share identical geometry (no drift
// between what is drawn and what a click resolves to). Returns empty when the
// window is gone or the bank is empty.
std::vector<CellRect> panelRects() {
if (!g_panel.hwnd) return {};
const BankIndex* bank = g_panel.session ? &g_panel.session->bank() : nullptr;
if (!bank || bank->empty()) return {};
RECT cr{};
GetClientRect(g_panel.hwnd, &cr);
const int w = cr.right - cr.left;
if (w <= 0) return {};
return computeCellRects(static_cast<int>(bank->size()), w, kGrid);
}
// The full paint: build/refresh the LICE backing bitmap at client size, draw the
// grid (or empty state), then blit to the window HDC.
void paintPanel(HWND hwnd, HDC hdc) {
@@ -318,8 +395,11 @@ void paintPanel(HWND hwnd, HDC hdc) {
// Skip cells entirely below the viewport (Wave A has no scroll; this
// just avoids computing thumbnails that cannot be seen).
if (rect.y >= h) continue;
const int idx = static_cast<int>(i);
const bool selected = g_panel.selection.contains(idx);
const bool focused = g_panel.selection.focus == idx;
const Envelope& env = thumbnailFor(samples[i], binWidth, projectDir);
drawThumbnail(&bmp, rect, env);
drawThumbnail(&bmp, rect, env, selected, focused);
}
}
@@ -352,9 +432,252 @@ bool refreshFingerprint() {
g_panel.bankFingerprint = std::move(fp);
++g_panel.generation;
g_panel.cache.clear();
// The selection indexes into the OLD bank order; a bank change (capture /
// project load) can invalidate those indices, so clear it and stop any
// audition of a sample that may no longer exist at the same index.
if (!g_panel.selection.empty() || g_panel.selection.focus >= 0) {
g_panel.selection = Selection{};
stopAudition();
}
g_panel.selItemCount = static_cast<int>(g_panel.session->bank().size());
return true;
}
// --- Audition preview ---------------------------------------------------------
//
// READ-ONLY / NON-DESTRUCTIVE (load-bearing principle): audition is PREVIEW
// playback only. It NEVER inserts into the arrange, creates items/tracks, or
// mutates the project or bank. PlayPreview streams a caller-owned PCM_source
// through REAPER's preview bus and touches nothing in the project.
//
// FLAGGED RUNTIME ASSUMPTIONS (header does not specify these; verified only by
// signature/struct, not semantics — DAW-verify):
// 1. REAPER's audio thread reads the preview_register_t by POINTER while the
// preview is active (the struct's own comment mandates a cs/mutex we init),
// so the register must outlive playback — we hold it in g_panel (static),
// never on the stack.
// 2. StopPreview is assumed to detach the source from the audio thread BEFORE it
// returns, making it safe to PCM_Source_Destroy the source immediately after.
// This is the conventional contract (SWS' preview helpers rely on it) but is
// NOT documented in the header — flagged. If a rare race surfaced, the fix is
// a StartPreviewFade + deferred free; not done now (YAGNI, no evidence).
// 3. m_out_chan == 0 routes to the first hardware output pair (stereo). We do not
// set mono (&1024). volume 1.0, loop false, curpos 0.
// Initializes the preview register's cs/mutex ONCE for the panel's lifetime. The
// preview struct guards its fields with a platform lock the caller must set up
// (reaper_plugin.h). Idempotent.
void initPreview() {
if (g_panel.previewInited) return;
#ifdef _WIN32
InitializeCriticalSection(&g_panel.preview.cs);
#else
pthread_mutex_init(&g_panel.preview.mutex, nullptr);
#endif
g_panel.previewInited = true;
}
// Stops any active preview and frees the owned PCM_source. Safe to call when
// nothing is playing (no-op). Every stop path funnels through here so the source
// is freed exactly once and never dangles.
void stopAudition() {
if (g_panel.previewActive) {
StopPreview(&g_panel.preview);
g_panel.previewActive = false;
}
// Free the source AFTER StopPreview has detached it (assumption #2). Clear the
// register's src so a stale pointer can never be handed back to PlayPreview.
if (g_panel.previewSrc) {
PCM_Source_Destroy(g_panel.previewSrc);
g_panel.previewSrc = nullptr;
}
g_panel.preview.src = nullptr;
}
// Destroys the preview register's cs/mutex on panel teardown, after stopAudition.
void deinitPreview() {
if (!g_panel.previewInited) return;
#ifdef _WIN32
DeleteCriticalSection(&g_panel.preview.cs);
#else
pthread_mutex_destroy(&g_panel.preview.mutex);
#endif
g_panel.previewInited = false;
}
// Auditions the sample at bank index `idx`: stops any prior preview, loads the
// sample's file as a PCM_source, and starts stock preview playback. Re-audition
// (calling with a new idx while one plays) stops the previous first. On any
// failure (bad index, unsaved project, unreadable file, PlayPreview refusal) it
// leaves nothing playing and no source leaked.
void startAudition(int idx) {
// Always stop+free the previous first — re-audition semantics, and it clears
// previewSrc so the load below starts clean.
stopAudition();
const BankIndex* bank = g_panel.session ? &g_panel.session->bank() : nullptr;
if (!bank) return;
const std::vector<Sample>& samples = bank->all();
if (idx < 0 || idx >= static_cast<int>(samples.size())) return;
const std::string projectDir = currentProjectDir();
const std::string abs = resolveBankFile(projectDir, samples[idx].relativePath);
if (abs.empty()) return; // unsaved project / unresolvable — nothing to play
PCM_source* src = PCM_Source_CreateFromFile(abs.c_str());
if (!src) return; // unreadable file — no preview, no leak
// Fill the register. cs/mutex already initialized (initPreview at panel open).
g_panel.preview.src = src;
g_panel.preview.m_out_chan = 0; // first hardware output pair (assumption #3)
g_panel.preview.curpos = 0.0;
g_panel.preview.loop = false;
g_panel.preview.volume = 1.0;
g_panel.preview.peakvol[0] = 0.0;
g_panel.preview.peakvol[1] = 0.0;
g_panel.preview.preview_track = nullptr;
if (PlayPreview(&g_panel.preview) != 0) {
g_panel.previewSrc = src; // we now own it until stopAudition frees it
g_panel.previewActive = true;
} else {
// PlayPreview refused — free the source we created rather than leak it.
PCM_Source_Destroy(src);
g_panel.preview.src = nullptr;
}
}
// --- Selection + input --------------------------------------------------------
// True while VK_CONTROL / VK_SHIFT is physically down. SWELL does NOT set MK_* bits
// in a mouse message's wParam (swell-types.h), so modifier state is read live via
// GetAsyncKeyState — the portable path (Win/mac/GDK all support these two VKs).
bool ctrlDown() { return (GetAsyncKeyState(VK_CONTROL) & 0x8000) != 0; }
bool shiftDown() { return (GetAsyncKeyState(VK_SHIFT) & 0x8000) != 0; }
// The current bank item count (0 when no session/bank).
int bankItemCount() {
const BankIndex* bank = g_panel.session ? &g_panel.session->bank() : nullptr;
return bank ? static_cast<int>(bank->size()) : 0;
}
// Requests a repaint of the whole client area (selection/focus chrome changed).
void invalidatePanel() {
if (g_panel.hwnd) InvalidateRect(g_panel.hwnd, nullptr, FALSE);
}
// Handles a left-button click at client (x, y): hit-test to a cell, update the
// selection through the pure model with the live modifier state, repaint. A click
// on empty space (gap/margin/below grid) clears the selection AND stops audition
// (deselect stop path). READ-ONLY: never mutates the bank/project.
void handleClick(int x, int y) {
const std::vector<CellRect> rects = panelRects();
const int hit = hitTestCell(x, y, rects);
const int count = bankItemCount();
if (hit < 0) {
// Click on empty space clears the selection and stops any audition.
if (!g_panel.selection.empty() || g_panel.selection.focus >= 0) {
g_panel.selection = Selection{};
stopAudition();
invalidatePanel();
}
return;
}
g_panel.selection =
applyClick(g_panel.selection, hit, ctrlDown(), shiftDown(), count);
g_panel.selItemCount = count;
invalidatePanel();
}
// The column count for the panel's CURRENT client width (nav needs the same wrap
// the layout uses). >= 1.
int columnsNow() {
if (!g_panel.hwnd) return 1;
RECT cr{};
GetClientRect(g_panel.hwnd, &cr);
return columnsForWidth(cr.right - cr.left, kGrid);
}
// True iff `hwnd` is our panel window or a descendant of it (the accelerator hook
// only claims keys when focus is inside the panel). Walks the parent chain.
bool isOurWindow(HWND hwnd) {
for (HWND w = hwnd; w; w = GetParent(w))
if (w == g_panel.hwnd) return true;
return false;
}
// Handles a key-down (virtual key `vk`) while the panel is focused. Returns true if
// the key was consumed (arrow nav / Enter/Space audition / Esc stop), false to let
// REAPER handle it. Arrow keys mutate the selection through the pure nav model and
// repaint; Shift extends. READ-ONLY: never mutates the bank/project.
bool handleKey(int vk) {
const int count = bankItemCount();
if (count <= 0) return false;
switch (vk) {
case VK_LEFT:
case VK_RIGHT:
case VK_UP:
case VK_DOWN: {
const NavKey nk = vk == VK_LEFT ? NavKey::Left
: vk == VK_RIGHT ? NavKey::Right
: vk == VK_UP ? NavKey::Up
: NavKey::Down;
g_panel.selection =
navigate(g_panel.selection, nk, columnsNow(), count, shiftDown());
g_panel.selItemCount = count;
invalidatePanel();
return true;
}
case VK_RETURN:
case VK_SPACE:
// Audition the focused cell. Enter/Space with no focus does nothing
// (nothing to play). Re-audition stops the previous inside startAudition.
if (g_panel.selection.focus >= 0)
startAudition(g_panel.selection.focus);
return true;
case VK_ESCAPE:
// Stop audition (does not clear the selection — Esc is "stop", not
// "deselect"). No-op when nothing is playing; still consume so REAPER
// does not treat Esc as a global stop while the panel is focused.
stopAudition();
return true;
default:
return false;
}
}
// The keyboard accelerator hook (registered with "accelerator"). REAPER calls this
// for every keystroke; we claim arrow/Enter/Space/Esc ONLY when focus is inside the
// panel, eating them so REAPER does not steal arrows for the arrange. Returns 1 to
// eat, 0 to pass on (not our window / not our key).
int translateAccel(MSG* msg, accelerator_register_t* /*ctx*/) {
if (!msg || msg->message != WM_KEYDOWN) return 0; // key-down only
if (!g_panel.open || !g_panel.hwnd) return 0;
if (!isOurWindow(GetFocus())) return 0; // focus not in the panel
return handleKey(static_cast<int>(msg->wParam)) ? 1 : 0;
}
accelerator_register_t g_accel{translateAccel, true, nullptr};
bool g_accelRegistered = false;
// Registers the keyboard hook once (on first panel open). isLocal must be true
// (reaper_plugin.h). Safe to call repeatedly.
void registerAccel() {
if (g_accelRegistered || !g_rec) return;
g_rec->Register("accelerator", &g_accel);
g_accelRegistered = true;
}
// Mirror-unregisters the keyboard hook on teardown.
void unregisterAccel() {
if (!g_accelRegistered || !g_rec) return;
g_rec->Register("-accelerator", &g_accel);
g_accelRegistered = false;
}
// --- Dialog proc + docking ----------------------------------------------------
WDL_DLGRET dlgProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) {
@@ -366,9 +689,23 @@ WDL_DLGRET dlgProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) {
EndPaint(hwnd, &ps);
return 0;
}
case WM_LBUTTONDOWN: {
// Take keyboard focus so the accelerator hook routes arrows/audition
// keys to us, then resolve the click. Coordinates are client-relative
// signed shorts in lParam (SWELL sets these even though it omits the
// MK_* modifier bits in wParam — hence GetAsyncKeyState for modifiers).
SetFocus(hwnd);
const int x = GET_X_LPARAM(lParam);
const int y = GET_Y_LPARAM(lParam);
handleClick(x, y);
return 0;
}
case WM_DESTROY:
// REAPER closed the dock (user X'd it). Reflect closed state so the
// toggle re-opens rather than trying to reuse a dead HWND.
// REAPER closed the dock (user X'd it). Stop any audition (window-close
// stop path — no preview may outlive the window) and reflect closed
// state so the toggle re-opens rather than reusing a dead HWND.
stopAudition();
g_panel.selection = Selection{};
g_panel.hwnd = nullptr;
g_panel.open = false;
return 0;
@@ -385,6 +722,9 @@ void openPanel() {
}
// Create the dialog as a child (WS_CHILD in the template); REAPER's docker
// reparents it. lParam is unused (state lives in g_panel).
// Set up the preview register's lock ONCE before the window can audition.
initPreview();
g_panel.hwnd = CreateDialogParam(g_hInst, MAKEINTRESOURCE(IDD_BANK_PANEL),
GetMainHwnd(), dlgProc, 0);
if (!g_panel.hwnd) return;
@@ -396,12 +736,21 @@ void openPanel() {
DockWindowActivate(g_panel.hwnd);
g_panel.open = true;
// Start receiving arrow/audition keys while the panel is open.
registerAccel();
// Prime the fingerprint so the first timer tick doesn't count the initial
// bank as a "change" (it's already drawn on open).
refreshFingerprint();
}
void closePanel() {
// Stop audition before the window goes away (window-close stop path). WM_DESTROY
// also stops, but stop here too so a DockWindowRemove that suppresses WM_DESTROY
// still tears the preview down (idempotent: stopAudition no-ops if not playing).
stopAudition();
g_panel.selection = Selection{};
unregisterAccel();
if (g_panel.hwnd) {
DockWindowRemove(g_panel.hwnd);
DestroyWindow(g_panel.hwnd);
@@ -438,7 +787,8 @@ void bankPanelRefresh() {
}
void bankPanelShutdown() {
closePanel();
closePanel(); // stops audition + destroys the window
deinitPreview(); // destroy the preview lock (after the last stop)
g_panel.cache.clear();
g_panel.session = nullptr;
}