gpu_convolution_reverb.hpp

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <cstdint>
#include <memory>
#include <vector>
 
#include <pulp/audio/buffer.hpp>
#include <pulp/gpu_audio/gpu_audio_capability.hpp>
#include <pulp/gpu_audio/gpu_audio_transport.hpp>
#include <pulp/gpu_audio/gpu_convolver.hpp>
#include <pulp/signal/zero_latency_convolver.hpp>
 
namespace pulp::gpu_audio {
 
namespace detail {
struct GpuConvolutionReverbTestAccess;
} // namespace detail

struct GpuConvolutionReverbConfig {
    std::uint32_t block_size = 0;
    std::uint32_t sample_rate = 0;
    // The asset's native rate.  This is intentionally distinct from the
    // session rate above: Forge may prepare one immutable IR at several host
    // rates, and ZeroLatencyConvolver owns the canonical resampling policy.
    double impulse_response_sample_rate = 0.0;
    std::vector<std::vector<float>> impulse_response;
    signal::IrNormalizeMode normalize = signal::IrNormalizeMode::energy;
    double tail_trim_db = signal::ZeroLatencyConvolver::kTailTrimDbDefault;
    double tail_fade_ms = signal::ZeroLatencyConvolver::kTailFadeMsDefault;
    int resample_taps_per_phase = signal::ZeroLatencyConvolver::kResampTapsPerPhaseDefault;
    std::uint32_t ring_blocks = 8;
    bool gpu_enabled = false;
    // Optional shared-I/O diagnostics.  Tracing remains off for a normal
    // Forge node until this is enabled or the host has an active runtime
    // tracing session.  The callback path only publishes fixed-size records.
    GpuConvolverTraceConfig trace{};
};

struct GpuConvolutionReverbLaneReport {
    GpuAudioCapabilityReport capability;
    GpuAudioTransport::Stats stats;
    GpuAudioTransport::DeliverySnapshot delivery;
    // The lane transport's status_snapshot(), including its convolver's
    // health. Appended so positional initialization of the fields above holds.
    GpuAudioStatus status;
};
 
struct GpuConvolutionReverbReport {
    bool prepared = false;
    bool gpu_enabled = false;
    bool authenticated_shared_provider = false;
    std::uint32_t block_size = 0;
    std::uint32_t latency_samples = 0;
    std::array<GpuConvolutionReverbLaneReport, 2> lanes{};
};

class GpuConvolutionReverb final {
  public:
    explicit GpuConvolutionReverb(GpuConvolutionReverbConfig config);
    ~GpuConvolutionReverb();
 
    GpuConvolutionReverb(const GpuConvolutionReverb&) = delete;
    GpuConvolutionReverb& operator=(const GpuConvolutionReverb&) = delete;

    bool prepare() noexcept;
    void release() noexcept;
 
    bool prepared() const noexcept {
        return prepared_;
    }
    bool gpu_enabled() const noexcept {
        return config_.gpu_enabled;
    }
    std::uint32_t block_size() const noexcept {
        return config_.block_size;
    }
    std::uint32_t latency_samples() const noexcept {
        return prepared_ ? 3u * config_.block_size : 0u;
    }
 
    // These setters are RT-safe and allocation-free.  As with the CPU
    // ZeroLatencyConvolver controls, callers change them at block boundaries.
    void set_ir_gain_db(double db) noexcept;
    void set_predelay_ms(double ms) noexcept;
    void set_wet_percent(double percent) noexcept;
    void set_dry_percent(double percent) noexcept;
    void set_width_percent(double percent) noexcept;
    void set_lowcut_hz(double hz) noexcept;
    void set_highcut_hz(double hz) noexcept;

    void process(const audio::BufferView<const float>& input, audio::BufferView<float>& output,
                 std::uint32_t n) noexcept;
 
    GpuConvolutionReverbReport report() const noexcept;

    GpuAudioStatus status_snapshot() const noexcept;
    GpuAudioRecoveryReason recovery_reason() const noexcept;
    bool fenced() const noexcept;
 
  private:
    struct Lane;
    struct ControlSample {
        double wet = 0.0;
        double dry = 0.0;
        double width = 1.0;
        double ir_gain = 1.0;
        std::uint32_t predelay = 0;
    };
 
    bool valid_config() const noexcept;
    // Prepares each lane's convolver: the authenticated shared provider by
    // default, or `prepare_node` when a private test seam supplies one.
    using LaneNodePreparer = bool (*)(GpuConvolver&, void*) noexcept;
    bool prepare_with(LaneNodePreparer prepare_node, void* context) noexcept;
    bool prepare_lanes(LaneNodePreparer prepare_node, void* context) noexcept;
    friend struct detail::GpuConvolutionReverbTestAccess;
    void update_filter_coefficients() noexcept;
    void clear_runtime_buffers() noexcept;
    void process_quantum() noexcept;
 
    GpuConvolutionReverbConfig config_;
    // Initialize after Lane is complete, in the out-of-line constructor.
    std::array<std::unique_ptr<Lane>, 2> lanes_;
    // The transports are fixed-quantum APIs.  `block_size` is the host's
    // prepared capacity, not a promise that every callback has that size;
    // lane input buffers accumulate short callbacks into one full quantum.
    std::vector<float> dry_delay_;
    std::vector<ControlSample> control_delay_;
    std::vector<float> predelay_ring_[2];
    std::vector<float> dry_due_[2];
    std::vector<ControlSample> control_due_;
    std::vector<float> output_fifo_[2];
    std::uint32_t predelay_capacity_ = 0;
    std::uint32_t predelay_samples_ = 0;
    std::uint32_t predelay_write_ = 0;
    std::uint32_t dry_write_ = 0;
    std::uint32_t quantum_fill_ = 0;
    std::uint32_t output_fifo_capacity_ = 0;
    std::uint32_t output_fifo_read_ = 0;
    std::uint32_t output_fifo_write_ = 0;
    std::uint32_t output_fifo_available_ = 0;
    double ir_gain_db_ = signal::ZeroLatencyConvolver::kIrGainDbDefault;
    double ir_gain_linear_ = 1.0;
    double predelay_ms_ = signal::ZeroLatencyConvolver::kPredelayMsDefault;
    double wet_gain_ = signal::ZeroLatencyConvolver::kWetPercentDefault / 100.0;
    double dry_gain_ = signal::ZeroLatencyConvolver::kDryPercentDefault / 100.0;
    double width_ = signal::ZeroLatencyConvolver::kWidthPercentDefault / 100.0;
    double lowcut_hz_ = signal::ZeroLatencyConvolver::kLowcutHzDefault;
    double highcut_hz_ = signal::ZeroLatencyConvolver::kHighcutHzDefault;
    double hp_coef_ = 1.0;
    double lp_coef_ = 1.0;
    std::array<double, 2> hp_prev_x_{};
    std::array<double, 2> hp_z_{};
    std::array<double, 2> lp_z_{};
    bool hp_active_ = false;
    bool lp_active_ = false;
    bool prepared_ = false;
};

using GpuConvolutionReverbNode = GpuConvolutionReverb;
 
} // namespace pulp::gpu_audio