serumalt/Source/engine/AGENT.md

engine module

Related source files

This directory contains guidance; the implementation remains in ../Engine.h and ../Engine.cpp. The preparation rules below are requirements for changes; current buffer resizing and lazy wavetable issues are recorded in the root AGENT.md.

Rules

• Own the voice pool, LFOs, wavetable library, FX rack, matrix and macros by value.
• Read every APVTS value through the null-guarding v() helper.
• Build the RenderContext once per block and pass it to voices as const&.
• Size mixBuffer once in prepare() and only clear() it per block.
• Prebuild wavetables in prepare() before the first render.
• Clamp the final output with the soft limiter.
• Never call setSize on any buffer inside processBlock.

IF-THEN

• IF a per-block buffer is needed THEN allocate it in prepare() and clear it per block.
• IF a module needs the matrix, macros or wavetables THEN go through Engine accessors rather than reaching into another module.

Examples

// BAD: per-callback buffer reconfiguration on the audio thread
void processBlock (...)
{
    mixBuffer.setSize (2, n, false, false, true);
    ...
}

// GOOD: size once, clear per block
void prepare (double sr, int blockSize)
{
    mixBuffer.setSize (2, blockSize, false, false, true);
}
void processBlock (...)
{
    mixBuffer.clear();
    ...
}

This file overrides /AGENT.md where they conflict.