native_core_processor.hpp

Go to the documentation of this file.

// pulp/format/native_core_processor.hpp
//
// A C++ `pulp::format::Processor` that owns a native-language DSP core through
// the language-neutral C ABI (pulp/native_components/native_core.h). This is
// the SDK seam for native-language DSP cores: a Rust / C / Zig core
// implements the C ABI vtable; this adapter translates Pulp's C++ Processor
// surface (StateStore params, ParameterEventQueue, BufferView, state blobs)
// into the POD FFI structs and back.
//
// The adapter itself has NO Rust dependency — it bridges any core that exports a
// `pulp_native_core_v1`. It is part of `pulp-format` and always builds; the Rust
// binding + reference cores are the separate opt-in lane.
//
// RT-safety: all scratch (channel-pointer arrays, the native param-event buffer)
// is allocated in prepare(); process() does no allocation, locking, or logging.
#pragma once
 
#include <pulp/native_components/native_core.h>
 
#include <pulp/audio/buffer.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/midi/buffer.hpp>
#include <pulp/state/store.hpp>
 
#include <atomic>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::format {

class NativeCoreProcessor : public Processor {
public:
    explicit NativeCoreProcessor(const pulp_native_core_v1* core);
    ~NativeCoreProcessor() override;
 
    NativeCoreProcessor(const NativeCoreProcessor&) = delete;
    NativeCoreProcessor& operator=(const NativeCoreProcessor&) = delete;
 
    PluginDescriptor descriptor() const override;
    void define_parameters(state::StateStore& store) override;
    void prepare(const PrepareContext& context) override;
    void release() override;
    void suspend() override;
    void resume() override;
    void process(audio::BufferView<float>& audio_output,
                 const audio::BufferView<const float>& audio_input,
                 midi::MidiBuffer& midi_in,
                 midi::MidiBuffer& midi_out,
                 const ProcessContext& context) override;
    std::vector<uint8_t> serialize_plugin_state() const override;
    bool deserialize_plugin_state(std::span<const uint8_t> data) override;
    int latency_samples() const override;
    // The native core receives every automation point with its offset.
    bool wants_sample_accurate_parameters() const override {
        return true;
    }

    std::optional<std::string> editor_command(std::string_view request_json);

    bool valid() const { return instance_ != nullptr; }
 
private:
    // Host-service callbacks handed to the core. `ctx` is always `this`.
    static void* host_alloc(void* ctx, std::size_t bytes);
    static void host_free(void* ctx, void* ptr);
    static void host_log(void* ctx, int32_t level, const char* utf8, std::size_t len);
    static int32_t host_push_midi_out(void* sink, const pulp_native_midi_event_v1* ev);
    static void host_notify_latency_changed(void* ctx);
 
    const pulp_native_core_v1* core_ = nullptr;
    pulp_native_instance* instance_ = nullptr;
    pulp_native_host_services_v1 host_{};
 
    // Native parameter id-hash per Pulp ParamID (ParamID == registration index).
    std::vector<uint64_t> paramid_to_hash_;
 
    // Preallocated process() scratch (filled per block, never resized in RT).
    std::vector<float*> in_ptrs_;
    std::vector<float*> out_ptrs_;
    std::vector<pulp_native_audio_bus_v1> in_buses_;
    std::vector<pulp_native_audio_bus_v1> out_buses_;
    std::vector<pulp_native_param_event_v1> event_scratch_;
 
    PrepareContext prepare_ctx_{};
    bool prepared_ = false;
    std::atomic<bool> latency_changed_{false};
};
 
}  // namespace pulp::format