rng.hpp

Go to the documentation of this file.

// sbl/dsp/rng.hpp — Lightweight pseudorandom number generator
//
// xorshift32 PRNG for audio/control applications. Not cryptographic.
// Period: 2^32-1. Each instance maintains independent state.
//
// Use cases: analog drift, sample-and-hold, stochastic gates,
// randomized delay taps, noise modulation at control rate.
//
// Usage:
//   sbl::dsp::Rng rng(42);           // seed at construction
//   float r = rng.bipolar();          // [-1.0, 1.0]
//   float u = rng.unipolar();         // [0.0, 1.0]
//   uint32_t raw = rng.next();        // raw 32-bit
 
#ifndef SBL_DSP_PRIMITIVES_RNG_HPP_
#define SBL_DSP_PRIMITIVES_RNG_HPP_
 
#include <cstdint>
 
namespace sbl::dsp::primitives {
 
class Rng {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /// Construct with seed. Each instance should use a different seed
    /// to ensure uncorrelated output.
    explicit Rng(uint32_t seed = 1) : state_(seed ? seed : 1) {}
 
    /// Advance state and return raw 32-bit value.
    uint32_t next() {
        state_ ^= state_ << 13;
        state_ ^= state_ >> 17;
        state_ ^= state_ << 5;
        return state_;
    }
 
    /// Random float in [-1.0, 1.0].
    float bipolar() {
        // Shift right 1 to get [0, 2^31-1], scale to [0, 1], then to [-1, 1]
        return (static_cast<float>(next() >> 1) / 1073741824.0f) - 1.0f;
    }
 
    /// Random float in [0.0, 1.0].
    float unipolar() {
        return static_cast<float>(next() >> 1) / 2147483647.0f;
    }
 
    /// Set state directly (for test reproducibility).
    void seed(uint32_t s) { state_ = s ? s : 1; }
 
private:
    uint32_t state_;
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_RNG_HPP_