@maruaudio/dsp/math/ring-stack lays a heptatonic scale's seven stacked-thirds chords out in line order (scale degrees 0 2 4 6 1 3 5) round a mod-7 ring. Positions run −3..+3 from the hinge, the first line index whose triad is two minor thirds, so C major reads C −3, E −2, G −1, B 0, D +1, F +2, A +3. A scale with no such triad takes line index 3. The stack at a position and height is that many scale notes up the line (3 a triad, 4 a seventh), returned as pitch classes or as close intervals above the root. Ring steps, the mirror, shared note counts and 7-bit note masks over the line complete it.
Parameters
| Call | Range as coded | Default from create |
|---|---|---|
configureRingStack(state, tonic, scale) | Tonic rounded, wrapped to 0..11; scale is a @maru/math-scale id and must be heptatonic | C major |
configureRingStackMask(state, tonic, relativeMask) | Mask must hold exactly seven notes including the tonic | |
ringHeptatonicScaleId(option) | 0..8: Major, Natural minor, Harmonic minor, Melodic minor, Dorian, Phrygian, Lydian, Mixolydian, Locrian; others → Major | |
height argument of the stack queries | Rounded, clamped to 1..7 | |
position arguments | Any integer, wrapped to −3..+3 |
Lifecycle
createRingStack() allocates the seven-entry pitch-class array and configures C major. Configure at control rate; a refused scale returns false and leaves the state unchanged. Every query is stateless over the configured ring; output arrays are caller-owned and at least RING_MAX_HEIGHT (7) long.
When to use it
Chord instruments that move around a scale by thirds: pick a position on the ring and a height, and get the diatonic chord there. The Ring Chords module is its consumer (pitch and harmony).
Limits
- Heptatonic scales only; pentatonic, blues, whole tone and chromatic are refused.
ringStackPositionOfPcreturnsRING_NO_POSITION(−128) for a pitch class outside the scale;ringMaskRootreturns −1 for an empty mask.- Integer arithmetic with compile-time loop bounds; no allocation after create.