offline_signal_graph_host.hpp

Go to the documentation of this file.

#pragma once
 
// Offline render host for pulp::host::SignalGraph.
//
// OfflineSignalGraphHost is a control-thread/test harness layered ON TOP of the
// public SignalGraph API — it never touches SignalGraph internals. It owns the
// staging + output buffers and steps a fixed block size across a frame range,
// feeding each block through SignalGraph::process(). Its purpose is to render a
// graph the same way a real-time host would, but deterministically and without
// a live audio device, so the same graph can be rendered at different block
// partitionings and compared.
//
// Scope note (invariant "offline equals online"): this host drives the
// no-transport SignalGraph::process() overload, so no node receives host
// transport here regardless of whether it opts in (routed nodes can consume
// transport via the transport-bearing overload, but this host never supplies
// one). The only thing that distinguishes an "online" (live, block-by-block)
// render from an "offline" one here is therefore the block partitioning. For
// DETERMINISTIC nodes whose output depends only on the current block's samples,
// rendering the same input at any block size must produce the same result.
// This host makes that comparison cheap to set up.
//
// Usage:
//   SignalGraph graph;
//   ... build + connect nodes ...
//   OfflineSignalGraphHost host(graph);
//   OfflineSignalGraphConfig cfg; cfg.block_frames = 128;
//   host.prepare(cfg);
//   OfflineSignalGraphOptions opt; opt.frame_count = 4096; opt.input = in_view;
//   auto result = host.render(opt);  // result.audio holds the rendered output
 
#include <pulp/audio/buffer.hpp>
 
#include <cstdint>
#include <vector>
 
namespace pulp::host {
 
class SignalGraph;

struct OfflineSignalGraphConfig {
    double sample_rate = 48000.0;
    int block_frames = 512;
    int input_channels = 2;
    int output_channels = 2;
};

struct OfflineSignalGraphOptions {
    std::uint64_t frame_count = 0;
    audio::BufferView<const float> input;
};

struct OfflineSignalGraphResult {
    bool ok = false;
    audio::Buffer<float> audio;
    int blocks_rendered = 0;
};

class OfflineSignalGraphHost {
public:
    explicit OfflineSignalGraphHost(SignalGraph& graph);

    bool prepare(const OfflineSignalGraphConfig& config);
 
    bool prepared() const noexcept { return prepared_; }
    const OfflineSignalGraphConfig& config() const noexcept { return config_; }

    OfflineSignalGraphResult render(const OfflineSignalGraphOptions& options);
 
private:
    SignalGraph& graph_;
    OfflineSignalGraphConfig config_;
    bool prepared_ = false;
 
    audio::Buffer<float> input_block_;
    audio::Buffer<float> output_block_;
    // Channel-pointer arrays over the staging buffers, rebuilt in prepare() so
    // render() can construct BufferViews without per-block allocation. Held as
    // float* (writable) and converted to const for the input view.
    std::vector<float*> input_ptrs_;
    std::vector<float*> output_ptrs_;
};
 
} // namespace pulp::host