convert.hpp

Go to the documentation of this file.

// sbl/dsp/convert.hpp — DMA boundary conversion utilities
//
// These are the ONLY int↔float conversion functions in a float pipeline.
// Widgets process entirely in float [-1.0, 1.0]. Conversion happens at the
// DMA boundary: interleaved int32 (24-bit audio) ↔ separate float L/R buffers.
//
// See FDP-024 for design rationale.
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/types.hpp>
 
// NaN detection macro — increments counter when profiling is enabled,
// compiles to nothing otherwise. Used in interleave_from_float().
#ifdef SBL_PROFILING_ENABLED
#define SBL_NAN_DETECTED() (++sbl::dsp::nan_detect_count())
#else
#define SBL_NAN_DETECTED() ((void)0)
#endif
 
namespace sbl::dsp {
 
// 24-bit audio range: ±8,388,607
inline constexpr float SAMPLE_SCALE_F     = 8388607.0f;
inline constexpr float SAMPLE_SCALE_INV_F = 1.0f / 8388607.0f;
 
// ─── Single-sample conversion ────────────────────────────────────────
 
inline float to_float(Sample s) {
    return static_cast<float>(s) * SAMPLE_SCALE_INV_F;
}
 
inline Sample to_sample(float f) {
    return static_cast<Sample>(f * SAMPLE_SCALE_F);
}
 
// ─── Block conversion (mono) ─────────────────────────────────────────
 
inline void to_float(const Sample* in, float* out, uint16_t frames) {
    for (uint16_t i = 0; i < frames; ++i) {
        out[i] = static_cast<float>(in[i]) * SAMPLE_SCALE_INV_F;
    }
}
 
inline void to_sample(const float* in, Sample* out, uint16_t frames) {
    for (uint16_t i = 0; i < frames; ++i) {
        out[i] = static_cast<Sample>(in[i] * SAMPLE_SCALE_F);
    }
}
 
// ─── Stereo interleave/deinterleave with conversion ──────────────────
//
// DMA buffers are interleaved: [L0, R0, L1, R1, ...] as int32_t.
// Audio processing uses separate float L/R buffers in [-1.0, 1.0].
 
inline void deinterleave_to_float(const int32_t* interleaved,
                                  float* left, float* right,
                                  uint16_t frames) {
    for (uint16_t i = 0; i < frames; ++i) {
        left[i]  = static_cast<float>(interleaved[i * 2])     * SAMPLE_SCALE_INV_F;
        right[i] = static_cast<float>(interleaved[i * 2 + 1]) * SAMPLE_SCALE_INV_F;
    }
}
 
// NaN detection counter — gated behind SBL_PROFILING_ENABLED.
// NaN in the audio path indicates a bug upstream (uninitialized buffer,
// division by zero, corrupted filter state). The counter helps identify
// the problem without adding runtime cost in release builds.
#ifdef SBL_PROFILING_ENABLED
inline uint32_t& nan_detect_count() {
    static uint32_t count = 0;
    return count;
}
#endif
 
// Hard clamps to [-1.0, 1.0] before conversion — the ONE place clamping
// happens. Signals are free to exceed unity anywhere in the float pipeline;
// only the final DMA output enforces range.
//
// NaN guard: IEEE 754 NaN fails all comparisons, so the clamp below would
// pass NaN through to static_cast<int32_t>(NaN * SCALE), which is undefined
// behavior. We check NaN first and replace with silence (0.0f). This is the
// audio equivalent of a fuse — you lose signal, but you protect hearing.
inline void interleave_from_float(const float* left, const float* right,
                                  int32_t* interleaved,
                                  uint16_t frames) {
    for (uint16_t i = 0; i < frames; ++i) {
        float l = left[i];
        float r = right[i];
        // NaN check: NaN != NaN is true per IEEE 754
        if (l != l) { l = 0.0f; SBL_NAN_DETECTED(); }
        if (r != r) { r = 0.0f; SBL_NAN_DETECTED(); }
        if (l >  1.0f) l =  1.0f;
        if (l < -1.0f) l = -1.0f;
        if (r >  1.0f) r =  1.0f;
        if (r < -1.0f) r = -1.0f;
        interleaved[i * 2]     = static_cast<int32_t>(l * SAMPLE_SCALE_F);
        interleaved[i * 2 + 1] = static_cast<int32_t>(r * SAMPLE_SCALE_F);
    }
}
 
} // namespace sbl::dsp