spectral_stack.hpp

Go to the documentation of this file.

#pragma once
 
#include <complex>
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
 
#include <pulp/render/gpu_compute.hpp>
#include <pulp/signal/fft.hpp>
#include <pulp/signal/windowing.hpp>
 
namespace pulp::gpu_audio {
 
namespace detail {
void circular_box_blur(const std::vector<float>& m, std::vector<float>& out,
                       std::uint32_t radius, float inv_kernel, std::uint32_t n);
}  // namespace detail
 

class SpectralStack {
public:
    virtual ~SpectralStack() = default;
 
    virtual uint32_t fft_size() const = 0;
    virtual uint32_t num_layers() const = 0;

    virtual bool available() const = 0;

    virtual bool capture(uint32_t layer, const float* frame_in) = 0;

    virtual void clear(uint32_t layer) = 0;
    virtual bool layer_active(uint32_t layer) const = 0;

    virtual bool render(float* frame_out, const float* weights, float smear,
                        float jitter) = 0;
};

class CpuSpectralStack : public SpectralStack {
public:
    bool prepare(uint32_t fft_size, uint32_t hop, uint32_t num_layers);
 
    uint32_t fft_size() const override { return n_; }
    uint32_t num_layers() const override {
        return static_cast<uint32_t>(layers_.size());
    }
    bool available() const override { return n_ > 0; }
    bool capture(uint32_t layer, const float* frame_in) override;
    void clear(uint32_t layer) override;
    bool layer_active(uint32_t layer) const override;
    bool render(float* frame_out, const float* weights, float smear,
                float jitter) override;
 
private:
    struct Layer {
        std::vector<float> mag;    // n
        std::vector<float> phase;  // n, persists + advances across renders
        bool active = false;
    };
    uint32_t n_ = 0;
    uint32_t hop_ = 0;
    float hop_ratio_ = 0.0f;          // hop / n: per-bin phase advance factor
    std::vector<Layer> layers_;
    std::unique_ptr<signal::Fft> fft_;
    std::vector<std::complex<float>> scratch_;  // n: capture + combine workspace
    std::vector<float> smear_scratch_;  // n: per-layer blurred magnitude (running-sum)
    std::vector<float> weights_;     // local copy (null weights => all 1)
    uint32_t seed_ = 0x9E3779B9u;    // jitter RNG seed, advanced each render
};

class GpuSpectralStack : public SpectralStack {
public:
    bool prepare(uint32_t fft_size, uint32_t hop, uint32_t num_layers,
                 render::GpuCompute* shared_device = nullptr);
 
    uint32_t fft_size() const override { return n_; }
    uint32_t num_layers() const override { return num_layers_; }
    bool available() const override;
    bool capture(uint32_t layer, const float* frame_in) override;
    void clear(uint32_t layer) override;
    bool layer_active(uint32_t layer) const override;
    bool render(float* frame_out, const float* weights, float smear,
                float jitter) override;

    std::string backend() const;
 
private:
    uint32_t n_ = 0;
    uint32_t hop_ = 0;
    uint32_t num_layers_ = 0;
    render::GpuCompute* gpu_ = nullptr;                 // borrowed or == owned_
    std::unique_ptr<render::GpuCompute> owned_;         // when not shared
    std::unique_ptr<signal::Fft> fft_;                  // CPU forward for capture
    std::vector<std::complex<float>> cap_scratch_;      // n
    std::vector<float> mag_up_, phase_up_;              // n upload scratch
    std::vector<std::uint8_t> active_;                  // per layer
    std::vector<float> weights_;                        // num_layers (null => 1)
    uint32_t seed_ = 0x9E3779B9u;                       // jitter seed, advanced
    std::uint64_t device_generation_ = 0;               // at prepare
};

struct SpectralFreezeControls {
    const float* weights = nullptr;  // length num_layers (null = all 1)
    float smear = 0.0f;
    float jitter = 0.0f;
    bool freeze = false;             // capture-trigger LEVEL (rising edge captures)
    bool active = true;              // false = emit silence (stack not primed)
};

class SpectralFreezeFramer {
public:
    bool prepare(SpectralStack* stack, uint32_t fft_size, uint32_t hop,
                 signal::WindowFunction::Type window = signal::WindowFunction::Type::hann);

    void process(const float* in, float* out, uint32_t n,
                 const SpectralFreezeControls& ctl);
 
    uint32_t fft_size() const { return fft_size_; }
    uint32_t hop() const { return hop_; }
    uint32_t captured_layers() const { return captured_; }
 
    void reset();
 
private:
    void run_hop(const SpectralFreezeControls& ctl);
 
    SpectralStack* stack_ = nullptr;
    uint32_t fft_size_ = 0;
    uint32_t hop_ = 0;
    std::vector<float> window_;     // analysis/synthesis window (hann)
    float ola_norm_ = 1.0f;         // steady-state window-overlap normalization
 
    std::vector<float> in_hist_;    // ring of the latest fft_size input samples
    uint32_t in_wr_ = 0;            // ring write index (oldest sample sits here)
    uint32_t in_fill_ = 0;          // samples accumulated toward the next hop
    std::vector<float> frame_;      // analysis frame scratch (fft_size)
    std::vector<float> rendered_;   // stack render output (fft_size)
    std::vector<float> ola_;        // overlap-add accumulator (fft_size)
    std::vector<float> out_fifo_;   // produced output waiting to be emitted
    uint32_t out_head_ = 0, out_tail_ = 0;
 
    bool prev_freeze_ = false;
    uint32_t next_layer_ = 0;       // round-robin capture target
    uint32_t captured_ = 0;
};
 
} // namespace pulp::gpu_audio