#pragma once #include /* EJOC_STATIC: this branch exists for building the sources directly into an application, where nothing is imported or exported. */ #if defined(_WIN32) #define EJOC_CALL __cdecl #else #define EJOC_CALL #endif #if defined(EJOC_STATIC) #define EJOC_API #elif defined(_WIN32) #if defined(EJOC_BUILD_DLL) #define EJOC_API __declspec(dllexport) #else #define EJOC_API __declspec(dllimport) #endif #else #define EJOC_API __attribute__((visibility("default"))) #endif #ifdef __cplusplus extern "C" { #endif enum { EJOC_ABI_VERSION = 4, EJOC_FRAME_SAMPLES = 1536, EJOC_TIMESLOTS = 24, EJOC_SUBBANDS = 64, EJOC_CORE_CHANNELS = 5, /* downmix configurations 0 and 3 */ EJOC_MAX_CORE_CHANNELS = 7, /* downmix configurations 1, 2 and 4 */ EJOC_OUTPUT_CHANNELS = 16, EJOC_CORE_OUT_CHANNELS = 8, /* passthrough order: L,R,C,LFE,Ls,Rs,(Lrs,Rrs) */ EJOC_LFE_SLOT = 3, /* LFE slot of the passthrough order */ EJOC_MAX_OBJECTS = 15, EJOC_MAX_DPOINTS = 2, EJOC_MAX_PARAMETER_BANDS = 23, EJOC_SPEAKER_BLOCK_SAMPLES = 32, EJOC_SPEAKER_COORDINATES = 3, EJOC_SPEAKER_CONTROLS_VERSION = 1, EJOC_BINAURAL_BLOCK_SAMPLES = 512, EJOC_BINAURAL_INPUT_CHANNELS = 16, EJOC_BINAURAL_OUTPUT_CHANNELS = 2, EJOC_BINAURAL_QMF_BANDS = 64, EJOC_BINAURAL_HYBRID_BANDS = 77 }; /* Per-frame status of ejoc_renderer_render_frame(). A status outside 0..6 is * the renderer's own no-metadata marker; the parse-status values match * joc_frame_params.status (JOC_FRAME_STATUS_* in joc_core.h). Any non-zero * status makes the frame invalid for matrix rendering: the renderer holds the * previous matrices or passes the core PCM through instead of decoding it. */ enum { EJOC_FRAME_STATUS_OK = 0, EJOC_FRAME_STATUS_UNSUPPORTED_DMX = 2, EJOC_FRAME_STATUS_OBJECTS_CLAMPED = 3, EJOC_FRAME_STATUS_BAD_PARAMETER_BAND = 4, EJOC_FRAME_STATUS_BAD_OFFSET_TS = 5, EJOC_FRAME_STATUS_TRAILING_DATA = 6, EJOC_FRAME_STATUS_NO_METADATA = 8 }; typedef void* ejoc_renderer_handle; typedef void* ejoc_speaker_renderer_handle; typedef void* ejoc_binaural_renderer_handle; /* Fixed array layouts used by ejoc_renderer_process(): bed_planar [core_channel_count][1536] lfe [1536] or NULL n_bands [15] n_dpoints [15] slope_idx [15] offset_ts [15][2] dq [15][2][7][23] output16 [16][1536] core_channel_count comes from ejoc_renderer_set_core_channels() and defaults to EJOC_CORE_CHANNELS; the dq stride is always EJOC_MAX_CORE_CHANNELS. Only objects selected by object_mask are read from the descriptor arrays. dq carries already dequantized matrix coefficients in double precision; the caller performs the JOC bitstream differential decoding for both dense and sparse objects, so this ABI is identical for both syntaxes. */ EJOC_API uint32_t EJOC_CALL ejoc_abi_version(void); EJOC_API const char* EJOC_CALL ejoc_build_info(void); EJOC_API ejoc_renderer_handle EJOC_CALL ejoc_renderer_create(void); EJOC_API void EJOC_CALL ejoc_renderer_destroy(ejoc_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_renderer_reset(ejoc_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_renderer_set_threads(ejoc_renderer_handle handle, uint32_t total_threads); /* core_channel_count comes from joc_dmx_config_idx: 5 for configurations 0 and 3, 7 for 1, 2 and 4. bed_planar is then [core_channel_count][1536] and only channels below core_channel_count are read from dq, whose stride stays [15][2][7][23]. phase_shift is sigma(k) = (k in {3,4}): it enables the Ls/Rs -j rotation of subbands above 0 together with the band-0 21-tap DC compensation. With the switch off, channels 3 and 4 only take the common ten-slot surround delay. The delay line and DC history advance either way, so the flag may change between frames. */ EJOC_API uint32_t EJOC_CALL ejoc_renderer_thread_count(ejoc_renderer_handle handle); EJOC_API const char* EJOC_CALL ejoc_renderer_last_error(ejoc_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_renderer_process( ejoc_renderer_handle handle, const float* bed_planar, const float* lfe, uint32_t core_channel_count, uint32_t phase_shift, uint32_t object_mask, const uint8_t* n_bands, const uint8_t* n_dpoints, const uint8_t* slope_idx, const uint8_t* offset_ts, const double* dq, double clipgain, float phase_new, float output_scale, float* output16_planar); /* Frame-level entry point: one E-AC-3 audio frame per call, with the seq state machine and the per-object previous-matrix state kept inside the renderer. This is what produces the 16-channel object result for the ADM, speaker and binaural backends; ejoc_renderer_process() stays as a single-frame kernel for A/B tests. Fixed array layouts, identical to ejoc_renderer_process(): bed_planar [core_channel_count][1536] (JOC lane order L,R,C,Ls,Rs,(pair)) lfe [1536] or NULL (zeros; the LFE delay ring still advances) n_bands, n_dpoints, slope_idx [15] offset_ts [15][2] (raw 5-bit JOC offsets, 0..23) dq [15][2][7][23] output16 [16][1536] (ch0 = LFE, ch1..15 = objects) frame_status is a JOC_FRAME_STATUS_* / EJOC_FRAME_STATUS_* value. has_metadata is 0 for an audio frame without a JOC EMDF container (frame_status must then be EJOC_FRAME_STATUS_NO_METADATA); such a frame always passes the 8 core planes through to output slots 0..7, delayed by 1217 samples, with slots 8..15 zero. declared_core_channels is the JOC header's n_channels (0 when unknown); a declared change against the previous frame's actual count turns the frame into a hard cut with the LFE ring cleared. phase_shift is sigma(k) = (k in {3,4}) for the frame's downmix configuration; phase_shift_valid = 0 keeps the previous switch (an unsupported downmix configuration has no usable one). clipgain is the frame's joc_clipgain when frame_status == 0. seq is the 10-bit JOC sequence counter. When has_metadata is 0 the object descriptors are ignored. Slot 0 of output16 is the LFE, slots 1..15 are the 15 objects; each frame's values are float32(clamped PCM) * output_scale, exactly like the reference. */ typedef struct ejoc_frame_input { uint32_t struct_size; uint32_t struct_version; const float* bed_planar; const float* lfe; uint32_t core_channel_count; uint32_t declared_core_channels; uint32_t phase_shift; uint32_t phase_shift_valid; uint32_t frame_status; uint32_t seq; uint32_t has_metadata; uint32_t object_mask; const uint8_t* n_bands; const uint8_t* n_dpoints; const uint8_t* slope_idx; const uint8_t* offset_ts; const double* dq; double clipgain; float output_scale; float* output16_planar; } ejoc_frame_input; enum { EJOC_FRAME_INPUT_VERSION = 1 }; EJOC_API int EJOC_CALL ejoc_renderer_render_frame(ejoc_renderer_handle handle, const ejoc_frame_input* input); /* High-precision object-to-speaker renderer. The renderer consumes interleaved float32 input PCM arranged as: objects16_interleaved [sample_count][16] where channel 0 is LFE and channels 1..15 are point objects. All spatial calculations, gain ramps, and accumulation use double. Output is interleaved: output_interleaved [sample_count][layout_channel_count] Each metadata entry is a complete object-state snapshot: metadata_offsets [metadata_count], relative to this process call ramp_durations [metadata_count], in samples positions_q15 [metadata_count][15][3] region_indices [metadata_count][15] or NULL (all region 0) height_enabled [metadata_count][15] or NULL (all enabled) object_gains [metadata_count][15] or NULL (all 1.0) metadata_offsets must be nondecreasing and <= sample_count. sample_count must be a multiple of EJOC_SPEAKER_BLOCK_SAMPLES. State and unfinished ramps are preserved across calls. */ /* Per-object speaker controls taken from OAMD metadata: warp mode, trim mode, the three trim levels and the two front-back balances. trim_bypass is indexed by object slot (1..15); slot 0 carries the LFE and is unused. warp_mode 0 leaves the floor Y coordinate unchanged; mode 1 maps it through clamp(2Y, 0, 1). Modes 2 and 3 render the 5.1-family and 4.0 layouts through an expanded surround layout (7.1-family, or a rear pair added to 4.0 without a centre or LFE) and fold the rear pair into the target surround pair: mode 2 uses the PLIIx coefficients (sqrt(3)/2 and 1/2), mode 3 the Standard (Lo/Ro) coefficients (1 and 0). Layouts without a single surround pair render directly. trim_mode selects where the gain comes from: automatic applies the layout position compensation, disabled applies no trim, and explicit applies the position-dependent trim from centre_db / surround_db / height_db. A bypassed object keeps its warp but loses the balance and the trim gain. Controls may change between calls; each call's metadata events use the controls passed with that call. A null pointer means warp 0, no trim and no balance. */ typedef enum ejoc_speaker_trim_mode { EJOC_SPEAKER_TRIM_AUTOMATIC = 0, EJOC_SPEAKER_TRIM_DISABLED = 1, EJOC_SPEAKER_TRIM_EXPLICIT = 2 } ejoc_speaker_trim_mode; typedef struct ejoc_speaker_controls { uint32_t struct_size; uint32_t struct_version; uint32_t warp_mode; uint32_t trim_mode; /* ejoc_speaker_trim_mode */ double centre_db; double surround_db; /* positive values are treated as zero */ double height_db; /* positive values are treated as zero */ double listener_balance; /* [-1, 1] */ double overhead_balance; /* [-1, 1] */ uint8_t trim_bypass[EJOC_MAX_OBJECTS + 1]; /* per object slot, slot 0 unused */ } ejoc_speaker_controls; EJOC_API uint32_t EJOC_CALL ejoc_speaker_layout_channel_count(uint32_t speaker_bitfield); EJOC_API ejoc_speaker_renderer_handle EJOC_CALL ejoc_speaker_renderer_create(uint32_t speaker_bitfield); EJOC_API void EJOC_CALL ejoc_speaker_renderer_destroy(ejoc_speaker_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_speaker_renderer_reset(ejoc_speaker_renderer_handle handle); EJOC_API const char* EJOC_CALL ejoc_speaker_renderer_last_error(ejoc_speaker_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_speaker_renderer_process( ejoc_speaker_renderer_handle handle, const float* objects16_interleaved, uint32_t sample_count, uint32_t metadata_count, const uint32_t* metadata_offsets, const uint32_t* ramp_durations, const uint16_t* positions_q15, const uint8_t* region_indices, const uint8_t* height_enabled, const double* object_gains, const ejoc_speaker_controls* controls, double* output_interleaved); EJOC_API ejoc_binaural_renderer_handle EJOC_CALL ejoc_binaural_renderer_create(void); EJOC_API void EJOC_CALL ejoc_binaural_renderer_destroy(ejoc_binaural_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_binaural_renderer_reset(ejoc_binaural_renderer_handle handle); EJOC_API const char* EJOC_CALL ejoc_binaural_renderer_last_error( ejoc_binaural_renderer_handle handle); EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_kernels( ejoc_binaural_renderer_handle handle, const double* qmf_analysis, const double* hybrid_low, const int16_t* hybrid_indices, const double* hybrid_values, uint32_t hybrid_count, const double* qmf_basis, const double* qmf_taps); EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_room( ejoc_binaural_renderer_handle handle, uint32_t bands, uint32_t allpass_count, const uint32_t* allpass_delays, const double* allpass_gains, const uint32_t* fdn_delays, const double* fdn_matrix, uint32_t output_tap_delay, const double* feedback_complex, const double* output_taps, const double* output_complex, uint32_t extra_count, const uint32_t* extra_delays, const double* extra_fields_complex, const double* extra_matrices); EJOC_API int EJOC_CALL ejoc_binaural_renderer_process( ejoc_binaural_renderer_handle handle, const double* input16_interleaved, const double* gains_complex, const double* room_sends, double output_gain, double* output_stereo_interleaved); /* Native SOFA binaural renderer. The handle owns the complete runtime: 64-QMF/77-hybrid analysis and synthesis, fifth-order ACN/N3D real spherical-harmonic direction-field evaluation, per-object whole-QMF-slot delay histories, six first-order image-source early reflections, the shared unitary-FDN late room, the 120-180 Hz LFE low-pass and the 961-sample latency compensation. The caller configures the filterbank tables, the compiled HRTF field and the room constants once, then per 512-sample block updates every source with ejoc_jochrtf_set_source() and calls ejoc_jochrtf_process(). Process returns the number of trimmed stereo samples written; the first 961 processed samples across calls are discarded. */ typedef void* ejoc_jochrtf_handle; EJOC_API ejoc_jochrtf_handle EJOC_CALL ejoc_jochrtf_create(void); EJOC_API void EJOC_CALL ejoc_jochrtf_destroy(ejoc_jochrtf_handle handle); EJOC_API int EJOC_CALL ejoc_jochrtf_reset(ejoc_jochrtf_handle handle); EJOC_API const char* EJOC_CALL ejoc_jochrtf_last_error( ejoc_jochrtf_handle handle); EJOC_API int EJOC_CALL ejoc_jochrtf_configure_kernels( ejoc_jochrtf_handle handle, const double* qmf_analysis, const double* hybrid_low, const int16_t* hybrid_indices, const double* hybrid_values, uint32_t hybrid_count, const double* qmf_basis, const double* qmf_taps); EJOC_API int EJOC_CALL ejoc_jochrtf_configure_field( ejoc_jochrtf_handle handle, const double* coefficients, const double* delay_coefficients, const double* delay_bounds, const double* band_centers, double measurement_radius_m); EJOC_API int EJOC_CALL ejoc_jochrtf_configure_room( ejoc_jochrtf_handle handle, const double* room_dims, const double* listener_pos, const double* wall_gains, double speed_of_sound, const uint32_t* fdn_delays, const double* fdn_feedback, double damping, double fdn_output_gain, const uint32_t* allpass_delays, const double* allpass_gains, uint32_t enable_early_reflections, uint32_t enable_late_room); EJOC_API int EJOC_CALL ejoc_jochrtf_set_source( ejoc_jochrtf_handle handle, uint32_t source, const double* position_adm, uint32_t profile, double gain, uint32_t enabled, uint32_t special_lfe, uint32_t fade); EJOC_API int EJOC_CALL ejoc_jochrtf_process( ejoc_jochrtf_handle handle, const double* input16_interleaved, uint32_t sample_count, double output_gain, double* output_stereo_interleaved); EJOC_API int EJOC_CALL ejoc_jochrtf_finish( ejoc_jochrtf_handle handle, uint32_t flush_samples, double* output_stereo_interleaved, uint32_t capacity); #ifdef __cplusplus } #endif