serumalt/Source/engine/AGENTS.md

engine module

Related source files

This directory contains guidance; the implementation remains in ../Engine.h and ../Engine.cpp.

Rules

• Own the voice pool, LFOs, wavetable library, FX rack, matrix and macros by value.
• Bind APVTS pointers in prepare(); v() reads captured values without constructing parameter-name strings.
• Build the RenderContext once per host block and refresh its modulation inputs for each render segment.
• Render up to 64 samples at a time, splitting at MIDI event offsets and respecting prepared buffer capacity.
• Size mixBuffer once in prepare(); use non-owning views for shorter segments.
• Prebuild wavetables in the Engine constructor, before either GUI painting or audio rendering can read them.
• 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, then wrap a non-owning view per segment
void prepare (double sr, int blockSize)
{
    mixBuffer.setSize (2, blockSize, false, false, true);
}
void processBlock (...)
{
    // No allocation; the view only borrows mixBuffer's channels.
    juce::AudioBuffer<float> block (mixBuffer.getArrayOfWritePointers(), 2, segmentLength);
    block.clear();
    ...
}

This file overrides /AGENTS.md where they conflict.