93 lines
4.9 KiB
C
93 lines
4.9 KiB
C
#ifndef XTC_BACKEND_H
|
|
#define XTC_BACKEND_H
|
|
|
|
#include "xtc_engine.h"
|
|
#include "xtc_audio.h"
|
|
#include "xtc_midi.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
typedef struct xtc_backend xtc_backend;
|
|
|
|
typedef enum {
|
|
XTC_BACKEND_JACK = 1
|
|
} xtc_backend_kind;
|
|
|
|
typedef struct {
|
|
xtc_backend_kind kind;
|
|
const char *client_name; /* Borrowed for open only; nonempty. */
|
|
size_t max_frames; /* 1..65536, at least the server's current block. */
|
|
size_t channel_count; /* 1 mono or 2 stereo output; input/recording remain mono. */
|
|
} xtc_backend_config;
|
|
|
|
typedef struct {
|
|
float peak_left, peak_right; /* Last-block output peaks, zero while stopped. */
|
|
unsigned int sample_rate;
|
|
unsigned int buffer_frames;
|
|
unsigned int xruns; /* Wraps modulo UINT_MAX + 1. */
|
|
unsigned int processed_blocks;
|
|
unsigned int midi_dropped; /* Malformed/overflowed input; unsigned wrap. */
|
|
unsigned int asset_issues; /* Unique missing/unreadable/unsupported assets. */
|
|
uint64_t sample_position; /* Successful callback frames; retained across stop/submit. */
|
|
unsigned int submitted_revision, active_revision;
|
|
int running;
|
|
int server_lost;
|
|
int sample_rate_changed; /* Sticky: close/reopen and resubmit to recover. */
|
|
xtc_result process_result;
|
|
} xtc_backend_status;
|
|
|
|
/* All operations are serialized on one control thread. Public API contains
|
|
* no JACK types. JACK is optional at build time (otherwise UNSUPPORTED).
|
|
* Opens without starting a server, changing devices, or connecting ports.
|
|
* Returns IO if server/client setup fails. On failure *out_backend is NULL,
|
|
* except if cleanup itself fails: a non-NULL handle must be closed/retried;
|
|
* only close is permitted on that partially initialized handle. */
|
|
xtc_result xtc_backend_open(const xtc_backend_config *config, xtc_backend **out_backend);
|
|
/* Stop/close establish callback quiescence before state can be destroyed.
|
|
* On failure the handle remains owned by caller; retry close. NULL close OK. */
|
|
xtc_result xtc_backend_close(xtc_backend *backend);
|
|
xtc_result xtc_backend_start(xtc_backend *backend);
|
|
xtc_result xtc_backend_stop(xtc_backend *backend);
|
|
/* Stopped only; changes transport clock, not oscillator phase. */
|
|
xtc_result xtc_backend_seek(xtc_backend *backend, uint64_t sample);
|
|
/* Copies graph. While running, capacity means pending slot busy.
|
|
* While stopped, transactionally replaces all retained plans (counters/revisions
|
|
* restart); failed compilation leaves the previous engine intact. */
|
|
xtc_result xtc_backend_submit(xtc_backend *backend, const xtc_graph *graph);
|
|
/* Stopped only. Preloads immutable audio and submits graph before committing.
|
|
* Asset issues are silent and reported in status/asset_issue. Other failures
|
|
* retain the previous plans. Arrangement edits are adopted on the next prepare. */
|
|
xtc_result xtc_backend_prepare_project(xtc_backend *backend, const xtc_project *project);
|
|
const char *xtc_backend_asset_issue(const xtc_backend *backend);
|
|
/* Borrowed recorder, set/detach only while stopped. Stop before finish/destroy. */
|
|
/* Control-thread panic is delivered at a block boundary via lock-free counter.
|
|
* Stops, seeks, xruns and event overflow also clear instrument voices. */
|
|
xtc_result xtc_backend_panic(xtc_backend *backend);
|
|
xtc_result xtc_backend_midi_port_name(const xtc_backend *backend, const char **out_name);
|
|
xtc_result xtc_backend_set_recorder(xtc_backend *backend, xtc_recorder *recorder);
|
|
void xtc_backend_collect(xtc_backend *backend);
|
|
/* Snapshot fields are individually coherent, not a transactional snapshot. */
|
|
xtc_result xtc_backend_get_status(const xtc_backend *backend, xtc_backend_status *out_status);
|
|
/* Borrowed names valid until close. Direction is the client's own port. */
|
|
/* Output channel 0 is legacy output, channel 1 is output_right in stereo. */
|
|
xtc_result xtc_backend_output_name(const xtc_backend *, size_t channel, const char **out_name);
|
|
xtc_result xtc_backend_port_name(const xtc_backend *backend, xtc_port_direction direction, const char **out_name);
|
|
/* Enumerates available mono audio ports (devices and software routes). Visitor
|
|
* receives a borrowed name valid only during call; return nonzero to stop.
|
|
* Control-thread only. JACK NULL list means no matching ports. */
|
|
typedef int (*xtc_backend_port_visitor)(const char *name, void *context);
|
|
xtc_result xtc_backend_visit_ports(xtc_backend *backend, xtc_port_direction direction, xtc_backend_port_visitor visitor,
|
|
void *context);
|
|
/* Connect/disconnect this client's port with a remote opposite-direction port.
|
|
* own_direction INPUT receives remote output; OUTPUT sends to remote input.
|
|
* Explicit user choice only; no automatic physical routing. */
|
|
xtc_result xtc_backend_connect(xtc_backend *backend, xtc_port_direction own_direction, const char *remote_name);
|
|
xtc_result xtc_backend_disconnect(xtc_backend *backend, xtc_port_direction own_direction, const char *remote_name);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|