gpu_audio_node.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <string>
 
#include <pulp/audio/buffer.hpp>
 
namespace pulp::gpu_audio {

enum class MissPolicy {
    Silence,

    PassthroughDry,

    CpuFallback,
};

struct GpuAudioNodeDescriptor {
    std::string name;
    uint32_t input_channels = 0;
    uint32_t output_channels = 0;
    uint32_t block_size = 0;
    uint32_t sample_rate = 0;
    uint32_t latency_blocks = 1;
 
    // Both default to FAILING CLOSED. A node that says nothing about its miss
    // behavior gets a bounded, obvious dropout — not a timeline break, and not a
    // CPU fallback it never implemented. Passing audio through on a miss has to
    // be a deliberate, stated choice, because a node author who never thought
    // about misses is exactly the author who has not made the fallback correct.
    MissPolicy miss_policy = MissPolicy::Silence;
    bool supports_cpu_fallback = false;

    std::uint32_t worker_pipeline_blocks = 0;
};
 
} // namespace pulp::gpu_audio
 
// After MissPolicy: the status header forward-declares it, and the class below
// needs GpuAudioStatus complete for status_snapshot().
#include <pulp/gpu_audio/gpu_audio_status.hpp>
 
namespace pulp::gpu_audio {
 
namespace detail {
struct RealtimeGpuNodeBinding;
} // namespace detail

class GpuAudioNode {
public:
    virtual ~GpuAudioNode() = default;
 
    virtual GpuAudioNodeDescriptor descriptor() const = 0;

    virtual bool prepare() = 0;

    virtual bool cpu_fallback_prepared() const noexcept {
        return false;
    }

    virtual void process_block(const audio::BufferView<const float>& input,
                               audio::BufferView<float>& output,
                               uint32_t n) = 0;

    virtual void prime_fallback(const audio::BufferView<const float>& /*input*/,
                                uint32_t /*n*/) noexcept {}

    virtual void process_cpu_fallback(const audio::BufferView<const float>& input,
                                      audio::BufferView<float>& output,
                                      uint32_t n) noexcept {
        const uint32_t ch = output.num_channels() < input.num_channels()
                                ? output.num_channels()
                                : input.num_channels();
        for (uint32_t c = 0; c < ch; ++c) {
            const float* src = input.channel_ptr(c);
            float* dst = output.channel_ptr(c);
            for (uint32_t i = 0; i < n; ++i) dst[i] = src[i];
        }
    }
 
    // Appended virtuals: new hooks go after every existing one so established
    // vtable slots keep their positions (tools/scripts/node_abi_gate.py).

    virtual GpuAudioStatus status_snapshot() const noexcept {
        return {};
    }

    virtual bool release_bounded(std::uint64_t /*budget_ns*/) noexcept {
        return true;
    }

    virtual bool bind_realtime_path(detail::RealtimeGpuNodeBinding& /*binding*/) noexcept {
        return false;
    }
};
 
} // namespace pulp::gpu_audio