Forge Audio Pool

forge-audio-pool

Add fire-and-forget sound effect playback using ForgeAudioPool and smooth volume transitions using the fade envelope on ForgeAudioSource. Based on Audio Lesson 02.

When to use

• Playing the same sound multiple times with overlap (polyphony)
• One-shot sound effects that should auto-clean-up when finished
• Starting or stopping sounds without audible clicks (fade-in / fade-out)
• Ambient loops that toggle smoothly with a volume ramp

Source pool pattern

#include "audio/forge_audio.h"

/* In app_state */
ForgeAudioPool pool;
ForgeAudioBuffer sfx_buffer;

/* In SDL_AppInit */
forge_audio_pool_init(&pool);
forge_audio_load_wav("assets/audio/impact.wav", &sfx_buffer);

/* Fire-and-forget: each call allocates a new slot (up to 32) */
int slot = forge_audio_pool_play(&pool, &sfx_buffer, 1.0f, false);
if (slot < 0) {
    SDL_Log("Pool full — sound dropped");
}

/* In SDL_AppIterate — mix all active sources, reclaim finished slots */
SDL_memset(scratch, 0, samples * sizeof(float));
forge_audio_pool_mix(&pool, scratch, frames_needed);

/* Stop everything */
forge_audio_pool_stop_all(&pool);

The pool scans for the first slot with playing == false. Non-looping sources auto-stop at buffer end; the slot is then reusable by the next pool_play().

Fade envelope pattern

/* Fade fields on ForgeAudioSource (initialized by forge_audio_source_create):
 *   fade_volume = 1.0  (current multiplier)
 *   fade_target = 1.0  (destination)
 *   fade_rate   = 0.0  (change per second, 0 = no fade) */

/* Start a fade to any target */
forge_audio_source_fade(src, 0.5f, 2.0f);  /* fade to 50% over 2 seconds */

/* Convenience: fade in from silence (sets fade_volume=0, starts playback) */
forge_audio_source_fade_in(src, 0.5f);

/* Convenience: fade out to zero (auto-stops when complete) */
forge_audio_source_fade_out(src, 1.0f);

/* MUST call once per frame to advance the ramp */
forge_audio_source_fade_update(src, dt);

The fade multiplier is applied on top of volume * pan during forge_audio_source_mix(). Default fade_volume=1.0 means existing code from Lesson 01 behaves identically.

Combining pool + fade

For pool sources that need fade control, get the source pointer after play:

int slot = forge_audio_pool_play(&pool, &buffer, 1.0f, true);
if (slot >= 0) {
    ForgeAudioSource *src = forge_audio_pool_get(&pool, slot);
    forge_audio_source_fade_in(src, 0.3f);
}

/* Update fades on all pool sources each frame */
for (int i = 0; i < FORGE_AUDIO_POOL_MAX_SOURCES; i++) {
    if (pool.sources[i].playing) {
        forge_audio_source_fade_update(&pool.sources[i], dt);
    }
}

Ambient loop with fade toggle

For a single looping source managed outside the pool (direct fade control):

/* In app_state */
ForgeAudioSource ambient;
bool ambient_active;

/* Toggle on key press */
if (ambient_active) {
    forge_audio_source_fade_out(&ambient, fade_duration);
    ambient_active = false;
} else {
    if (!ambient.playing) forge_audio_source_reset(&ambient);
    forge_audio_source_fade_in(&ambient, fade_duration);
    ambient_active = true;
}

Common mistakes

• Forgetting fade_update — The fade does not advance automatically. Call forge_audio_source_fade_update(src, dt) once per frame for every source that might be fading.
• Calling fade_update per mix call — Call it per frame, not per mix invocation. The rate is in units per second, scaled by dt.
• Not zeroing the mix buffer — forge_audio_pool_mix() is additive. Always memset(out, 0, ...) before the first mix call each frame.
• Ignoring pool_play return value — Returns -1 when full. Decide whether to drop the sound or steal an existing slot.

API reference