sOURnd 文件 你的引擎
本頁內容
  1. 引擎的生命週期
  2. 規則
  3. 狀態碼
  4. 標頭檔

C ABI 參考

第 1 版。一個小巧、有版本控管的 C 介面,通往每一個 sournd 引擎。JUCE 模組只是它的薄薄一層封裝;任何支援 C FFI 的語言都能直接呼叫。

引擎的生命週期

控制執行緒,音訊已停止

  1. abi_version先檢查
  2. create
  3. prepare
  4. load_state如果有的話
  5. save_state
  6. destroy

音訊執行緒,即時安全

  1. set_param
  2. process影格數不得超過 prepare 時設定的上限
  3. 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 時的最大值。允許就地處理;輸出聲道不得重疊。影格數為零時什麼也不做。
  • 先用 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。

狀態碼

代碼名稱意義
0SOURND_OK成功
-1SOURND_INVALID空指標、超出範圍的值或錯誤的引數
-2SOURND_NOT_FOUND未知的引擎 id、參數 id 或索引
-3SOURND_BUFFER_TOO_SMALL輸出緩衝區太小;請先查詢所需大小
-4SOURND_NOT_PREPARED處理之前請先呼叫 prepare
-5SOURND_PANIC引擎發生故障;請銷毀該實例
-6SOURND_UNSUPPORTED此引擎不支援該聲道配置或功能
c
// 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