C ABI 레퍼런스
버전 1. 모든 sournd 엔진을 위한 작고 버전이 관리되는 C 인터페이스예요. JUCE 모듈은 이 위에 얹은 얇은 래퍼이고, C FFI가 있는 언어라면 어디서든 호출할 수 있어요.
엔진의 수명 주기
컨트롤 스레드, 오디오 정지 상태
abi_version먼저 확인createprepareload_state있는 경우save_statedestroy
오디오 스레드, 리얼타임 안전
set_paramprocessprepare한 프레임 수를 넘지 않게latency,tail_seconds, 그리고 리드아웃
규칙
- 엔진을 만들기 전에
sournd_engine_abi_version()이SOURND_ENGINE_ABI_VERSION과 같은지 확인하세요. - 한 인스턴스에 대한 호출은 직렬화하세요. 처리 스레드마다 인스턴스를 하나씩 쓰세요.
- 컨트롤 스레드, 오디오 정지 상태:
create,destroy,prepare,prepare_layout,save_state,load_state,value_to_text, 그리고 메타데이터 호출. - 오디오 스레드, 리얼타임 안전:
process,process_sidechain,reset,set_param,get_param,latency,tail_seconds, 그리고 리드아웃. - 파라미터 id는 엔진 매니페스트에서 그 파라미터가 놓인 위치예요.
- 문자열은 UTF-8이고 NUL로 끝나요. 카탈로그 문자열은 라이브러리 수명 동안, 파라미터 문자열은
destroy까지 유효해요. process는 채널 하나 또는 둘을 받고,frames는 prepare한 최대값을 넘으면 안 돼요. 제자리 처리도 가능하지만 출력 채널끼리 겹치면 안 돼요. 프레임이 0이면 아무 일도 하지 않아요.- 상태 크기는
save_state(e, NULL, 0, &size)로 조회하고, 메모리를 할당한 다음 저장하세요. load_state는 엔진 버전이 달라도 이전해 줘요. 저장된 값은 파라미터 id로 맞추고, 상태에 없는 파라미터는 기본값을 쓰고, 엔진에 더 이상 없는 id는 무시해요.state_report는 마지막 로드에서 두 경우가 각각 몇 개인지 알려 줘요. 다른 엔진의 상태이거나 손상된 데이터만 거부하고, 그 경우에는 아무것도 바뀌지 않아요.SOURND_PARAM_LOG는 로그 테이퍼를 뜻해요. 0에서 1 사이의 호스트 비율p는min * (max / min)^p가 돼요. 이 플래그가 없으면 범위는 선형이에요.SOURND_PANIC이 나면 인스턴스는 손상된 상태예요.destroy만 허용돼요.
상태 코드
| 코드 | 이름 | 의미 |
|---|---|---|
| 0 | SOURND_OK | 성공 |
| -1 | SOURND_INVALID | 널 포인터, 범위를 벗어난 값 또는 잘못된 인자 |
| -2 | SOURND_NOT_FOUND | 알 수 없는 엔진 id, 파라미터 id 또는 인덱스 |
| -3 | SOURND_BUFFER_TOO_SMALL | 출력 버퍼가 너무 작음. 먼저 크기를 조회하세요 |
| -4 | SOURND_NOT_PREPARED | 처리하기 전에 prepare를 호출하세요 |
| -5 | SOURND_PANIC | 엔진이 실패했어요. 인스턴스를 destroy하세요 |
| -6 | SOURND_UNSUPPORTED | 이 엔진이 지원하지 않는 레이아웃 또는 기능 |
헤더
// SPDX-License-Identifier: Apache-2.0
#ifndef SOURND_ENGINE_H
#define SOURND_ENGINE_H
#include <stdint.h>
#include <stddef.h>
#define SOURND_ENGINE_ABI_VERSION 1u
#ifdef __cplusplus
extern "C" {
#endif
typedef struct sournd_engine sournd_engine;
enum { SOURND_OK=0, SOURND_INVALID=-1, SOURND_NOT_FOUND=-2, SOURND_BUFFER_TOO_SMALL=-3,
SOURND_NOT_PREPARED=-4, SOURND_PANIC=-5, SOURND_UNSUPPORTED=-6,
SOURND_QUEUE_FULL=-7 };
/* Descriptor flags. INSTRUMENT: an engine the musician plays with notes (catalogue kind
"instrument"); see the note input section below. */
enum { SOURND_ENGINE_SIDECHAIN=1, SOURND_ENGINE_INSTRUMENT=2 };
/* Note events one instance holds for its next process call. */
#define SOURND_NOTE_QUEUE_CAPACITY 256u
/* LOG (added to ABI version 1 append-only): the parameter has a logarithmic taper, so equal
travel is an equal ratio: value = min * pow(max / min, p) for a proportion p in 0..1. Only
set when 0 < min < max. Without it the taper is linear. Hosts and UIs that ignore the flag
still work; they show a linear range. */
enum { SOURND_PARAM_STEPPED=1, SOURND_PARAM_BOOL=2, SOURND_PARAM_HIDDEN=4, SOURND_PARAM_LOG=8 };
/* UTF-8, NUL terminated. Metadata remains valid until destroy (catalogue info: forever). */
typedef struct { const char *id, *name, *version; uint32_t flags; } sournd_engine_descriptor;
typedef struct { uint32_t id; const char *name; double min, max, default_value;
const char *unit; uint32_t flags; } sournd_param_descriptor;
uint32_t sournd_engine_abi_version(void);
uint32_t sournd_engine_count(void);
int32_t sournd_engine_info(uint32_t index, sournd_engine_descriptor *out);
int32_t sournd_engine_create(const char *id, sournd_engine **out);
int32_t sournd_engine_destroy(sournd_engine *engine);
int32_t sournd_engine_param_count(sournd_engine *engine, uint32_t *out);
int32_t sournd_engine_param_info(sournd_engine *engine, uint32_t index, sournd_param_descriptor *out);
int32_t sournd_engine_value_to_text(sournd_engine *engine, uint32_t id, double value, char *out, size_t capacity);
int32_t sournd_engine_prepare(sournd_engine *engine, double sample_rate, uint32_t max_block);
/* Explicit layout for Processor implementations whose prepare depends on bus width.
prepare() selects stereo and, when declared, stereo sidechain. */
int32_t sournd_engine_prepare_layout(sournd_engine *engine, double sample_rate, uint32_t max_block, uint32_t channels, uint32_t side_channels);
int32_t sournd_engine_reset(sournd_engine *engine);
int32_t sournd_engine_set_param(sournd_engine *engine, uint32_t id, double value);
int32_t sournd_engine_get_param(sournd_engine *engine, uint32_t id, double *out);
/* One or two channels, frames <= prepared max_block. In-place is allowed. Output channels
must not overlap each other. Sidechain can be absent (0 channels), mono or stereo.
Buffers and pointer arrays must be valid for the call. Zero frames is a no-op.
An instrument may be given in=NULL (it hears silence); effects require input. */
int32_t sournd_engine_process(sournd_engine *engine, const float *const *in, float *const *out, uint32_t channels, uint32_t frames);
int32_t sournd_engine_process_sidechain(sournd_engine *engine, const float *const *in, float *const *out, uint32_t channels, const float *const *side, uint32_t side_channels, uint32_t frames);
int32_t sournd_engine_latency(sournd_engine *engine, uint32_t *out);
int32_t sournd_engine_tail_seconds(sournd_engine *engine, double *out);
int32_t sournd_engine_readout_count(sournd_engine *engine, uint32_t *out);
int32_t sournd_engine_readout_value(sournd_engine *engine, uint32_t index, double *out);
/* Note input (instruments). Added to ABI version 1 append-only: effects and existing calls
are unchanged, and a v1 host that never calls these sees no difference.
is_instrument returns 1 for an instrument, 0 for an effect, or a negative status.
note_on/note_off/all_notes_off follow the threading rules of set_param: audio thread (or
any thread that owns the instance), serialised with process, called before the process
call they belong to. They never allocate, lock or block.
Timing: sample_offset is a frame position inside the NEXT process call; 0 is its first
frame. Each event takes effect before the frame at its offset (the engine splits the
block there). Events at the same offset apply in call order; events need not be sent in
offset order. An offset at or past the frame count of the next process call is carried,
not dropped: it takes effect at frame 0 of the call after that. A zero-frame process call
applies and carries nothing.
Arguments: note is a MIDI note number 0..127; velocity is 0..1 (a note_on at velocity 0 is a
note_off, as in MIDI); sample_offset must be below the prepared max_block. Status codes:
SOURND_INVALID for a NULL engine or a bad note, velocity (NaN, infinite, outside 0..1) or
offset; SOURND_UNSUPPORTED on an effect; SOURND_NOT_PREPARED before prepare;
SOURND_QUEUE_FULL when SOURND_NOTE_QUEUE_CAPACITY events already wait for the next process
call: that event is refused and nothing else changes (send all_notes_off to recover).
all_notes_off ends every note at once and drops every queued event; it works prepared or
not (SOURND_UNSUPPORTED on an effect). prepare, prepare_layout and reset also drop queued
events. */
int32_t sournd_engine_is_instrument(sournd_engine *engine);
int32_t sournd_engine_note_on(sournd_engine *engine, uint32_t note, float velocity, uint32_t sample_offset);
int32_t sournd_engine_note_off(sournd_engine *engine, uint32_t note, uint32_t sample_offset);
int32_t sournd_engine_all_notes_off(sournd_engine *engine);
/* Control thread, audio stopped. Query required length using out=NULL, capacity=0.
State is engine-specific and versioned; it preserves settings, not delay history.
Loading migrates across engine versions: saved parameters are matched by id (never by
position or count), a current parameter the state lacks takes its default, and a saved id
this version does not have is ignored. Loading refuses the whole state (SOURND_INVALID,
nothing changes) only on a genuine clash: another engine's id, a value that is not finite,
outside the parameter's range or fractional for a stepped or switch parameter, an id saved
twice, or a truncated or malformed envelope.
state_report (added to ABI version 1 append-only) gives what the last successful load
migrated: ignored = saved ids this version does not have, defaulted = parameters set to
their default. Both are 0 before any load. */
int32_t sournd_engine_save_state(sournd_engine *engine, uint8_t *out, size_t capacity, size_t *written);
int32_t sournd_engine_load_state(sournd_engine *engine, const uint8_t *data, size_t length);
int32_t sournd_engine_state_report(sournd_engine *engine, uint32_t *ignored, uint32_t *defaulted);
/* Ownership: serialise ALL calls for an instance. create/destroy/prepare/state/text/metadata
are control-thread operations; process/reset/set/get/latency/tail/readouts and the note
calls are RT safe for conforming engines. Null is rejected (destroy(NULL) succeeds). Dangling, fabricated,
misaligned pointers and concurrent access violate the contract and cannot be checked.
On PANIC the instance is poisoned: only destroy is permitted. Build with panic=unwind. */
#ifdef __cplusplus
}
#endif
#endif