xtc/include/xtc/xtc_native.h

#ifndef XTC_NATIVE_H
#define XTC_NATIVE_H

#include "xtc_midi.h"

#ifdef __cplusplus
extern "C" {
#endif

#define XTC_NATIVE_ABI_VERSION 1U
#define XTC_NATIVE_ID_BYTES 64U

typedef enum {
    XTC_NATIVE_EFFECT = 1,
    XTC_NATIVE_SOURCE,
    XTC_NATIVE_INSTRUMENT
} xtc_native_kind;

typedef struct {
    const float *input; /* NULL is silence; may equal output. Borrowed for call. */
    float *output;      /* Write every frame, including silence. */
    size_t frames;
    uint64_t position;            /* Absolute sample position, no wall clock. */
    const xtc_midi_event *events; /* Instruments only, sorted block offsets. */
    size_t event_count;
} xtc_native_block;

typedef struct {
    unsigned int abi_version;
    size_t struct_size;                   /* Must equal sizeof(xtc_native_descriptor) for ABI 1. */
    char identifier[XTC_NATIVE_ID_BYTES]; /* Nonempty printable ASCII, terminated. */
    xtc_native_kind kind;
    /* Control thread. On error, any non-NULL *state is destroyed by host. */
    /**
     * @brief Allocates and prepares plugin state on the control thread.
     *
     * @param sample_rate Processing rate in hertz.
     * @param max_frames Maximum frames per processing block.
     * @param parameter Initial processor parameter.
     * @param state Receives plugin state; the host destroys non-NULL state even on failure.
     * @return XTC_OK on success, or a preparation error.
     */
    xtc_result (*prepare)(double sample_rate, size_t max_frames, float parameter, void **state);
    /* Single audio owner (or stopped). No allocation/free, I/O, locks or GUI. */
    /**
     * @brief Resets plugin state without allocation, I/O, locking, or GUI calls.
     *
     * @param state Plugin state owned exclusively by the audio consumer, or stopped.
     */
    void (*reset)(void *state);
    /**
     * @brief Processes one block without allocation, I/O, locking, or GUI calls.
     *
     * @param state Plugin state owned exclusively by the audio consumer.
     * @param block Borrowed buffers and events; write every output frame, including silence.
     * @return XTC_OK on success, or a processing error that makes the host silence the block.
     */
    xtc_result (*process)(void *state, const xtc_native_block *block);
    /* Control thread after quiescence; must accept NULL. */
    /**
     * @brief Releases plugin state on the control thread after callback quiescence.
     *
     * @param state Plugin state to release; must accept NULL.
     */
    void (*destroy)(void *state);
} xtc_native_descriptor;
typedef struct xtc_native xtc_native;

/* Descriptors are copied; callback code must remain loaded through destruction.
 * Trusted statically linked C code, not a sandbox or stable shared-library ABI. */
/**
 * @brief Checks the native descriptor's ABI, identifier, kind, and required callbacks.
 *
 * @param d Native processor descriptor.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_native_validate(const xtc_native_descriptor * d);
/**
 * @brief Copies a native descriptor and prepares a processor instance on the control thread.
 *
 * @param d Native processor descriptor.
 * @param rate Sample rate in hertz.
 * @param max_frames Maximum frames per processing block.
 * @param parameter Native parameter or automation lane selector, as applicable.
 * @param out_processor Receives the newly allocated processor; caller owns it on success.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_native_create(const xtc_native_descriptor * d, double rate, size_t max_frames, float parameter,
                             xtc_native **out_processor);
/**
 * @brief Destroys native state and releases the host wrapper; accepts NULL.
 *
 * @param p Native processor instance.
 */
void xtc_native_destroy(xtc_native * p);
/**
 * @brief Resets native state and transport continuity; accepts NULL.
 *
 * @param p Native processor instance.
 */
void xtc_native_reset(xtc_native * p);
/* Bounded, single-owner, realtime-safe host path (callbacks must obey contract).
 * Invalid arguments leave state/output unchanged. Zero frames is a no-op.
 * Discontinuity resets before processing. Callback failure silences this block
 * and resets the processor. Successful nonfinite output samples become zero. */
/**
 * @brief Processes a bounded native block, resetting on discontinuity and silencing callback failures.
 *
 * @param p Native processor instance.
 * @param b Borrowed processing buffers and block metadata.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_native_process(xtc_native * p, const xtc_native_block * b);
/* Graph accepts effects/sources; creates independent L/R instances on compile.
 * For instruments, process events explicitly then feed the existing instrument
 * source buffer through xtc_plan_process_sources/stereo. Graph add returns
 * UNSUPPORTED for instrument descriptors (no event port in current topology).
 * Native graphs are session-only: project save returns UNSUPPORTED. */
/**
 * @brief Adds a validated native effect or source descriptor to the graph.
 *
 * @param graph Graph model; borrowed for this call.
 * @param descriptor Native processor descriptor.
 * @param parameter Native parameter or automation lane selector, as applicable.
 * @param out_id Receives the id.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_graph_add_native(xtc_graph * graph, const xtc_native_descriptor * descriptor, float parameter, size_t *out_id);
/**
 * @brief Copies the native descriptor of a node selected by stable identifier.
 *
 * @param graph Graph model; borrowed for this call.
 * @param node_id Stable node identifier.
 * @param out_descriptor Receives the descriptor.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_graph_get_native(const xtc_graph * graph, size_t node_id, xtc_native_descriptor *out_descriptor);

#ifdef __cplusplus
}
#endif

#endif