xtc/include/xtc/xtc_realtime.h

#ifndef XTC_REALTIME_H
#define XTC_REALTIME_H

#include "xtc_engine.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef struct xtc_realtime xtc_realtime;
/* Single audio owner, or stopped/joined control owner: position current/future plans. */
xtc_result xtc_realtime_position(xtc_realtime *engine, uint64_t position);

typedef struct {
    unsigned int processed_blocks; /* Wraps modulo UINT_MAX + 1. */
    xtc_result last_result;
    unsigned int submitted_revision, active_revision; /* Wrap like block counter. */
} xtc_realtime_status;

/* Control thread only. A single control producer and single audio consumer.
 * C99 with GCC/Clang lock-free __atomic builtins is required; unsupported
 * targets return XTC_ERR_UNSUPPORTED. No ownership is shared with callers. */
/**
 * @brief Allocates the single-producer, single-consumer realtime engine.
 *
 * @param sample_rate Sample rate in hertz.
 * @param max_frames Maximum frames per processing block.
 * @param out_engine Receives the newly allocated engine; caller owns it on success.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_create(double sample_rate, size_t max_frames, xtc_realtime **out_engine);
/* Requires the audio consumer to have stopped and joined. */
/**
 * @brief Releases the engine after the audio consumer has stopped; accepts NULL.
 *
 * @param engine Realtime engine handle.
 */
void xtc_realtime_destroy(xtc_realtime *engine);
/* Compiles/copies a graph. One pending plan allowed; full mailbox returns
 * XTC_ERR_CAPACITY without changing the active or pending plan. */
/**
 * @brief Compiles and publishes a graph to the single pending-plan slot.
 *
 * @param engine Realtime engine handle.
 * @param graph Graph model; borrowed for this call.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_submit(xtc_realtime *engine, const xtc_graph *graph);
/* Frees acknowledged retired state, never the audio thread's active plan. */
/**
 * @brief Frees acknowledged retired plans on the control thread.
 *
 * @param engine Realtime engine handle.
 */
void xtc_realtime_collect(xtc_realtime *engine);
/**
 * @brief Copies processing counters, plan revisions, and the last processing result.
 *
 * @param engine Realtime engine handle.
 * @param out_status Receives the status.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_get_status(const xtc_realtime *engine, xtc_realtime_status *out_status);
/* Audio consumer only. Adopts at most one plan per block, without allocation,
 * freeing, locks or I/O. No plan means silence. On failure writes silence.
 * frame_count must be <= configured max_frames and output must hold it.
 * Oversized buffers are silenced too; callers must bound their own frame count.
 * NULL input means silence. Zero frames is a no-op. */
/**
 * @brief Adopts a pending plan and processes stereo sources without allocation or locking.
 *
 * @param engine Realtime engine handle.
 * @param input Borrowed input sample buffer.
 * @param audio_left Borrowed left timeline source buffer; NULL means silence.
 * @param audio_right Borrowed right timeline source buffer; NULL means silence.
 * @param midi_left Borrowed left instrument source buffer; NULL means silence.
 * @param midi_right Borrowed right instrument source buffer; NULL means silence.
 * @param left Destination left-channel buffer.
 * @param right Destination right-channel buffer; NULL selects mono rendering.
 * @param frames Number of audio frames.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_process_stereo(xtc_realtime * engine, const float *input, const float *audio_left,
                                       const float *audio_right, const float *midi_left, const float *midi_right,
                                       float *left, float *right, size_t frames);
/**
 * @brief Processes mono timeline and instrument sources through the realtime engine.
 *
 * @param engine Realtime engine handle.
 * @param input Borrowed input sample buffer.
 * @param timeline Borrowed timeline source buffer; NULL means silence.
 * @param instrument Borrowed instrument source buffer; NULL means silence.
 * @param output Destination buffer with room for the requested frames.
 * @param frames Number of audio frames.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_process_sources(xtc_realtime *engine, const float *input, const float *timeline,
                                        const float *instrument, float *output, size_t frames);
/**
 * @brief Processes a mono block with timeline audio and no instrument source.
 *
 * @param engine Realtime engine handle.
 * @param input Borrowed input sample buffer.
 * @param timeline Borrowed timeline source buffer; NULL means silence.
 * @param output Destination buffer with room for the requested frames.
 * @param frames Number of audio frames.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_process_audio(xtc_realtime *engine, const float *input, const float *timeline, float *output,
                                      size_t frames);
/**
 * @brief Processes a mono block with external input only.
 *
 * @param engine Realtime engine handle.
 * @param input Borrowed input sample buffer.
 * @param output Destination buffer with room for the requested frames.
 * @param frame_count Number of audio frames.
 * @return XTC_OK on success, or an error code describing the failure.
 */
xtc_result xtc_realtime_process(xtc_realtime *engine, const float *input, float *output, size_t frame_count);

#ifdef __cplusplus
}
#endif

#endif