From a223340c4498f49633d4108bb1ea5024071b1d53 Mon Sep 17 00:00:00 2001
From: bkrypt <4868093+bkrypt@users.noreply.github.com>
Date: Fri, 15 Apr 2022 13:38:58 +0200
Subject: [PATCH 1/7] Update `vendor/miniaudio` to v0.11.9
---
vendor/miniaudio/common.odin | 108 +-
vendor/miniaudio/data_conversion.odin | 291 +-
vendor/miniaudio/decoding.odin | 102 +-
vendor/miniaudio/device_io_procs.odin | 786 +-
vendor/miniaudio/device_io_types.odin | 365 +-
vendor/miniaudio/doc.odin | 2955 +-
vendor/miniaudio/effects.odin | 300 +
vendor/miniaudio/encoding.odin | 23 +-
vendor/miniaudio/engine.odin | 341 +
vendor/miniaudio/filtering.odin | 129 +-
vendor/miniaudio/generation.odin | 28 +-
vendor/miniaudio/job_queue.odin | 239 +
vendor/miniaudio/lib/miniaudio.lib | Bin 1873426 -> 2767136 bytes
vendor/miniaudio/logging.odin | 30 +
vendor/miniaudio/node_graph.odin | 469 +
vendor/miniaudio/resource_manager.odin | 288 +
vendor/miniaudio/src/miniaudio.h | 34632 ++++++++++++++++++-----
vendor/miniaudio/synchronization.odin | 152 +
vendor/miniaudio/utilities.odin | 175 +-
vendor/miniaudio/vfs.odin | 10 +-
20 files changed, 32998 insertions(+), 8425 deletions(-)
create mode 100644 vendor/miniaudio/effects.odin
create mode 100644 vendor/miniaudio/engine.odin
create mode 100644 vendor/miniaudio/job_queue.odin
create mode 100644 vendor/miniaudio/node_graph.odin
create mode 100644 vendor/miniaudio/resource_manager.odin
create mode 100644 vendor/miniaudio/synchronization.odin
diff --git a/vendor/miniaudio/common.odin b/vendor/miniaudio/common.odin
index 89e3d6bd2..d7b901714 100644
--- a/vendor/miniaudio/common.odin
+++ b/vendor/miniaudio/common.odin
@@ -13,13 +13,15 @@ when ODIN_OS == .Windows {
handle :: distinct rawptr
-/* SIMD alignment in bytes. Currently set to 64 bytes in preparation for future AVX-512 optimizations. */
-SIMD_ALIGNMENT :: 64
+/* SIMD alignment in bytes. Currently set to 32 bytes in preparation for future AVX optimizations. */
+SIMD_ALIGNMENT :: 32
-LOG_LEVEL_DEBUG :: 4
-LOG_LEVEL_INFO :: 3
-LOG_LEVEL_WARNING :: 2
-LOG_LEVEL_ERROR :: 1
+log_level :: enum c.int {
+ LOG_LEVEL_DEBUG = 4,
+ LOG_LEVEL_INFO = 3,
+ LOG_LEVEL_WARNING = 2,
+ LOG_LEVEL_ERROR = 1,
+}
channel :: enum u8 {
@@ -158,13 +160,13 @@ result :: enum c.int {
FAILED_TO_STOP_BACKEND_DEVICE = -303,
}
+
MIN_CHANNELS :: 1
-MAX_CHANNELS :: 32
+MAX_CHANNELS :: 254
MAX_FILTER_ORDER :: 8
-
stream_format :: enum c.int {
pcm = 0,
}
@@ -175,9 +177,9 @@ stream_layout :: enum c.int {
}
dither_mode :: enum c.int {
- none = 0,
- rectangle,
- triangle,
+ none = 0,
+ rectangle,
+ triangle,
}
format :: enum c.int {
@@ -191,6 +193,7 @@ format :: enum c.int {
s24 = 3, /* Tightly packed. 3 bytes per sample. */
s32 = 4,
f32 = 5,
+ count,
}
standard_sample_rate :: enum u32 {
@@ -224,7 +227,6 @@ channel_mix_mode :: enum c.int {
rectangular = 0, /* Simple averaging based on the plane(s) the channel is sitting on. */
simple, /* Drop excess channels; zeroed out extra channels. */
custom_weights, /* Use custom weights specified in ma_channel_router_config. */
- planar_blend = rectangular,
default = rectangular,
}
@@ -257,6 +259,10 @@ lcg :: struct {
state: i32,
}
+
+/* Spinlocks are 32-bit for compatibility reasons. */
+spinlock :: distinct u32
+
NO_THREADING :: false
when !NO_THREADING {
@@ -272,8 +278,6 @@ thread_priority :: enum c.int {
default = 0,
}
-/* Spinlocks are 32-bit for compatibility reasons. */
-spinlock :: distinct u32
when ODIN_OS == .Windows {
thread :: distinct rawptr
@@ -297,69 +301,6 @@ when ODIN_OS == .Windows {
}
}
-
-@(default_calling_convention="c", link_prefix="ma_")
-foreign lib {
- /*
- Locks a spinlock.
- */
- spinlock_lock :: proc(/*volatile*/ pSpinlock: ^spinlock) -> result ---
-
- /*
- Locks a spinlock, but does not yield() when looping.
- */
- spinlock_lock_noyield :: proc(/*volatile*/ pSpinlock: ^spinlock) -> result ---
-
- /*
- Unlocks a spinlock.
- */
- spinlock_unlock :: proc(/*volatile*/ pSpinlock: ^spinlock) -> result ---
-
-
- /*
- Creates a mutex.
-
- A mutex must be created from a valid context. A mutex is initially unlocked.
- */
- mutex_init :: proc(pMutex: ^mutex) -> result ---
-
- /*
- Deletes a mutex.
- */
- mutex_uninit :: proc(pMutex: ^mutex) ---
-
- /*
- Locks a mutex with an infinite timeout.
- */
- mutex_lock :: proc(pMutex: ^mutex) ---
-
- /*
- Unlocks a mutex.
- */
- mutex_unlock :: proc(pMutex: ^mutex) ---
-
-
- /*
- Initializes an auto-reset event.
- */
- event_init :: proc(pEvent: ^event) -> result ---
-
- /*
- Uninitializes an auto-reset event.
- */
- event_uninit :: proc(pEvent: ^event) ---
-
- /*
- Waits for the specified auto-reset event to become signalled.
- */
- event_wait :: proc(pEvent: ^event) -> result ---
-
- /*
- Signals the specified auto-reset event.
- */
- event_signal :: proc(pEvent: ^event) -> result ---
-}
-
} /* NO_THREADING */
@@ -385,17 +326,22 @@ foreign lib {
result_description :: proc(result: result) -> cstring ---
/*
- malloc(). Calls MA_MALLOC().
+ malloc()
*/
malloc :: proc(sz: c.size_t, pAllocationCallbacks: ^allocation_callbacks) -> rawptr ---
/*
- realloc(). Calls MA_REALLOC().
+ calloc()
+ */
+ calloc :: proc(sz: c.size_t, pAllocationCallbacks: ^allocation_callbacks) -> rawptr ---
+
+ /*
+ realloc()
*/
realloc :: proc(p: rawptr, sz: c.size_t, pAllocationCallbacks: ^allocation_callbacks) -> rawptr ---
/*
- free(). Calls MA_FREE().
+ free()
*/
free :: proc(p: rawptr, pAllocationCallbacks: ^allocation_callbacks) ---
@@ -417,7 +363,7 @@ foreign lib {
/*
Blends two frames in floating point format.
*/
- blend_f32 :: proc(pOut, pInA, pInB: ^f32, factor: f32, channels: u32) ---
+ blend_f32 :: proc(pOut, pInA, pInB: [^]f32, factor: f32, channels: u32) ---
/*
Retrieves the size of a sample in bytes for the given format.
diff --git a/vendor/miniaudio/data_conversion.odin b/vendor/miniaudio/data_conversion.odin
index 7167270a1..ffcf2fcb3 100644
--- a/vendor/miniaudio/data_conversion.odin
+++ b/vendor/miniaudio/data_conversion.odin
@@ -36,77 +36,106 @@ linear_resampler_config :: struct {
}
linear_resampler :: struct {
- config: linear_resampler_config,
+ config: linear_resampler_config,
inAdvanceInt: u32,
inAdvanceFrac: u32,
inTimeInt: u32,
inTimeFrac: u32,
x0: struct #raw_union {
- f32: [MAX_CHANNELS]f32,
- s16: [MAX_CHANNELS]i16,
+ f32: [^]f32,
+ s16: [^]i16,
}, /* The previous input frame. */
x1: struct #raw_union {
- f32: [MAX_CHANNELS]f32,
- s16: [MAX_CHANNELS]i16,
+ f32: [^]f32,
+ s16: [^]i16,
}, /* The next input frame. */
lpf: lpf,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
+}
+
+resampling_backend :: struct {}
+resampling_backend_vtable :: struct {
+ onGetHeapSize: proc "c" (pUserData: rawptr, pConfig: ^resampler_config, pHeapSizeInBytes: ^c.size_t) -> result,
+ onInit: proc "c" (pUserData: rawptr, pConfig: ^resampler_config, pHeap: rawptr, ppBackend: ^^resampling_backend) -> result,
+ onUninit: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend, pAllocationCallbacks: ^allocation_callbacks),
+ onProcess: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend, pFramesIn: rawptr, pFrameCountIn: ^u64, pFramesOut: rawptr, pFrameCountOut: ^u64) -> result,
+ onSetRate: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend, sampleRateIn: u32, sampleRateOut: u32) -> result, /* Optional. Rate changes will be disabled. */
+ onGetInputLatency: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend) -> u64, /* Optional. Latency will be reported as 0. */
+ onGetOutputLatency: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend) -> u64, /* Optional. Latency will be reported as 0. */
+ onGetRequiredInputFrameCount: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend, outputFrameCount: u64, pInputFrameCount: ^u64) -> result, /* Optional. Latency mitigation will be disabled. */
+ onGetExpectedOutputFrameCount: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend, inputFrameCount: u64, pOutputFrameCount: ^u64) -> result, /* Optional. Latency mitigation will be disabled. */
+ onReset: proc "c" (pUserData: rawptr, pBackend: ^resampling_backend) -> result,
}
resample_algorithm :: enum {
linear = 0, /* Fastest, lowest quality. Optional low-pass filtering. Default. */
- speex,
+ custom,
}
resampler_config :: struct {
- format: format, /* Must be either ma_format_f32 or ma_format_s16. */
- channels: u32,
- sampleRateIn: u32,
- sampleRateOut: u32,
- algorithm: resample_algorithm,
+ format: format, /* Must be either ma_format_f32 or ma_format_s16. */
+ channels: u32,
+ sampleRateIn: u32,
+ sampleRateOut: u32,
+ algorithm: resample_algorithm, /* When set to ma_resample_algorithm_custom, pBackendVTable will be used. */
+ pBackendVTable: ^resampling_backend_vtable,
+ pBackendUserData: rawptr,
linear: struct {
lpfOrder: u32,
- lpfNyquistFactor: f64,
- },
- speex: struct {
- quality: c.int, /* 0 to 10. Defaults to 3. */
},
}
resampler :: struct {
- config: resampler_config,
+ pBackend: ^resampling_backend,
+ pBackendVTable: ^resampling_backend_vtable,
+ pBackendUserData: rawptr,
+ format: format,
+ channels: u32,
+ sampleRateIn: u32,
+ sampleRateOut: u32,
state: struct #raw_union {
linear: linear_resampler,
- speex: struct {
- pSpeexResamplerState: rawptr, /* SpeexResamplerState* */
- },
- },
+ }, /* State for stock resamplers so we can avoid a malloc. For stock resamplers, pBackend will point here. */
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
linear_resampler_config_init :: proc(format: format, channels: u32, sampleRateIn, sampleRateOut: u32) -> linear_resampler_config ---
- linear_resampler_init :: proc(pConfig: ^linear_resampler_config, pResampler: ^linear_resampler) -> result ---
- linear_resampler_uninit :: proc(pResampler: ^linear_resampler) ---
+ linear_resampler_get_heap_size :: proc(pConfig: ^linear_resampler_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ linear_resampler_init_preallocated :: proc(pConfig: ^linear_resampler_config, pHeap: rawptr, pResampler: ^linear_resampler) -> result ---
+ linear_resampler_init :: proc(pConfig: ^linear_resampler_config, pAllocationCallbacks: ^allocation_callbacks, pResampler: ^linear_resampler) -> result ---
+ linear_resampler_uninit :: proc(pResampler: ^linear_resampler, pAllocationCallbacks: ^allocation_callbacks) ---
linear_resampler_process_pcm_frames :: proc(pResampler: ^linear_resampler, pFramesIn: rawptr, pFrameCountIn: ^u64, pFramesOut: rawptr, pFrameCountOut: ^u64) -> result ---
linear_resampler_set_rate :: proc(pResampler: ^linear_resampler, sampleRateIn, sampleRateOut: u32) -> result ---
linear_resampler_set_rate_ratio :: proc(pResampler: ^linear_resampler, ratioInOut: f32) -> result ---
- linear_resampler_get_required_input_frame_count :: proc(pResampler: ^linear_resampler, outputFrameCount: u64) -> u64 ---
- linear_resampler_get_expected_output_frame_count :: proc(pResampler: ^linear_resampler, inputFrameCount: u64) -> u64 ---
linear_resampler_get_input_latency :: proc(pResampler: ^linear_resampler) -> u64 ---
linear_resampler_get_output_latency :: proc(pResampler: ^linear_resampler) -> u64 ---
+ linear_resampler_get_required_input_frame_count :: proc(pResampler: ^linear_resampler, outputFrameCount: u64, pInputFrameCount: ^u64) -> result ---
+ linear_resampler_get_expected_output_frame_count :: proc(pResampler: ^linear_resampler, inputFrameCount: u64, pOutputFrameCount: ^u64) -> result ---
+ linear_resampler_reset :: proc(pResampler: ^linear_resampler) -> result ---
resampler_config_init :: proc(format: format, channels: u32, sampleRateIn, sampleRateOut: u32, algorithm: resample_algorithm) -> resampler_config ---
+ resampler_get_heap_size :: proc(pConfig: ^resampler_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ resampler_init_preallocated :: proc(pConfig: ^resampler_config, pHeap: rawptr, pResampler: ^resampler) -> result ---
+
/*
Initializes a new resampler object from a config.
*/
- resampler_init :: proc(pConfig: ^resampler_config, pResampler: ^resampler) -> result ---
+ resampler_init :: proc(pConfig: ^resampler_config, pAllocationCallbacks: ^allocation_callbacks, pResampler: ^resampler) -> result ---
/*
Uninitializes a resampler.
*/
- resampler_uninit :: proc(pResampler: ^resampler) ---
+ resampler_uninit :: proc(pResampler: ^resampler, pAllocationCallbacks: ^allocation_callbacks) ---
/*
Converts the given input data.
@@ -145,23 +174,6 @@ foreign lib {
*/
resampler_set_rate_ratio :: proc(pResampler: ^resampler, ratio: f32) -> result ---
-
- /*
- Calculates the number of whole input frames that would need to be read from the client in order to output the specified
- number of output frames.
-
- The returned value does not include cached input frames. It only returns the number of extra frames that would need to be
- read from the input buffer in order to output the specified number of output frames.
- */
- resampler_get_required_input_frame_count :: proc(pResampler: ^resampler, outputFrameCount: u64) -> u64 ---
-
- /*
- Calculates the number of whole output frames that would be output after fully reading and consuming the specified number of
- input frames.
- */
- resampler_get_expected_output_frame_count :: proc(pResampler: ^resampler, inputFrameCount: u64) -> u64 ---
-
-
/*
Retrieves the latency introduced by the resampler in input frames.
*/
@@ -171,6 +183,26 @@ foreign lib {
Retrieves the latency introduced by the resampler in output frames.
*/
resampler_get_output_latency :: proc(pResampler: ^resampler) -> u64 ---
+
+ /*
+ Calculates the number of whole input frames that would need to be read from the client in order to output the specified
+ number of output frames.
+
+ The returned value does not include cached input frames. It only returns the number of extra frames that would need to be
+ read from the input buffer in order to output the specified number of output frames.
+ */
+ resampler_get_required_input_frame_count :: proc(pResampler: ^resampler, outputFrameCount: u64, pInputFrameCount: ^u64) -> result ---
+
+ /*
+ Calculates the number of whole output frames that would be output after fully reading and consuming the specified number of
+ input frames.
+ */
+ resampler_get_expected_output_frame_count :: proc(pResampler: ^resampler, inputFrameCount: u64, pOutputFrameCount: ^u64) -> result ---
+
+ /*
+ Resets the resampler's timer and clears it's internal cache.
+ */
+ resampler_reset :: proc(pResampler: ^resampler) -> result ---
}
@@ -179,42 +211,63 @@ foreign lib {
Channel Conversion
**************************************************************************************************************************************************************/
+channel_conversion_path :: enum c.int {
+ unknown,
+ passthrough,
+ mono_out, /* Converting to mono. */
+ mono_in, /* Converting from mono. */
+ shuffle, /* Simple shuffle. Will use this when all channels are present in both input and output channel maps, but just in a different order. */
+ weights, /* Blended based on weights. */
+}
+
+mono_expansion_mode :: enum c.int {
+ duplicate = 0, /* The default. */
+ average, /* Average the mono channel across all channels. */
+ stereo_only, /* Duplicate to the left and right channels only and ignore the others. */
+ default = duplicate,
+}
+
channel_converter_config :: struct {
- format: format,
- channelsIn: u32,
- channelsOut: u32,
- channelMapIn: [MAX_CHANNELS]channel,
- channelMapOut: [MAX_CHANNELS]channel,
- mixingMode: channel_mix_mode,
- weights: [MAX_CHANNELS][MAX_CHANNELS]f32, /* [in][out]. Only used when mixingMode is set to ma_channel_mix_mode_custom_weights. */
+ format: format,
+ channelsIn: u32,
+ channelsOut: u32,
+ pChannelMapIn: [^]channel,
+ pChannelMapOut: [^]channel,
+ mixingMode: channel_mix_mode,
+ ppWeights: ^[^]f32, /* [in][out]. Only used when mixingMode is set to ma_channel_mix_mode_custom_weights. */
}
channel_converter :: struct {
- format: format,
- channelsIn: u32,
- channelsOut: u32,
- channelMapIn: [MAX_CHANNELS]channel,
- channelMapOut: [MAX_CHANNELS]channel,
- mixingMode: channel_mix_mode,
- weights: struct #raw_union {
- f32: [MAX_CHANNELS][MAX_CHANNELS]f32,
- s16: [MAX_CHANNELS][MAX_CHANNELS]i32,
+ format: format,
+ channelsIn: u32,
+ channelsOut: u32,
+ mixingMode: channel_mix_mode,
+ conversionPath: channel_conversion_path,
+ pChannelMapIn: [^]channel,
+ pChannelMapOut: [^]channel,
+ pShuffleTable: [^]u8,
+ weights: struct #raw_union { /* [in][out] */
+ f32: ^[^]f32,
+ s16: ^[^]i32,
},
- isPassthrough: b8,
- isSimpleShuffle: b8,
- isSimpleMonoExpansion: b8,
- isStereoToMono: b8,
- shuffleTable: [MAX_CHANNELS]u8,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
- channel_converter_config_init :: proc(format: format, channelsIn: u32, pChannelMapIn: ^channel, channelsOut: u32, pChannelMapOut: ^channel, mixingMode: channel_mix_mode) -> channel_converter_config ---
+ channel_converter_config_init :: proc(format: format, channelsIn: u32, pChannelMapIn: [^]channel, channelsOut: u32, pChannelMapOut: [^]channel, mixingMode: channel_mix_mode) -> channel_converter_config ---
- channel_converter_init :: proc(pConfig: ^channel_converter_config, pConverter: ^channel_converter) -> result ---
- channel_converter_uninit :: proc(pConverter: ^channel_converter) ---
- channel_converter_process_pcm_frames :: proc(pConverter: ^channel_converter, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
+ channel_converter_get_heap_size :: proc(pConfig: ^channel_converter_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ channel_converter_init_preallocated :: proc(pConfig: ^channel_converter_config, pHeap: rawptr, pConverter: ^channel_converter) -> result ---
+ channel_converter_init :: proc(pConfig: ^channel_converter_config, pAllocationCallbacks: ^allocation_callbacks, pConverter: ^channel_converter) -> result ---
+ channel_converter_uninit :: proc(pConverter: ^channel_converter, pAllocationCallbacks: ^allocation_callbacks) ---
+ channel_converter_process_pcm_frames :: proc(pConverter: ^channel_converter, pFramesOut, pFramesIn: rawptr, frameCount: u64) -> result ---
+ channel_converter_get_input_channel_map :: proc(pConverter: ^channel_converter, pChannelMap: [^]channel, channelMapCap: c.size_t) -> result ---
+ channel_converter_get_output_channel_map :: proc(pConverter: ^channel_converter, pChannelMap: [^]channel, channelMapCap: c.size_t) -> result ---
}
@@ -224,32 +277,39 @@ Data Conversion
**************************************************************************************************************************************************************/
data_converter_config :: struct {
- formatIn: format,
- formatOut: format,
- channelsIn: u32,
- channelsOut: u32,
- sampleRateIn: u32,
- sampleRateOut: u32,
- channelMapIn: [MAX_CHANNELS]channel,
- channelMapOut: [MAX_CHANNELS]channel,
- ditherMode: dither_mode,
- channelMixMode: channel_mix_mode,
- channelWeights: [MAX_CHANNELS][MAX_CHANNELS]f32, /* [in][out]. Only used when channelMixMode is set to ma_channel_mix_mode_custom_weights. */
- resampling: struct {
- algorithm: resample_algorithm,
- allowDynamicSampleRate: b32,
- linear: struct {
- lpfOrderL: u32,
- lpfNyquistFactor: f64,
- },
- speex: struct {
- quality: c.int,
- },
- },
+ formatIn: format,
+ formatOut: format,
+ channelsIn: u32,
+ channelsOut: u32,
+ sampleRateIn: u32,
+ sampleRateOut: u32,
+ pChannelMapIn: [^]channel,
+ pChannelMapOut: [^]channel,
+ ditherMode: dither_mode,
+ channelMixMode: channel_mix_mode,
+ ppChannelWeights: ^[^]f32, /* [in][out]. Only used when channelMixMode is set to ma_channel_mix_mode_custom_weights. */
+ allowDynamicSampleRate: b32,
+ resampling: resampler_config,
+}
+
+data_converter_execution_path :: enum c.int {
+ passthrough, /* No conversion. */
+ format_only, /* Only format conversion. */
+ channels_only, /* Only channel conversion. */
+ resample_only, /* Only resampling. */
+ resample_first, /* All conversions, but resample as the first step. */
+ channels_first, /* All conversions, but channels as the first step. */
}
data_converter :: struct {
- config: data_converter_config,
+ formatIn: format,
+ formatOut: format,
+ channelsIn: u32,
+ channelsOut: u32,
+ sampleRateIn: u32,
+ sampleRateOut: u32,
+ ditherMode: dither_mode,
+ executionPath: data_converter_execution_path, /* The execution path the data converter will follow when processing. */
channelConverter: channel_converter,
resampler: resampler,
hasPreFormatConversion: b8,
@@ -257,6 +317,10 @@ data_converter :: struct {
hasChannelConverter: b8,
hasResampler: b8,
isPassthrough: b8,
+
+ /* Memory management. */
+ _ownsHeap: b8,
+ _pHeap: rawptr,
}
@@ -265,15 +329,20 @@ foreign lib {
data_converter_config_init_default :: proc() -> data_converter_config ---
data_converter_config_init :: proc(formatIn, formatOut: format, channelsIn, channelsOut: u32, sampleRateIn, sampleRateOut: u32) -> data_converter_config ---
- data_converter_init :: proc(pConfig: ^data_converter_config, pConverter: ^data_converter) -> result ---
- data_converter_uninit :: proc(pConverter: ^data_converter) ---
+ data_converter_get_heap_size :: proc(pConfig: ^data_converter_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ data_converter_init_preallocated :: proc(pConfig: ^data_converter_config, pHeap: rawptr, pConverter: ^data_converter) -> result ---
+ data_converter_init :: proc(pConfig: ^data_converter_config, pAllocationCallbacks: ^allocation_callbacks, pConverter: ^data_converter) -> result ---
+ data_converter_uninit :: proc(pConverter: ^data_converter, pAllocationCallbacks: ^allocation_callbacks) ---
data_converter_process_pcm_frames :: proc(pConverter: ^data_converter, pFramesIn: rawptr, pFrameCountIn: ^u64, pFramesOut: rawptr, pFrameCountOut: ^u64) -> result ---
data_converter_set_rate :: proc(pConverter: ^data_converter, sampleRateIn, sampleRateOut: u32) -> result ---
data_converter_set_rate_ratio :: proc(pConverter: ^data_converter, ratioInOut: f32) -> result ---
- data_converter_get_required_input_frame_count :: proc(pConverter: ^data_converter, outputFrameCount: u64) -> u64 ---
- data_converter_get_expected_output_frame_count :: proc(pConverter: ^data_converter, inputFrameCount: u64) -> u64 ---
data_converter_get_input_latency :: proc(pConverter: ^data_converter) -> u64 ---
data_converter_get_output_latency :: proc(pConverter: ^data_converter) -> u64 ---
+ data_converter_get_required_input_frame_count :: proc(pConverter: ^data_converter, outputFrameCount: u64, pInputFrameCount: ^u64) -> result ---
+ data_converter_get_expected_output_frame_count :: proc(pConverter: ^data_converter, inputFrameCount: u64, pOutputFrameCount: ^u64) -> result ---
+ data_converter_get_input_channel_map :: proc(pConverter: ^data_converter, pChannelMap: [^]channel, channelMapCap: c.size_t) -> result ---
+ data_converter_get_output_channel_map :: proc(pConverter: ^data_converter, pChannelMap: [^]channel, channelMapCap: c.size_t) -> result ---
+ data_converter_reset :: proc(pConverter: ^data_converter) -> result ---
}
/************************************************************************************************************************************************************
@@ -332,43 +401,40 @@ CHANNEL_INDEX_NULL :: 255
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
- /* Retrieves the channel position of the specified channel based on miniaudio's default channel map. */
- channel_map_get_default_channel :: proc(channelCount: u32, channelIndex: u32) -> channel ---
-
/*
Retrieves the channel position of the specified channel in the given channel map.
The pChannelMap parameter can be null, in which case miniaudio's default channel map will be assumed.
*/
- channel_map_get_channel :: proc(pChannelMap: ^channel, channelCount: u32, channelIndex: u32) -> channel ---
+ channel_map_get_channel :: proc(pChannelMap: [^]channel, channelCount: u32, channelIndex: u32) -> channel ---
/*
Initializes a blank channel map.
When a blank channel map is specified anywhere it indicates that the native channel map should be used.
*/
- channel_map_init_blank :: proc(channels: u32, pChannelMap: ^channel) ---
+ channel_map_init_blank :: proc(pChannelMap: [^]channel, channels: u32) ---
/*
Helper for retrieving a standard channel map.
- The output channel map buffer must have a capacity of at least `channels`.
+ The output channel map buffer must have a capacity of at least `channelMapCap`.
*/
- get_standard_channel_map :: proc(standardChannelMap: standard_channel_map, channels: u32, pChannelMap: ^channel) ---
+ channel_map_init_standard :: proc(standardChannelMap: standard_channel_map, pChannelMap: [^]channel, channelMapCap: c.size_t, channels: u32) ---
/*
Copies a channel map.
Both input and output channel map buffers must have a capacity of at at least `channels`.
*/
- channel_map_copy :: proc(pOut: ^channel, pIn: ^channel, channels: u32) ---
+ channel_map_copy :: proc(pOut: [^]channel, pIn: [^]channel, channels: u32) ---
/*
Copies a channel map if one is specified, otherwise copies the default channel map.
The output buffer must have a capacity of at least `channels`. If not NULL, the input channel map must also have a capacity of at least `channels`.
*/
- channel_map_copy_or_default :: proc(pOut: ^channel, pIn: ^channel, channels: u32) ---
+ channel_map_copy_or_default :: proc(pOut: [^]channel, channelMapCapOut: c.size_t, pIn: [^]channel, channels: u32) ---
/*
@@ -378,12 +444,12 @@ foreign lib {
is usually treated as a passthrough.
Invalid channel maps:
- - A channel map with no channels
- - A channel map with more than one channel and a mono channel
+ - A channel map with no channels
+ - A channel map with more than one channel and a mono channel
The channel map buffer must have a capacity of at least `channels`.
*/
- channel_map_valid :: proc(channels: u32, pChannelMap: ^channel) -> b32 ---
+ channel_map_is_valid :: proc(pChannelMap: [^]channel, channels: u32) -> b32 ---
/*
Helper for comparing two channel maps for equality.
@@ -392,23 +458,24 @@ foreign lib {
Both channels map buffers must have a capacity of at least `channels`.
*/
- channel_map_equal :: proc(channels: u32, pChannelMapA, pChannelMapB: ^channel) -> b32 ---
+ channel_map_is_equal :: proc(pChannelMapA, pChannelMapB: [^]channel, channels: u32) -> b32 ---
/*
Helper for determining if a channel map is blank (all channels set to MA_CHANNEL_NONE).
The channel map buffer must have a capacity of at least `channels`.
*/
- channel_map_blank :: proc(channels: u32, pChannelMap: ^channel) -> b32 ---
+ channel_map_is_blank :: proc(pChannelMap: [^]channel, channels: u32) -> b32 ---
/*
Helper for determining whether or not a channel is present in the given channel map.
The channel map buffer must have a capacity of at least `channels`.
*/
- channel_map_contains_channel_position :: proc(channels: u32, pChannelMap: ^channel, channelPosition: channel) -> b32 ---
+ channel_map_contains_channel_position :: proc(channels: u32, pChannelMap: [^]channel, channelPosition: channel) -> b32 ---
}
+
/************************************************************************************************************************************************************
Conversion Helpers
@@ -461,9 +528,9 @@ foreign lib {
rb_uninit :: proc(pRB: ^rb) ---
rb_reset :: proc(pRB: ^rb) ---
rb_acquire_read :: proc(pRB: ^rb, pSizeInBytes: ^c.size_t, ppBufferOut: ^rawptr) -> result ---
- rb_commit_read :: proc(pRB: ^rb, sizeInBytes: c.size_t, pBufferOut: rawptr) -> result ---
+ rb_commit_read :: proc(pRB: ^rb, sizeInBytes: c.size_t) -> result ---
rb_acquire_write :: proc(pRB: ^rb, pSizeInBytes: ^c.size_t, ppBufferOut: ^rawptr) -> result ---
- rb_commit_write :: proc(pRB: ^rb, sizeInBytes: c.size_t, pBufferOut: rawptr) -> result ---
+ rb_commit_write :: proc(pRB: ^rb, sizeInBytes: c.size_t) -> result ---
rb_seek_read :: proc(pRB: ^rb, offsetInBytes: c.size_t) -> result ---
rb_seek_write :: proc(pRB: ^rb, offsetInBytes: c.size_t) -> result ---
rb_pointer_distance :: proc(pRB: ^rb) -> i32 --- /* Returns the distance between the write pointer and the read pointer. Should never be negative for a correct program. Will return the number of bytes that can be read before the read pointer hits the write pointer. */
diff --git a/vendor/miniaudio/decoding.odin b/vendor/miniaudio/decoding.odin
index dcf3b7a1a..003f6f950 100644
--- a/vendor/miniaudio/decoding.odin
+++ b/vendor/miniaudio/decoding.odin
@@ -22,68 +22,63 @@ you do your own synchronization.
decoding_backend_config :: struct {
preferredFormat: format,
+ seekPointCount: u32, /* Set to > 0 to generate a seektable if the decoding backend supports it. */
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
- decoding_backend_config_init :: proc(preferredFormat: format) -> decoding_backend_config ---
+ decoding_backend_config_init :: proc(preferredFormat: format, seekPointCount: u32) -> decoding_backend_config ---
}
decoding_backend_vtable :: struct {
onInit: proc "c" (pUserData: rawptr, onRead: decoder_read_proc, onSeek: decoder_seek_proc, onTell: decoder_tell_proc, pReadSeekTellUserData: rawptr, pConfig: ^decoding_backend_config, pAllocationCallbacks: ^allocation_callbacks, ppBackend: ^^data_source) -> result,
- onInitFile: proc "c" (pUserData: rawptr, pFilePath: cstring, pConfig: ^decoding_backend_config, pAllocationCallbacks: ^allocation_callbacks, ppBackend: ^^data_source) -> result, /* Optional. */
+ onInitFile: proc "c" (pUserData: rawptr, pFilePath: cstring, pConfig: ^decoding_backend_config, pAllocationCallbacks: ^allocation_callbacks, ppBackend: ^^data_source) -> result, /* Optional. */
onInitFileW: proc "c" (pUserData: rawptr, pFilePath: [^]c.wchar_t, pConfig: ^decoding_backend_config, pAllocationCallbacks: ^allocation_callbacks, ppBackend: ^^data_source) -> result, /* Optional. */
onInitMemory: proc "c" (pUserData: rawptr, pData: rawptr, dataSize: c.size_t, pConfig: ^decoding_backend_config, pAllocationCallbacks: ^allocation_callbacks, ppBackend: ^^data_source) -> result, /* Optional. */
onUninit: proc "c" (pUserData: rawptr, pBackend: ^data_source, pAllocationCallbacks: ^allocation_callbacks),
- onGetChannelMap: proc "c" (pUserData: rawptr, pBackend: ^data_source, pChannelMap: ^channel, channelMapCap: c.size_t) -> result,
}
-/* TODO: Convert read and seek to be consistent with the VFS API (ma_result return value, bytes read moved to an output parameter). */
-decoder_read_proc :: proc "c" (pDecoder: ^decoder, pBufferOut: rawptr, bytesToRead: c.size_t) -> c.size_t /* Returns the number of bytes read. */
-decoder_seek_proc :: proc "c" (pDecoder: ^decoder, byteOffset: i64, origin: seek_origin) -> b32
+decoder_read_proc :: proc "c" (pDecoder: ^decoder, pBufferOut: rawptr, bytesToRead: c.size_t, pBytesRead: ^c.size_t) -> result /* Returns the number of bytes read. */
+decoder_seek_proc :: proc "c" (pDecoder: ^decoder, byteOffset: i64, origin: seek_origin) -> result
decoder_tell_proc :: proc "c" (pDecoder: ^decoder, pCursor: ^i64) -> result
decoder_config :: struct {
- format: format, /* Set to 0 or ma_format_unknown to use the stream's internal format. */
- channels: u32, /* Set to 0 to use the stream's internal channels. */
- sampleRate: u32, /* Set to 0 to use the stream's internal sample rate. */
- channelMap: [MAX_CHANNELS]channel,
- channelMixMode: channel_mix_mode,
- ditherMode: dither_mode,
- resampling: struct {
- algorithm: resample_algorithm,
- linear: struct {
- lpfOrder: u32,
- },
- speex: struct {
- quality: c.int,
- },
- },
+ format: format, /* Set to 0 or ma_format_unknown to use the stream's internal format. */
+ channels: u32, /* Set to 0 to use the stream's internal channels. */
+ sampleRate: u32, /* Set to 0 to use the stream's internal sample rate. */
+ channelMap: [^]channel,
+ channelMixMode: channel_mix_mode,
+ ditherMode: dither_mode,
+ resampling: resampler_config,
allocationCallbacks: allocation_callbacks,
encodingFormat: encoding_format,
- ppCustomBackendVTables: ^^decoding_backend_vtable,
+ seekPointCount: u32, /* When set to > 0, specifies the number of seek points to use for the generation of a seek table. Not all decoding backends support this. */
+ ppCustomBackendVTables: ^[^]decoding_backend_vtable,
customBackendCount: u32,
pCustomBackendUserData: rawptr,
}
decoder :: struct {
- ds: data_source_base,
- pBackend: ^data_source, /* The decoding backend we'll be pulling data from. */
- pBackendVTable: ^^decoding_backend_vtable, /* The vtable for the decoding backend. This needs to be stored so we can access the onUninit() callback. */
- pBackendUserData: rawptr,
- onRead: decoder_read_proc,
- onSeek: decoder_seek_proc,
- onTell: decoder_tell_proc,
- pUserData: rawptr,
+ ds: data_source_base,
+ pBackend: ^data_source, /* The decoding backend we'll be pulling data from. */
+ pBackendVTable: ^decoding_backend_vtable, /* The vtable for the decoding backend. This needs to be stored so we can access the onUninit() callback. */
+ pBackendUserData: rawptr,
+ onRead: decoder_read_proc,
+ onSeek: decoder_seek_proc,
+ onTell: decoder_tell_proc,
+ pUserData: rawptr,
readPointerInPCMFrames: u64, /* In output sample rate. Used for keeping track of how many frames are available for decoding. */
- outputFormat: format,
- outputChannels: u32,
- outputSampleRate: u32,
- outputChannelMap: [MAX_CHANNELS]channel,
- converter: data_converter, /* <-- Data conversion is achieved by running frames through this. */
- allocationCallbacks: allocation_callbacks,
+ outputFormat: format,
+ outputChannels: u32,
+ outputSampleRate: u32,
+ converter: data_converter, /* <-- Data conversion is achieved by running frames through this. */
+ pInputCache: rawptr, /* In input format. Can be null if it's not needed. */
+ inputCacheCap: u64, /* The capacity of the input cache. */
+ inputCacheConsumed: u64, /* The number of frames that have been consumed in the cache. Used for determining the next valid frame. */
+ inputCacheRemaining: u64, /* The number of valid frames remaining in the cahce. */
+ allocationCallbacks: allocation_callbacks,
data: struct #raw_union {
vfs: struct {
pVFS: ^vfs,
@@ -114,6 +109,25 @@ foreign lib {
*/
decoder_uninit :: proc(pDecoder: ^decoder) -> result ---
+ /*
+ Reads PCM frames from the given decoder.
+
+ This is not thread safe without your own synchronization.
+ */
+ decoder_read_pcm_frames :: proc(pDecoder: ^decoder, pFramesOut: rawptr, frameCount: u64, pFramesRead: ^u64) -> result ---
+
+ /*
+ Seeks to a PCM frame based on it's absolute index.
+
+ This is not thread safe without your own synchronization.
+ */
+ decoder_seek_to_pcm_frame :: proc(pDecoder: ^decoder, frameIndex: u64) -> result ---
+
+ /*
+ Retrieves the decoder's output data format.
+ */
+ decoder_get_data_format :: proc(pDecoder: ^decoder, pFormat: ^format, pChannels, pSampleRate: ^u32, pChannelMap: ^channel, channelMapCap: c.size_t) -> result ---
+
/*
Retrieves the current position of the read cursor in PCM frames.
*/
@@ -133,21 +147,7 @@ foreign lib {
This function is not thread safe without your own synchronization.
*/
- decoder_get_length_in_pcm_frames :: proc(pDecoder: ^decoder) -> u64 ---
-
- /*
- Reads PCM frames from the given decoder.
-
- This is not thread safe without your own synchronization.
- */
- decoder_read_pcm_frames :: proc(pDecoder: ^decoder, pFramesOut: rawptr, frameCount: u64) -> u64 ---
-
- /*
- Seeks to a PCM frame based on it's absolute index.
-
- This is not thread safe without your own synchronization.
- */
- decoder_seek_to_pcm_frame :: proc(pDecoder: ^decoder, frameIndex: u64) -> result ---
+ decoder_get_length_in_pcm_frames :: proc(pDecoder: ^decoder, pLength: ^u64) -> result ---
/*
Retrieves the number of frames that can be read before reaching the end.
diff --git a/vendor/miniaudio/device_io_procs.odin b/vendor/miniaudio/device_io_procs.odin
index 7cff3f621..de60645e4 100644
--- a/vendor/miniaudio/device_io_procs.odin
+++ b/vendor/miniaudio/device_io_procs.odin
@@ -12,6 +12,12 @@ import "core:c"
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
+ device_job_thread_config_init :: proc() -> device_job_thread_config ---
+
+ device_job_thread_init :: proc(pConfig: ^device_job_thread_config, pAllocationCallbacks: ^allocation_callbacks, pJobThread: ^device_job_thread) -> result ---
+ device_job_thread_uninit :: proc(pJobThread: ^device_job_thread, pAllocationCallbacks: ^allocation_callbacks) ---
+ device_job_thread_post :: proc(pJobThread: ^device_job_thread, pJob: ^job) -> result ---
+ device_job_thread_next :: proc(pJobThread: ^device_job_thread, pJob: ^job) -> result ---
/*
Initializes a `ma_context_config` object.
@@ -46,16 +52,16 @@ foreign lib {
Parameters
----------
backends (in, optional)
- A list of backends to try initializing, in priority order. Can be NULL, in which case it uses default priority order.
+ A list of backends to try initializing, in priority order. Can be NULL, in which case it uses default priority order.
backendCount (in, optional)
- The number of items in `backend`. Ignored if `backend` is NULL.
+ The number of items in `backend`. Ignored if `backend` is NULL.
pConfig (in, optional)
- The context configuration.
+ The context configuration.
pContext (in)
- A pointer to the context object being initialized.
+ A pointer to the context object being initialized.
Return Value
@@ -72,107 +78,116 @@ foreign lib {
-------
When `backends` is NULL, the default priority order will be used. Below is a list of backends in priority order:
- |-------------|-----------------------|--------------------------------------------------------|
- | Name | Enum Name | Supported Operating Systems |
- |-------------|-----------------------|--------------------------------------------------------|
- | WASAPI | ma_backend_wasapi | Windows Vista+ |
- | DirectSound | ma_backend_dsound | Windows XP+ |
- | WinMM | ma_backend_winmm | Windows XP+ (may work on older versions, but untested) |
- | Core Audio | ma_backend_coreaudio | macOS, iOS |
- | ALSA | ma_backend_alsa | Linux |
- | PulseAudio | ma_backend_pulseaudio | Cross Platform (disabled on Windows, BSD and Android) |
- | JACK | ma_backend_jack | Cross Platform (disabled on BSD and Android) |
- | sndio | ma_backend_sndio | OpenBSD |
- | audio(4) | ma_backend_audio4 | NetBSD, OpenBSD |
- | OSS | ma_backend_oss | FreeBSD |
- | AAudio | ma_backend_aaudio | Android 8+ |
- | OpenSL|ES | ma_backend_opensl | Android (API level 16+) |
- | Web Audio | ma_backend_webaudio | Web (via Emscripten) |
- | Null | ma_backend_null | Cross Platform (not used on Web) |
- |-------------|-----------------------|--------------------------------------------------------|
+ |-------------|-----------------------|--------------------------------------------------------|
+ | Name | Enum Name | Supported Operating Systems |
+ |-------------|-----------------------|--------------------------------------------------------|
+ | WASAPI | ma_backend_wasapi | Windows Vista+ |
+ | DirectSound | ma_backend_dsound | Windows XP+ |
+ | WinMM | ma_backend_winmm | Windows XP+ (may work on older versions, but untested) |
+ | Core Audio | ma_backend_coreaudio | macOS, iOS |
+ | ALSA | ma_backend_alsa | Linux |
+ | PulseAudio | ma_backend_pulseaudio | Cross Platform (disabled on Windows, BSD and Android) |
+ | JACK | ma_backend_jack | Cross Platform (disabled on BSD and Android) |
+ | sndio | ma_backend_sndio | OpenBSD |
+ | audio(4) | ma_backend_audio4 | NetBSD, OpenBSD |
+ | OSS | ma_backend_oss | FreeBSD |
+ | AAudio | ma_backend_aaudio | Android 8+ |
+ | OpenSL|ES | ma_backend_opensl | Android (API level 16+) |
+ | Web Audio | ma_backend_webaudio | Web (via Emscripten) |
+ | Null | ma_backend_null | Cross Platform (not used on Web) |
+ |-------------|-----------------------|--------------------------------------------------------|
The context can be configured via the `pConfig` argument. The config object is initialized with `ma_context_config_init()`. Individual configuration settings
can then be set directly on the structure. Below are the members of the `ma_context_config` object.
- pLog
- A pointer to the `ma_log` to post log messages to. Can be NULL if the application does not
- require logging. See the `ma_log` API for details on how to use the logging system.
+ pLog
+ A pointer to the `ma_log` to post log messages to. Can be NULL if the application does not
+ require logging. See the `ma_log` API for details on how to use the logging system.
- threadPriority
- The desired priority to use for the audio thread. Allowable values include the following:
+ threadPriority
+ The desired priority to use for the audio thread. Allowable values include the following:
- |--------------------------------------|
- | Thread Priority |
- |--------------------------------------|
- | ma_thread_priority_idle |
- | ma_thread_priority_lowest |
- | ma_thread_priority_low |
- | ma_thread_priority_normal |
- | ma_thread_priority_high |
- | ma_thread_priority_highest (default) |
- | ma_thread_priority_realtime |
- | ma_thread_priority_default |
- |--------------------------------------|
+ |--------------------------------------|
+ | Thread Priority |
+ |--------------------------------------|
+ | ma_thread_priority_idle |
+ | ma_thread_priority_lowest |
+ | ma_thread_priority_low |
+ | ma_thread_priority_normal |
+ | ma_thread_priority_high |
+ | ma_thread_priority_highest (default) |
+ | ma_thread_priority_realtime |
+ | ma_thread_priority_default |
+ |--------------------------------------|
- pUserData
- A pointer to application-defined data. This can be accessed from the context object directly such as `context.pUserData`.
+ threadStackSize
+ The desired size of the stack for the audio thread. Defaults to the operating system's default.
- allocationCallbacks
- Structure containing custom allocation callbacks. Leaving this at defaults will cause it to use MA_MALLOC, MA_REALLOC and MA_FREE. These allocation
- callbacks will be used for anything tied to the context, including devices.
+ pUserData
+ A pointer to application-defined data. This can be accessed from the context object directly such as `context.pUserData`.
- alsa.useVerboseDeviceEnumeration
- ALSA will typically enumerate many different devices which can be intrusive and not user-friendly. To combat this, miniaudio will enumerate only unique
- card/device pairs by default. The problem with this is that you lose a bit of flexibility and control. Setting alsa.useVerboseDeviceEnumeration makes
- it so the ALSA backend includes all devices. Defaults to false.
+ allocationCallbacks
+ Structure containing custom allocation callbacks. Leaving this at defaults will cause it to use MA_MALLOC, MA_REALLOC and MA_FREE. These allocation
+ callbacks will be used for anything tied to the context, including devices.
- pulse.pApplicationName
- PulseAudio only. The application name to use when initializing the PulseAudio context with `pa_context_new()`.
+ alsa.useVerboseDeviceEnumeration
+ ALSA will typically enumerate many different devices which can be intrusive and not user-friendly. To combat this, miniaudio will enumerate only unique
+ card/device pairs by default. The problem with this is that you lose a bit of flexibility and control. Setting alsa.useVerboseDeviceEnumeration makes
+ it so the ALSA backend includes all devices. Defaults to false.
- pulse.pServerName
- PulseAudio only. The name of the server to connect to with `pa_context_connect()`.
+ pulse.pApplicationName
+ PulseAudio only. The application name to use when initializing the PulseAudio context with `pa_context_new()`.
- pulse.tryAutoSpawn
- PulseAudio only. Whether or not to try automatically starting the PulseAudio daemon. Defaults to false. If you set this to true, keep in mind that
- miniaudio uses a trial and error method to find the most appropriate backend, and this will result in the PulseAudio daemon starting which may be
- intrusive for the end user.
+ pulse.pServerName
+ PulseAudio only. The name of the server to connect to with `pa_context_connect()`.
- coreaudio.sessionCategory
- iOS only. The session category to use for the shared AudioSession instance. Below is a list of allowable values and their Core Audio equivalents.
+ pulse.tryAutoSpawn
+ PulseAudio only. Whether or not to try automatically starting the PulseAudio daemon. Defaults to false. If you set this to true, keep in mind that
+ miniaudio uses a trial and error method to find the most appropriate backend, and this will result in the PulseAudio daemon starting which may be
+ intrusive for the end user.
- |-----------------------------------------|-------------------------------------|
- | miniaudio Token | Core Audio Token |
- |-----------------------------------------|-------------------------------------|
- | ma_ios_session_category_ambient | AVAudioSessionCategoryAmbient |
- | ma_ios_session_category_solo_ambient | AVAudioSessionCategorySoloAmbient |
- | ma_ios_session_category_playback | AVAudioSessionCategoryPlayback |
- | ma_ios_session_category_record | AVAudioSessionCategoryRecord |
- | ma_ios_session_category_play_and_record | AVAudioSessionCategoryPlayAndRecord |
- | ma_ios_session_category_multi_route | AVAudioSessionCategoryMultiRoute |
- | ma_ios_session_category_none | AVAudioSessionCategoryAmbient |
- | ma_ios_session_category_default | AVAudioSessionCategoryAmbient |
- |-----------------------------------------|-------------------------------------|
+ coreaudio.sessionCategory
+ iOS only. The session category to use for the shared AudioSession instance. Below is a list of allowable values and their Core Audio equivalents.
- coreaudio.sessionCategoryOptions
- iOS only. Session category options to use with the shared AudioSession instance. Below is a list of allowable values and their Core Audio equivalents.
+ |-----------------------------------------|-------------------------------------|
+ | miniaudio Token | Core Audio Token |
+ |-----------------------------------------|-------------------------------------|
+ | ma_ios_session_category_ambient | AVAudioSessionCategoryAmbient |
+ | ma_ios_session_category_solo_ambient | AVAudioSessionCategorySoloAmbient |
+ | ma_ios_session_category_playback | AVAudioSessionCategoryPlayback |
+ | ma_ios_session_category_record | AVAudioSessionCategoryRecord |
+ | ma_ios_session_category_play_and_record | AVAudioSessionCategoryPlayAndRecord |
+ | ma_ios_session_category_multi_route | AVAudioSessionCategoryMultiRoute |
+ | ma_ios_session_category_none | AVAudioSessionCategoryAmbient |
+ | ma_ios_session_category_default | AVAudioSessionCategoryAmbient |
+ |-----------------------------------------|-------------------------------------|
- |---------------------------------------------------------------------------|------------------------------------------------------------------|
- | miniaudio Token | Core Audio Token |
- |---------------------------------------------------------------------------|------------------------------------------------------------------|
- | ma_ios_session_category_option_mix_with_others | AVAudioSessionCategoryOptionMixWithOthers |
- | ma_ios_session_category_option_duck_others | AVAudioSessionCategoryOptionDuckOthers |
- | ma_ios_session_category_option_allow_bluetooth | AVAudioSessionCategoryOptionAllowBluetooth |
- | ma_ios_session_category_option_default_to_speaker | AVAudioSessionCategoryOptionDefaultToSpeaker |
- | ma_ios_session_category_option_interrupt_spoken_audio_and_mix_with_others | AVAudioSessionCategoryOptionInterruptSpokenAudioAndMixWithOthers |
- | ma_ios_session_category_option_allow_bluetooth_a2dp | AVAudioSessionCategoryOptionAllowBluetoothA2DP |
- | ma_ios_session_category_option_allow_air_play | AVAudioSessionCategoryOptionAllowAirPlay |
- |---------------------------------------------------------------------------|------------------------------------------------------------------|
+ coreaudio.sessionCategoryOptions
+ iOS only. Session category options to use with the shared AudioSession instance. Below is a list of allowable values and their Core Audio equivalents.
- jack.pClientName
- The name of the client to pass to `jack_client_open()`.
+ |---------------------------------------------------------------------------|------------------------------------------------------------------|
+ | miniaudio Token | Core Audio Token |
+ |---------------------------------------------------------------------------|------------------------------------------------------------------|
+ | ma_ios_session_category_option_mix_with_others | AVAudioSessionCategoryOptionMixWithOthers |
+ | ma_ios_session_category_option_duck_others | AVAudioSessionCategoryOptionDuckOthers |
+ | ma_ios_session_category_option_allow_bluetooth | AVAudioSessionCategoryOptionAllowBluetooth |
+ | ma_ios_session_category_option_default_to_speaker | AVAudioSessionCategoryOptionDefaultToSpeaker |
+ | ma_ios_session_category_option_interrupt_spoken_audio_and_mix_with_others | AVAudioSessionCategoryOptionInterruptSpokenAudioAndMixWithOthers |
+ | ma_ios_session_category_option_allow_bluetooth_a2dp | AVAudioSessionCategoryOptionAllowBluetoothA2DP |
+ | ma_ios_session_category_option_allow_air_play | AVAudioSessionCategoryOptionAllowAirPlay |
+ |---------------------------------------------------------------------------|------------------------------------------------------------------|
- jack.tryStartServer
- Whether or not to try auto-starting the JACK server. Defaults to false.
+ coreaudio.noAudioSessionActivate
+ iOS only. When set to true, does not perform an explicit [[AVAudioSession sharedInstace] setActive:true] on initialization.
+
+ coreaudio.noAudioSessionDeactivate
+ iOS only. When set to true, does not perform an explicit [[AVAudioSession sharedInstace] setActive:false] on uninitialization.
+
+ jack.pClientName
+ The name of the client to pass to `jack_client_open()`.
+
+ jack.tryStartServer
+ Whether or not to try auto-starting the JACK server. Defaults to false.
It is recommended that only a single context is active at any given time because it's a bulky data structure which performs run-time linking for the
@@ -190,7 +205,7 @@ foreign lib {
ma_context context;
ma_result result = ma_context_init(NULL, 0, NULL, &context);
if (result != MA_SUCCESS) {
- // Error.
+ // Error.
}
```
@@ -205,24 +220,30 @@ foreign lib {
```c
ma_backend backends[] = {
- ma_backend_alsa,
- ma_backend_pulseaudio,
- ma_backend_wasapi,
- ma_backend_dsound
+ ma_backend_alsa,
+ ma_backend_pulseaudio,
+ ma_backend_wasapi,
+ ma_backend_dsound
};
+ ma_log log;
+ ma_log_init(&log);
+ ma_log_register_callback(&log, ma_log_callback_init(my_log_callbac, pMyLogUserData));
+
ma_context_config config = ma_context_config_init();
- config.logCallback = my_log_callback;
- config.pUserData = pMyUserData;
+ config.pLog = &log; // Specify a custom log object in the config so any logs that are posted from ma_context_init() are captured.
ma_context context;
ma_result result = ma_context_init(backends, sizeof(backends)/sizeof(backends[0]), &config, &context);
if (result != MA_SUCCESS) {
- // Error.
- if (result == MA_NO_BACKEND) {
- // Couldn't find an appropriate backend.
- }
+ // Error.
+ if (result == MA_NO_BACKEND) {
+ // Couldn't find an appropriate backend.
+ }
}
+
+ // You could also attach a log callback post-initialization:
+ ma_log_register_callback(ma_context_get_log(&context), ma_log_callback_init(my_log_callback, pMyLogUserData));
```
@@ -298,13 +319,13 @@ foreign lib {
Parameters
----------
pContext (in)
- A pointer to the context performing the enumeration.
+ A pointer to the context performing the enumeration.
callback (in)
- The callback to fire for each enumerated device.
+ The callback to fire for each enumerated device.
pUserData (in)
- A pointer to application-defined data passed to the callback.
+ A pointer to application-defined data passed to the callback.
Return Value
@@ -331,15 +352,15 @@ foreign lib {
Example 1 - Simple Enumeration
------------------------------
- ma_bool32 ma_device_enum_callback(pContext: ^context_type, ma_device_type deviceType, const ma_device_info* pInfo, void* pUserData)
+ ma_bool32 ma_device_enum_callback(ma_context* pContext, ma_device_type deviceType, const ma_device_info* pInfo, void* pUserData)
{
- printf("Device Name: %s\n", pInfo->name);
- return MA_TRUE;
+ printf("Device Name: %s\n", pInfo->name);
+ return MA_TRUE;
}
ma_result result = ma_context_enumerate_devices(&context, my_device_enum_callback, pMyUserData);
if (result != MA_SUCCESS) {
- // Error.
+ // Error.
}
@@ -359,19 +380,19 @@ foreign lib {
Parameters
----------
pContext (in)
- A pointer to the context performing the enumeration.
+ A pointer to the context performing the enumeration.
ppPlaybackDeviceInfos (out)
- A pointer to a pointer that will receive the address of a buffer containing the list of `ma_device_info` structures for playback devices.
+ A pointer to a pointer that will receive the address of a buffer containing the list of `ma_device_info` structures for playback devices.
pPlaybackDeviceCount (out)
- A pointer to an unsigned integer that will receive the number of playback devices.
+ A pointer to an unsigned integer that will receive the number of playback devices.
ppCaptureDeviceInfos (out)
- A pointer to a pointer that will receive the address of a buffer containing the list of `ma_device_info` structures for capture devices.
+ A pointer to a pointer that will receive the address of a buffer containing the list of `ma_device_info` structures for capture devices.
pCaptureDeviceCount (out)
- A pointer to an unsigned integer that will receive the number of capture devices.
+ A pointer to an unsigned integer that will receive the number of capture devices.
Return Value
@@ -407,20 +428,16 @@ foreign lib {
Parameters
----------
pContext (in)
- A pointer to the context performing the query.
+ A pointer to the context performing the query.
deviceType (in)
- The type of the device being queried. Must be either `ma_device_type_playback` or `ma_device_type_capture`.
+ The type of the device being queried. Must be either `ma_device_type_playback` or `ma_device_type_capture`.
pDeviceID (in)
- The ID of the device being queried.
-
- shareMode (in)
- The share mode to query for device capabilities. This should be set to whatever you're intending on using when initializing the device. If you're unsure,
- set this to `ma_share_mode_shared`.
+ The ID of the device being queried.
pDeviceInfo (out)
- A pointer to the `ma_device_info` structure that will receive the device information.
+ A pointer to the `ma_device_info` structure that will receive the device information.
Return Value
@@ -444,7 +461,7 @@ foreign lib {
This leaves pDeviceInfo unmodified in the result of an error.
*/
- context_get_device_info :: proc(pContext: ^context_type, deviceType: device_type, pDeviceID: ^device_id, shareMode: share_mode, pDeviceInfo: ^device_info) -> result ---
+ context_get_device_info :: proc(pContext: ^context_type, deviceType: device_type, pDeviceID: ^device_id, pDeviceInfo: ^device_info) -> result ---
/*
Determines if the given context supports loopback mode.
@@ -471,16 +488,16 @@ foreign lib {
Parameters
----------
deviceType (in)
- The type of the device this config is being initialized for. This must set to one of the following:
+ The type of the device this config is being initialized for. This must set to one of the following:
- |-------------------------|
- | Device Type |
- |-------------------------|
- | ma_device_type_playback |
- | ma_device_type_capture |
- | ma_device_type_duplex |
- | ma_device_type_loopback |
- |-------------------------|
+ |-------------------------|
+ | Device Type |
+ |-------------------------|
+ | ma_device_type_playback |
+ | ma_device_type_capture |
+ | ma_device_type_duplex |
+ | ma_device_type_loopback |
+ |-------------------------|
Return Value
@@ -554,13 +571,13 @@ foreign lib {
Parameters
----------
pContext (in, optional)
- A pointer to the context that owns the device. This can be null, in which case it creates a default context internally.
+ A pointer to the context that owns the device. This can be null, in which case it creates a default context internally.
pConfig (in)
- A pointer to the device configuration. Cannot be null. See remarks for details.
+ A pointer to the device configuration. Cannot be null. See remarks for details.
pDevice (out)
- A pointer to the device object being initialized.
+ A pointer to the device object being initialized.
Return Value
@@ -583,9 +600,9 @@ foreign lib {
-------
Setting `pContext` to NULL will result in miniaudio creating a default context internally and is equivalent to passing in a context initialized like so:
- ```c
- ma_context_init(NULL, 0, NULL, &context);
- ```
+ ```c
+ ma_context_init(NULL, 0, NULL, &context);
+ ```
Do not set `pContext` to NULL if you are needing to open multiple devices. You can, however, use NULL when initializing the first device, and then use
device.pContext for the initialization of other devices.
@@ -593,136 +610,173 @@ foreign lib {
The device can be configured via the `pConfig` argument. The config object is initialized with `ma_device_config_init()`. Individual configuration settings can
then be set directly on the structure. Below are the members of the `ma_device_config` object.
- deviceType
- Must be `ma_device_type_playback`, `ma_device_type_capture`, `ma_device_type_duplex` of `ma_device_type_loopback`.
+ deviceType
+ Must be `ma_device_type_playback`, `ma_device_type_capture`, `ma_device_type_duplex` of `ma_device_type_loopback`.
- sampleRate
- The sample rate, in hertz. The most common sample rates are 48000 and 44100. Setting this to 0 will use the device's native sample rate.
+ sampleRate
+ The sample rate, in hertz. The most common sample rates are 48000 and 44100. Setting this to 0 will use the device's native sample rate.
- periodSizeInFrames
- The desired size of a period in PCM frames. If this is 0, `periodSizeInMilliseconds` will be used instead. If both are 0 the default buffer size will
- be used depending on the selected performance profile. This value affects latency. See below for details.
+ periodSizeInFrames
+ The desired size of a period in PCM frames. If this is 0, `periodSizeInMilliseconds` will be used instead. If both are 0 the default buffer size will
+ be used depending on the selected performance profile. This value affects latency. See below for details.
- periodSizeInMilliseconds
- The desired size of a period in milliseconds. If this is 0, `periodSizeInFrames` will be used instead. If both are 0 the default buffer size will be
- used depending on the selected performance profile. The value affects latency. See below for details.
+ periodSizeInMilliseconds
+ The desired size of a period in milliseconds. If this is 0, `periodSizeInFrames` will be used instead. If both are 0 the default buffer size will be
+ used depending on the selected performance profile. The value affects latency. See below for details.
- periods
- The number of periods making up the device's entire buffer. The total buffer size is `periodSizeInFrames` or `periodSizeInMilliseconds` multiplied by
- this value. This is just a hint as backends will be the ones who ultimately decide how your periods will be configured.
+ periods
+ The number of periods making up the device's entire buffer. The total buffer size is `periodSizeInFrames` or `periodSizeInMilliseconds` multiplied by
+ this value. This is just a hint as backends will be the ones who ultimately decide how your periods will be configured.
- performanceProfile
- A hint to miniaudio as to the performance requirements of your program. Can be either `ma_performance_profile_low_latency` (default) or
- `ma_performance_profile_conservative`. This mainly affects the size of default buffers and can usually be left at it's default value.
+ performanceProfile
+ A hint to miniaudio as to the performance requirements of your program. Can be either `ma_performance_profile_low_latency` (default) or
+ `ma_performance_profile_conservative`. This mainly affects the size of default buffers and can usually be left at it's default value.
- noPreZeroedOutputBuffer
- When set to true, the contents of the output buffer passed into the data callback will be left undefined. When set to false (default), the contents of
- the output buffer will be cleared the zero. You can use this to avoid the overhead of zeroing out the buffer if you can guarantee that your data
- callback will write to every sample in the output buffer, or if you are doing your own clearing.
+ noPreSilencedOutputBuffer
+ When set to true, the contents of the output buffer passed into the data callback will be left undefined. When set to false (default), the contents of
+ the output buffer will be cleared the zero. You can use this to avoid the overhead of zeroing out the buffer if you can guarantee that your data
+ callback will write to every sample in the output buffer, or if you are doing your own clearing.
- noClip
- When set to true, the contents of the output buffer passed into the data callback will be clipped after returning. When set to false (default), the
- contents of the output buffer are left alone after returning and it will be left up to the backend itself to decide whether or not the clip. This only
- applies when the playback sample format is f32.
+ noClip
+ When set to true, the contents of the output buffer passed into the data callback will be clipped after returning. When set to false (default), the
+ contents of the output buffer are left alone after returning and it will be left up to the backend itself to decide whether or not the clip. This only
+ applies when the playback sample format is f32.
- dataCallback
- The callback to fire whenever data is ready to be delivered to or from the device.
+ noDisableDenormals
+ By default, miniaudio will disable denormals when the data callback is called. Setting this to true will prevent the disabling of denormals.
- stopCallback
- The callback to fire whenever the device has stopped, either explicitly via `ma_device_stop()`, or implicitly due to things like the device being
- disconnected.
+ noFixedSizedCallback
+ Allows miniaudio to fire the data callback with any frame count. When this is set to true, the data callback will be fired with a consistent frame
+ count as specified by `periodSizeInFrames` or `periodSizeInMilliseconds`. When set to false, miniaudio will fire the callback with whatever the
+ backend requests, which could be anything.
- pUserData
- The user data pointer to use with the device. You can access this directly from the device object like `device.pUserData`.
+ dataCallback
+ The callback to fire whenever data is ready to be delivered to or from the device.
- resampling.algorithm
- The resampling algorithm to use when miniaudio needs to perform resampling between the rate specified by `sampleRate` and the device's native rate. The
- default value is `ma_resample_algorithm_linear`, and the quality can be configured with `resampling.linear.lpfOrder`.
+ notificationCallback
+ The callback to fire when something has changed with the device, such as whether or not it has been started or stopped.
- resampling.linear.lpfOrder
- The linear resampler applies a low-pass filter as part of it's procesing for anti-aliasing. This setting controls the order of the filter. The higher
- the value, the better the quality, in general. Setting this to 0 will disable low-pass filtering altogether. The maximum value is
- `MA_MAX_FILTER_ORDER`. The default value is `min(4, MA_MAX_FILTER_ORDER)`.
+ pUserData
+ The user data pointer to use with the device. You can access this directly from the device object like `device.pUserData`.
- playback.pDeviceID
- A pointer to a `ma_device_id` structure containing the ID of the playback device to initialize. Setting this NULL (default) will use the system's
- default playback device. Retrieve the device ID from the `ma_device_info` structure, which can be retrieved using device enumeration.
+ resampling.algorithm
+ The resampling algorithm to use when miniaudio needs to perform resampling between the rate specified by `sampleRate` and the device's native rate. The
+ default value is `ma_resample_algorithm_linear`, and the quality can be configured with `resampling.linear.lpfOrder`.
- playback.format
- The sample format to use for playback. When set to `ma_format_unknown` the device's native format will be used. This can be retrieved after
- initialization from the device object directly with `device.playback.format`.
+ resampling.pBackendVTable
+ A pointer to an optional vtable that can be used for plugging in a custom resampler.
- playback.channels
- The number of channels to use for playback. When set to 0 the device's native channel count will be used. This can be retrieved after initialization
- from the device object directly with `device.playback.channels`.
+ resampling.pBackendUserData
+ A pointer that will passed to callbacks in pBackendVTable.
- playback.channelMap
- The channel map to use for playback. When left empty, the device's native channel map will be used. This can be retrieved after initialization from the
- device object direct with `device.playback.channelMap`.
+ resampling.linear.lpfOrder
+ The linear resampler applies a low-pass filter as part of it's procesing for anti-aliasing. This setting controls the order of the filter. The higher
+ the value, the better the quality, in general. Setting this to 0 will disable low-pass filtering altogether. The maximum value is
+ `MA_MAX_FILTER_ORDER`. The default value is `min(4, MA_MAX_FILTER_ORDER)`.
- playback.shareMode
- The preferred share mode to use for playback. Can be either `ma_share_mode_shared` (default) or `ma_share_mode_exclusive`. Note that if you specify
- exclusive mode, but it's not supported by the backend, initialization will fail. You can then fall back to shared mode if desired by changing this to
- ma_share_mode_shared and reinitializing.
+ playback.pDeviceID
+ A pointer to a `ma_device_id` structure containing the ID of the playback device to initialize. Setting this NULL (default) will use the system's
+ default playback device. Retrieve the device ID from the `ma_device_info` structure, which can be retrieved using device enumeration.
- capture.pDeviceID
- A pointer to a `ma_device_id` structure containing the ID of the capture device to initialize. Setting this NULL (default) will use the system's
- default capture device. Retrieve the device ID from the `ma_device_info` structure, which can be retrieved using device enumeration.
+ playback.format
+ The sample format to use for playback. When set to `ma_format_unknown` the device's native format will be used. This can be retrieved after
+ initialization from the device object directly with `device.playback.format`.
- capture.format
- The sample format to use for capture. When set to `ma_format_unknown` the device's native format will be used. This can be retrieved after
- initialization from the device object directly with `device.capture.format`.
+ playback.channels
+ The number of channels to use for playback. When set to 0 the device's native channel count will be used. This can be retrieved after initialization
+ from the device object directly with `device.playback.channels`.
- capture.channels
- The number of channels to use for capture. When set to 0 the device's native channel count will be used. This can be retrieved after initialization
- from the device object directly with `device.capture.channels`.
+ playback.pChannelMap
+ The channel map to use for playback. When left empty, the device's native channel map will be used. This can be retrieved after initialization from the
+ device object direct with `device.playback.pChannelMap`. When set, the buffer should contain `channels` items.
- capture.channelMap
- The channel map to use for capture. When left empty, the device's native channel map will be used. This can be retrieved after initialization from the
- device object direct with `device.capture.channelMap`.
+ playback.shareMode
+ The preferred share mode to use for playback. Can be either `ma_share_mode_shared` (default) or `ma_share_mode_exclusive`. Note that if you specify
+ exclusive mode, but it's not supported by the backend, initialization will fail. You can then fall back to shared mode if desired by changing this to
+ ma_share_mode_shared and reinitializing.
- capture.shareMode
- The preferred share mode to use for capture. Can be either `ma_share_mode_shared` (default) or `ma_share_mode_exclusive`. Note that if you specify
- exclusive mode, but it's not supported by the backend, initialization will fail. You can then fall back to shared mode if desired by changing this to
- ma_share_mode_shared and reinitializing.
+ capture.pDeviceID
+ A pointer to a `ma_device_id` structure containing the ID of the capture device to initialize. Setting this NULL (default) will use the system's
+ default capture device. Retrieve the device ID from the `ma_device_info` structure, which can be retrieved using device enumeration.
- wasapi.noAutoConvertSRC
- WASAPI only. When set to true, disables WASAPI's automatic resampling and forces the use of miniaudio's resampler. Defaults to false.
+ capture.format
+ The sample format to use for capture. When set to `ma_format_unknown` the device's native format will be used. This can be retrieved after
+ initialization from the device object directly with `device.capture.format`.
- wasapi.noDefaultQualitySRC
- WASAPI only. Only used when `wasapi.noAutoConvertSRC` is set to false. When set to true, disables the use of `AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY`.
- You should usually leave this set to false, which is the default.
+ capture.channels
+ The number of channels to use for capture. When set to 0 the device's native channel count will be used. This can be retrieved after initialization
+ from the device object directly with `device.capture.channels`.
- wasapi.noAutoStreamRouting
- WASAPI only. When set to true, disables automatic stream routing on the WASAPI backend. Defaults to false.
+ capture.pChannelMap
+ The channel map to use for capture. When left empty, the device's native channel map will be used. This can be retrieved after initialization from the
+ device object direct with `device.capture.pChannelMap`. When set, the buffer should contain `channels` items.
- wasapi.noHardwareOffloading
- WASAPI only. When set to true, disables the use of WASAPI's hardware offloading feature. Defaults to false.
+ capture.shareMode
+ The preferred share mode to use for capture. Can be either `ma_share_mode_shared` (default) or `ma_share_mode_exclusive`. Note that if you specify
+ exclusive mode, but it's not supported by the backend, initialization will fail. You can then fall back to shared mode if desired by changing this to
+ ma_share_mode_shared and reinitializing.
- alsa.noMMap
- ALSA only. When set to true, disables MMap mode. Defaults to false.
+ wasapi.noAutoConvertSRC
+ WASAPI only. When set to true, disables WASAPI's automatic resampling and forces the use of miniaudio's resampler. Defaults to false.
- alsa.noAutoFormat
- ALSA only. When set to true, disables ALSA's automatic format conversion by including the SND_PCM_NO_AUTO_FORMAT flag. Defaults to false.
+ wasapi.noDefaultQualitySRC
+ WASAPI only. Only used when `wasapi.noAutoConvertSRC` is set to false. When set to true, disables the use of `AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY`.
+ You should usually leave this set to false, which is the default.
- alsa.noAutoChannels
- ALSA only. When set to true, disables ALSA's automatic channel conversion by including the SND_PCM_NO_AUTO_CHANNELS flag. Defaults to false.
+ wasapi.noAutoStreamRouting
+ WASAPI only. When set to true, disables automatic stream routing on the WASAPI backend. Defaults to false.
- alsa.noAutoResample
- ALSA only. When set to true, disables ALSA's automatic resampling by including the SND_PCM_NO_AUTO_RESAMPLE flag. Defaults to false.
+ wasapi.noHardwareOffloading
+ WASAPI only. When set to true, disables the use of WASAPI's hardware offloading feature. Defaults to false.
- pulse.pStreamNamePlayback
- PulseAudio only. Sets the stream name for playback.
+ alsa.noMMap
+ ALSA only. When set to true, disables MMap mode. Defaults to false.
- pulse.pStreamNameCapture
- PulseAudio only. Sets the stream name for capture.
+ alsa.noAutoFormat
+ ALSA only. When set to true, disables ALSA's automatic format conversion by including the SND_PCM_NO_AUTO_FORMAT flag. Defaults to false.
- coreaudio.allowNominalSampleRateChange
- Core Audio only. Desktop only. When enabled, allows the sample rate of the device to be changed at the operating system level. This
- is disabled by default in order to prevent intrusive changes to the user's system. This is useful if you want to use a sample rate
- that is known to be natively supported by the hardware thereby avoiding the cost of resampling. When set to true, miniaudio will
- find the closest match between the sample rate requested in the device config and the sample rates natively supported by the
- hardware. When set to false, the sample rate currently set by the operating system will always be used.
+ alsa.noAutoChannels
+ ALSA only. When set to true, disables ALSA's automatic channel conversion by including the SND_PCM_NO_AUTO_CHANNELS flag. Defaults to false.
+
+ alsa.noAutoResample
+ ALSA only. When set to true, disables ALSA's automatic resampling by including the SND_PCM_NO_AUTO_RESAMPLE flag. Defaults to false.
+
+ pulse.pStreamNamePlayback
+ PulseAudio only. Sets the stream name for playback.
+
+ pulse.pStreamNameCapture
+ PulseAudio only. Sets the stream name for capture.
+
+ coreaudio.allowNominalSampleRateChange
+ Core Audio only. Desktop only. When enabled, allows the sample rate of the device to be changed at the operating system level. This
+ is disabled by default in order to prevent intrusive changes to the user's system. This is useful if you want to use a sample rate
+ that is known to be natively supported by the hardware thereby avoiding the cost of resampling. When set to true, miniaudio will
+ find the closest match between the sample rate requested in the device config and the sample rates natively supported by the
+ hardware. When set to false, the sample rate currently set by the operating system will always be used.
+
+ opensl.streamType
+ OpenSL only. Explicitly sets the stream type. If left unset (`ma_opensl_stream_type_default`), the
+ stream type will be left unset. Think of this as the type of audio you're playing.
+
+ opensl.recordingPreset
+ OpenSL only. Explicitly sets the type of recording your program will be doing. When left
+ unset, the recording preset will be left unchanged.
+
+ aaudio.usage
+ AAudio only. Explicitly sets the nature of the audio the program will be consuming. When
+ left unset, the usage will be left unchanged.
+
+ aaudio.contentType
+ AAudio only. Sets the content type. When left unset, the content type will be left unchanged.
+
+ aaudio.inputPreset
+ AAudio only. Explicitly sets the type of recording your program will be doing. When left
+ unset, the input preset will be left unchanged.
+
+ aaudio.noAutoStartAfterReroute
+ AAudio only. Controls whether or not the device should be automatically restarted after a
+ stream reroute. When set to false (default) the device will be restarted automatically;
+ otherwise the device will be stopped.
Once initialized, the device's config is immutable. If you need to change the config you will need to initialize a new device.
@@ -767,7 +821,7 @@ foreign lib {
ma_device device;
ma_result result = ma_device_init(NULL, &config, &device);
if (result != MA_SUCCESS) {
- // Error
+ // Error
}
```
@@ -782,14 +836,14 @@ foreign lib {
ma_context context;
ma_result result = ma_context_init(NULL, 0, NULL, &context);
if (result != MA_SUCCESS) {
- // Error
+ // Error
}
ma_device_info* pPlaybackDeviceInfos;
ma_uint32 playbackDeviceCount;
result = ma_context_get_devices(&context, &pPlaybackDeviceInfos, &playbackDeviceCount, NULL, NULL);
if (result != MA_SUCCESS) {
- // Error
+ // Error
}
// ... choose a device from pPlaybackDeviceInfos ...
@@ -807,7 +861,7 @@ foreign lib {
ma_device device;
result = ma_device_init(&context, &config, &device);
if (result != MA_SUCCESS) {
- // Error
+ // Error
}
```
@@ -833,19 +887,19 @@ foreign lib {
Parameters
----------
backends (in, optional)
- A list of backends to try initializing, in priority order. Can be NULL, in which case it uses default priority order.
+ A list of backends to try initializing, in priority order. Can be NULL, in which case it uses default priority order.
backendCount (in, optional)
- The number of items in `backend`. Ignored if `backend` is NULL.
+ The number of items in `backend`. Ignored if `backend` is NULL.
pContextConfig (in, optional)
- The context configuration.
+ The context configuration.
pConfig (in)
- A pointer to the device configuration. Cannot be null. See remarks for details.
+ A pointer to the device configuration. Cannot be null. See remarks for details.
pDevice (out)
- A pointer to the device object being initialized.
+ A pointer to the device object being initialized.
Return Value
@@ -890,7 +944,7 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device to stop.
+ A pointer to the device to stop.
Return Value
@@ -927,6 +981,95 @@ foreign lib {
device_get_log :: proc(pDevice: ^device) -> ^log ---
+ /*
+ Retrieves information about the device.
+
+
+ Parameters
+ ----------
+ pDevice (in)
+ A pointer to the device whose information is being retrieved.
+
+ type (in)
+ The device type. This parameter is required for duplex devices. When retrieving device
+ information, you are doing so for an individual playback or capture device.
+
+ pDeviceInfo (out)
+ A pointer to the `ma_device_info` that will receive the device information.
+
+
+ Return Value
+ ------------
+ MA_SUCCESS if successful; any other error code otherwise.
+
+
+ Thread Safety
+ -------------
+ Unsafe. This should be considered unsafe because it may be calling into the backend which may or
+ may not be safe.
+
+
+ Callback Safety
+ ---------------
+ Unsafe. You should avoid calling this in the data callback because it may call into the backend
+ which may or may not be safe.
+ */
+ device_get_info :: proc(pDevice: ^device, type: device_type, pDeviceInfo: ^device_info) -> result ---
+
+
+ /*
+ Retrieves the name of the device.
+
+
+ Parameters
+ ----------
+ pDevice (in)
+ A pointer to the device whose information is being retrieved.
+
+ type (in)
+ The device type. This parameter is required for duplex devices. When retrieving device
+ information, you are doing so for an individual playback or capture device.
+
+ pName (out)
+ A pointer to the buffer that will receive the name.
+
+ nameCap (in)
+ The capacity of the output buffer, including space for the null terminator.
+
+ pLengthNotIncludingNullTerminator (out, optional)
+ A pointer to the variable that will receive the length of the name, not including the null
+ terminator.
+
+
+ Return Value
+ ------------
+ MA_SUCCESS if successful; any other error code otherwise.
+
+
+ Thread Safety
+ -------------
+ Unsafe. This should be considered unsafe because it may be calling into the backend which may or
+ may not be safe.
+
+
+ Callback Safety
+ ---------------
+ Unsafe. You should avoid calling this in the data callback because it may call into the backend
+ which may or may not be safe.
+
+
+ Remarks
+ -------
+ If the name does not fully fit into the output buffer, it'll be truncated. You can pass in NULL to
+ `pName` if you want to first get the length of the name for the purpose of memory allocation of the
+ output buffer. Allocating a buffer of size `MA_MAX_DEVICE_NAME_LENGTH + 1` should be enough for
+ most cases and will avoid the need for the inefficiency of calling this function twice.
+
+ This is implemented in terms of `ma_device_get_info()`.
+ */
+ device_get_name :: proc(pDevice: ^device, type: device_type, pName: [^]c.char, nameCap: c.size_t, pLengthNotIncludingNullTerminator: ^c.size_t) -> result ---
+
+
/*
Starts the device. For playback devices this begins playback. For capture devices it begins recording.
@@ -936,7 +1079,7 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device to start.
+ A pointer to the device to start.
Return Value
@@ -979,7 +1122,7 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device to stop.
+ A pointer to the device to stop.
Return Value
@@ -1025,7 +1168,7 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device whose start state is being retrieved.
+ A pointer to the device whose start state is being retrieved.
Return Value
@@ -1059,24 +1202,24 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device whose state is being retrieved.
+ A pointer to the device whose state is being retrieved.
Return Value
------------
The current state of the device. The return value will be one of the following:
- +------------------------+------------------------------------------------------------------------------+
- | MA_STATE_UNINITIALIZED | Will only be returned if the device is in the middle of initialization. |
- +------------------------+------------------------------------------------------------------------------+
- | MA_STATE_STOPPED | The device is stopped. The initial state of the device after initialization. |
- +------------------------+------------------------------------------------------------------------------+
- | MA_STATE_STARTED | The device started and requesting and/or delivering audio data. |
- +------------------------+------------------------------------------------------------------------------+
- | MA_STATE_STARTING | The device is in the process of starting. |
- +------------------------+------------------------------------------------------------------------------+
- | MA_STATE_STOPPING | The device is in the process of stopping. |
- +------------------------+------------------------------------------------------------------------------+
+ +-------------------------------+------------------------------------------------------------------------------+
+ | ma_device_state_uninitialized | Will only be returned if the device is in the middle of initialization. |
+ +-------------------------------+------------------------------------------------------------------------------+
+ | ma_device_state_stopped | The device is stopped. The initial state of the device after initialization. |
+ +-------------------------------+------------------------------------------------------------------------------+
+ | ma_device_state_started | The device started and requesting and/or delivering audio data. |
+ +-------------------------------+------------------------------------------------------------------------------+
+ | ma_device_state_starting | The device is in the process of starting. |
+ +-------------------------------+------------------------------------------------------------------------------+
+ | ma_device_state_stopping | The device is in the process of stopping. |
+ +-------------------------------+------------------------------------------------------------------------------+
Thread Safety
@@ -1094,40 +1237,89 @@ foreign lib {
-------
The general flow of a devices state goes like this:
- ```
- ma_device_init() -> MA_STATE_UNINITIALIZED -> MA_STATE_STOPPED
- ma_device_start() -> MA_STATE_STARTING -> MA_STATE_STARTED
- ma_device_stop() -> MA_STATE_STOPPING -> MA_STATE_STOPPED
- ```
+ ```
+ ma_device_init() -> ma_device_state_uninitialized -> ma_device_state_stopped
+ ma_device_start() -> ma_device_state_starting -> ma_device_state_started
+ ma_device_stop() -> ma_device_state_stopping -> ma_device_state_stopped
+ ```
When the state of the device is changed with `ma_device_start()` or `ma_device_stop()` at this same time as this function is called, the
value returned by this function could potentially be out of sync. If this is significant to your program you need to implement your own
synchronization.
*/
- device_get_state :: proc(pDevice: ^device) -> u32 ---
+ device_get_state :: proc(pDevice: ^device) -> device_state ---
+
+
+ /*
+ Performs post backend initialization routines for setting up internal data conversion.
+
+ This should be called whenever the backend is initialized. The only time this should be called from
+ outside of miniaudio is if you're implementing a custom backend, and you would only do it if you
+ are reinitializing the backend due to rerouting or reinitializing for some reason.
+
+
+ Parameters
+ ----------
+ pDevice [in]
+ A pointer to the device.
+
+ deviceType [in]
+ The type of the device that was just reinitialized.
+
+ pPlaybackDescriptor [in]
+ The descriptor of the playback device containing the internal data format and buffer sizes.
+
+ pPlaybackDescriptor [in]
+ The descriptor of the capture device containing the internal data format and buffer sizes.
+
+
+ Return Value
+ ------------
+ MA_SUCCESS if successful; any other error otherwise.
+
+
+ Thread Safety
+ -------------
+ Unsafe. This will be reinitializing internal data converters which may be in use by another thread.
+
+
+ Callback Safety
+ ---------------
+ Unsafe. This will be reinitializing internal data converters which may be in use by the callback.
+
+
+ Remarks
+ -------
+ For a duplex device, you can call this for only one side of the system. This is why the deviceType
+ is specified as a parameter rather than deriving it from the device.
+
+ You do not need to call this manually unless you are doing a custom backend, in which case you need
+ only do it if you're manually performing rerouting or reinitialization.
+ */
+ device_post_init :: proc(pDevice: ^device, deviceType: device_type, pPlaybackDescriptor, pCaptureDescriptor: ^device_descriptor) -> result ---
/*
Sets the master volume factor for the device.
- The volume factor must be between 0 (silence) and 1 (full volume). Use `ma_device_set_master_gain_db()` to use decibel notation, where 0 is full volume and
+ The volume factor must be between 0 (silence) and 1 (full volume). Use `ma_device_set_master_volume_db()` to use decibel notation, where 0 is full volume and
values less than 0 decreases the volume.
Parameters
----------
pDevice (in)
- A pointer to the device whose volume is being set.
+ A pointer to the device whose volume is being set.
volume (in)
- The new volume factor. Must be within the range of [0, 1].
+ The new volume factor. Must be >= 0.
Return Value
------------
MA_SUCCESS if the volume was set successfully.
MA_INVALID_ARGS if pDevice is NULL.
- MA_INVALID_ARGS if the volume factor is not within the range of [0, 1].
+ MA_INVALID_ARGS if volume is negative.
Thread Safety
@@ -1150,8 +1342,8 @@ foreign lib {
See Also
--------
ma_device_get_master_volume()
- ma_device_set_master_volume_gain_db()
- ma_device_get_master_volume_gain_db()
+ ma_device_set_master_volume_db()
+ ma_device_get_master_volume_db()
*/
device_set_master_volume :: proc(pDevice: ^device, volume: f32) -> result ---
@@ -1162,10 +1354,10 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device whose volume factor is being retrieved.
+ A pointer to the device whose volume factor is being retrieved.
pVolume (in)
- A pointer to the variable that will receive the volume factor. The returned value will be in the range of [0, 1].
+ A pointer to the variable that will receive the volume factor. The returned value will be in the range of [0, 1].
Return Value
@@ -1207,10 +1399,10 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device whose gain is being set.
+ A pointer to the device whose gain is being set.
gainDB (in)
- The new volume as gain in decibels. Must be less than or equal to 0, where 0 is full volume and anything less than 0 decreases the volume.
+ The new volume as gain in decibels. Must be less than or equal to 0, where 0 is full volume and anything less than 0 decreases the volume.
Return Value
@@ -1243,7 +1435,7 @@ foreign lib {
ma_device_set_master_volume()
ma_device_get_master_volume()
*/
- device_set_master_gain_db :: proc(pDevice: ^device, gainDB: f32) -> result ---
+ device_set_master_volume_db :: proc(pDevice: ^device, gainDB: f32) -> result ---
/*
Retrieves the master gain in decibels.
@@ -1252,10 +1444,10 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to the device whose gain is being retrieved.
+ A pointer to the device whose gain is being retrieved.
pGainDB (in)
- A pointer to the variable that will receive the gain in decibels. The returned value will be <= 0.
+ A pointer to the variable that will receive the gain in decibels. The returned value will be <= 0.
Return Value
@@ -1282,11 +1474,11 @@ foreign lib {
See Also
--------
- ma_device_set_master_volume_gain_db()
+ ma_device_set_master_volume_db()
ma_device_set_master_volume()
ma_device_get_master_volume()
*/
- device_get_master_gain_db :: proc(pDevice: ^device, pGainDB: ^f32) -> result ---
+ device_get_master_volume_db :: proc(pDevice: ^device, pGainDB: ^f32) -> result ---
/*
@@ -1296,18 +1488,18 @@ foreign lib {
Parameters
----------
pDevice (in)
- A pointer to device whose processing the data callback.
+ A pointer to device whose processing the data callback.
pOutput (out)
- A pointer to the buffer that will receive the output PCM frame data. On a playback device this must not be NULL. On a duplex device
- this can be NULL, in which case pInput must not be NULL.
+ A pointer to the buffer that will receive the output PCM frame data. On a playback device this must not be NULL. On a duplex device
+ this can be NULL, in which case pInput must not be NULL.
pInput (in)
- A pointer to the buffer containing input PCM frame data. On a capture device this must not be NULL. On a duplex device this can be
- NULL, in which case `pOutput` must not be NULL.
+ A pointer to the buffer containing input PCM frame data. On a capture device this must not be NULL. On a duplex device this can be
+ NULL, in which case `pOutput` must not be NULL.
frameCount (in)
- The number of frames being processed.
+ The number of frames being processed.
Return Value
@@ -1334,7 +1526,7 @@ foreign lib {
If you are implementing a custom backend, and that backend uses a callback for data delivery, you'll need to call this from inside that
callback.
*/
- device_handle_backend_data_callback :: proc(pDevice: ^device, pOutput: rawptr, pInput: rawptr, frameCount: u32) -> result ---
+ device_handle_backend_data_callback :: proc(pDevice: ^device, pOutput, pInput: rawptr, frameCount: u32) -> result ---
/*
@@ -1351,18 +1543,18 @@ foreign lib {
Parameters
----------
pDescriptor (in)
- A pointer to device descriptor whose `periodSizeInFrames` and `periodSizeInMilliseconds` members
- will be used for the calculation of the buffer size.
+ A pointer to device descriptor whose `periodSizeInFrames` and `periodSizeInMilliseconds` members
+ will be used for the calculation of the buffer size.
nativeSampleRate (in)
- The device's native sample rate. This is only ever used when the `periodSizeInFrames` member of
- `pDescriptor` is zero. In this case, `periodSizeInMilliseconds` will be used instead, in which
- case a sample rate is required to convert to a size in frames.
+ The device's native sample rate. This is only ever used when the `periodSizeInFrames` member of
+ `pDescriptor` is zero. In this case, `periodSizeInMilliseconds` will be used instead, in which
+ case a sample rate is required to convert to a size in frames.
performanceProfile (in)
- When both the `periodSizeInFrames` and `periodSizeInMilliseconds` members of `pDescriptor` are
- zero, miniaudio will fall back to a buffer size based on the performance profile. The profile
- to use for this calculation is determine by this parameter.
+ When both the `periodSizeInFrames` and `periodSizeInMilliseconds` members of `pDescriptor` are
+ zero, miniaudio will fall back to a buffer size based on the performance profile. The profile
+ to use for this calculation is determine by this parameter.
Return Value
@@ -1408,14 +1600,14 @@ foreign lib {
Parameters
----------
pBackends (out, optional)
- A pointer to the buffer that will receive the enabled backends. Set to NULL to retrieve the backend count. Setting
- the capacity of the buffer to `MA_BUFFER_COUNT` will guarantee it's large enough for all backends.
+ A pointer to the buffer that will receive the enabled backends. Set to NULL to retrieve the backend count. Setting
+ the capacity of the buffer to `MA_BUFFER_COUNT` will guarantee it's large enough for all backends.
backendCap (in)
- The capacity of the `pBackends` buffer.
+ The capacity of the `pBackends` buffer.
pBackendCount (out)
- A pointer to the variable that will receive the enabled backend count.
+ A pointer to the variable that will receive the enabled backend count.
Return Value
@@ -1463,7 +1655,7 @@ foreign lib {
result = ma_get_enabled_backends(enabledBackends, MA_BACKEND_COUNT, &enabledBackendCount);
if (result != MA_SUCCESS) {
- // Failed to retrieve enabled backends. Should never happen in this example since all inputs are valid.
+ // Failed to retrieve enabled backends. Should never happen in this example since all inputs are valid.
}
```
diff --git a/vendor/miniaudio/device_io_types.odin b/vendor/miniaudio/device_io_types.odin
index e05f94665..b3ecb2301 100644
--- a/vendor/miniaudio/device_io_types.odin
+++ b/vendor/miniaudio/device_io_types.odin
@@ -18,12 +18,13 @@ SUPPORT_WEBAUDIO :: false // ODIN_OS == .Emscripten
SUPPORT_CUSTOM :: true
SUPPORT_NULL :: true // ODIN_OS != .Emscripten
-STATE_UNINITIALIZED :: 0
-STATE_STOPPED :: 1 /* The device's default state after initialization. */
-STATE_STARTED :: 2 /* The device is started and is requesting and/or delivering audio data. */
-STATE_STARTING :: 3 /* Transitioning from a stopped state to started. */
-STATE_STOPPING :: 4 /* Transitioning from a started state to stopped. */
-
+device_state :: enum c.int {
+ uninitialized = 0,
+ stopped = 1, /* The device's default state after initialization. */
+ started = 2, /* The device is started and is requesting and/or delivering audio data. */
+ starting = 3, /* Transitioning from a stopped state to started. */
+ stopping = 4, /* Transitioning from a started state to stopped. */
+}
when SUPPORT_WASAPI {
@@ -56,6 +57,96 @@ backend :: enum c.int {
BACKEND_COUNT :: len(backend)
+/*
+Device job thread. This is used by backends that require asynchronous processing of certain
+operations. It is not used by all backends.
+
+The device job thread is made up of a thread and a job queue. You can post a job to the thread with
+ma_device_job_thread_post(). The thread will do the processing of the job.
+*/
+device_job_thread_config :: struct {
+ noThread: b32, /* Set this to true if you want to process jobs yourself. */
+ jobQueueCapacity: u32,
+ jobQueueFlags: u32,
+}
+
+device_job_thread :: struct {
+ thread: thread,
+ jobQueue: job_queue,
+ _hasThread: b32,
+}
+
+
+/* Device notification types. */
+device_notification_type :: enum c.int {
+ started,
+ stopped,
+ rerouted,
+ interruption_began,
+ interruption_ended,
+}
+
+device_notification :: struct {
+ pDevice: ^device,
+ type: device_notification_type,
+ data: struct #raw_union {
+ started: struct {
+ _unused: c.int,
+ },
+ stopped: struct {
+ _unused: c.int,
+ },
+ rerouted: struct {
+ _unused: c.int,
+ },
+ interruption: struct {
+ _unused: c.int,
+ },
+ },
+}
+
+/*
+The notification callback for when the application should be notified of a change to the device.
+
+This callback is used for notifying the application of changes such as when the device has started,
+stopped, rerouted or an interruption has occurred. Note that not all backends will post all
+notification types. For example, some backends will perform automatic stream routing without any
+kind of notification to the host program which means miniaudio will never know about it and will
+never be able to fire the rerouted notification. You should keep this in mind when designing your
+program.
+
+The stopped notification will *not* get fired when a device is rerouted.
+
+
+Parameters
+----------
+pNotification (in)
+ A pointer to a structure containing information about the event. Use the `pDevice` member of
+ this object to retrieve the relevant device. The `type` member can be used to discriminate
+ against each of the notification types.
+
+
+Remarks
+-------
+Do not restart or uninitialize the device from the callback.
+
+Not all notifications will be triggered by all backends, however the started and stopped events
+should be reliable for all backends. Some backends do not have a good way to detect device
+stoppages due to unplugging the device which may result in the stopped callback not getting
+fired. This has been observed with at least one BSD variant.
+
+The rerouted notification is fired *after* the reroute has occurred. The stopped notification will
+*not* get fired when a device is rerouted. The following backends are known to do automatic stream
+rerouting, but do not have a way to be notified of the change:
+
+ * DirectSound
+
+The interruption notifications are used on mobile platforms for detecting when audio is interrupted
+due to things like an incoming phone call. Currently this is only implemented on iOS. None of the
+Android backends will report this notification.
+*/
+device_notification_proc :: proc "c" (pNotification: ^device_notification)
+
/*
The callback for processing audio data from the device.
@@ -96,9 +187,11 @@ callback. The following APIs cannot be called from inside the callback:
The proper way to stop the device is to call `ma_device_stop()` from a different thread, normally the main application thread.
*/
-device_callback_proc :: proc "c" (pDevice: ^device, pOutput: rawptr, pInput: rawptr, frameCount: u32)
+device_data_proc :: proc "c" (pDevice: ^device, pOutput, pInput: rawptr, frameCount: u32)
/*
+DEPRECATED. Use ma_device_notification_proc instead.
+
The callback for when the device has been stopped.
This will be called when the device is stopped explicitly with `ma_device_stop()` and also called implicitly when the device is stopped through external forces
@@ -108,48 +201,15 @@ such as being unplugged or an internal error occuring.
Parameters
----------
pDevice (in)
- A pointer to the device that has just stopped.
+ A pointer to the device that has just stopped.
Remarks
-------
Do not restart or uninitialize the device from the callback.
*/
-stop_proc :: proc "c" (pDevice: ^device)
+stop_proc :: proc "c" (pDevice: ^device) /* DEPRECATED. Use ma_device_notification_proc instead. */
-/*
-The callback for handling log messages.
-
-
-Parameters
-----------
-pContext (in)
- A pointer to the context the log message originated from.
-
-pDevice (in)
- A pointer to the device the log message originate from, if any. This can be null, in which case the message came from the context.
-
-logLevel (in)
- The log level. This can be one of the following:
-
- +----------------------+
- | Log Level |
- +----------------------+
- | MA_LOG_LEVEL_DEBUG |
- | MA_LOG_LEVEL_INFO |
- | MA_LOG_LEVEL_WARNING |
- | MA_LOG_LEVEL_ERROR |
- +----------------------+
-
-message (in)
- The log message.
-
-
-Remarks
--------
-Do not modify the state of the device from inside the callback.
-*/
-log_proc :: proc "c" (pContext: context_type, pDevice: ^device, logLevel: u32, message: cstring)
device_type :: enum c.int {
playback = 1,
@@ -279,29 +339,14 @@ device_id :: struct #raw_union {
DATA_FORMAT_FLAG_EXCLUSIVE_MODE :: 1 << 1 /* If set, this is supported in exclusive mode. Otherwise not natively supported by exclusive mode. */
+MAX_DEVICE_NAME_LENGTH :: 255
+
device_info :: struct {
/* Basic info. This is the only information guaranteed to be filled in during device enumeration. */
id: device_id,
- name: [256]byte,
+ name: [MAX_DEVICE_NAME_LENGTH + 1]c.char, /* +1 for null terminator. */
isDefault: b32,
- /*
- Detailed info. As much of this is filled as possible with ma_context_get_device_info(). Note that you are allowed to initialize
- a device with settings outside of this range, but it just means the data will be converted using miniaudio's data conversion
- pipeline before sending the data to/from the device. Most programs will need to not worry about these values, but it's provided
- here mainly for informational purposes or in the rare case that someone might find it useful.
-
- These will be set to 0 when returned by ma_context_enumerate_devices() or ma_context_get_devices().
- */
- formatCount: u32,
- formats: [format]format,
- minChannels: u32,
- maxChannels: u32,
- minSampleRate: u32,
- maxSampleRate: u32,
-
-
- /* Experimental. Don't use these right now. */
nativeDataFormatCount: u32,
nativeDataFormats: [/*len(format_count) * standard_sample_rate.rate_count * MAX_CHANNELS*/ 64]struct { /* Not sure how big to make this. There can be *many* permutations for virtual devices which can support anything. */
format: format, /* Sample format. If set to ma_format_unknown, all sample formats are supported. */
@@ -312,31 +357,26 @@ device_info :: struct {
}
device_config :: struct {
- deviceType: device_type,
- sampleRate: u32,
- periodSizeInFrames: u32,
- periodSizeInMilliseconds: u32,
- periods: u32,
- performanceProfile: performance_profile,
- noPreZeroedOutputBuffer: b8, /* When set to true, the contents of the output buffer passed into the data callback will be left undefined rather than initialized to zero. */
- noClip: b8, /* When set to true, the contents of the output buffer passed into the data callback will be clipped after returning. Only applies when the playback sample format is f32. */
- dataCallback: device_callback_proc,
- stopCallback: stop_proc,
- pUserData: rawptr,
- resampling: struct {
- algorithm: resample_algorithm,
- linear: struct {
- lpfOrder: u32,
- },
- speex: struct {
- quality: c.int,
- },
- },
+ deviceType: device_type,
+ sampleRate: u32,
+ periodSizeInFrames: u32,
+ periodSizeInMilliseconds: u32,
+ periods: u32,
+ performanceProfile: performance_profile,
+ noPreSilencedOutputBuffer: b8, /* When set to true, the contents of the output buffer passed into the data callback will be left undefined rather than initialized to zero. */
+ noClip: b8, /* When set to true, the contents of the output buffer passed into the data callback will be clipped after returning. Only applies when the playback sample format is f32. */
+ noDisableDenormals: b8, /* Do not disable denormals when firing the data callback. */
+ noFixedSizedCallback: b8, /* Disables strict fixed-sized data callbacks. Setting this to true will result in the period size being treated only as a hint to the backend. This is an optimization for those who don't need fixed sized callbacks. */
+ dataCallback: device_data_proc,
+ notificationCallback: device_notification_proc,
+ stopCallback: stop_proc,
+ pUserData: rawptr,
+ resampling: resampler_config,
playback: struct {
pDeviceID: ^device_id,
format: format,
channels: u32,
- channelMap: [MAX_CHANNELS]channel,
+ channelMap: [^]channel,
channelMixMode: channel_mix_mode,
shareMode: share_mode,
},
@@ -344,7 +384,7 @@ device_config :: struct {
pDeviceID: ^device_id,
format: format,
channels: u32,
- channelMap: [MAX_CHANNELS]channel,
+ channelMap: [^]channel,
channelMixMode: channel_mix_mode,
shareMode: share_mode,
},
@@ -373,9 +413,10 @@ device_config :: struct {
recordingPreset: opensl_recording_preset,
},
aaudio: struct {
- usage: aaudio_usage,
- contentType: aaudio_content_type,
- inputPreset: aaudio_input_preset,
+ usage: aaudio_usage,
+ contentType: aaudio_content_type,
+ inputPreset: aaudio_input_preset,
+ noAutoStartAfterReroute: b32,
},
}
@@ -425,14 +466,14 @@ to many devices. A device is created from a context.
The general flow goes like this:
1) A context is created with `onContextInit()`
- 1a) Available devices can be enumerated with `onContextEnumerateDevices()` if required.
- 1b) Detailed information about a device can be queried with `onContextGetDeviceInfo()` if required.
+ 1a) Available devices can be enumerated with `onContextEnumerateDevices()` if required.
+ 1b) Detailed information about a device can be queried with `onContextGetDeviceInfo()` if required.
2) A device is created from the context that was created in the first step using `onDeviceInit()`, and optionally a device ID that was
- selected from device enumeration via `onContextEnumerateDevices()`.
+ selected from device enumeration via `onContextEnumerateDevices()`.
3) A device is started or stopped with `onDeviceStart()` / `onDeviceStop()`
4) Data is delivered to and from the device by the backend. This is always done based on the native format returned by the prior call
- to `onDeviceInit()`. Conversion between the device's native format and the format requested by the application will be handled by
- miniaudio internally.
+ to `onDeviceInit()`. Conversion between the device's native format and the format requested by the application will be handled by
+ miniaudio internally.
Initialization of the context is quite simple. You need to do any necessary initialization of internal objects and then output the
callbacks defined in this structure.
@@ -440,7 +481,7 @@ callbacks defined in this structure.
Once the context has been initialized you can initialize a device. Before doing so, however, the application may want to know which
physical devices are available. This is where `onContextEnumerateDevices()` comes in. This is fairly simple. For each device, fire the
given callback with, at a minimum, the basic information filled out in `ma_device_info`. When the callback returns `MA_FALSE`, enumeration
-needs to stop and the `onContextEnumerateDevices()` function return with a success code.
+needs to stop and the `onContextEnumerateDevices()` function returns with a success code.
Detailed device information can be retrieved from a device ID using `onContextGetDeviceInfo()`. This takes as input the device type and ID,
and on output returns detailed information about the device in `ma_device_info`. The `onContextGetDeviceInfo()` callback must handle the
@@ -455,7 +496,7 @@ internally by miniaudio.
On input, if the sample format is set to `ma_format_unknown`, the backend is free to use whatever sample format it desires, so long as it's
supported by miniaudio. When the channel count is set to 0, the backend should use the device's native channel count. The same applies for
-sample rate. For the channel map, the default should be used when `ma_channel_map_blank()` returns true (all channels set to
+sample rate. For the channel map, the default should be used when `ma_channel_map_is_blank()` returns true (all channels set to
`MA_CHANNEL_NONE`). On input, the `periodSizeInFrames` or `periodSizeInMilliseconds` option should always be set. The backend should
inspect both of these variables. If `periodSizeInFrames` is set, it should take priority, otherwise it needs to be derived from the period
size in milliseconds (`periodSizeInMilliseconds`) and the sample rate, keeping in mind that the sample rate may be 0, in which case the
@@ -474,14 +515,17 @@ This allows miniaudio to then process any necessary data conversion and then pas
If the backend requires absolute flexibility with it's data delivery, it can optionally implement the `onDeviceDataLoop()` callback
which will allow it to implement the logic that will run on the audio thread. This is much more advanced and is completely optional.
-The audio thread should run data delivery logic in a loop while `ma_device_get_state() == MA_STATE_STARTED` and no errors have been
+The audio thread should run data delivery logic in a loop while `ma_device_get_state() == ma_device_state_started` and no errors have been
encounted. Do not start or stop the device here. That will be handled from outside the `onDeviceDataLoop()` callback.
The invocation of the `onDeviceDataLoop()` callback will be handled by miniaudio. When you start the device, miniaudio will fire this
-callback. When the device is stopped, the `ma_device_get_state() == MA_STATE_STARTED` condition will fail and the loop will be terminated
+callback. When the device is stopped, the `ma_device_get_state() == ma_device_state_started` condition will fail and the loop will be terminated
which will then fall through to the part that stops the device. For an example on how to implement the `onDeviceDataLoop()` callback,
look at `ma_device_audio_thread__default_read_write()`. Implement the `onDeviceDataLoopWakeup()` callback if you need a mechanism to
wake up the audio thread.
+
+If the backend supports an optimized retrieval of device information from an initialized `ma_device` object, it should implement the
+`onDeviceGetInfo()` callback. This is optional, in which case it will fall back to `onContextGetDeviceInfo()` which is less efficient.
*/
backend_callbacks :: struct {
onContextInit: proc "c" (pContext: ^context_type, pConfig: ^context_config, pCallbacks: ^backend_callbacks) -> result,
@@ -496,10 +540,10 @@ backend_callbacks :: struct {
onDeviceWrite: proc "c" (pDevice: ^device, pFrames: rawptr, frameCount: u32, pFramesWritten: ^u32) -> result,
onDeviceDataLoop: proc "c" (pDevice: ^device) -> result,
onDeviceDataLoopWakeup: proc "c" (pDevice: ^device) -> result,
+ onDeviceGetInfo: proc "c" (pDevice: ^device, type: device_type, pDeviceInfo: ^device_info) -> result,
}
context_config :: struct {
- logCallback: log_proc, /* Legacy logging callback. Will be removed in version 0.11. */
pLog: ^log,
threadPriority: thread_priority,
threadStackSize: c.size_t,
@@ -538,7 +582,7 @@ context_command__wasapi :: struct {
deviceType: device_type,
pAudioClient: rawptr,
ppAudioClientService: ^rawptr,
- pResult: ^rawptr, /* The result from creating the audio client service. */
+ pResult: ^result, /* The result from creating the audio client service. */
},
releaseAudioClient: struct {
pDevice: ^device,
@@ -548,21 +592,20 @@ context_command__wasapi :: struct {
}
context_type :: struct {
- callbacks: backend_callbacks,
- backend: backend, /* DirectSound, ALSA, etc. */
- pLog: ^log,
- log: log, /* Only used if the log is owned by the context. The pLog member will be set to &log in this case. */
- logCallback: log_proc, /* Legacy callback. Will be removed in version 0.11. */
- threadPriority: thread_priority,
- threadStackSize: c.size_t,
- pUserData: rawptr,
- allocationCallbacks: allocation_callbacks,
- deviceEnumLock: mutex, /* Used to make ma_context_get_devices() thread safe. */
- deviceInfoLock: mutex, /* Used to make ma_context_get_device_info() thread safe. */
- deviceInfoCapacity: u32, /* Total capacity of pDeviceInfos. */
+ callbacks: backend_callbacks,
+ backend: backend, /* DirectSound, ALSA, etc. */
+ pLog: ^log,
+ log: log, /* Only used if the log is owned by the context. The pLog member will be set to &log in this case. */
+ threadPriority: thread_priority,
+ threadStackSize: c.size_t,
+ pUserData: rawptr,
+ allocationCallbacks: allocation_callbacks,
+ deviceEnumLock: mutex, /* Used to make ma_context_get_devices() thread safe. */
+ deviceInfoLock: mutex, /* Used to make ma_context_get_device_info() thread safe. */
+ deviceInfoCapacity: u32, /* Total capacity of pDeviceInfos. */
playbackDeviceInfoCount: u32,
- captureDeviceInfoCount: u32,
- pDeviceInfos: [^]device_info, /* Playback devices first, then capture. */
+ captureDeviceInfoCount: u32,
+ pDeviceInfos: [^]device_info, /* Playback devices first, then capture. */
using _: struct #raw_union {
wasapi: (struct {
@@ -575,7 +618,7 @@ context_type :: struct {
} when SUPPORT_WASAPI else struct {}),
dsound: (struct {
- DSoundDLL: handle,
+ hDSoundDLL: handle,
DirectSoundCreate: proc "system" (),
DirectSoundEnumerateA: proc "system" (),
DirectSoundCaptureCreate: proc "system" (),
@@ -741,6 +784,8 @@ context_type :: struct {
/*pa_mainloop**/ pMainLoop: rawptr,
/*pa_context**/ pPulseContext: rawptr,
+ pApplicationName: cstring, /* Set when the context is initialized. Used by devices for their local pa_context objects. */
+ pServerName: cstring, /* Set when the context is initialized. Used by devices for their local pa_context objects. */
} when SUPPORT_PULSEAUDIO else struct {}),
jack: (struct {
@@ -762,7 +807,7 @@ context_type :: struct {
jack_port_get_buffer: proc "system" (),
jack_free: proc "system" (),
- pClientName: [^]c.char,
+ pClientName: cstring,
tryStartServer: b32,
} when SUPPORT_JACK else struct {}),
@@ -817,7 +862,7 @@ context_type :: struct {
} when SUPPORT_SNDIO else struct {}),
audio4: (struct {
- _unused: cint,
+ _unused: c.int,
} when SUPPORT_AUDIO4 else struct {}),
oss: (struct {
@@ -855,6 +900,7 @@ context_type :: struct {
AAudioStream_getFramesPerBurst: proc "system" (),
AAudioStream_requestStart: proc "system" (),
AAudioStream_requestStop: proc "system" (),
+ jobThread: device_job_thread, /* For processing operations outside of the error callback, specifically device disconnections and rerouting. */
} when SUPPORT_AAUDIO else struct {}),
opensl: (struct {
@@ -921,37 +967,40 @@ context_type :: struct {
}
device :: struct {
- pContext: ^context_type,
- type: device_type,
- sampleRate: u32,
- state: u32, /*atomic*/ /* The state of the device is variable and can change at any time on any thread. Must be used atomically. */
- onData: device_callback_proc, /* Set once at initialization time and should not be changed after. */
- onStop: stop_proc, /* Set once at initialization time and should not be changed after. */
- pUserData: rawptr, /* Application defined data. */
- startStopLock: mutex,
- wakeupEvent: event,
- startEvent: event,
- stopEvent: event,
- device_thread: thread,
- workResult: result, /* This is set by the worker thread after it's finished doing a job. */
- isOwnerOfContext: b8, /* When set to true, uninitializing the device will also uninitialize the context. Set to true when NULL is passed into ma_device_init(). */
- noPreZeroedOutputBuffer: b8,
- noClip: b8,
- masterVolumeFactor: f32, /*atomic*/ /* Linear 0..1. Can be read and written simultaneously by different threads. Must be used atomically. */
- duplexRB: duplex_rb, /* Intermediary buffer for duplex device on asynchronous backends. */
+ pContext: ^context_type,
+ type: device_type,
+ sampleRate: u32,
+ state: u32, /*atomic*/ /* The state of the device is variable and can change at any time on any thread. Must be used atomically. */
+ onData: device_data_proc, /* Set once at initialization time and should not be changed after. */
+ onNotification: device_notification_proc, /* Set once at initialization time and should not be changed after. */
+ onStop: stop_proc, /* DEPRECATED. Use the notification callback instead. Set once at initialization time and should not be changed after. */
+ pUserData: rawptr, /* Application defined data. */
+ startStopLock: mutex,
+ wakeupEvent: event,
+ startEvent: event,
+ stopEvent: event,
+ device_thread: thread,
+ workResult: result, /* This is set by the worker thread after it's finished doing a job. */
+ isOwnerOfContext: b8, /* When set to true, uninitializing the device will also uninitialize the context. Set to true when NULL is passed into ma_device_init(). */
+ noPreSilencedOutputBuffer: b8,
+ noClip: b8,
+ noDisableDenormals: b8,
+ noFixedSizedCallback: b8,
+ masterVolumeFactor: f32, /*atomic*/ /* Linear 0..1. Can be read and written simultaneously by different threads. Must be used atomically. */
+ duplexRB: duplex_rb, /* Intermediary buffer for duplex device on asynchronous backends. */
resampling: struct {
- algorithm: resample_algorithm,
+ algorithm: resample_algorithm,
+ pBackendVTable: ^resampling_backend_vtable,
+ pBackendUserData: rawptr,
linear: struct {
lpfOrder: u32,
},
- speex: struct {
- quality: c.int,
- },
},
playback: struct {
- id: device_id, /* If using an explicit device, will be set to a copy of the ID used for initialization. Otherwise cleared to 0. */
- name: [256]byte, /* Maybe temporary. Likely to be replaced with a query API. */
- shareMode: share_mode, /* Set to whatever was passed in when the device was initialized. */
+ pID: ^device_id, /* Set to NULL if using default ID, otherwise set to the address of "id". */
+ id: device_id, /* If using an explicit device, will be set to a copy of the ID used for initialization. Otherwise cleared to 0. */
+ name: [MAX_DEVICE_NAME_LENGTH + 1]c.char, /* Maybe temporary. Likely to be replaced with a query API. */
+ shareMode: share_mode, /* Set to whatever was passed in when the device was initialized. */
playback_format: format,
channels: u32,
channelMap: [MAX_CHANNELS]channel,
@@ -963,11 +1012,19 @@ device :: struct {
internalPeriods: u32,
channelMixMode: channel_mix_mode,
converter: data_converter,
+ pIntermediaryBuffer: rawptr, /* For implementing fixed sized buffer callbacks. Will be null if using variable sized callbacks. */
+ intermediaryBufferCap: u32,
+ intermediaryBufferLen: u32, /* How many valid frames are sitting in the intermediary buffer. */
+ pInputCache: rawptr, /* In external format. Can be null. */
+ inputCacheCap: u64,
+ inputCacheConsumed: u64,
+ inputCacheRemaining: u64,
},
capture: struct {
- id: device_id, /* If using an explicit device, will be set to a copy of the ID used for initialization. Otherwise cleared to 0. */
- name: [256]byte, /* Maybe temporary. Likely to be replaced with a query API. */
- shareMode: share_mode, /* Set to whatever was passed in when the device was initialized. */
+ pID: ^device_id, /* Set to NULL if using default ID, otherwise set to the address of "id". */
+ id: device_id, /* If using an explicit device, will be set to a copy of the ID used for initialization. Otherwise cleared to 0. */
+ name: [MAX_DEVICE_NAME_LENGTH + 1]c.char, /* Maybe temporary. Likely to be replaced with a query API. */
+ shareMode: share_mode, /* Set to whatever was passed in when the device was initialized. */
capture_format: format,
channels: u32,
channelMap: [MAX_CHANNELS]channel,
@@ -979,6 +1036,9 @@ device :: struct {
internalPeriods: u32,
channelMixMode: channel_mix_mode,
converter: data_converter,
+ pIntermediaryBuffer: rawptr, /* For implementing fixed sized buffer callbacks. Will be null if using variable sized callbacks. */
+ intermediaryBufferCap: u32,
+ intermediaryBufferLen: u32, /* How many valid frames are sitting in the intermediary buffer. */
},
using _: struct #raw_union {
@@ -991,7 +1051,7 @@ device :: struct {
notificationClient: IMMNotificationClient,
/*HANDLE*/ hEventPlayback: handle, /* Auto reset. Initialized to signaled. */
/*HANDLE*/ hEventCapture: handle, /* Auto reset. Initialized to unsignaled. */
- actualPeriodSizeInFramesPlayback: u32, /* Value from GetBufferSize(). internalPeriodSizeInFrames is not set to the _actual_ buffer size when low-latency shared mode is being used due to the way the IAudioClient3 API works. */
+ actualPeriodSizeInFramesPlayback: u32, /* Value from GetBufferSize(). internalPeriodSizeInFrames is not set to the _actual_ buffer size when low-latency shared mode is being used due to the way the IAudioClient3 API works. */
actualPeriodSizeInFramesCapture: u32,
originalPeriodSizeInFrames: u32,
originalPeriodSizeInMilliseconds: u32,
@@ -999,8 +1059,14 @@ device :: struct {
originalPerformanceProfile: performance_profile,
periodSizeInFramesPlayback: u32,
periodSizeInFramesCapture: u32,
- isStartedCapture: b32, /*atomic*/ /* Can be read and written simultaneously across different threads. Must be used atomically, and must be 32-bit. */
- isStartedPlayback: b32, /*atomic*/ /* Can be read and written simultaneously across different threads. Must be used atomically, and must be 32-bit. */
+ pMappedBufferCapture: rawptr,
+ mappedBufferCaptureCap: u32,
+ mappedBufferCaptureLen: u32,
+ pMappedBufferPlayback: rawptr,
+ mappedBufferPlaybackCap: u32,
+ mappedBufferPlaybackLen: u32,
+ isStartedCapture: b32, /*atomic*/ /* Can be read and written simultaneously across different threads. Must be used atomically, and must be 32-bit. */
+ isStartedPlayback: b32, /*atomic*/ /* Can be read and written simultaneously across different threads. Must be used atomically, and must be 32-bit. */
noAutoConvertSRC: b8, /* When set to true, disables the use of AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM. */
noDefaultQualitySRC: b8, /* When set to true, disables the use of AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY. */
noHardwareOffloading: b8,
@@ -1049,14 +1115,16 @@ device :: struct {
} when SUPPORT_ALSA else struct {}),
pulse: (struct {
+ /*pa_mainloop**/ pMainLoop: rawptr,
+ /*pa_context**/ pPulseContext: rawptr,
/*pa_stream**/ pStreamPlayback: rawptr,
/*pa_stream**/ pStreamCapture: rawptr,
} when SUPPORT_PULSEAUDIO else struct {}),
jack: (struct {
/*jack_client_t**/ pClient: rawptr,
- /*jack_port_t**/ pPortsPlayback: [MAX_CHANNELS]rawptr,
- /*jack_port_t**/ pPortsCapture: [MAX_CHANNELS]rawptr,
+ /*jack_port_t**/ pPortsPlayback: [^]rawptr,
+ /*jack_port_t**/ pPortsCapture: [^]rawptr,
pIntermediaryBufferPlayback: [^]f32, /* Typed as a float because JACK is always floating point. */
pIntermediaryBufferCapture: [^]f32,
} when SUPPORT_JACK else struct {}),
@@ -1079,6 +1147,7 @@ device :: struct {
isSwitchingCaptureDevice: b32, /* <-- Set to true when the default device has changed and miniaudio is in the process of switching. */
pRouteChangeHandler: rawptr, /* Only used on mobile platforms. Obj-C object for handling route changes. */
} when SUPPORT_COREAUDIO else struct {}),
+
sndio: (struct {
handlePlayback: rawptr,
handleCapture: rawptr,
@@ -1099,6 +1168,10 @@ device :: struct {
aaudio: (struct {
/*AAudioStream**/ pStreamPlayback: rawptr,
/*AAudioStream**/ pStreamCapture: rawptr,
+ usage: aaudio_usage,
+ contentType: aaudio_content_type,
+ inputPreset: aaudio_input_preset,
+ noAutoStartAfterReroute: b32,
} when SUPPORT_AAUDIO else struct {}),
opensl: (struct {
diff --git a/vendor/miniaudio/doc.odin b/vendor/miniaudio/doc.odin
index 887e5d149..c6de0ec61 100644
--- a/vendor/miniaudio/doc.odin
+++ b/vendor/miniaudio/doc.odin
@@ -2,7 +2,7 @@ package miniaudio
/*
Audio playback and capture library. Choice of public domain or MIT-0. See license statements at the end of this file.
-miniaudio - v0.10.42 - 2021-08-22
+miniaudio - v0.11.9 - 2022-04-20
David Reid - mackron@gmail.com
@@ -14,7 +14,8 @@ GitHub: https://github.com/mackron/miniaudio
/*
1. Introduction
===============
-miniaudio is a single file library for audio playback and capture. To use it, do the following in one .c file:
+miniaudio is a single file library for audio playback and capture. To use it, do the following in
+one .c file:
```c
#define MINIAUDIO_IMPLEMENTATION
@@ -23,16 +24,44 @@ miniaudio is a single file library for audio playback and capture. To use it, do
You can do `#include "miniaudio.h"` in other parts of the program just like any other header.
-miniaudio uses the concept of a "device" as the abstraction for physical devices. The idea is that you choose a physical device to emit or capture audio from,
-and then move data to/from the device when miniaudio tells you to. Data is delivered to and from devices asynchronously via a callback which you specify when
-initializing the device.
+miniaudio includes both low level and high level APIs. The low level API is good for those who want
+to do all of their mixing themselves and only require a light weight interface to the underlying
+audio device. The high level API is good for those who have complex mixing and effect requirements.
-When initializing the device you first need to configure it. The device configuration allows you to specify things like the format of the data delivered via
-the callback, the size of the internal buffer and the ID of the device you want to emit or capture audio from.
+In miniaudio, objects are transparent structures. Unlike many other libraries, there are no handles
+to opaque objects which means you need to allocate memory for objects yourself. In the examples
+presented in this documentation you will often see objects declared on the stack. You need to be
+careful when translating these examples to your own code so that you don't accidentally declare
+your objects on the stack and then cause them to become invalid once the function returns. In
+addition, you must ensure the memory address of your objects remain the same throughout their
+lifetime. You therefore cannot be making copies of your objects.
-Once you have the device configuration set up you can initialize the device. When initializing a device you need to allocate memory for the device object
-beforehand. This gives the application complete control over how the memory is allocated. In the example below we initialize a playback device on the stack,
-but you could allocate it on the heap if that suits your situation better.
+A config/init pattern is used throughout the entire library. The idea is that you set up a config
+object and pass that into the initialization routine. The advantage to this system is that the
+config object can be initialized with logical defaults and new properties added to it without
+breaking the API. The config object can be allocated on the stack and does not need to be
+maintained after initialization of the corresponding object.
+
+
+1.1. Low Level API
+------------------
+The low level API gives you access to the raw audio data of an audio device. It supports playback,
+capture, full-duplex and loopback (WASAPI only). You can enumerate over devices to determine which
+physical device(s) you want to connect to.
+
+The low level API uses the concept of a "device" as the abstraction for physical devices. The idea
+is that you choose a physical device to emit or capture audio from, and then move data to/from the
+device when miniaudio tells you to. Data is delivered to and from devices asynchronously via a
+callback which you specify when initializing the device.
+
+When initializing the device you first need to configure it. The device configuration allows you to
+specify things like the format of the data delivered via the callback, the size of the internal
+buffer and the ID of the device you want to emit or capture audio from.
+
+Once you have the device configuration set up you can initialize the device. When initializing a
+device you need to allocate memory for the device object beforehand. This gives the application
+complete control over how the memory is allocated. In the example below we initialize a playback
+device on the stack, but you could allocate it on the heap if that suits your situation better.
```c
void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
@@ -65,20 +94,27 @@ but you could allocate it on the heap if that suits your situation better.
}
```
-In the example above, `data_callback()` is where audio data is written and read from the device. The idea is in playback mode you cause sound to be emitted
-from the speakers by writing audio data to the output buffer (`pOutput` in the example). In capture mode you read data from the input buffer (`pInput`) to
-extract sound captured by the microphone. The `frameCount` parameter tells you how many frames can be written to the output buffer and read from the input
-buffer. A "frame" is one sample for each channel. For example, in a stereo stream (2 channels), one frame is 2 samples: one for the left, one for the right.
-The channel count is defined by the device config. The size in bytes of an individual sample is defined by the sample format which is also specified in the
-device config. Multi-channel audio data is always interleaved, which means the samples for each frame are stored next to each other in memory. For example, in
-a stereo stream the first pair of samples will be the left and right samples for the first frame, the second pair of samples will be the left and right samples
-for the second frame, etc.
+In the example above, `data_callback()` is where audio data is written and read from the device.
+The idea is in playback mode you cause sound to be emitted from the speakers by writing audio data
+to the output buffer (`pOutput` in the example). In capture mode you read data from the input
+buffer (`pInput`) to extract sound captured by the microphone. The `frameCount` parameter tells you
+how many frames can be written to the output buffer and read from the input buffer. A "frame" is
+one sample for each channel. For example, in a stereo stream (2 channels), one frame is 2
+samples: one for the left, one for the right. The channel count is defined by the device config.
+The size in bytes of an individual sample is defined by the sample format which is also specified
+in the device config. Multi-channel audio data is always interleaved, which means the samples for
+each frame are stored next to each other in memory. For example, in a stereo stream the first pair
+of samples will be the left and right samples for the first frame, the second pair of samples will
+be the left and right samples for the second frame, etc.
-The configuration of the device is defined by the `ma_device_config` structure. The config object is always initialized with `ma_device_config_init()`. It's
-important to always initialize the config with this function as it initializes it with logical defaults and ensures your program doesn't break when new members
-are added to the `ma_device_config` structure. The example above uses a fairly simple and standard device configuration. The call to `ma_device_config_init()`
-takes a single parameter, which is whether or not the device is a playback, capture, duplex or loopback device (loopback devices are not supported on all
-backends). The `config.playback.format` member sets the sample format which can be one of the following (all formats are native-endian):
+The configuration of the device is defined by the `ma_device_config` structure. The config object
+is always initialized with `ma_device_config_init()`. It's important to always initialize the
+config with this function as it initializes it with logical defaults and ensures your program
+doesn't break when new members are added to the `ma_device_config` structure. The example above
+uses a fairly simple and standard device configuration. The call to `ma_device_config_init()` takes
+a single parameter, which is whether or not the device is a playback, capture, duplex or loopback
+device (loopback devices are not supported on all backends). The `config.playback.format` member
+sets the sample format which can be one of the following (all formats are native-endian):
+---------------+----------------------------------------+---------------------------+
| Symbol | Description | Range |
@@ -90,22 +126,30 @@ backends). The `config.playback.format` member sets the sample format which can
| ma_format_u8 | 8-bit unsigned integer | [0, 255] |
+---------------+----------------------------------------+---------------------------+
-The `config.playback.channels` member sets the number of channels to use with the device. The channel count cannot exceed MA_MAX_CHANNELS. The
-`config.sampleRate` member sets the sample rate (which must be the same for both playback and capture in full-duplex configurations). This is usually set to
-44100 or 48000, but can be set to anything. It's recommended to keep this between 8000 and 384000, however.
+The `config.playback.channels` member sets the number of channels to use with the device. The
+channel count cannot exceed MA_MAX_CHANNELS. The `config.sampleRate` member sets the sample rate
+(which must be the same for both playback and capture in full-duplex configurations). This is
+usually set to 44100 or 48000, but can be set to anything. It's recommended to keep this between
+8000 and 384000, however.
-Note that leaving the format, channel count and/or sample rate at their default values will result in the internal device's native configuration being used
-which is useful if you want to avoid the overhead of miniaudio's automatic data conversion.
+Note that leaving the format, channel count and/or sample rate at their default values will result
+in the internal device's native configuration being used which is useful if you want to avoid the
+overhead of miniaudio's automatic data conversion.
-In addition to the sample format, channel count and sample rate, the data callback and user data pointer are also set via the config. The user data pointer is
-not passed into the callback as a parameter, but is instead set to the `pUserData` member of `ma_device` which you can access directly since all miniaudio
-structures are transparent.
+In addition to the sample format, channel count and sample rate, the data callback and user data
+pointer are also set via the config. The user data pointer is not passed into the callback as a
+parameter, but is instead set to the `pUserData` member of `ma_device` which you can access
+directly since all miniaudio structures are transparent.
-Initializing the device is done with `ma_device_init()`. This will return a result code telling you what went wrong, if anything. On success it will return
-`MA_SUCCESS`. After initialization is complete the device will be in a stopped state. To start it, use `ma_device_start()`. Uninitializing the device will stop
-it, which is what the example above does, but you can also stop the device with `ma_device_stop()`. To resume the device simply call `ma_device_start()` again.
-Note that it's important to never stop or start the device from inside the callback. This will result in a deadlock. Instead you set a variable or signal an
-event indicating that the device needs to stop and handle it in a different thread. The following APIs must never be called inside the callback:
+Initializing the device is done with `ma_device_init()`. This will return a result code telling you
+what went wrong, if anything. On success it will return `MA_SUCCESS`. After initialization is
+complete the device will be in a stopped state. To start it, use `ma_device_start()`.
+Uninitializing the device will stop it, which is what the example above does, but you can also stop
+the device with `ma_device_stop()`. To resume the device simply call `ma_device_start()` again.
+Note that it's important to never stop or start the device from inside the callback. This will
+result in a deadlock. Instead you set a variable or signal an event indicating that the device
+needs to stop and handle it in a different thread. The following APIs must never be called inside
+the callback:
```c
ma_device_init()
@@ -115,12 +159,14 @@ event indicating that the device needs to stop and handle it in a different thre
ma_device_stop()
```
-You must never try uninitializing and reinitializing a device inside the callback. You must also never try to stop and start it from inside the callback. There
-are a few other things you shouldn't do in the callback depending on your requirements, however this isn't so much a thread-safety thing, but rather a
-real-time processing thing which is beyond the scope of this introduction.
+You must never try uninitializing and reinitializing a device inside the callback. You must also
+never try to stop and start it from inside the callback. There are a few other things you shouldn't
+do in the callback depending on your requirements, however this isn't so much a thread-safety
+thing, but rather a real-time processing thing which is beyond the scope of this introduction.
-The example above demonstrates the initialization of a playback device, but it works exactly the same for capture. All you need to do is change the device type
-from `ma_device_type_playback` to `ma_device_type_capture` when setting up the config, like so:
+The example above demonstrates the initialization of a playback device, but it works exactly the
+same for capture. All you need to do is change the device type from `ma_device_type_playback` to
+`ma_device_type_capture` when setting up the config, like so:
```c
ma_device_config config = ma_device_config_init(ma_device_type_capture);
@@ -128,8 +174,9 @@ from `ma_device_type_playback` to `ma_device_type_capture` when setting up the c
config.capture.channels = MY_CHANNEL_COUNT;
```
-In the data callback you just read from the input buffer (`pInput` in the example above) and leave the output buffer alone (it will be set to NULL when the
-device type is set to `ma_device_type_capture`).
+In the data callback you just read from the input buffer (`pInput` in the example above) and leave
+the output buffer alone (it will be set to NULL when the device type is set to
+`ma_device_type_capture`).
These are the available device types and how you should handle the buffers in the callback:
@@ -142,23 +189,29 @@ These are the available device types and how you should handle the buffers in th
| ma_device_type_loopback | Read from input buffer, leave output buffer untouched. |
+-------------------------+--------------------------------------------------------+
-You will notice in the example above that the sample format and channel count is specified separately for playback and capture. This is to support different
-data formats between the playback and capture devices in a full-duplex system. An example may be that you want to capture audio data as a monaural stream (one
-channel), but output sound to a stereo speaker system. Note that if you use different formats between playback and capture in a full-duplex configuration you
-will need to convert the data yourself. There are functions available to help you do this which will be explained later.
+You will notice in the example above that the sample format and channel count is specified
+separately for playback and capture. This is to support different data formats between the playback
+and capture devices in a full-duplex system. An example may be that you want to capture audio data
+as a monaural stream (one channel), but output sound to a stereo speaker system. Note that if you
+use different formats between playback and capture in a full-duplex configuration you will need to
+convert the data yourself. There are functions available to help you do this which will be
+explained later.
-The example above did not specify a physical device to connect to which means it will use the operating system's default device. If you have multiple physical
-devices connected and you want to use a specific one you will need to specify the device ID in the configuration, like so:
+The example above did not specify a physical device to connect to which means it will use the
+operating system's default device. If you have multiple physical devices connected and you want to
+use a specific one you will need to specify the device ID in the configuration, like so:
```c
config.playback.pDeviceID = pMyPlaybackDeviceID; // Only if requesting a playback or duplex device.
config.capture.pDeviceID = pMyCaptureDeviceID; // Only if requesting a capture, duplex or loopback device.
```
-To retrieve the device ID you will need to perform device enumeration, however this requires the use of a new concept called the "context". Conceptually
-speaking the context sits above the device. There is one context to many devices. The purpose of the context is to represent the backend at a more global level
-and to perform operations outside the scope of an individual device. Mainly it is used for performing run-time linking against backend libraries, initializing
-backends and enumerating devices. The example below shows how to enumerate devices.
+To retrieve the device ID you will need to perform device enumeration, however this requires the
+use of a new concept called the "context". Conceptually speaking the context sits above the device.
+There is one context to many devices. The purpose of the context is to represent the backend at a
+more global level and to perform operations outside the scope of an individual device. Mainly it is
+used for performing run-time linking against backend libraries, initializing backends and
+enumerating devices. The example below shows how to enumerate devices.
```c
ma_context context;
@@ -199,44 +252,236 @@ backends and enumerating devices. The example below shows how to enumerate devic
ma_context_uninit(&context);
```
-The first thing we do in this example is initialize a `ma_context` object with `ma_context_init()`. The first parameter is a pointer to a list of `ma_backend`
-values which are used to override the default backend priorities. When this is NULL, as in this example, miniaudio's default priorities are used. The second
-parameter is the number of backends listed in the array pointed to by the first parameter. The third parameter is a pointer to a `ma_context_config` object
-which can be NULL, in which case defaults are used. The context configuration is used for setting the logging callback, custom memory allocation callbacks,
-user-defined data and some backend-specific configurations.
+The first thing we do in this example is initialize a `ma_context` object with `ma_context_init()`.
+The first parameter is a pointer to a list of `ma_backend` values which are used to override the
+default backend priorities. When this is NULL, as in this example, miniaudio's default priorities
+are used. The second parameter is the number of backends listed in the array pointed to by the
+first parameter. The third parameter is a pointer to a `ma_context_config` object which can be
+NULL, in which case defaults are used. The context configuration is used for setting the logging
+callback, custom memory allocation callbacks, user-defined data and some backend-specific
+configurations.
-Once the context has been initialized you can enumerate devices. In the example above we use the simpler `ma_context_get_devices()`, however you can also use a
-callback for handling devices by using `ma_context_enumerate_devices()`. When using `ma_context_get_devices()` you provide a pointer to a pointer that will,
-upon output, be set to a pointer to a buffer containing a list of `ma_device_info` structures. You also provide a pointer to an unsigned integer that will
-receive the number of items in the returned buffer. Do not free the returned buffers as their memory is managed internally by miniaudio.
+Once the context has been initialized you can enumerate devices. In the example above we use the
+simpler `ma_context_get_devices()`, however you can also use a callback for handling devices by
+using `ma_context_enumerate_devices()`. When using `ma_context_get_devices()` you provide a pointer
+to a pointer that will, upon output, be set to a pointer to a buffer containing a list of
+`ma_device_info` structures. You also provide a pointer to an unsigned integer that will receive
+the number of items in the returned buffer. Do not free the returned buffers as their memory is
+managed internally by miniaudio.
-The `ma_device_info` structure contains an `id` member which is the ID you pass to the device config. It also contains the name of the device which is useful
-for presenting a list of devices to the user via the UI.
+The `ma_device_info` structure contains an `id` member which is the ID you pass to the device
+config. It also contains the name of the device which is useful for presenting a list of devices
+to the user via the UI.
-When creating your own context you will want to pass it to `ma_device_init()` when initializing the device. Passing in NULL, like we do in the first example,
-will result in miniaudio creating the context for you, which you don't want to do since you've already created a context. Note that internally the context is
-only tracked by it's pointer which means you must not change the location of the `ma_context` object. If this is an issue, consider using `malloc()` to
-allocate memory for the context.
+When creating your own context you will want to pass it to `ma_device_init()` when initializing the
+device. Passing in NULL, like we do in the first example, will result in miniaudio creating the
+context for you, which you don't want to do since you've already created a context. Note that
+internally the context is only tracked by it's pointer which means you must not change the location
+of the `ma_context` object. If this is an issue, consider using `malloc()` to allocate memory for
+the context.
+
+
+1.2. High Level API
+-------------------
+The high level API consists of three main parts:
+
+ * Resource management for loading and streaming sounds.
+ * A node graph for advanced mixing and effect processing.
+ * A high level "engine" that wraps around the resource manager and node graph.
+
+The resource manager (`ma_resource_manager`) is used for loading sounds. It supports loading sounds
+fully into memory and also streaming. It will also deal with reference counting for you which
+avoids the same sound being loaded multiple times.
+
+The node graph is used for mixing and effect processing. The idea is that you connect a number of
+nodes into the graph by connecting each node's outputs to another node's inputs. Each node can
+implement it's own effect. By chaining nodes together, advanced mixing and effect processing can
+be achieved.
+
+The engine encapsulates both the resource manager and the node graph to create a simple, easy to
+use high level API. The resource manager and node graph APIs are covered in more later sections of
+this manual.
+
+The code below shows how you can initialize an engine using it's default configuration.
+
+ ```c
+ ma_result result;
+ ma_engine engine;
+
+ result = ma_engine_init(NULL, &engine);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to initialize the engine.
+ }
+ ```
+
+This creates an engine instance which will initialize a device internally which you can access with
+`ma_engine_get_device()`. It will also initialize a resource manager for you which can be accessed
+with `ma_engine_get_resource_manager()`. The engine itself is a node graph (`ma_node_graph`) which
+means you can pass a pointer to the engine object into any of the `ma_node_graph` APIs (with a
+cast). Alternatively, you can use `ma_engine_get_node_graph()` instead of a cast.
+
+Note that all objects in miniaudio, including the `ma_engine` object in the example above, are
+transparent structures. There are no handles to opaque structures in miniaudio which means you need
+to be mindful of how you declare them. In the example above we are declaring it on the stack, but
+this will result in the struct being invalidated once the function encapsulating it returns. If
+allocating the engine on the heap is more appropriate, you can easily do so with a standard call
+to `malloc()` or whatever heap allocation routine you like:
+
+ ```c
+ ma_engine* pEngine = malloc(sizeof(*pEngine));
+ ```
+
+The `ma_engine` API uses the same config/init pattern used all throughout miniaudio. To configure
+an engine, you can fill out a `ma_engine_config` object and pass it into the first parameter of
+`ma_engine_init()`:
+
+ ```c
+ ma_result result;
+ ma_engine engine;
+ ma_engine_config engineConfig;
+
+ engineConfig = ma_engine_config_init();
+ engineConfig.pResourceManager = &myCustomResourceManager; // <-- Initialized as some earlier stage.
+
+ result = ma_engine_init(&engineConfig, &engine);
+ if (result != MA_SUCCESS) {
+ return result;
+ }
+ ```
+
+This creates an engine instance using a custom config. In this particular example it's showing how
+you can specify a custom resource manager rather than having the engine initialize one internally.
+This is particularly useful if you want to have multiple engine's share the same resource manager.
+
+The engine must be uninitialized with `ma_engine_uninit()` when it's no longer needed.
+
+By default the engine will be started, but nothing will be playing because no sounds have been
+initialized. The easiest but least flexible way of playing a sound is like so:
+
+ ```c
+ ma_engine_play_sound(&engine, "my_sound.wav", NULL);
+ ```
+
+This plays what miniaudio calls an "inline" sound. It plays the sound once, and then puts the
+internal sound up for recycling. The last parameter is used to specify which sound group the sound
+should be associated with which will be explained later. This particular way of playing a sound is
+simple, but lacks flexibility and features. A more flexible way of playing a sound is to first
+initialize a sound:
+
+ ```c
+ ma_result result;
+ ma_sound sound;
+
+ result = ma_sound_init_from_file(&engine, "my_sound.wav", 0, NULL, NULL, &sound);
+ if (result != MA_SUCCESS) {
+ return result;
+ }
+
+ ma_sound_start(&sound);
+ ```
+
+This returns a `ma_sound` object which represents a single instance of the specified sound file. If
+you want to play the same file multiple times simultaneously, you need to create one sound for each
+instance.
+
+Sounds should be uninitialized with `ma_sound_uninit()`.
+
+Sounds are not started by default. Start a sound with `ma_sound_start()` and stop it with
+`ma_sound_stop()`. When a sound is stopped, it is not rewound to the start. Use
+`ma_sound_seek_to_pcm_frames(&sound, 0)` to seek back to the start of a sound. By default, starting
+and stopping sounds happens immediately, but sometimes it might be convenient to schedule the sound
+the be started and/or stopped at a specific time. This can be done with the following functions:
+
+ ```c
+ ma_sound_set_start_time_in_pcm_frames()
+ ma_sound_set_start_time_in_milliseconds()
+ ma_sound_set_stop_time_in_pcm_frames()
+ ma_sound_set_stop_time_in_milliseconds()
+ ```
+
+The start/stop time needs to be specified based on the absolute timer which is controlled by the
+engine. The current global time time in PCM frames can be retrieved with `ma_engine_get_time()`.
+The engine's global time can be changed with `ma_engine_set_time()` for synchronization purposes if
+required. Note that scheduling a start time still requires an explicit call to `ma_sound_start()`
+before anything will play:
+
+ ```c
+ ma_sound_set_start_time_in_pcm_frames(&sound, ma_engine_get_time(&engine) + (ma_engine_get_sample_rate(&engine) * 2);
+ ma_sound_start(&sound);
+ ```
+
+The third parameter of `ma_sound_init_from_file()` is a set of flags that control how the sound be
+loaded and a few options on which features should be enabled for that sound. By default, the sound
+is synchronously loaded fully into memory straight from the file system without any kind of
+decoding. If you want to decode the sound before storing it in memory, you need to specify the
+`MA_SOUND_FLAG_DECODE` flag. This is useful if you want to incur the cost of decoding at an earlier
+stage, such as a loading stage. Without this option, decoding will happen dynamically at mixing
+time which might be too expensive on the audio thread.
+
+If you want to load the sound asynchronously, you can specify the `MA_SOUND_FLAG_ASYNC` flag. This
+will result in `ma_sound_init_from_file()` returning quickly, but the sound will not start playing
+until the sound has had some audio decoded.
+
+The fourth parameter is a pointer to sound group. A sound group is used as a mechanism to organise
+sounds into groups which have their own effect processing and volume control. An example is a game
+which might have separate groups for sfx, voice and music. Each of these groups have their own
+independent volume control. Use `ma_sound_group_init()` or `ma_sound_group_init_ex()` to initialize
+a sound group.
+
+Sounds and sound groups are nodes in the engine's node graph and can be plugged into any `ma_node`
+API. This makes it possible to connect sounds and sound groups to effect nodes to produce complex
+effect chains.
+
+A sound can have it's volume changed with `ma_sound_set_volume()`. If you prefer decibel volume
+control you can use `ma_volume_db_to_linear()` to convert from decibel representation to linear.
+
+Panning and pitching is supported with `ma_sound_set_pan()` and `ma_sound_set_pitch()`. If you know
+a sound will never have it's pitch changed with `ma_sound_set_pitch()` or via the doppler effect,
+you can specify the `MA_SOUND_FLAG_NO_PITCH` flag when initializing the sound for an optimization.
+
+By default, sounds and sound groups have spatialization enabled. If you don't ever want to
+spatialize your sounds, initialize the sound with the `MA_SOUND_FLAG_NO_SPATIALIZATION` flag. The
+spatialization model is fairly simple and is roughly on feature parity with OpenAL. HRTF and
+environmental occlusion are not currently supported, but planned for the future. The supported
+features include:
+
+ * Sound and listener positioning and orientation with cones
+ * Attenuation models: none, inverse, linear and exponential
+ * Doppler effect
+
+Sounds can be faded in and out with `ma_sound_set_fade_in_pcm_frames()`.
+
+To check if a sound is currently playing, you can use `ma_sound_is_playing()`. To check if a sound
+is at the end, use `ma_sound_at_end()`. Looping of a sound can be controlled with
+`ma_sound_set_looping()`. Use `ma_sound_is_looping()` to check whether or not the sound is looping.
2. Building
===========
-miniaudio should work cleanly out of the box without the need to download or install any dependencies. See below for platform-specific details.
+miniaudio should work cleanly out of the box without the need to download or install any
+dependencies. See below for platform-specific details.
2.1. Windows
------------
-The Windows build should compile cleanly on all popular compilers without the need to configure any include paths nor link to any libraries.
+The Windows build should compile cleanly on all popular compilers without the need to configure any
+include paths nor link to any libraries.
+
+The UWP build may require linking to mmdevapi.lib if you get errors about an unresolved external
+symbol for `ActivateAudioInterfaceAsync()`.
+
2.2. macOS and iOS
------------------
-The macOS build should compile cleanly without the need to download any dependencies nor link to any libraries or frameworks. The iOS build needs to be
-compiled as Objective-C and will need to link the relevant frameworks but should compile cleanly out of the box with Xcode. Compiling through the command line
-requires linking to `-lpthread` and `-lm`.
+The macOS build should compile cleanly without the need to download any dependencies nor link to
+any libraries or frameworks. The iOS build needs to be compiled as Objective-C and will need to
+link the relevant frameworks but should compile cleanly out of the box with Xcode. Compiling
+through the command line requires linking to `-lpthread` and `-lm`.
-Due to the way miniaudio links to frameworks at runtime, your application may not pass Apple's notarization process. To fix this there are two options. The
-first is to use the `MA_NO_RUNTIME_LINKING` option, like so:
+Due to the way miniaudio links to frameworks at runtime, your application may not pass Apple's
+notarization process. To fix this there are two options. The first is to use the
+`MA_NO_RUNTIME_LINKING` option, like so:
```c
#ifdef __APPLE__
@@ -246,8 +491,9 @@ first is to use the `MA_NO_RUNTIME_LINKING` option, like so:
#include "miniaudio.h"
```
-This will require linking with `-framework CoreFoundation -framework CoreAudio -framework AudioUnit`. Alternatively, if you would rather keep using runtime
-linking you can add the following to your entitlements.xcent file:
+This will require linking with `-framework CoreFoundation -framework CoreAudio -framework AudioUnit`.
+Alternatively, if you would rather keep using runtime linking you can add the following to your
+entitlements.xcent file:
```
com.apple.security.cs.allow-dyld-environment-variables
@@ -256,26 +502,37 @@ linking you can add the following to your entitlements.xcent file:
```
+See this discussion for more info: https://github.com/mackron/miniaudio/issues/203.
+
2.3. Linux
----------
-The Linux build only requires linking to `-ldl`, `-lpthread` and `-lm`. You do not need any development packages.
+The Linux build only requires linking to `-ldl`, `-lpthread` and `-lm`. You do not need any
+development packages. You may need to link with `-latomic` if you're compiling for 32-bit ARM.
+
2.4. BSD
--------
-The BSD build only requires linking to `-lpthread` and `-lm`. NetBSD uses audio(4), OpenBSD uses sndio and FreeBSD uses OSS.
+The BSD build only requires linking to `-lpthread` and `-lm`. NetBSD uses audio(4), OpenBSD uses
+sndio and FreeBSD uses OSS. You may need to link with `-latomic` if you're compiling for 32-bit
+ARM.
+
2.5. Android
------------
-AAudio is the highest priority backend on Android. This should work out of the box without needing any kind of compiler configuration. Support for AAudio
-starts with Android 8 which means older versions will fall back to OpenSL|ES which requires API level 16+.
+AAudio is the highest priority backend on Android. This should work out of the box without needing
+any kind of compiler configuration. Support for AAudio starts with Android 8 which means older
+versions will fall back to OpenSL|ES which requires API level 16+.
+
+There have been reports that the OpenSL|ES backend fails to initialize on some Android based
+devices due to `dlopen()` failing to open "libOpenSLES.so". If this happens on your platform
+you'll need to disable run-time linking with `MA_NO_RUNTIME_LINKING` and link with -lOpenSLES.
-There have been reports that the OpenSL|ES backend fails to initialize on some Android based devices due to `dlopen()` failing to open "libOpenSLES.so". If
-this happens on your platform you'll need to disable run-time linking with `MA_NO_RUNTIME_LINKING` and link with -lOpenSLES.
2.6. Emscripten
---------------
-The Emscripten build emits Web Audio JavaScript directly and should compile cleanly out of the box. You cannot use -std=c* compiler flags, nor -ansi.
+The Emscripten build emits Web Audio JavaScript directly and should compile cleanly out of the box.
+You cannot use `-std=c*` compiler flags, nor `-ansi`.
2.7. Build Options
@@ -368,28 +625,26 @@ The Emscripten build emits Web Audio JavaScript directly and should compile clea
+----------------------------------+--------------------------------------------------------------------+
| MA_NO_MP3 | Disables the built-in MP3 decoder. |
+----------------------------------+--------------------------------------------------------------------+
- | MA_NO_DEVICE_IO | Disables playback and recording. This will disable ma_context and |
- | | ma_device APIs. This is useful if you only want to use miniaudio's |
- | | data conversion and/or decoding APIs. |
+ | MA_NO_DEVICE_IO | Disables playback and recording. This will disable `ma_context` |
+ | | and `ma_device` APIs. This is useful if you only want to use |
+ | | miniaudio's data conversion and/or decoding APIs. |
+----------------------------------+--------------------------------------------------------------------+
- | MA_NO_THREADING | Disables the ma_thread, ma_mutex, ma_semaphore and ma_event APIs. |
- | | This option is useful if you only need to use miniaudio for data |
- | | conversion, decoding and/or encoding. Some families of APIs |
- | | require threading which means the following options must also be |
- | | set: |
+ | MA_NO_THREADING | Disables the `ma_thread`, `ma_mutex`, `ma_semaphore` and |
+ | | `ma_event` APIs. This option is useful if you only need to use |
+ | | miniaudio for data conversion, decoding and/or encoding. Some |
+ | | families of APIsrequire threading which means the following |
+ | | options must also be set: |
| | |
| | ``` |
| | MA_NO_DEVICE_IO |
| | ``` |
+----------------------------------+--------------------------------------------------------------------+
- | MA_NO_GENERATION | Disables generation APIs such a ma_waveform and ma_noise. |
+ | MA_NO_GENERATION | Disables generation APIs such a `ma_waveform` and `ma_noise`. |
+----------------------------------+--------------------------------------------------------------------+
| MA_NO_SSE2 | Disables SSE2 optimizations. |
+----------------------------------+--------------------------------------------------------------------+
| MA_NO_AVX2 | Disables AVX2 optimizations. |
+----------------------------------+--------------------------------------------------------------------+
- | MA_NO_AVX512 | Disables AVX-512 optimizations. |
- +----------------------------------+--------------------------------------------------------------------+
| MA_NO_NEON | Disables NEON optimizations. |
+----------------------------------+--------------------------------------------------------------------+
| MA_NO_RUNTIME_LINKING | Disables runtime linking. This is useful for passing Apple's |
@@ -401,47 +656,47 @@ The Emscripten build emits Web Audio JavaScript directly and should compile clea
| | You may need to enable this if your target platform does not allow |
| | runtime linking via `dlopen()`. |
+----------------------------------+--------------------------------------------------------------------+
- | MA_DEBUG_OUTPUT | Enable processing of MA_LOG_LEVEL_DEBUG messages and `printf()` |
- | | output. |
+ | MA_DEBUG_OUTPUT | Enable `printf()` output of debug logs (`MA_LOG_LEVEL_DEBUG`). |
+----------------------------------+--------------------------------------------------------------------+
| MA_COINIT_VALUE | Windows only. The value to pass to internal calls to |
| | `CoInitializeEx()`. Defaults to `COINIT_MULTITHREADED`. |
+----------------------------------+--------------------------------------------------------------------+
| MA_API | Controls how public APIs should be decorated. Default is `extern`. |
+----------------------------------+--------------------------------------------------------------------+
- | MA_DLL | If set, configures MA_API to either import or export APIs |
- | | depending on whether or not the implementation is being defined. |
- | | If defining the implementation, MA_API will be configured to |
- | | export. Otherwise it will be configured to import. This has no |
- | | effect if MA_API is defined externally. |
- +----------------------------------+--------------------------------------------------------------------+
3. Definitions
==============
-This section defines common terms used throughout miniaudio. Unfortunately there is often ambiguity in the use of terms throughout the audio space, so this
-section is intended to clarify how miniaudio uses each term.
+This section defines common terms used throughout miniaudio. Unfortunately there is often ambiguity
+in the use of terms throughout the audio space, so this section is intended to clarify how miniaudio
+uses each term.
3.1. Sample
-----------
-A sample is a single unit of audio data. If the sample format is f32, then one sample is one 32-bit floating point number.
+A sample is a single unit of audio data. If the sample format is f32, then one sample is one 32-bit
+floating point number.
3.2. Frame / PCM Frame
----------------------
-A frame is a group of samples equal to the number of channels. For a stereo stream a frame is 2 samples, a mono frame is 1 sample, a 5.1 surround sound frame
-is 6 samples, etc. The terms "frame" and "PCM frame" are the same thing in miniaudio. Note that this is different to a compressed frame. If ever miniaudio
-needs to refer to a compressed frame, such as a FLAC frame, it will always clarify what it's referring to with something like "FLAC frame".
+A frame is a group of samples equal to the number of channels. For a stereo stream a frame is 2
+samples, a mono frame is 1 sample, a 5.1 surround sound frame is 6 samples, etc. The terms "frame"
+and "PCM frame" are the same thing in miniaudio. Note that this is different to a compressed frame.
+If ever miniaudio needs to refer to a compressed frame, such as a FLAC frame, it will always
+clarify what it's referring to with something like "FLAC frame".
3.3. Channel
------------
-A stream of monaural audio that is emitted from an individual speaker in a speaker system, or received from an individual microphone in a microphone system. A
-stereo stream has two channels (a left channel, and a right channel), a 5.1 surround sound system has 6 channels, etc. Some audio systems refer to a channel as
-a complex audio stream that's mixed with other channels to produce the final mix - this is completely different to miniaudio's use of the term "channel" and
-should not be confused.
+A stream of monaural audio that is emitted from an individual speaker in a speaker system, or
+received from an individual microphone in a microphone system. A stereo stream has two channels (a
+left channel, and a right channel), a 5.1 surround sound system has 6 channels, etc. Some audio
+systems refer to a channel as a complex audio stream that's mixed with other channels to produce
+the final mix - this is completely different to miniaudio's use of the term "channel" and should
+not be confused.
3.4. Sample Rate
----------------
-The sample rate in miniaudio is always expressed in Hz, such as 44100, 48000, etc. It's the number of PCM frames that are processed per second.
+The sample rate in miniaudio is always expressed in Hz, such as 44100, 48000, etc. It's the number
+of PCM frames that are processed per second.
3.5. Formats
------------
@@ -461,10 +716,1685 @@ All formats are native-endian.
-4. Decoding
+4. Data Sources
+===============
+The data source abstraction in miniaudio is used for retrieving audio data from some source. A few
+examples include `ma_decoder`, `ma_noise` and `ma_waveform`. You will need to be familiar with data
+sources in order to make sense of some of the higher level concepts in miniaudio.
+
+The `ma_data_source` API is a generic interface for reading from a data source. Any object that
+implements the data source interface can be plugged into any `ma_data_source` function.
+
+To read data from a data source:
+
+ ```c
+ ma_result result;
+ ma_uint64 framesRead;
+
+ result = ma_data_source_read_pcm_frames(pDataSource, pFramesOut, frameCount, &framesRead, loop);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to read data from the data source.
+ }
+ ```
+
+If you don't need the number of frames that were successfully read you can pass in `NULL` to the
+`pFramesRead` parameter. If this returns a value less than the number of frames requested it means
+the end of the file has been reached. `MA_AT_END` will be returned only when the number of frames
+read is 0.
+
+When calling any data source function, with the exception of `ma_data_source_init()` and
+`ma_data_source_uninit()`, you can pass in any object that implements a data source. For example,
+you could plug in a decoder like so:
+
+ ```c
+ ma_result result;
+ ma_uint64 framesRead;
+ ma_decoder decoder; // <-- This would be initialized with `ma_decoder_init_*()`.
+
+ result = ma_data_source_read_pcm_frames(&decoder, pFramesOut, frameCount, &framesRead, loop);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to read data from the decoder.
+ }
+ ```
+
+If you want to seek forward you can pass in `NULL` to the `pFramesOut` parameter. Alternatively you
+can use `ma_data_source_seek_pcm_frames()`.
+
+To seek to a specific PCM frame:
+
+ ```c
+ result = ma_data_source_seek_to_pcm_frame(pDataSource, frameIndex);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to seek to PCM frame.
+ }
+ ```
+
+You can retrieve the total length of a data source in PCM frames, but note that some data sources
+may not have the notion of a length, such as noise and waveforms, and others may just not have a
+way of determining the length such as some decoders. To retrieve the length:
+
+ ```c
+ ma_uint64 length;
+
+ result = ma_data_source_get_length_in_pcm_frames(pDataSource, &length);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to retrieve the length.
+ }
+ ```
+
+Care should be taken when retrieving the length of a data source where the underlying decoder is
+pulling data from a data stream with an undefined length, such as internet radio or some kind of
+broadcast. If you do this, `ma_data_source_get_length_in_pcm_frames()` may never return.
+
+The current position of the cursor in PCM frames can also be retrieved:
+
+ ```c
+ ma_uint64 cursor;
+
+ result = ma_data_source_get_cursor_in_pcm_frames(pDataSource, &cursor);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to retrieve the cursor.
+ }
+ ```
+
+You will often need to know the data format that will be returned after reading. This can be
+retrieved like so:
+
+ ```c
+ ma_format format;
+ ma_uint32 channels;
+ ma_uint32 sampleRate;
+ ma_channel channelMap[MA_MAX_CHANNELS];
+
+ result = ma_data_source_get_data_format(pDataSource, &format, &channels, &sampleRate, channelMap, MA_MAX_CHANNELS);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to retrieve data format.
+ }
+ ```
+
+If you do not need a specific data format property, just pass in NULL to the respective parameter.
+
+There may be cases where you want to implement something like a sound bank where you only want to
+read data within a certain range of the underlying data. To do this you can use a range:
+
+ ```c
+ result = ma_data_source_set_range_in_pcm_frames(pDataSource, rangeBegInFrames, rangeEndInFrames);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to set the range.
+ }
+ ```
+
+This is useful if you have a sound bank where many sounds are stored in the same file and you want
+the data source to only play one of those sub-sounds.
+
+Custom loop points can also be used with data sources. By default, data sources will loop after
+they reach the end of the data source, but if you need to loop at a specific location, you can do
+the following:
+
+ ```c
+ result = ma_data_set_loop_point_in_pcm_frames(pDataSource, loopBegInFrames, loopEndInFrames);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to set the loop point.
+ }
+ ```
+
+The loop point is relative to the current range.
+
+It's sometimes useful to chain data sources together so that a seamless transition can be achieved.
+To do this, you can use chaining:
+
+ ```c
+ ma_decoder decoder1;
+ ma_decoder decoder2;
+
+ // ... initialize decoders with ma_decoder_init_*() ...
+
+ result = ma_data_source_set_next(&decoder1, &decoder2);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to set the next data source.
+ }
+
+ result = ma_data_source_read_pcm_frames(&decoder1, pFramesOut, frameCount, pFramesRead, MA_FALSE);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to read from the decoder.
+ }
+ ```
+
+In the example above we're using decoders. When reading from a chain, you always want to read from
+the top level data source in the chain. In the example above, `decoder1` is the top level data
+source in the chain. When `decoder1` reaches the end, `decoder2` will start seamlessly without any
+gaps.
+
+Note that the `loop` parameter is set to false in the example above. When this is set to true, only
+the current data source will be looped. You can loop the entire chain by linking in a loop like so:
+
+ ```c
+ ma_data_source_set_next(&decoder1, &decoder2); // decoder1 -> decoder2
+ ma_data_source_set_next(&decoder2, &decoder1); // decoder2 -> decoder1 (loop back to the start).
+ ```
+
+Note that setting up chaining is not thread safe, so care needs to be taken if you're dynamically
+changing links while the audio thread is in the middle of reading.
+
+Do not use `ma_decoder_seek_to_pcm_frame()` as a means to reuse a data source to play multiple
+instances of the same sound simultaneously. Instead, initialize multiple data sources for each
+instance. This can be extremely inefficient depending on the data source and can result in
+glitching due to subtle changes to the state of internal filters.
+
+
+4.1. Custom Data Sources
+------------------------
+You can implement a custom data source by implementing the functions in `ma_data_source_vtable`.
+Your custom object must have `ma_data_source_base` as it's first member:
+
+ ```c
+ struct my_data_source
+ {
+ ma_data_source_base base;
+ ...
+ };
+ ```
+
+In your initialization routine, you need to call `ma_data_source_init()` in order to set up the
+base object (`ma_data_source_base`):
+
+ ```c
+ static ma_result my_data_source_read(ma_data_source* pDataSource, void* pFramesOut, ma_uint64 frameCount, ma_uint64* pFramesRead)
+ {
+ // Read data here. Output in the same format returned by my_data_source_get_data_format().
+ }
+
+ static ma_result my_data_source_seek(ma_data_source* pDataSource, ma_uint64 frameIndex)
+ {
+ // Seek to a specific PCM frame here. Return MA_NOT_IMPLEMENTED if seeking is not supported.
+ }
+
+ static ma_result my_data_source_get_data_format(ma_data_source* pDataSource, ma_format* pFormat, ma_uint32* pChannels, ma_uint32* pSampleRate, ma_channel* pChannelMap, size_t channelMapCap)
+ {
+ // Return the format of the data here.
+ }
+
+ static ma_result my_data_source_get_cursor(ma_data_source* pDataSource, ma_uint64* pCursor)
+ {
+ // Retrieve the current position of the cursor here. Return MA_NOT_IMPLEMENTED and set *pCursor to 0 if there is no notion of a cursor.
+ }
+
+ static ma_result my_data_source_get_length(ma_data_source* pDataSource, ma_uint64* pLength)
+ {
+ // Retrieve the length in PCM frames here. Return MA_NOT_IMPLEMENTED and set *pLength to 0 if there is no notion of a length or if the length is unknown.
+ }
+
+ static g_my_data_source_vtable =
+ {
+ my_data_source_read,
+ my_data_source_seek,
+ my_data_source_get_data_format,
+ my_data_source_get_cursor,
+ my_data_source_get_length
+ };
+
+ ma_result my_data_source_init(my_data_source* pMyDataSource)
+ {
+ ma_result result;
+ ma_data_source_config baseConfig;
+
+ baseConfig = ma_data_source_config_init();
+ baseConfig.vtable = &g_my_data_source_vtable;
+
+ result = ma_data_source_init(&baseConfig, &pMyDataSource->base);
+ if (result != MA_SUCCESS) {
+ return result;
+ }
+
+ // ... do the initialization of your custom data source here ...
+
+ return MA_SUCCESS;
+ }
+
+ void my_data_source_uninit(my_data_source* pMyDataSource)
+ {
+ // ... do the uninitialization of your custom data source here ...
+
+ // You must uninitialize the base data source.
+ ma_data_source_uninit(&pMyDataSource->base);
+ }
+ ```
+
+Note that `ma_data_source_init()` and `ma_data_source_uninit()` are never called directly outside
+of the custom data source. It's up to the custom data source itself to call these within their own
+init/uninit functions.
+
+
+
+5. Engine
+=========
+The `ma_engine` API is a high level API for managing and mixing sounds and effect processing. The
+`ma_engine` object encapsulates a resource manager and a node graph, both of which will be
+explained in more detail later.
+
+Sounds are called `ma_sound` and are created from an engine. Sounds can be associated with a mixing
+group called `ma_sound_group` which are also created from the engine. Both `ma_sound` and
+`ma_sound_group` objects are nodes within the engine's node graph.
+
+When the engine is initialized, it will normally create a device internally. If you would rather
+manage the device yourself, you can do so and just pass a pointer to it via the engine config when
+you initialize the engine. You can also just use the engine without a device, which again can be
+configured via the engine config.
+
+The most basic way to initialize the engine is with a default config, like so:
+
+ ```c
+ ma_result result;
+ ma_engine engine;
+
+ result = ma_engine_init(NULL, &engine);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to initialize the engine.
+ }
+ ```
+
+This will result in the engine initializing a playback device using the operating system's default
+device. This will be sufficient for many use cases, but if you need more flexibility you'll want to
+configure the engine with an engine config:
+
+ ```c
+ ma_result result;
+ ma_engine engine;
+ ma_engine_config engineConfig;
+
+ engineConfig = ma_engine_config_init();
+ engineConfig.pPlaybackDevice = &myDevice;
+
+ result = ma_engine_init(&engineConfig, &engine);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to initialize the engine.
+ }
+ ```
+
+In the example above we're passing in a pre-initialized device. Since the caller is the one in
+control of the device's data callback, it's their responsibility to manually call
+`ma_engine_read_pcm_frames()` from inside their data callback:
+
+ ```c
+ void playback_data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
+ {
+ ma_engine_read_pcm_frames(&g_Engine, pOutput, frameCount, NULL);
+ }
+ ```
+
+You can also use the engine independent of a device entirely:
+
+ ```c
+ ma_result result;
+ ma_engine engine;
+ ma_engine_config engineConfig;
+
+ engineConfig = ma_engine_config_init();
+ engineConfig.noDevice = MA_TRUE;
+ engineConfig.channels = 2; // Must be set when not using a device.
+ engineConfig.sampleRate = 48000; // Must be set when not using a device.
+
+ result = ma_engine_init(&engineConfig, &engine);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to initialize the engine.
+ }
+ ```
+
+Note that when you're not using a device, you must set the channel count and sample rate in the
+config or else miniaudio won't know what to use (miniaudio will use the device to determine this
+normally). When not using a device, you need to use `ma_engine_read_pcm_frames()` to process audio
+data from the engine. This kind of setup is useful if you want to do something like offline
+processing.
+
+When a sound is loaded it goes through a resource manager. By default the engine will initialize a
+resource manager internally, but you can also specify a pre-initialized resource manager:
+
+ ```c
+ ma_result result;
+ ma_engine engine1;
+ ma_engine engine2;
+ ma_engine_config engineConfig;
+
+ engineConfig = ma_engine_config_init();
+ engineConfig.pResourceManager = &myResourceManager;
+
+ ma_engine_init(&engineConfig, &engine1);
+ ma_engine_init(&engineConfig, &engine2);
+ ```
+
+In this example we are initializing two engines, both of which are sharing the same resource
+manager. This is especially useful for saving memory when loading the same file across multiple
+engines. If you were not to use a shared resource manager, each engine instance would use their own
+which would result in any sounds that are used between both engine's being loaded twice. By using
+a shared resource manager, it would only be loaded once. Using multiple engine's is useful when you
+need to output to multiple playback devices, such as in a local multiplayer game where each player
+is using their own set of headphones.
+
+By default an engine will be in a started state. To make it so the engine is not automatically
+started you can configure it as such:
+
+ ```c
+ engineConfig.noAutoStart = MA_TRUE;
+
+ // The engine will need to be started manually.
+ ma_engine_start(&engine);
+
+ // Later on the engine can be stopped with ma_engine_stop().
+ ma_engine_stop(&engine);
+ ```
+
+The concept of starting or stopping an engine is only relevant when using the engine with a
+device. Attempting to start or stop an engine that is not associated with a device will result in
+`MA_INVALID_OPERATION`.
+
+The master volume of the engine can be controlled with `ma_engine_set_volume()` which takes a
+linear scale, with 0 resulting in silence and anything above 1 resulting in amplification. If you
+prefer decibel based volume control, use `ma_volume_db_to_linear()` to convert from dB to linear.
+
+When a sound is spatialized, it is done so relative to a listener. An engine can be configured to
+have multiple listeners which can be configured via the config:
+
+ ```c
+ engineConfig.listenerCount = 2;
+ ```
+
+The maximum number of listeners is restricted to `MA_ENGINE_MAX_LISTENERS`. By default, when a
+sound is spatialized, it will be done so relative to the closest listener. You can also pin a sound
+to a specific listener which will be explained later. Listener's have a position, direction, cone,
+and velocity (for doppler effect). A listener is referenced by an index, the meaning of which is up
+to the caller (the index is 0 based and cannot go beyond the listener count, minus 1). The
+position, direction and velocity are all specified in absolute terms:
+
+ ```c
+ ma_engine_listener_set_position(&engine, listenerIndex, worldPosX, worldPosY, worldPosZ);
+ ```
+
+The direction of the listener represents it's forward vector. The listener's up vector can also be
+specified and defaults to +1 on the Y axis.
+
+ ```c
+ ma_engine_listener_set_direction(&engine, listenerIndex, forwardX, forwardY, forwardZ);
+ ma_engine_listener_set_world_up(&engine, listenerIndex, 0, 1, 0);
+ ```
+
+The engine supports directional attenuation. The listener can have a cone the controls how sound is
+attenuated based on the listener's direction. When a sound is between the inner and outer cones, it
+will be attenuated between 1 and the cone's outer gain:
+
+ ```c
+ ma_engine_listener_set_cone(&engine, listenerIndex, innerAngleInRadians, outerAngleInRadians, outerGain);
+ ```
+
+When a sound is inside the inner code, no directional attenuation is applied. When the sound is
+outside of the outer cone, the attenuation will be set to `outerGain` in the example above. When
+the sound is in between the inner and outer cones, the attenuation will be interpolated between 1
+and the outer gain.
+
+The engine's coordinate system follows the OpenGL coordinate system where positive X points right,
+positive Y points up and negative Z points forward.
+
+The simplest and least flexible way to play a sound is like so:
+
+ ```c
+ ma_engine_play_sound(&engine, "my_sound.wav", pGroup);
+ ```
+
+This is a "fire and forget" style of function. The engine will manage the `ma_sound` object
+internally. When the sound finishes playing, it'll be put up for recycling. For more flexibility
+you'll want to initialize a sound object:
+
+ ```c
+ ma_sound sound;
+
+ result = ma_sound_init_from_file(&engine, "my_sound.wav", flags, pGroup, NULL, &sound);
+ if (result != MA_SUCCESS) {
+ return result; // Failed to load sound.
+ }
+ ```
+
+Sounds need to be uninitialized with `ma_sound_uninit()`.
+
+The example above loads a sound from a file. If the resource manager has been disabled you will not
+be able to use this function and instead you'll need to initialize a sound directly from a data
+source:
+
+ ```c
+ ma_sound sound;
+
+ result = ma_sound_init_from_data_source(&engine, &dataSource, flags, pGroup, &sound);
+ if (result != MA_SUCCESS) {
+ return result;
+ }
+ ```
+
+Each `ma_sound` object represents a single instance of the sound. If you want to play the same
+sound multiple times at the same time, you need to initialize a separate `ma_sound` object.
+
+For the most flexibility when initializing sounds, use `ma_sound_init_ex()`. This uses miniaudio's
+standard config/init pattern:
+
+ ```c
+ ma_sound sound;
+ ma_sound_config soundConfig;
+
+ soundConfig = ma_sound_config_init();
+ soundConfig.pFilePath = NULL; // Set this to load from a file path.
+ soundConfig.pDataSource = NULL; // Set this to initialize from an existing data source.
+ soundConfig.pInitialAttachment = &someNodeInTheNodeGraph;
+ soundConfig.initialAttachmentInputBusIndex = 0;
+ soundConfig.channelsIn = 1;
+ soundConfig.channelsOut = 0; // Set to 0 to use the engine's native channel count.
+
+ result = ma_sound_init_ex(&soundConfig, &sound);
+ if (result != MA_SUCCESS) {
+ return result;
+ }
+ ```
+
+In the example above, the sound is being initialized without a file nor a data source. This is
+valid, in which case the sound acts as a node in the middle of the node graph. This means you can
+connect other sounds to this sound and allow it to act like a sound group. Indeed, this is exactly
+what a `ma_sound_group` is.
+
+When loading a sound, you specify a set of flags that control how the sound is loaded and what
+features are enabled for that sound. When no flags are set, the sound will be fully loaded into
+memory in exactly the same format as how it's stored on the file system. The resource manager will
+allocate a block of memory and then load the file directly into it. When reading audio data, it
+will be decoded dynamically on the fly. In order to save processing time on the audio thread, it
+might be beneficial to pre-decode the sound. You can do this with the `MA_SOUND_FLAG_DECODE` flag:
+
+ ```c
+ ma_sound_init_from_file(&engine, "my_sound.wav", MA_SOUND_FLAG_DECODE, pGroup, NULL, &sound);
+ ```
+
+By default, sounds will be loaded synchronously, meaning `ma_sound_init_*()` will not return until
+the sound has been fully loaded. If this is prohibitive you can instead load sounds asynchronously
+by specificying the `MA_SOUND_FLAG_ASYNC` flag:
+
+ ```c
+ ma_sound_init_from_file(&engine, "my_sound.wav", MA_SOUND_FLAG_DECODE | MA_SOUND_FLAG_ASYNC, pGroup, NULL, &sound);
+ ```
+
+This will result in `ma_sound_init_*()` returning quickly, but the sound won't yet have been fully
+loaded. When you start the sound, it won't output anything until some sound is available. The sound
+will start outputting audio before the sound has been fully decoded when the `MA_SOUND_FLAG_DECODE`
+is specified.
+
+If you need to wait for an asynchronously loaded sound to be fully loaded, you can use a fence. A
+fence in miniaudio is a simple synchronization mechanism which simply blocks until it's internal
+counter hit's zero. You can specify a fence like so:
+
+ ```c
+ ma_result result;
+ ma_fence fence;
+ ma_sound sounds[4];
+
+ result = ma_fence_init(&fence);
+ if (result != MA_SUCCES) {
+ return result;
+ }
+
+ // Load some sounds asynchronously.
+ for (int iSound = 0; iSound < 4; iSound += 1) {
+ ma_sound_init_from_file(&engine, mySoundFilesPaths[iSound], MA_SOUND_FLAG_DECODE | MA_SOUND_FLAG_ASYNC, pGroup, &fence, &sounds[iSound]);
+ }
+
+ // ... do some other stuff here in the mean time ...
+
+ // Wait for all sounds to finish loading.
+ ma_fence_wait(&fence);
+ ```
+
+If loading the entire sound into memory is prohibitive, you can also configure the engine to stream
+the audio data:
+
+ ```c
+ ma_sound_init_from_file(&engine, "my_sound.wav", MA_SOUND_FLAG_STREAM, pGroup, NULL, &sound);
+ ```
+
+When streaming sounds, 2 seconds worth of audio data is stored in memory. Although it should work
+fine, it's inefficient to use streaming for short sounds. Streaming is useful for things like music
+tracks in games.
+
+When you initialize a sound, if you specify a sound group the sound will be attached to that group
+automatically. If you set it to NULL, it will be automatically attached to the engine's endpoint.
+If you would instead rather leave the sound unattached by default, you can can specify the
+`MA_SOUND_FLAG_NO_DEFAULT_ATTACHMENT` flag. This is useful if you want to set up a complex node
+graph.
+
+Sounds are not started by default. To start a sound, use `ma_sound_start()`. Stop a sound with
+`ma_sound_stop()`.
+
+Sounds can have their volume controlled with `ma_sound_set_volume()` in the same way as the
+engine's master volume.
+
+Sounds support stereo panning and pitching. Set the pan with `ma_sound_set_pan()`. Setting the pan
+to 0 will result in an unpanned sound. Setting it to -1 will shift everything to the left, whereas
++1 will shift it to the right. The pitch can be controlled with `ma_sound_set_pitch()`. A larger
+value will result in a higher pitch. The pitch must be greater than 0.
+
+The engine supports 3D spatialization of sounds. By default sounds will have spatialization
+enabled, but if a sound does not need to be spatialized it's best to disable it. There are two ways
+to disable spatialization of a sound:
+
+ ```c
+ // Disable spatialization at initialization time via a flag:
+ ma_sound_init_from_file(&engine, "my_sound.wav", MA_SOUND_FLAG_NO_SPATIALIZATION, NULL, NULL, &sound);
+
+ // Dynamically disable or enable spatialization post-initialization:
+ ma_sound_set_spatialization_enabled(&sound, isSpatializationEnabled);
+ ```
+
+By default sounds will be spatialized based on the closest listener. If a sound should always be
+spatialized relative to a specific listener it can be pinned to one:
+
+ ```c
+ ma_sound_set_pinned_listener_index(&sound, listenerIndex);
+ ```
+
+Like listeners, sounds have a position. By default, the position of a sound is in absolute space,
+but it can be changed to be relative to a listener:
+
+ ```c
+ ma_sound_set_positioning(&sound, ma_positioning_relative);
+ ```
+
+Note that relative positioning of a sound only makes sense if there is either only one listener, or
+the sound is pinned to a specific listener. To set the position of a sound:
+
+ ```c
+ ma_sound_set_position(&sound, posX, posY, posZ);
+ ```
+
+The direction works the same way as a listener and represents the sound's forward direction:
+
+ ```c
+ ma_sound_set_direction(&sound, forwardX, forwardY, forwardZ);
+ ```
+
+Sound's also have a cone for controlling directional attenuation. This works exactly the same as
+listeners:
+
+ ```c
+ ma_sound_set_cone(&sound, innerAngleInRadians, outerAngleInRadians, outerGain);
+ ```
+
+The velocity of a sound is used for doppler effect and can be set as such:
+
+ ```c
+ ma_sound_set_velocity(&sound, velocityX, velocityY, velocityZ);
+ ```
+
+The engine supports different attenuation models which can be configured on a per-sound basis. By
+default the attenuation model is set to `ma_attenuation_model_inverse` which is the equivalent to
+OpenAL's `AL_INVERSE_DISTANCE_CLAMPED`. Configure the attenuation model like so:
+
+ ```c
+ ma_sound_set_attenuation_model(&sound, ma_attenuation_model_inverse);
+ ```
+
+The supported attenuation models include the following:
+
+ +----------------------------------+----------------------------------------------+
+ | ma_attenuation_model_none | No distance attenuation. |
+ +----------------------------------+----------------------------------------------+
+ | ma_attenuation_model_inverse | Equivalent to `AL_INVERSE_DISTANCE_CLAMPED`. |
+ +----------------------------------+----------------------------------------------+
+ | ma_attenuation_model_linear | Linear attenuation. |
+ +----------------------------------+----------------------------------------------+
+ | ma_attenuation_model_exponential | Exponential attenuation. |
+ +----------------------------------+----------------------------------------------+
+
+To control how quickly a sound rolls off as it moves away from the listener, you need to configure
+the rolloff:
+
+ ```c
+ ma_sound_set_rolloff(&sound, rolloff);
+ ```
+
+You can control the minimum and maximum gain to apply from spatialization:
+
+ ```c
+ ma_sound_set_min_gain(&sound, minGain);
+ ma_sound_set_max_gain(&sound, maxGain);
+ ```
+
+Likewise, in the calculation of attenuation, you can control the minimum and maximum distances for
+the attenuation calculation. This is useful if you want to ensure sounds don't drop below a certain
+volume after the listener moves further away and to have sounds play a maximum volume when the
+listener is within a certain distance:
+
+ ```c
+ ma_sound_set_min_distance(&sound, minDistance);
+ ma_sound_set_max_distance(&sound, maxDistance);
+ ```
+
+The engine's spatialization system supports doppler effect. The doppler factor can be configure on
+a per-sound basis like so:
+
+ ```c
+ ma_sound_set_doppler_factor(&sound, dopplerFactor);
+ ```
+
+You can fade sounds in and out with `ma_sound_set_fade_in_pcm_frames()` and
+`ma_sound_set_fade_in_milliseconds()`. Set the volume to -1 to use the current volume as the
+starting volume:
+
+ ```c
+ // Fade in over 1 second.
+ ma_sound_set_fade_in_milliseconds(&sound, 0, 1, 1000);
+
+ // ... sometime later ...
+
+ // Fade out over 1 second, starting from the current volume.
+ ma_sound_set_fade_in_milliseconds(&sound, -1, 0, 1000);
+ ```
+
+By default sounds will start immediately, but sometimes for timing and synchronization purposes it
+can be useful to schedule a sound to start or stop:
+
+ ```c
+ // Start the sound in 1 second from now.
+ ma_sound_set_start_time_in_pcm_frames(&sound, ma_engine_get_time(&engine) + (ma_engine_get_sample_rate(&engine) * 1));
+
+ // Stop the sound in 2 seconds from now.
+ ma_sound_set_stop_time_in_pcm_frames(&sound, ma_engine_get_time(&engine) + (ma_engine_get_sample_rate(&engine) * 2));
+ ```
+
+Note that scheduling a start time still requires an explicit call to `ma_sound_start()` before
+anything will play.
+
+The time is specified in global time which is controlled by the engine. You can get the engine's
+current time with `ma_engine_get_time()`. The engine's global time is incremented automatically as
+audio data is read, but it can be reset with `ma_engine_set_time()` in case it needs to be
+resynchronized for some reason.
+
+To determine whether or not a sound is currently playing, use `ma_sound_is_playing()`. This will
+take the scheduled start and stop times into account.
+
+Whether or not a sound should loop can be controlled with `ma_sound_set_looping()`. Sounds will not
+be looping by default. Use `ma_sound_is_looping()` to determine whether or not a sound is looping.
+
+Use `ma_sound_at_end()` to determine whether or not a sound is currently at the end. For a looping
+sound this should never return true.
+
+Internally a sound wraps around a data source. Some APIs exist to control the underlying data
+source, mainly for convenience:
+
+ ```c
+ ma_sound_seek_to_pcm_frame(&sound, frameIndex);
+ ma_sound_get_data_format(&sound, &format, &channels, &sampleRate, pChannelMap, channelMapCapacity);
+ ma_sound_get_cursor_in_pcm_frames(&sound, &cursor);
+ ma_sound_get_length_in_pcm_frames(&sound, &length);
+ ```
+
+Sound groups have the same API as sounds, only they are called `ma_sound_group`, and since they do
+not have any notion of a data source, anything relating to a data source is unavailable.
+
+Internally, sound data is loaded via the `ma_decoder` API which means by default in only supports
+file formats that have built-in support in miniaudio. You can extend this to support any kind of
+file format through the use of custom decoders. To do this you'll need to use a self-managed
+resource manager and configure it appropriately. See the "Resource Management" section below for
+details on how to set this up.
+
+
+6. Resource Management
+======================
+Many programs will want to manage sound resources for things such as reference counting and
+streaming. This is supported by miniaudio via the `ma_resource_manager` API.
+
+The resource manager is mainly responsible for the following:
+
+ * Loading of sound files into memory with reference counting.
+ * Streaming of sound data
+
+When loading a sound file, the resource manager will give you back a `ma_data_source` compatible
+object called `ma_resource_manager_data_source`. This object can be passed into any
+`ma_data_source` API which is how you can read and seek audio data. When loading a sound file, you
+specify whether or not you want the sound to be fully loaded into memory (and optionally
+pre-decoded) or streamed. When loading into memory, you can also specify whether or not you want
+the data to be loaded asynchronously.
+
+The example below is how you can initialize a resource manager using it's default configuration:
+
+ ```c
+ ma_resource_manager_config config;
+ ma_resource_manager resourceManager;
+
+ config = ma_resource_manager_config_init();
+ result = ma_resource_manager_init(&config, &resourceManager);
+ if (result != MA_SUCCESS) {
+ ma_device_uninit(&device);
+ printf("Failed to initialize the resource manager.");
+ return -1;
+ }
+ ```
+
+You can configure the format, channels and sample rate of the decoded audio data. By default it
+will use the file's native data format, but you can configure it to use a consistent format. This
+is useful for offloading the cost of data conversion to load time rather than dynamically
+converting at mixing time. To do this, you configure the decoded format, channels and sample rate
+like the code below:
+
+ ```c
+ config = ma_resource_manager_config_init();
+ config.decodedFormat = device.playback.format;
+ config.decodedChannels = device.playback.channels;
+ config.decodedSampleRate = device.sampleRate;
+ ```
+
+In the code above, the resource manager will be configured so that any decoded audio data will be
+pre-converted at load time to the device's native data format. If instead you used defaults and
+the data format of the file did not match the device's data format, you would need to convert the
+data at mixing time which may be prohibitive in high-performance and large scale scenarios like
+games.
+
+Internally the resource manager uses the `ma_decoder` API to load sounds. This means by default it
+only supports decoders that are built into miniaudio. It's possible to support additional encoding
+formats through the use of custom decoders. To do so, pass in your `ma_decoding_backend_vtable`
+vtables into the resource manager config:
+
+ ```c
+ ma_decoding_backend_vtable* pCustomBackendVTables[] =
+ {
+ &g_ma_decoding_backend_vtable_libvorbis,
+ &g_ma_decoding_backend_vtable_libopus
+ };
+
+ ...
+
+ resourceManagerConfig.ppCustomDecodingBackendVTables = pCustomBackendVTables;
+ resourceManagerConfig.customDecodingBackendCount = sizeof(pCustomBackendVTables) / sizeof(pCustomBackendVTables[0]);
+ resourceManagerConfig.pCustomDecodingBackendUserData = NULL;
+ ```
+
+This system can allow you to support any kind of file format. See the "Decoding" section for
+details on how to implement custom decoders. The miniaudio repository includes examples for Opus
+via libopus and libopusfile and Vorbis via libvorbis and libvorbisfile.
+
+Asynchronicity is achieved via a job system. When an operation needs to be performed, such as the
+decoding of a page, a job will be posted to a queue which will then be processed by a job thread.
+By default there will be only one job thread running, but this can be configured, like so:
+
+ ```c
+ config = ma_resource_manager_config_init();
+ config.jobThreadCount = MY_JOB_THREAD_COUNT;
+ ```
+
+By default job threads are managed internally by the resource manager, however you can also self
+manage your job threads if, for example, you want to integrate the job processing into your
+existing job infrastructure, or if you simply don't like the way the resource manager does it. To
+do this, just set the job thread count to 0 and process jobs manually. To process jobs, you first
+need to retrieve a job using `ma_resource_manager_next_job()` and then process it using
+`ma_job_process()`:
+
+ ```c
+ config = ma_resource_manager_config_init();
+ config.jobThreadCount = 0; // Don't manage any job threads internally.
+ config.flags = MA_RESOURCE_MANAGER_FLAG_NON_BLOCKING; // Optional. Makes `ma_resource_manager_next_job()` non-blocking.
+
+ // ... Initialize your custom job threads ...
+
+ void my_custom_job_thread(...)
+ {
+ for (;;) {
+ ma_job job;
+ ma_result result = ma_resource_manager_next_job(pMyResourceManager, &job);
+ if (result != MA_SUCCESS) {
+ if (result == MA_NOT_DATA_AVAILABLE) {
+ // No jobs are available. Keep going. Will only get this if the resource manager was initialized
+ // with MA_RESOURCE_MANAGER_FLAG_NON_BLOCKING.
+ continue;
+ } else if (result == MA_CANCELLED) {
+ // MA_JOB_TYPE_QUIT was posted. Exit.
+ break;
+ } else {
+ // Some other error occurred.
+ break;
+ }
+ }
+
+ ma_job_process(&job);
+ }
+ }
+ ```
+
+In the example above, the `MA_JOB_TYPE_QUIT` event is the used as the termination
+indicator, but you can use whatever you would like to terminate the thread. The call to
+`ma_resource_manager_next_job()` is blocking by default, but can be configured to be non-blocking
+by initializing the resource manager with the `MA_RESOURCE_MANAGER_FLAG_NON_BLOCKING` configuration
+flag. Note that the `MA_JOB_TYPE_QUIT` will never be removed from the job queue. This
+is to give every thread the opportunity to catch the event and terminate naturally.
+
+When loading a file, it's sometimes convenient to be able to customize how files are opened and
+read instead of using standard `fopen()`, `fclose()`, etc. which is what miniaudio will use by
+default. This can be done by setting `pVFS` member of the resource manager's config:
+
+ ```c
+ // Initialize your custom VFS object. See documentation for VFS for information on how to do this.
+ my_custom_vfs vfs = my_custom_vfs_init();
+
+ config = ma_resource_manager_config_init();
+ config.pVFS = &vfs;
+ ```
+
+This is particularly useful in programs like games where you want to read straight from an archive
+rather than the normal file system. If you do not specify a custom VFS, the resource manager will
+use the operating system's normal file operations. This is default.
+
+To load a sound file and create a data source, call `ma_resource_manager_data_source_init()`. When
+loading a sound you need to specify the file path and options for how the sounds should be loaded.
+By default a sound will be loaded synchronously. The returned data source is owned by the caller
+which means the caller is responsible for the allocation and freeing of the data source. Below is
+an example for initializing a data source:
+
+ ```c
+ ma_resource_manager_data_source dataSource;
+ ma_result result = ma_resource_manager_data_source_init(pResourceManager, pFilePath, flags, &dataSource);
+ if (result != MA_SUCCESS) {
+ // Error.
+ }
+
+ // ...
+
+ // A ma_resource_manager_data_source object is compatible with the `ma_data_source` API. To read data, just call
+ // the `ma_data_source_read_pcm_frames()` like you would with any normal data source.
+ result = ma_data_source_read_pcm_frames(&dataSource, pDecodedData, frameCount, &framesRead);
+ if (result != MA_SUCCESS) {
+ // Failed to read PCM frames.
+ }
+
+ // ...
+
+ ma_resource_manager_data_source_uninit(pResourceManager, &dataSource);
+ ```
+
+The `flags` parameter specifies how you want to perform loading of the sound file. It can be a
+combination of the following flags:
+
+ ```
+ MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM
+ MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_DECODE
+ MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_ASYNC
+ MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_WAIT_INIT
+ ```
+
+When no flags are specified (set to 0), the sound will be fully loaded into memory, but not
+decoded, meaning the raw file data will be stored in memory, and then dynamically decoded when
+`ma_data_source_read_pcm_frames()` is called. To instead decode the audio data before storing it in
+memory, use the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_DECODE` flag. By default, the sound file will
+be loaded synchronously, meaning `ma_resource_manager_data_source_init()` will only return after
+the entire file has been loaded. This is good for simplicity, but can be prohibitively slow. You
+can instead load the sound asynchronously using the `MA_RESOURCE_MANAGER_DATA_SOURCE_ASYNC` flag.
+This will result in `ma_resource_manager_data_source_init()` returning quickly, but no data will be
+returned by `ma_data_source_read_pcm_frames()` until some data is available. When no data is
+available because the asynchronous decoding hasn't caught up, `MA_BUSY` will be returned by
+`ma_data_source_read_pcm_frames()`.
+
+For large sounds, it's often prohibitive to store the entire file in memory. To mitigate this, you
+can instead stream audio data which you can do by specifying the
+`MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM` flag. When streaming, data will be decoded in 1
+second pages. When a new page needs to be decoded, a job will be posted to the job queue and then
+subsequently processed in a job thread.
+
+For in-memory sounds, reference counting is used to ensure the data is loaded only once. This means
+multiple calls to `ma_resource_manager_data_source_init()` with the same file path will result in
+the file data only being loaded once. Each call to `ma_resource_manager_data_source_init()` must be
+matched up with a call to `ma_resource_manager_data_source_uninit()`. Sometimes it can be useful
+for a program to register self-managed raw audio data and associate it with a file path. Use the
+`ma_resource_manager_register_*()` and `ma_resource_manager_unregister_*()` APIs to do this.
+`ma_resource_manager_register_decoded_data()` is used to associate a pointer to raw, self-managed
+decoded audio data in the specified data format with the specified name. Likewise,
+`ma_resource_manager_register_encoded_data()` is used to associate a pointer to raw self-managed
+encoded audio data (the raw file data) with the specified name. Note that these names need not be
+actual file paths. When `ma_resource_manager_data_source_init()` is called (without the
+`MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM` flag), the resource manager will look for these
+explicitly registered data buffers and, if found, will use it as the backing data for the data
+source. Note that the resource manager does *not* make a copy of this data so it is up to the
+caller to ensure the pointer stays valid for it's lifetime. Use
+`ma_resource_manager_unregister_data()` to unregister the self-managed data. You can also use
+`ma_resource_manager_register_file()` and `ma_resource_manager_unregister_file()` to register and
+unregister a file. It does not make sense to use the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM`
+flag with a self-managed data pointer.
+
+
+6.1. Asynchronous Loading and Synchronization
+---------------------------------------------
+When loading asynchronously, it can be useful to poll whether or not loading has finished. Use
+`ma_resource_manager_data_source_result()` to determine this. For in-memory sounds, this will
+return `MA_SUCCESS` when the file has been *entirely* decoded. If the sound is still being decoded,
+`MA_BUSY` will be returned. Otherwise, some other error code will be returned if the sound failed
+to load. For streaming data sources, `MA_SUCCESS` will be returned when the first page has been
+decoded and the sound is ready to be played. If the first page is still being decoded, `MA_BUSY`
+will be returned. Otherwise, some other error code will be returned if the sound failed to load.
+
+In addition to polling, you can also use a simple synchronization object called a "fence" to wait
+for asynchronously loaded sounds to finish. This is called `ma_fence`. The advantage to using a
+fence is that it can be used to wait for a group of sounds to finish loading rather than waiting
+for sounds on an individual basis. There are two stages to loading a sound:
+
+ * Initialization of the internal decoder; and
+ * Completion of decoding of the file (the file is fully decoded)
+
+You can specify separate fences for each of the different stages. Waiting for the initialization
+of the internal decoder is important for when you need to know the sample format, channels and
+sample rate of the file.
+
+The example below shows how you could use a fence when loading a number of sounds:
+
+ ```c
+ // This fence will be released when all sounds are finished loading entirely.
+ ma_fence fence;
+ ma_fence_init(&fence);
+
+ // This will be passed into the initialization routine for each sound.
+ ma_resource_manager_pipeline_notifications notifications = ma_resource_manager_pipeline_notifications_init();
+ notifications.done.pFence = &fence;
+
+ // Now load a bunch of sounds:
+ for (iSound = 0; iSound < soundCount; iSound += 1) {
+ ma_resource_manager_data_source_init(pResourceManager, pSoundFilePaths[iSound], flags, ¬ifications, &pSoundSources[iSound]);
+ }
+
+ // ... DO SOMETHING ELSE WHILE SOUNDS ARE LOADING ...
+
+ // Wait for loading of sounds to finish.
+ ma_fence_wait(&fence);
+ ```
+
+In the example above we used a fence for waiting until the entire file has been fully decoded. If
+you only need to wait for the initialization of the internal decoder to complete, you can use the
+`init` member of the `ma_resource_manager_pipeline_notifications` object:
+
+ ```c
+ notifications.init.pFence = &fence;
+ ```
+
+If a fence is not appropriate for your situation, you can instead use a callback that is fired on
+an individual sound basis. This is done in a very similar way to fences:
+
+ ```c
+ typedef struct
+ {
+ ma_async_notification_callbacks cb;
+ void* pMyData;
+ } my_notification;
+
+ void my_notification_callback(ma_async_notification* pNotification)
+ {
+ my_notification* pMyNotification = (my_notification*)pNotification;
+
+ // Do something in response to the sound finishing loading.
+ }
+
+ ...
+
+ my_notification myCallback;
+ myCallback.cb.onSignal = my_notification_callback;
+ myCallback.pMyData = pMyData;
+
+ ma_resource_manager_pipeline_notifications notifications = ma_resource_manager_pipeline_notifications_init();
+ notifications.done.pNotification = &myCallback;
+
+ ma_resource_manager_data_source_init(pResourceManager, "my_sound.wav", flags, ¬ifications, &mySound);
+ ```
+
+In the example above we just extend the `ma_async_notification_callbacks` object and pass an
+instantiation into the `ma_resource_manager_pipeline_notifications` in the same way as we did with
+the fence, only we set `pNotification` instead of `pFence`. You can set both of these at the same
+time and they should both work as expected. If using the `pNotification` system, you need to ensure
+your `ma_async_notification_callbacks` object stays valid.
+
+
+
+6.2. Resource Manager Implementation Details
+--------------------------------------------
+Resources are managed in two main ways:
+
+ * By storing the entire sound inside an in-memory buffer (referred to as a data buffer)
+ * By streaming audio data on the fly (referred to as a data stream)
+
+A resource managed data source (`ma_resource_manager_data_source`) encapsulates a data buffer or
+data stream, depending on whether or not the data source was initialized with the
+`MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM` flag. If so, it will make use of a
+`ma_resource_manager_data_stream` object. Otherwise it will use a `ma_resource_manager_data_buffer`
+object. Both of these objects are data sources which means they can be used with any
+`ma_data_source_*()` API.
+
+Another major feature of the resource manager is the ability to asynchronously decode audio files.
+This relieves the audio thread of time-consuming decoding which can negatively affect scalability
+due to the audio thread needing to complete it's work extremely quickly to avoid glitching.
+Asynchronous decoding is achieved through a job system. There is a central multi-producer,
+multi-consumer, fixed-capacity job queue. When some asynchronous work needs to be done, a job is
+posted to the queue which is then read by a job thread. The number of job threads can be
+configured for improved scalability, and job threads can all run in parallel without needing to
+worry about the order of execution (how this is achieved is explained below).
+
+When a sound is being loaded asynchronously, playback can begin before the sound has been fully
+decoded. This enables the application to start playback of the sound quickly, while at the same
+time allowing to resource manager to keep loading in the background. Since there may be less
+threads than the number of sounds being loaded at a given time, a simple scheduling system is used
+to keep decoding time balanced and fair. The resource manager solves this by splitting decoding
+into chunks called pages. By default, each page is 1 second long. When a page has been decoded, a
+new job will be posted to start decoding the next page. By dividing up decoding into pages, an
+individual sound shouldn't ever delay every other sound from having their first page decoded. Of
+course, when loading many sounds at the same time, there will always be an amount of time required
+to process jobs in the queue so in heavy load situations there will still be some delay. To
+determine if a data source is ready to have some frames read, use
+`ma_resource_manager_data_source_get_available_frames()`. This will return the number of frames
+available starting from the current position.
+
+
+6.2.1. Job Queue
+----------------
+The resource manager uses a job queue which is multi-producer, multi-consumer, and fixed-capacity.
+This job queue is not currently lock-free, and instead uses a spinlock to achieve thread-safety.
+Only a fixed number of jobs can be allocated and inserted into the queue which is done through a
+lock-free data structure for allocating an index into a fixed sized array, with reference counting
+for mitigation of the ABA problem. The reference count is 32-bit.
+
+For many types of jobs it's important that they execute in a specific order. In these cases, jobs
+are executed serially. For the resource manager, serial execution of jobs is only required on a
+per-object basis (per data buffer or per data stream). Each of these objects stores an execution
+counter. When a job is posted it is associated with an execution counter. When the job is
+processed, it checks if the execution counter of the job equals the execution counter of the
+owning object and if so, processes the job. If the counters are not equal, the job will be posted
+back onto the job queue for later processing. When the job finishes processing the execution order
+of the main object is incremented. This system means the no matter how many job threads are
+executing, decoding of an individual sound will always get processed serially. The advantage to
+having multiple threads comes into play when loading multiple sounds at the same time.
+
+The resource manager's job queue is not 100% lock-free and will use a spinlock to achieve
+thread-safety for a very small section of code. This is only relevant when the resource manager
+uses more than one job thread. If only using a single job thread, which is the default, the
+lock should never actually wait in practice. The amount of time spent locking should be quite
+short, but it's something to be aware of for those who have pedantic lock-free requirements and
+need to use more than one job thread. There are plans to remove this lock in a future version.
+
+In addition, posting a job will release a semaphore, which on Win32 is implemented with
+`ReleaseSemaphore` and on POSIX platforms via a condition variable:
+
+ ```c
+ pthread_mutex_lock(&pSemaphore->lock);
+ {
+ pSemaphore->value += 1;
+ pthread_cond_signal(&pSemaphore->cond);
+ }
+ pthread_mutex_unlock(&pSemaphore->lock);
+ ```
+
+Again, this is relevant for those with strict lock-free requirements in the audio thread. To avoid
+this, you can use non-blocking mode (via the `MA_JOB_QUEUE_FLAG_NON_BLOCKING`
+flag) and implement your own job processing routine (see the "Resource Manager" section above for
+details on how to do this).
+
+
+
+6.2.2. Data Buffers
+-------------------
+When the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM` flag is excluded at initialization time, the
+resource manager will try to load the data into an in-memory data buffer. Before doing so, however,
+it will first check if the specified file is already loaded. If so, it will increment a reference
+counter and just use the already loaded data. This saves both time and memory. When the data buffer
+is uninitialized, the reference counter will be decremented. If the counter hits zero, the file
+will be unloaded. This is a detail to keep in mind because it could result in excessive loading and
+unloading of a sound. For example, the following sequence will result in a file be loaded twice,
+once after the other:
+
+ ```c
+ ma_resource_manager_data_source_init(pResourceManager, "my_file", ..., &myDataBuffer0); // Refcount = 1. Initial load.
+ ma_resource_manager_data_source_uninit(pResourceManager, &myDataBuffer0); // Refcount = 0. Unloaded.
+
+ ma_resource_manager_data_source_init(pResourceManager, "my_file", ..., &myDataBuffer1); // Refcount = 1. Reloaded because previous uninit() unloaded it.
+ ma_resource_manager_data_source_uninit(pResourceManager, &myDataBuffer1); // Refcount = 0. Unloaded.
+ ```
+
+A binary search tree (BST) is used for storing data buffers as it has good balance between
+efficiency and simplicity. The key of the BST is a 64-bit hash of the file path that was passed
+into `ma_resource_manager_data_source_init()`. The advantage of using a hash is that it saves
+memory over storing the entire path, has faster comparisons, and results in a mostly balanced BST
+due to the random nature of the hash. The disadvantage is that file names are case-sensitive. If
+this is an issue, you should normalize your file names to upper- or lower-case before initializing
+your data sources.
+
+When a sound file has not already been loaded and the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_ASYNC`
+flag is excluded, the file will be decoded synchronously by the calling thread. There are two
+options for controlling how the audio is stored in the data buffer - encoded or decoded. When the
+`MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_DECODE` option is excluded, the raw file data will be stored
+in memory. Otherwise the sound will be decoded before storing it in memory. Synchronous loading is
+a very simple and standard process of simply adding an item to the BST, allocating a block of
+memory and then decoding (if `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_DECODE` is specified).
+
+When the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_ASYNC` flag is specified, loading of the data buffer
+is done asynchronously. In this case, a job is posted to the queue to start loading and then the
+function immediately returns, setting an internal result code to `MA_BUSY`. This result code is
+returned when the program calls `ma_resource_manager_data_source_result()`. When decoding has fully
+completed `MA_SUCCESS` will be returned. This can be used to know if loading has fully completed.
+
+When loading asynchronously, a single job is posted to the queue of the type
+`MA_JOB_TYPE_RESOURCE_MANAGER_LOAD_DATA_BUFFER_NODE`. This involves making a copy of the file path and
+associating it with job. When the job is processed by the job thread, it will first load the file
+using the VFS associated with the resource manager. When using a custom VFS, it's important that it
+be completely thread-safe because it will be used from one or more job threads at the same time.
+Individual files should only ever be accessed by one thread at a time, however. After opening the
+file via the VFS, the job will determine whether or not the file is being decoded. If not, it
+simply allocates a block of memory and loads the raw file contents into it and returns. On the
+other hand, when the file is being decoded, it will first allocate a decoder on the heap and
+initialize it. Then it will check if the length of the file is known. If so it will allocate a
+block of memory to store the decoded output and initialize it to silence. If the size is unknown,
+it will allocate room for one page. After memory has been allocated, the first page will be
+decoded. If the sound is shorter than a page, the result code will be set to `MA_SUCCESS` and the
+completion event will be signalled and loading is now complete. If, however, there is more to
+decode, a job with the code `MA_JOB_TYPE_RESOURCE_MANAGER_PAGE_DATA_BUFFER_NODE` is posted. This job
+will decode the next page and perform the same process if it reaches the end. If there is more to
+decode, the job will post another `MA_JOB_TYPE_RESOURCE_MANAGER_PAGE_DATA_BUFFER_NODE` job which will
+keep on happening until the sound has been fully decoded. For sounds of an unknown length, each
+page will be linked together as a linked list. Internally this is implemented via the
+`ma_paged_audio_buffer` object.
+
+
+6.2.3. Data Streams
+-------------------
+Data streams only ever store two pages worth of data for each instance. They are most useful for
+large sounds like music tracks in games that would consume too much memory if fully decoded in
+memory. After every frame from a page has been read, a job will be posted to load the next page
+which is done from the VFS.
+
+For data streams, the `MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_ASYNC` flag will determine whether or
+not initialization of the data source waits until the two pages have been decoded. When unset,
+`ma_resource_manager_data_source_init()` will wait until the two pages have been loaded, otherwise
+it will return immediately.
+
+When frames are read from a data stream using `ma_resource_manager_data_source_read_pcm_frames()`,
+`MA_BUSY` will be returned if there are no frames available. If there are some frames available,
+but less than the number requested, `MA_SUCCESS` will be returned, but the actual number of frames
+read will be less than the number requested. Due to the asynchronous nature of data streams,
+seeking is also asynchronous. If the data stream is in the middle of a seek, `MA_BUSY` will be
+returned when trying to read frames.
+
+When `ma_resource_manager_data_source_read_pcm_frames()` results in a page getting fully consumed
+a job is posted to load the next page. This will be posted from the same thread that called
+`ma_resource_manager_data_source_read_pcm_frames()`.
+
+Data streams are uninitialized by posting a job to the queue, but the function won't return until
+that job has been processed. The reason for this is that the caller owns the data stream object and
+therefore miniaudio needs to ensure everything completes before handing back control to the caller.
+Also, if the data stream is uninitialized while pages are in the middle of decoding, they must
+complete before destroying any underlying object and the job system handles this cleanly.
+
+Note that when a new page needs to be loaded, a job will be posted to the resource manager's job
+thread from the audio thread. You must keep in mind the details mentioned in the "Job Queue"
+section above regarding locking when posting an event if you require a strictly lock-free audio
+thread.
+
+
+
+7. Node Graph
+=============
+miniaudio's routing infrastructure follows a node graph paradigm. The idea is that you create a
+node whose outputs are attached to inputs of another node, thereby creating a graph. There are
+different types of nodes, with each node in the graph processing input data to produce output,
+which is then fed through the chain. Each node in the graph can apply their own custom effects. At
+the start of the graph will usually be one or more data source nodes which have no inputs, but
+instead pull their data from a data source. At the end of the graph is an endpoint which represents
+the end of the chain and is where the final output is ultimately extracted from.
+
+Each node has a number of input buses and a number of output buses. An output bus from a node is
+attached to an input bus of another. Multiple nodes can connect their output buses to another
+node's input bus, in which case their outputs will be mixed before processing by the node. Below is
+a diagram that illustrates a hypothetical node graph setup:
+
+ ```
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Data flows left to right >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+ +---------------+ +-----------------+
+ | Data Source 1 =----+ +----------+ +----= Low Pass Filter =----+
+ +---------------+ | | =----+ +-----------------+ | +----------+
+ +----= Splitter | +----= ENDPOINT |
+ +---------------+ | | =----+ +-----------------+ | +----------+
+ | Data Source 2 =----+ +----------+ +----= Echo / Delay =----+
+ +---------------+ +-----------------+
+ ```
+
+In the above graph, it starts with two data sources whose outputs are attached to the input of a
+splitter node. It's at this point that the two data sources are mixed. After mixing, the splitter
+performs it's processing routine and produces two outputs which is simply a duplication of the
+input stream. One output is attached to a low pass filter, whereas the other output is attached to
+a echo/delay. The outputs of the the low pass filter and the echo are attached to the endpoint, and
+since they're both connected to the same input but, they'll be mixed.
+
+Each input bus must be configured to accept the same number of channels, but the number of channels
+used by input buses can be different to the number of channels for output buses in which case
+miniaudio will automatically convert the input data to the output channel count before processing.
+The number of channels of an output bus of one node must match the channel count of the input bus
+it's attached to. The channel counts cannot be changed after the node has been initialized. If you
+attempt to attach an output bus to an input bus with a different channel count, attachment will
+fail.
+
+To use a node graph, you first need to initialize a `ma_node_graph` object. This is essentially a
+container around the entire graph. The `ma_node_graph` object is required for some thread-safety
+issues which will be explained later. A `ma_node_graph` object is initialized using miniaudio's
+standard config/init system:
+
+ ```c
+ ma_node_graph_config nodeGraphConfig = ma_node_graph_config_init(myChannelCount);
+
+ result = ma_node_graph_init(&nodeGraphConfig, NULL, &nodeGraph); // Second parameter is a pointer to allocation callbacks.
+ if (result != MA_SUCCESS) {
+ // Failed to initialize node graph.
+ }
+ ```
+
+When you initialize the node graph, you're specifying the channel count of the endpoint. The
+endpoint is a special node which has one input bus and one output bus, both of which have the
+same channel count, which is specified in the config. Any nodes that connect directly to the
+endpoint must be configured such that their output buses have the same channel count. When you read
+audio data from the node graph, it'll have the channel count you specified in the config. To read
+data from the graph:
+
+ ```c
+ ma_uint32 framesRead;
+ result = ma_node_graph_read_pcm_frames(&nodeGraph, pFramesOut, frameCount, &framesRead);
+ if (result != MA_SUCCESS) {
+ // Failed to read data from the node graph.
+ }
+ ```
+
+When you read audio data, miniaudio starts at the node graph's endpoint node which then pulls in
+data from it's input attachments, which in turn recusively pull in data from their inputs, and so
+on. At the start of the graph there will be some kind of data source node which will have zero
+inputs and will instead read directly from a data source. The base nodes don't literally need to
+read from a `ma_data_source` object, but they will always have some kind of underlying object that
+sources some kind of audio. The `ma_data_source_node` node can be used to read from a
+`ma_data_source`. Data is always in floating-point format and in the number of channels you
+specified when the graph was initialized. The sample rate is defined by the underlying data sources.
+It's up to you to ensure they use a consistent and appropraite sample rate.
+
+The `ma_node` API is designed to allow custom nodes to be implemented with relative ease, but
+miniaudio includes a few stock nodes for common functionality. This is how you would initialize a
+node which reads directly from a data source (`ma_data_source_node`) which is an example of one
+of the stock nodes that comes with miniaudio:
+
+ ```c
+ ma_data_source_node_config config = ma_data_source_node_config_init(pMyDataSource);
+
+ ma_data_source_node dataSourceNode;
+ result = ma_data_source_node_init(&nodeGraph, &config, NULL, &dataSourceNode);
+ if (result != MA_SUCCESS) {
+ // Failed to create data source node.
+ }
+ ```
+
+The data source node will use the output channel count to determine the channel count of the output
+bus. There will be 1 output bus and 0 input buses (data will be drawn directly from the data
+source). The data source must output to floating-point (`ma_format_f32`) or else an error will be
+returned from `ma_data_source_node_init()`.
+
+By default the node will not be attached to the graph. To do so, use `ma_node_attach_output_bus()`:
+
+ ```c
+ result = ma_node_attach_output_bus(&dataSourceNode, 0, ma_node_graph_get_endpoint(&nodeGraph), 0);
+ if (result != MA_SUCCESS) {
+ // Failed to attach node.
+ }
+ ```
+
+The code above connects the data source node directly to the endpoint. Since the data source node
+has only a single output bus, the index will always be 0. Likewise, the endpoint only has a single
+input bus which means the input bus index will also always be 0.
+
+To detach a specific output bus, use `ma_node_detach_output_bus()`. To detach all output buses, use
+`ma_node_detach_all_output_buses()`. If you want to just move the output bus from one attachment to
+another, you do not need to detach first. You can just call `ma_node_attach_output_bus()` and it'll
+deal with it for you.
+
+Less frequently you may want to create a specialized node. This will be a node where you implement
+your own processing callback to apply a custom effect of some kind. This is similar to initalizing
+one of the stock node types, only this time you need to specify a pointer to a vtable containing a
+pointer to the processing function and the number of input and output buses. Example:
+
+ ```c
+ static void my_custom_node_process_pcm_frames(ma_node* pNode, const float** ppFramesIn, ma_uint32* pFrameCountIn, float** ppFramesOut, ma_uint32* pFrameCountOut)
+ {
+ // Do some processing of ppFramesIn (one stream of audio data per input bus)
+ const float* pFramesIn_0 = ppFramesIn[0]; // Input bus @ index 0.
+ const float* pFramesIn_1 = ppFramesIn[1]; // Input bus @ index 1.
+ float* pFramesOut_0 = ppFramesOut[0]; // Output bus @ index 0.
+
+ // Do some processing. On input, `pFrameCountIn` will be the number of input frames in each
+ // buffer in `ppFramesIn` and `pFrameCountOut` will be the capacity of each of the buffers
+ // in `ppFramesOut`. On output, `pFrameCountIn` should be set to the number of input frames
+ // your node consumed and `pFrameCountOut` should be set the number of output frames that
+ // were produced.
+ //
+ // You should process as many frames as you can. If your effect consumes input frames at the
+ // same rate as output frames (always the case, unless you're doing resampling), you need
+ // only look at `ppFramesOut` and process that exact number of frames. If you're doing
+ // resampling, you'll need to be sure to set both `pFrameCountIn` and `pFrameCountOut`
+ // properly.
+ }
+
+ static ma_node_vtable my_custom_node_vtable =
+ {
+ my_custom_node_process_pcm_frames, // The function that will be called process your custom node. This is where you'd implement your effect processing.
+ NULL, // Optional. A callback for calculating the number of input frames that are required to process a specified number of output frames.
+ 2, // 2 input buses.
+ 1, // 1 output bus.
+ 0 // Default flags.
+ };
+
+ ...
+
+ // Each bus needs to have a channel count specified. To do this you need to specify the channel
+ // counts in an array and then pass that into the node config.
+ ma_uint32 inputChannels[2]; // Equal in size to the number of input channels specified in the vtable.
+ ma_uint32 outputChannels[1]; // Equal in size to the number of output channels specicied in the vtable.
+
+ inputChannels[0] = channelsIn;
+ inputChannels[1] = channelsIn;
+ outputChannels[0] = channelsOut;
+
+ ma_node_config nodeConfig = ma_node_config_init();
+ nodeConfig.vtable = &my_custom_node_vtable;
+ nodeConfig.pInputChannels = inputChannels;
+ nodeConfig.pOutputChannels = outputChannels;
+
+ ma_node_base node;
+ result = ma_node_init(&nodeGraph, &nodeConfig, NULL, &node);
+ if (result != MA_SUCCESS) {
+ // Failed to initialize node.
+ }
+ ```
+
+When initializing a custom node, as in the code above, you'll normally just place your vtable in
+static space. The number of input and output buses are specified as part of the vtable. If you need
+a variable number of buses on a per-node bases, the vtable should have the relevant bus count set
+to `MA_NODE_BUS_COUNT_UNKNOWN`. In this case, the bus count should be set in the node config:
+
+ ```c
+ static ma_node_vtable my_custom_node_vtable =
+ {
+ my_custom_node_process_pcm_frames, // The function that will be called process your custom node. This is where you'd implement your effect processing.
+ NULL, // Optional. A callback for calculating the number of input frames that are required to process a specified number of output frames.
+ MA_NODE_BUS_COUNT_UNKNOWN, // The number of input buses is determined on a per-node basis.
+ 1, // 1 output bus.
+ 0 // Default flags.
+ };
+
+ ...
+
+ ma_node_config nodeConfig = ma_node_config_init();
+ nodeConfig.vtable = &my_custom_node_vtable;
+ nodeConfig.inputBusCount = myBusCount; // <-- Since the vtable specifies MA_NODE_BUS_COUNT_UNKNOWN, the input bus count should be set here.
+ nodeConfig.pInputChannels = inputChannels; // <-- Make sure there are nodeConfig.inputBusCount elements in this array.
+ nodeConfig.pOutputChannels = outputChannels; // <-- The vtable specifies 1 output bus, so there must be 1 element in this array.
+ ```
+
+In the above example it's important to never set the `inputBusCount` and `outputBusCount` members
+to anything other than their defaults if the vtable specifies an explicit count. They can only be
+set if the vtable specifies MA_NODE_BUS_COUNT_UNKNOWN in the relevant bus count.
+
+Most often you'll want to create a structure to encapsulate your node with some extra data. You
+need to make sure the `ma_node_base` object is your first member of the structure:
+
+ ```c
+ typedef struct
+ {
+ ma_node_base base; // <-- Make sure this is always the first member.
+ float someCustomData;
+ } my_custom_node;
+ ```
+
+By doing this, your object will be compatible with all `ma_node` APIs and you can attach it to the
+graph just like any other node.
+
+In the custom processing callback (`my_custom_node_process_pcm_frames()` in the example above), the
+number of channels for each bus is what was specified by the config when the node was initialized
+with `ma_node_init()`. In addition, all attachments to each of the input buses will have been
+pre-mixed by miniaudio. The config allows you to specify different channel counts for each
+individual input and output bus. It's up to the effect to handle it appropriate, and if it can't,
+return an error in it's initialization routine.
+
+Custom nodes can be assigned some flags to describe their behaviour. These are set via the vtable
+and include the following:
+
+ +-----------------------------------------+---------------------------------------------------+
+ | Flag Name | Description |
+ +-----------------------------------------+---------------------------------------------------+
+ | MA_NODE_FLAG_PASSTHROUGH | Useful for nodes that do not do any kind of audio |
+ | | processing, but are instead used for tracking |
+ | | time, handling events, etc. Also used by the |
+ | | internal endpoint node. It reads directly from |
+ | | the input bus to the output bus. Nodes with this |
+ | | flag must have exactly 1 input bus and 1 output |
+ | | bus, and both buses must have the same channel |
+ | | counts. |
+ +-----------------------------------------+---------------------------------------------------+
+ | MA_NODE_FLAG_CONTINUOUS_PROCESSING | Causes the processing callback to be called even |
+ | | when no data is available to be read from input |
+ | | attachments. This is useful for effects like |
+ | | echos where there will be a tail of audio data |
+ | | that still needs to be processed even when the |
+ | | original data sources have reached their ends. |
+ +-----------------------------------------+---------------------------------------------------+
+ | MA_NODE_FLAG_ALLOW_NULL_INPUT | Used in conjunction with |
+ | | `MA_NODE_FLAG_CONTINUOUS_PROCESSING`. When this |
+ | | is set, the `ppFramesIn` parameter of the |
+ | | processing callback will be set to NULL when |
+ | | there are no input frames are available. When |
+ | | this is unset, silence will be posted to the |
+ | | processing callback. |
+ +-----------------------------------------+---------------------------------------------------+
+ | MA_NODE_FLAG_DIFFERENT_PROCESSING_RATES | Used to tell miniaudio that input and output |
+ | | frames are processed at different rates. You |
+ | | should set this for any nodes that perform |
+ | | resampling. |
+ +-----------------------------------------+---------------------------------------------------+
+ | MA_NODE_FLAG_SILENT_OUTPUT | Used to tell miniaudio that a node produces only |
+ | | silent output. This is useful for nodes where you |
+ | | don't want the output to contribute to the final |
+ | | mix. An example might be if you want split your |
+ | | stream and have one branch be output to a file. |
+ | | When using this flag, you should avoid writing to |
+ | | the output buffer of the node's processing |
+ | | callback because miniaudio will ignore it anyway. |
+ +-----------------------------------------+---------------------------------------------------+
+
+
+If you need to make a copy of an audio stream for effect processing you can use a splitter node
+called `ma_splitter_node`. This takes has 1 input bus and splits the stream into 2 output buses.
+You can use it like this:
+
+ ```c
+ ma_splitter_node_config splitterNodeConfig = ma_splitter_node_config_init(channelsIn, channelsOut);
+
+ ma_splitter_node splitterNode;
+ result = ma_splitter_node_init(&nodeGraph, &splitterNodeConfig, NULL, &splitterNode);
+ if (result != MA_SUCCESS) {
+ // Failed to create node.
+ }
+
+ // Attach your output buses to two different input buses (can be on two different nodes).
+ ma_node_attach_output_bus(&splitterNode, 0, ma_node_graph_get_endpoint(&nodeGraph), 0); // Attach directly to the endpoint.
+ ma_node_attach_output_bus(&splitterNode, 1, &myEffectNode, 0); // Attach to input bus 0 of some effect node.
+ ```
+
+The volume of an output bus can be configured on a per-bus basis:
+
+ ```c
+ ma_node_set_output_bus_volume(&splitterNode, 0, 0.5f);
+ ma_node_set_output_bus_volume(&splitterNode, 1, 0.5f);
+ ```
+
+In the code above we're using the splitter node from before and changing the volume of each of the
+copied streams.
+
+You can start and stop a node with the following:
+
+ ```c
+ ma_node_set_state(&splitterNode, ma_node_state_started); // The default state.
+ ma_node_set_state(&splitterNode, ma_node_state_stopped);
+ ```
+
+By default the node is in a started state, but since it won't be connected to anything won't
+actually be invoked by the node graph until it's connected. When you stop a node, data will not be
+read from any of it's input connections. You can use this property to stop a group of sounds
+atomically.
+
+You can configure the initial state of a node in it's config:
+
+ ```c
+ nodeConfig.initialState = ma_node_state_stopped;
+ ```
+
+Note that for the stock specialized nodes, all of their configs will have a `nodeConfig` member
+which is the config to use with the base node. This is where the initial state can be configured
+for specialized nodes:
+
+ ```c
+ dataSourceNodeConfig.nodeConfig.initialState = ma_node_state_stopped;
+ ```
+
+When using a specialized node like `ma_data_source_node` or `ma_splitter_node`, be sure to not
+modify the `vtable` member of the `nodeConfig` object.
+
+
+7.1. Timing
+-----------
+The node graph supports starting and stopping nodes at scheduled times. This is especially useful
+for data source nodes where you want to get the node set up, but only start playback at a specific
+time. There are two clocks: local and global.
+
+A local clock is per-node, whereas the global clock is per graph. Scheduling starts and stops can
+only be done based on the global clock because the local clock will not be running while the node
+is stopped. The global clocks advances whenever `ma_node_graph_read_pcm_frames()` is called. On the
+other hand, the local clock only advances when the node's processing callback is fired, and is
+advanced based on the output frame count.
+
+To retrieve the global time, use `ma_node_graph_get_time()`. The global time can be set with
+`ma_node_graph_set_time()` which might be useful if you want to do seeking on a global timeline.
+Getting and setting the local time is similar. Use `ma_node_get_time()` to retrieve the local time,
+and `ma_node_set_time()` to set the local time. The global and local times will be advanced by the
+audio thread, so care should be taken to avoid data races. Ideally you should avoid calling these
+outside of the node processing callbacks which are always run on the audio thread.
+
+There is basic support for scheduling the starting and stopping of nodes. You can only schedule one
+start and one stop at a time. This is mainly intended for putting nodes into a started or stopped
+state in a frame-exact manner. Without this mechanism, starting and stopping of a node is limited
+to the resolution of a call to `ma_node_graph_read_pcm_frames()` which would typically be in blocks
+of several milliseconds. The following APIs can be used for scheduling node states:
+
+ ```c
+ ma_node_set_state_time()
+ ma_node_get_state_time()
+ ```
+
+The time is absolute and must be based on the global clock. An example is below:
+
+ ```c
+ ma_node_set_state_time(&myNode, ma_node_state_started, sampleRate*1); // Delay starting to 1 second.
+ ma_node_set_state_time(&myNode, ma_node_state_stopped, sampleRate*5); // Delay stopping to 5 seconds.
+ ```
+
+An example for changing the state using a relative time.
+
+ ```c
+ ma_node_set_state_time(&myNode, ma_node_state_started, sampleRate*1 + ma_node_graph_get_time(&myNodeGraph));
+ ma_node_set_state_time(&myNode, ma_node_state_stopped, sampleRate*5 + ma_node_graph_get_time(&myNodeGraph));
+ ```
+
+Note that due to the nature of multi-threading the times may not be 100% exact. If this is an
+issue, consider scheduling state changes from within a processing callback. An idea might be to
+have some kind of passthrough trigger node that is used specifically for tracking time and handling
+events.
+
+
+
+7.2. Thread Safety and Locking
+------------------------------
+When processing audio, it's ideal not to have any kind of locking in the audio thread. Since it's
+expected that `ma_node_graph_read_pcm_frames()` would be run on the audio thread, it does so
+without the use of any locks. This section discusses the implementation used by miniaudio and goes
+over some of the compromises employed by miniaudio to achieve this goal. Note that the current
+implementation may not be ideal - feedback and critiques are most welcome.
+
+The node graph API is not *entirely* lock-free. Only `ma_node_graph_read_pcm_frames()` is expected
+to be lock-free. Attachment, detachment and uninitialization of nodes use locks to simplify the
+implementation, but are crafted in a way such that such locking is not required when reading audio
+data from the graph. Locking in these areas are achieved by means of spinlocks.
+
+The main complication with keeping `ma_node_graph_read_pcm_frames()` lock-free stems from the fact
+that a node can be uninitialized, and it's memory potentially freed, while in the middle of being
+processed on the audio thread. There are times when the audio thread will be referencing a node,
+which means the uninitialization process of a node needs to make sure it delays returning until the
+audio thread is finished so that control is not handed back to the caller thereby giving them a
+chance to free the node's memory.
+
+When the audio thread is processing a node, it does so by reading from each of the output buses of
+the node. In order for a node to process data for one of it's output buses, it needs to read from
+each of it's input buses, and so on an so forth. It follows that once all output buses of a node
+are detached, the node as a whole will be disconnected and no further processing will occur unless
+it's output buses are reattached, which won't be happening when the node is being uninitialized.
+By having `ma_node_detach_output_bus()` wait until the audio thread is finished with it, we can
+simplify a few things, at the expense of making `ma_node_detach_output_bus()` a bit slower. By
+doing this, the implementation of `ma_node_uninit()` becomes trivial - just detach all output
+nodes, followed by each of the attachments to each of it's input nodes, and then do any final clean
+up.
+
+With the above design, the worst-case scenario is `ma_node_detach_output_bus()` taking as long as
+it takes to process the output bus being detached. This will happen if it's called at just the
+wrong moment where the audio thread has just iterated it and has just started processing. The
+caller of `ma_node_detach_output_bus()` will stall until the audio thread is finished, which
+includes the cost of recursively processing it's inputs. This is the biggest compromise made with
+the approach taken by miniaudio for it's lock-free processing system. The cost of detaching nodes
+earlier in the pipeline (data sources, for example) will be cheaper than the cost of detaching
+higher level nodes, such as some kind of final post-processing endpoint. If you need to do mass
+detachments, detach starting from the lowest level nodes and work your way towards the final
+endpoint node (but don't try detaching the node graph's endpoint). If the audio thread is not
+running, detachment will be fast and detachment in any order will be the same. The reason nodes
+need to wait for their input attachments to complete is due to the potential for desyncs between
+data sources. If the node was to terminate processing mid way through processing it's inputs,
+there's a chance that some of the underlying data sources will have been read, but then others not.
+That will then result in a potential desynchronization when detaching and reattaching higher-level
+nodes. A possible solution to this is to have an option when detaching to terminate processing
+before processing all input attachments which should be fairly simple.
+
+Another compromise, albeit less significant, is locking when attaching and detaching nodes. This
+locking is achieved by means of a spinlock in order to reduce memory overhead. A lock is present
+for each input bus and output bus. When an output bus is connected to an input bus, both the output
+bus and input bus is locked. This locking is specifically for attaching and detaching across
+different threads and does not affect `ma_node_graph_read_pcm_frames()` in any way. The locking and
+unlocking is mostly self-explanatory, but a slightly less intuitive aspect comes into it when
+considering that iterating over attachments must not break as a result of attaching or detaching a
+node while iteration is occuring.
+
+Attaching and detaching are both quite simple. When an output bus of a node is attached to an input
+bus of another node, it's added to a linked list. Basically, an input bus is a linked list, where
+each item in the list is and output bus. We have some intentional (and convenient) restrictions on
+what can done with the linked list in order to simplify the implementation. First of all, whenever
+something needs to iterate over the list, it must do so in a forward direction. Backwards iteration
+is not supported. Also, items can only be added to the start of the list.
+
+The linked list is a doubly-linked list where each item in the list (an output bus) holds a pointer
+to the next item in the list, and another to the previous item. A pointer to the previous item is
+only required for fast detachment of the node - it is never used in iteration. This is an
+important property because it means from the perspective of iteration, attaching and detaching of
+an item can be done with a single atomic assignment. This is exploited by both the attachment and
+detachment process. When attaching the node, the first thing that is done is the setting of the
+local "next" and "previous" pointers of the node. After that, the item is "attached" to the list
+by simply performing an atomic exchange with the head pointer. After that, the node is "attached"
+to the list from the perspective of iteration. Even though the "previous" pointer of the next item
+hasn't yet been set, from the perspective of iteration it's been attached because iteration will
+only be happening in a forward direction which means the "previous" pointer won't actually ever get
+used. The same general process applies to detachment. See `ma_node_attach_output_bus()` and
+`ma_node_detach_output_bus()` for the implementation of this mechanism.
+
+
+
+8. Decoding
===========
-The `ma_decoder` API is used for reading audio files. Decoders are completely decoupled from devices and can be used independently. The following formats are
-supported:
+The `ma_decoder` API is used for reading audio files. Decoders are completely decoupled from
+devices and can be used independently. The following formats are supported:
+---------+------------------+----------+
| Format | Decoding Backend | Built-In |
@@ -475,7 +2405,8 @@ supported:
| Vorbis | stb_vorbis | No |
+---------+------------------+----------+
-Vorbis is supported via stb_vorbis which can be enabled by including the header section before the implementation of miniaudio, like the following:
+Vorbis is supported via stb_vorbis which can be enabled by including the header section before the
+implementation of miniaudio, like the following:
```c
#define STB_VORBIS_HEADER_ONLY
@@ -491,8 +2422,9 @@ Vorbis is supported via stb_vorbis which can be enabled by including the header
A copy of stb_vorbis is included in the "extras" folder in the miniaudio repository (https://github.com/mackron/miniaudio).
-Built-in decoders are amalgamated into the implementation section of miniaudio. You can disable the built-in decoders by specifying one or more of the
-following options before the miniaudio implementation:
+Built-in decoders are amalgamated into the implementation section of miniaudio. You can disable the
+built-in decoders by specifying one or more of the following options before the miniaudio
+implementation:
```c
#define MA_NO_WAV
@@ -500,10 +2432,12 @@ following options before the miniaudio implementation:
#define MA_NO_FLAC
```
-Disabling built-in decoding libraries is useful if you use these libraries independantly of the `ma_decoder` API.
+Disabling built-in decoding libraries is useful if you use these libraries independantly of the
+`ma_decoder` API.
-A decoder can be initialized from a file with `ma_decoder_init_file()`, a block of memory with `ma_decoder_init_memory()`, or from data delivered via callbacks
-with `ma_decoder_init()`. Here is an example for loading a decoder from a file:
+A decoder can be initialized from a file with `ma_decoder_init_file()`, a block of memory with
+`ma_decoder_init_memory()`, or from data delivered via callbacks with `ma_decoder_init()`. Here is
+an example for loading a decoder from a file:
```c
ma_decoder decoder;
@@ -517,20 +2451,23 @@ with `ma_decoder_init()`. Here is an example for loading a decoder from a file:
ma_decoder_uninit(&decoder);
```
-When initializing a decoder, you can optionally pass in a pointer to a `ma_decoder_config` object (the `NULL` argument in the example above) which allows you
-to configure the output format, channel count, sample rate and channel map:
+When initializing a decoder, you can optionally pass in a pointer to a `ma_decoder_config` object
+(the `NULL` argument in the example above) which allows you to configure the output format, channel
+count, sample rate and channel map:
```c
ma_decoder_config config = ma_decoder_config_init(ma_format_f32, 2, 48000);
```
-When passing in `NULL` for decoder config in `ma_decoder_init*()`, the output format will be the same as that defined by the decoding backend.
+When passing in `NULL` for decoder config in `ma_decoder_init*()`, the output format will be the
+same as that defined by the decoding backend.
-Data is read from the decoder as PCM frames. This will return the number of PCM frames actually read. If the return value is less than the requested number of
-PCM frames it means you've reached the end:
+Data is read from the decoder as PCM frames. This will output the number of PCM frames actually
+read. If this is less than the requested number of PCM frames it means you've reached the end. The
+return value will be `MA_AT_END` if no samples have been read and the end has been reached.
```c
- ma_uint64 framesRead = ma_decoder_read_pcm_frames(pDecoder, pFrames, framesToRead);
+ ma_result result = ma_decoder_read_pcm_frames(pDecoder, pFrames, framesToRead, &framesRead);
if (framesRead < framesToRead) {
// Reached the end.
}
@@ -551,8 +2488,10 @@ If you want to loop back to the start, you can simply seek back to the first PCM
ma_decoder_seek_to_pcm_frame(pDecoder, 0);
```
-When loading a decoder, miniaudio uses a trial and error technique to find the appropriate decoding backend. This can be unnecessarily inefficient if the type
-is already known. In this case you can use `encodingFormat` variable in the device config to specify a specific encoding format you want to decode:
+When loading a decoder, miniaudio uses a trial and error technique to find the appropriate decoding
+backend. This can be unnecessarily inefficient if the type is already known. In this case you can
+use `encodingFormat` variable in the device config to specify a specific encoding format you want
+to decode:
```c
decoderConfig.encodingFormat = ma_encoding_format_wav;
@@ -560,24 +2499,95 @@ is already known. In this case you can use `encodingFormat` variable in the devi
See the `ma_encoding_format` enum for possible encoding formats.
-The `ma_decoder_init_file()` API will try using the file extension to determine which decoding backend to prefer.
+The `ma_decoder_init_file()` API will try using the file extension to determine which decoding
+backend to prefer.
+
+
+8.1. Custom Decoders
+--------------------
+It's possible to implement a custom decoder and plug it into miniaudio. This is extremely useful
+when you want to use the `ma_decoder` API, but need to support an encoding format that's not one of
+the stock formats supported by miniaudio. This can be put to particularly good use when using the
+`ma_engine` and/or `ma_resource_manager` APIs because they use `ma_decoder` internally. If, for
+example, you wanted to support Opus, you can do so with a custom decoder (there if a reference
+Opus decoder in the "extras" folder of the miniaudio repository which uses libopus + libopusfile).
+
+A custom decoder must implement a data source. A vtable called `ma_decoding_backend_vtable` needs
+to be implemented which is then passed into the decoder config:
+
+ ```c
+ ma_decoding_backend_vtable* pCustomBackendVTables[] =
+ {
+ &g_ma_decoding_backend_vtable_libvorbis,
+ &g_ma_decoding_backend_vtable_libopus
+ };
+
+ ...
+
+ decoderConfig = ma_decoder_config_init_default();
+ decoderConfig.pCustomBackendUserData = NULL;
+ decoderConfig.ppCustomBackendVTables = pCustomBackendVTables;
+ decoderConfig.customBackendCount = sizeof(pCustomBackendVTables) / sizeof(pCustomBackendVTables[0]);
+ ```
+
+The `ma_decoding_backend_vtable` vtable has the following functions:
+
+ ```
+ onInit
+ onInitFile
+ onInitFileW
+ onInitMemory
+ onUninit
+ ```
+
+There are only two functions that must be implemented - `onInit` and `onUninit`. The other
+functions can be implemented for a small optimization for loading from a file path or memory. If
+these are not specified, miniaudio will deal with it for you via a generic implementation.
+
+When you initialize a custom data source (by implementing the `onInit` function in the vtable) you
+will need to output a pointer to a `ma_data_source` which implements your custom decoder. See the
+section about data sources for details on how to implemen this. Alternatively, see the
+"custom_decoders" example in the miniaudio repository.
+
+The `onInit` function takes a pointer to some callbacks for the purpose of reading raw audio data
+from some abitrary source. You'll use these functions to read from the raw data and perform the
+decoding. When you call them, you will pass in the `pReadSeekTellUserData` pointer to the relevant
+parameter.
+
+The `pConfig` parameter in `onInit` can be used to configure the backend if appropriate. It's only
+used as a hint and can be ignored. However, if any of the properties are relevant to your decoder,
+an optimal implementation will handle the relevant properties appropriately.
+
+If memory allocation is required, it should be done so via the specified allocation callbacks if
+possible (the `pAllocationCallbacks` parameter).
+
+If an error occurs when initializing the decoder, you should leave `ppBackend` unset, or set to
+NULL, and make sure everything is cleaned up appropriately and an appropriate result code returned.
+When multiple custom backends are specified, miniaudio will cycle through the vtables in the order
+they're listed in the array that's passed into the decoder config so it's important that your
+initialization routine is clean.
+
+When a decoder is uninitialized, the `onUninit` callback will be fired which will give you an
+opportunity to clean up and internal data.
-5. Encoding
+9. Encoding
===========
-The `ma_encoding` API is used for writing audio files. The only supported output format is WAV which is achieved via dr_wav which is amalgamated into the
-implementation section of miniaudio. This can be disabled by specifying the following option before the implementation of miniaudio:
+The `ma_encoding` API is used for writing audio files. The only supported output format is WAV
+which is achieved via dr_wav which is amalgamated into the implementation section of miniaudio.
+This can be disabled by specifying the following option before the implementation of miniaudio:
```c
#define MA_NO_WAV
```
-An encoder can be initialized to write to a file with `ma_encoder_init_file()` or from data delivered via callbacks with `ma_encoder_init()`. Below is an
-example for initializing an encoder to output to a file.
+An encoder can be initialized to write to a file with `ma_encoder_init_file()` or from data
+delivered via callbacks with `ma_encoder_init()`. Below is an example for initializing an encoder
+to output to a file.
```c
- ma_encoder_config config = ma_encoder_config_init(ma_resource_format_wav, FORMAT, CHANNELS, SAMPLE_RATE);
+ ma_encoder_config config = ma_encoder_config_init(ma_encoding_format_wav, FORMAT, CHANNELS, SAMPLE_RATE);
ma_encoder encoder;
ma_result result = ma_encoder_init_file("my_file.wav", &config, &encoder);
if (result != MA_SUCCESS) {
@@ -589,17 +2599,20 @@ example for initializing an encoder to output to a file.
ma_encoder_uninit(&encoder);
```
-When initializing an encoder you must specify a config which is initialized with `ma_encoder_config_init()`. Here you must specify the file type, the output
-sample format, output channel count and output sample rate. The following file types are supported:
+When initializing an encoder you must specify a config which is initialized with
+`ma_encoder_config_init()`. Here you must specify the file type, the output sample format, output
+channel count and output sample rate. The following file types are supported:
+------------------------+-------------+
| Enum | Description |
+------------------------+-------------+
- | ma_resource_format_wav | WAV |
+ | ma_encoding_format_wav | WAV |
+------------------------+-------------+
-If the format, channel count or sample rate is not supported by the output file type an error will be returned. The encoder will not perform data conversion so
-you will need to convert it before outputting any audio data. To output audio data, use `ma_encoder_write_pcm_frames()`, like in the example below:
+If the format, channel count or sample rate is not supported by the output file type an error will
+be returned. The encoder will not perform data conversion so you will need to convert it before
+outputting any audio data. To output audio data, use `ma_encoder_write_pcm_frames()`, like in the
+example below:
```c
framesWritten = ma_encoder_write_pcm_frames(&encoder, pPCMFramesToWrite, framesToWrite);
@@ -608,21 +2621,25 @@ you will need to convert it before outputting any audio data. To output audio da
Encoders must be uninitialized with `ma_encoder_uninit()`.
-6. Data Conversion
-==================
-A data conversion API is included with miniaudio which supports the majority of data conversion requirements. This supports conversion between sample formats,
-channel counts (with channel mapping) and sample rates.
+
+10. Data Conversion
+===================
+A data conversion API is included with miniaudio which supports the majority of data conversion
+requirements. This supports conversion between sample formats, channel counts (with channel
+mapping) and sample rates.
-6.1. Sample Format Conversion
------------------------------
-Conversion between sample formats is achieved with the `ma_pcm_*_to_*()`, `ma_pcm_convert()` and `ma_convert_pcm_frames_format()` APIs. Use `ma_pcm_*_to_*()`
-to convert between two specific formats. Use `ma_pcm_convert()` to convert based on a `ma_format` variable. Use `ma_convert_pcm_frames_format()` to convert
-PCM frames where you want to specify the frame count and channel count as a variable instead of the total sample count.
+10.1. Sample Format Conversion
+------------------------------
+Conversion between sample formats is achieved with the `ma_pcm_*_to_*()`, `ma_pcm_convert()` and
+`ma_convert_pcm_frames_format()` APIs. Use `ma_pcm_*_to_*()` to convert between two specific
+formats. Use `ma_pcm_convert()` to convert based on a `ma_format` variable. Use
+`ma_convert_pcm_frames_format()` to convert PCM frames where you want to specify the frame count
+and channel count as a variable instead of the total sample count.
-6.1.1. Dithering
-----------------
+10.1.1. Dithering
+-----------------
Dithering can be set using the ditherMode parameter.
The different dithering modes include the following, in order of efficiency:
@@ -635,8 +2652,9 @@ The different dithering modes include the following, in order of efficiency:
| Triangle | ma_dither_mode_triangle |
+-----------+--------------------------+
-Note that even if the dither mode is set to something other than `ma_dither_mode_none`, it will be ignored for conversions where dithering is not needed.
-Dithering is available for the following conversions:
+Note that even if the dither mode is set to something other than `ma_dither_mode_none`, it will be
+ignored for conversions where dithering is not needed. Dithering is available for the following
+conversions:
```
s16 -> u8
@@ -648,14 +2666,16 @@ Dithering is available for the following conversions:
f32 -> s16
```
-Note that it is not an error to pass something other than ma_dither_mode_none for conversions where dither is not used. It will just be ignored.
+Note that it is not an error to pass something other than ma_dither_mode_none for conversions where
+dither is not used. It will just be ignored.
-6.2. Channel Conversion
------------------------
-Channel conversion is used for channel rearrangement and conversion from one channel count to another. The `ma_channel_converter` API is used for channel
-conversion. Below is an example of initializing a simple channel converter which converts from mono to stereo.
+10.2. Channel Conversion
+------------------------
+Channel conversion is used for channel rearrangement and conversion from one channel count to
+another. The `ma_channel_converter` API is used for channel conversion. Below is an example of
+initializing a simple channel converter which converts from mono to stereo.
```c
ma_channel_converter_config config = ma_channel_converter_config_init(
@@ -666,7 +2686,7 @@ conversion. Below is an example of initializing a simple channel converter which
NULL, // Output channel map
ma_channel_mix_mode_default); // The mixing algorithm to use when combining channels.
- result = ma_channel_converter_init(&config, &converter);
+ result = ma_channel_converter_init(&config, NULL, &converter);
if (result != MA_SUCCESS) {
// Error.
}
@@ -681,34 +2701,43 @@ To perform the conversion simply call `ma_channel_converter_process_pcm_frames()
}
```
-It is up to the caller to ensure the output buffer is large enough to accomodate the new PCM frames.
+It is up to the caller to ensure the output buffer is large enough to accomodate the new PCM
+frames.
Input and output PCM frames are always interleaved. Deinterleaved layouts are not supported.
-6.2.1. Channel Mapping
-----------------------
-In addition to converting from one channel count to another, like the example above, the channel converter can also be used to rearrange channels. When
-initializing the channel converter, you can optionally pass in channel maps for both the input and output frames. If the channel counts are the same, and each
-channel map contains the same channel positions with the exception that they're in a different order, a simple shuffling of the channels will be performed. If,
-however, there is not a 1:1 mapping of channel positions, or the channel counts differ, the input channels will be mixed based on a mixing mode which is
-specified when initializing the `ma_channel_converter_config` object.
+10.2.1. Channel Mapping
+-----------------------
+In addition to converting from one channel count to another, like the example above, the channel
+converter can also be used to rearrange channels. When initializing the channel converter, you can
+optionally pass in channel maps for both the input and output frames. If the channel counts are the
+same, and each channel map contains the same channel positions with the exception that they're in
+a different order, a simple shuffling of the channels will be performed. If, however, there is not
+a 1:1 mapping of channel positions, or the channel counts differ, the input channels will be mixed
+based on a mixing mode which is specified when initializing the `ma_channel_converter_config`
+object.
-When converting from mono to multi-channel, the mono channel is simply copied to each output channel. When going the other way around, the audio of each output
-channel is simply averaged and copied to the mono channel.
+When converting from mono to multi-channel, the mono channel is simply copied to each output
+channel. When going the other way around, the audio of each output channel is simply averaged and
+copied to the mono channel.
-In more complicated cases blending is used. The `ma_channel_mix_mode_simple` mode will drop excess channels and silence extra channels. For example, converting
-from 4 to 2 channels, the 3rd and 4th channels will be dropped, whereas converting from 2 to 4 channels will put silence into the 3rd and 4th channels.
+In more complicated cases blending is used. The `ma_channel_mix_mode_simple` mode will drop excess
+channels and silence extra channels. For example, converting from 4 to 2 channels, the 3rd and 4th
+channels will be dropped, whereas converting from 2 to 4 channels will put silence into the 3rd and
+4th channels.
-The `ma_channel_mix_mode_rectangle` mode uses spacial locality based on a rectangle to compute a simple distribution between input and output. Imagine sitting
-in the middle of a room, with speakers on the walls representing channel positions. The MA_CHANNEL_FRONT_LEFT position can be thought of as being in the corner
-of the front and left walls.
+The `ma_channel_mix_mode_rectangle` mode uses spacial locality based on a rectangle to compute a
+simple distribution between input and output. Imagine sitting in the middle of a room, with
+speakers on the walls representing channel positions. The `MA_CHANNEL_FRONT_LEFT` position can be
+thought of as being in the corner of the front and left walls.
-Finally, the `ma_channel_mix_mode_custom_weights` mode can be used to use custom user-defined weights. Custom weights can be passed in as the last parameter of
+Finally, the `ma_channel_mix_mode_custom_weights` mode can be used to use custom user-defined
+weights. Custom weights can be passed in as the last parameter of
`ma_channel_converter_config_init()`.
-Predefined channel maps can be retrieved with `ma_get_standard_channel_map()`. This takes a `ma_standard_channel_map` enum as it's first parameter, which can
-be one of the following:
+Predefined channel maps can be retrieved with `ma_channel_map_init_standard()`. This takes a
+`ma_standard_channel_map` enum as it's first parameter, which can be one of the following:
+-----------------------------------+-----------------------------------------------------------+
| Name | Description |
@@ -780,9 +2809,10 @@ Below are the channel maps used by default in miniaudio (`ma_standard_channel_ma
-6.3. Resampling
----------------
-Resampling is achieved with the `ma_resampler` object. To create a resampler object, do something like the following:
+10.3. Resampling
+----------------
+Resampling is achieved with the `ma_resampler` object. To create a resampler object, do something
+like the following:
```c
ma_resampler_config config = ma_resampler_config_init(
@@ -819,104 +2849,128 @@ The following example shows how data can be processed
// number of output frames written.
```
-To initialize the resampler you first need to set up a config (`ma_resampler_config`) with `ma_resampler_config_init()`. You need to specify the sample format
-you want to use, the number of channels, the input and output sample rate, and the algorithm.
+To initialize the resampler you first need to set up a config (`ma_resampler_config`) with
+`ma_resampler_config_init()`. You need to specify the sample format you want to use, the number of
+channels, the input and output sample rate, and the algorithm.
-The sample format can be either `ma_format_s16` or `ma_format_f32`. If you need a different format you will need to perform pre- and post-conversions yourself
-where necessary. Note that the format is the same for both input and output. The format cannot be changed after initialization.
+The sample format can be either `ma_format_s16` or `ma_format_f32`. If you need a different format
+you will need to perform pre- and post-conversions yourself where necessary. Note that the format
+is the same for both input and output. The format cannot be changed after initialization.
-The resampler supports multiple channels and is always interleaved (both input and output). The channel count cannot be changed after initialization.
+The resampler supports multiple channels and is always interleaved (both input and output). The
+channel count cannot be changed after initialization.
-The sample rates can be anything other than zero, and are always specified in hertz. They should be set to something like 44100, etc. The sample rate is the
-only configuration property that can be changed after initialization.
+The sample rates can be anything other than zero, and are always specified in hertz. They should be
+set to something like 44100, etc. The sample rate is the only configuration property that can be
+changed after initialization.
-The miniaudio resampler supports multiple algorithms:
+The miniaudio resampler has built-in support for the following algorithms:
+-----------+------------------------------+
| Algorithm | Enum Token |
+-----------+------------------------------+
| Linear | ma_resample_algorithm_linear |
- | Speex | ma_resample_algorithm_speex |
+ | Custom | ma_resample_algorithm_custom |
+-----------+------------------------------+
-Because Speex is not public domain it is strictly opt-in and the code is stored in separate files. if you opt-in to the Speex backend you will need to consider
-it's license, the text of which can be found in it's source files in "extras/speex_resampler". Details on how to opt-in to the Speex resampler is explained in
-the Speex Resampler section below.
-
The algorithm cannot be changed after initialization.
-Processing always happens on a per PCM frame basis and always assumes interleaved input and output. De-interleaved processing is not supported. To process
-frames, use `ma_resampler_process_pcm_frames()`. On input, this function takes the number of output frames you can fit in the output buffer and the number of
-input frames contained in the input buffer. On output these variables contain the number of output frames that were written to the output buffer and the
-number of input frames that were consumed in the process. You can pass in NULL for the input buffer in which case it will be treated as an infinitely large
-buffer of zeros. The output buffer can also be NULL, in which case the processing will be treated as seek.
+Processing always happens on a per PCM frame basis and always assumes interleaved input and output.
+De-interleaved processing is not supported. To process frames, use
+`ma_resampler_process_pcm_frames()`. On input, this function takes the number of output frames you
+can fit in the output buffer and the number of input frames contained in the input buffer. On
+output these variables contain the number of output frames that were written to the output buffer
+and the number of input frames that were consumed in the process. You can pass in NULL for the
+input buffer in which case it will be treated as an infinitely large buffer of zeros. The output
+buffer can also be NULL, in which case the processing will be treated as seek.
-The sample rate can be changed dynamically on the fly. You can change this with explicit sample rates with `ma_resampler_set_rate()` and also with a decimal
-ratio with `ma_resampler_set_rate_ratio()`. The ratio is in/out.
+The sample rate can be changed dynamically on the fly. You can change this with explicit sample
+rates with `ma_resampler_set_rate()` and also with a decimal ratio with
+`ma_resampler_set_rate_ratio()`. The ratio is in/out.
-Sometimes it's useful to know exactly how many input frames will be required to output a specific number of frames. You can calculate this with
-`ma_resampler_get_required_input_frame_count()`. Likewise, it's sometimes useful to know exactly how many frames would be output given a certain number of
-input frames. You can do this with `ma_resampler_get_expected_output_frame_count()`.
+Sometimes it's useful to know exactly how many input frames will be required to output a specific
+number of frames. You can calculate this with `ma_resampler_get_required_input_frame_count()`.
+Likewise, it's sometimes useful to know exactly how many frames would be output given a certain
+number of input frames. You can do this with `ma_resampler_get_expected_output_frame_count()`.
-Due to the nature of how resampling works, the resampler introduces some latency. This can be retrieved in terms of both the input rate and the output rate
-with `ma_resampler_get_input_latency()` and `ma_resampler_get_output_latency()`.
+Due to the nature of how resampling works, the resampler introduces some latency. This can be
+retrieved in terms of both the input rate and the output rate with
+`ma_resampler_get_input_latency()` and `ma_resampler_get_output_latency()`.
-6.3.1. Resampling Algorithms
-----------------------------
-The choice of resampling algorithm depends on your situation and requirements. The linear resampler is the most efficient and has the least amount of latency,
-but at the expense of poorer quality. The Speex resampler is higher quality, but slower with more latency. It also performs several heap allocations internally
-for memory management.
+10.3.1. Resampling Algorithms
+-----------------------------
+The choice of resampling algorithm depends on your situation and requirements.
-6.3.1.1. Linear Resampling
---------------------------
-The linear resampler is the fastest, but comes at the expense of poorer quality. There is, however, some control over the quality of the linear resampler which
-may make it a suitable option depending on your requirements.
+10.3.1.1. Linear Resampling
+---------------------------
+The linear resampler is the fastest, but comes at the expense of poorer quality. There is, however,
+some control over the quality of the linear resampler which may make it a suitable option depending
+on your requirements.
-The linear resampler performs low-pass filtering before or after downsampling or upsampling, depending on the sample rates you're converting between. When
-decreasing the sample rate, the low-pass filter will be applied before downsampling. When increasing the rate it will be performed after upsampling. By default
-a fourth order low-pass filter will be applied. This can be configured via the `lpfOrder` configuration variable. Setting this to 0 will disable filtering.
+The linear resampler performs low-pass filtering before or after downsampling or upsampling,
+depending on the sample rates you're converting between. When decreasing the sample rate, the
+low-pass filter will be applied before downsampling. When increasing the rate it will be performed
+after upsampling. By default a fourth order low-pass filter will be applied. This can be configured
+via the `lpfOrder` configuration variable. Setting this to 0 will disable filtering.
-The low-pass filter has a cutoff frequency which defaults to half the sample rate of the lowest of the input and output sample rates (Nyquist Frequency). This
-can be controlled with the `lpfNyquistFactor` config variable. This defaults to 1, and should be in the range of 0..1, although a value of 0 does not make
-sense and should be avoided. A value of 1 will use the Nyquist Frequency as the cutoff. A value of 0.5 will use half the Nyquist Frequency as the cutoff, etc.
-Values less than 1 will result in more washed out sound due to more of the higher frequencies being removed. This config variable has no impact on performance
-and is a purely perceptual configuration.
+The low-pass filter has a cutoff frequency which defaults to half the sample rate of the lowest of
+the input and output sample rates (Nyquist Frequency).
-The API for the linear resampler is the same as the main resampler API, only it's called `ma_linear_resampler`.
+The API for the linear resampler is the same as the main resampler API, only it's called
+`ma_linear_resampler`.
-6.3.1.2. Speex Resampling
+10.3.2. Custom Resamplers
-------------------------
-The Speex resampler is made up of third party code which is released under the BSD license. Because it is licensed differently to miniaudio, which is public
-domain, it is strictly opt-in and all of it's code is stored in separate files. If you opt-in to the Speex resampler you must consider the license text in it's
-source files. To opt-in, you must first `#include` the following file before the implementation of miniaudio.h:
+You can implement a custom resampler by using the `ma_resample_algorithm_custom` resampling
+algorithm and setting a vtable in the resampler config:
```c
- #include "extras/speex_resampler/ma_speex_resampler.h"
+ ma_resampler_config config = ma_resampler_config_init(..., ma_resample_algorithm_custom);
+ config.pBackendVTable = &g_customResamplerVTable;
```
-Both the header and implementation is contained within the same file. The implementation can be included in your program like so:
+Custom resamplers are useful if the stock algorithms are not appropriate for your use case. You
+need to implement the required functions in `ma_resampling_backend_vtable`. Note that not all
+functions in the vtable need to be implemented, but if it's possible to implement, they should be.
- ```c
- #define MINIAUDIO_SPEEX_RESAMPLER_IMPLEMENTATION
- #include "extras/speex_resampler/ma_speex_resampler.h"
- ```
+You can use the `ma_linear_resampler` object for an example on how to implement the vtable. The
+`onGetHeapSize` callback is used to calculate the size of any internal heap allocation the custom
+resampler will need to make given the supplied config. When you initialize the resampler via the
+`onInit` callback, you'll be given a pointer to a heap allocation which is where you should store
+the heap allocated data. You should not free this data in `onUninit` because miniaudio will manage
+it for you.
-Note that even if you opt-in to the Speex backend, miniaudio won't use it unless you explicitly ask for it in the respective config of the object you are
-initializing. If you try to use the Speex resampler without opting in, initialization of the `ma_resampler` object will fail with `MA_NO_BACKEND`.
+The `onProcess` callback is where the actual resampling takes place. On input, `pFrameCountIn`
+points to a variable containing the number of frames in the `pFramesIn` buffer and
+`pFrameCountOut` points to a variable containing the capacity in frames of the `pFramesOut` buffer.
+On output, `pFrameCountIn` should be set to the number of input frames that were fully consumed,
+whereas `pFrameCountOut` should be set to the number of frames that were written to `pFramesOut`.
-The only configuration option to consider with the Speex resampler is the `speex.quality` config variable. This is a value between 0 and 10, with 0 being
-the fastest with the poorest quality and 10 being the slowest with the highest quality. The default value is 3.
+The `onSetRate` callback is optional and is used for dynamically changing the sample rate. If
+dynamic rate changes are not supported, you can set this callback to NULL.
+
+The `onGetInputLatency` and `onGetOutputLatency` functions are used for retrieving the latency in
+input and output rates respectively. These can be NULL in which case latency calculations will be
+assumed to be NULL.
+
+The `onGetRequiredInputFrameCount` callback is used to give miniaudio a hint as to how many input
+frames are required to be available to produce the given number of output frames. Likewise, the
+`onGetExpectedOutputFrameCount` callback is used to determine how many output frames will be
+produced given the specified number of input frames. miniaudio will use these as a hint, but they
+are optional and can be set to NULL if you're unable to implement them.
-6.4. General Data Conversion
-----------------------------
-The `ma_data_converter` API can be used to wrap sample format conversion, channel conversion and resampling into one operation. This is what miniaudio uses
-internally to convert between the format requested when the device was initialized and the format of the backend's native device. The API for general data
-conversion is very similar to the resampling API. Create a `ma_data_converter` object like this:
+10.4. General Data Conversion
+-----------------------------
+The `ma_data_converter` API can be used to wrap sample format conversion, channel conversion and
+resampling into one operation. This is what miniaudio uses internally to convert between the format
+requested when the device was initialized and the format of the backend's native device. The API
+for general data conversion is very similar to the resampling API. Create a `ma_data_converter`
+object like this:
```c
ma_data_converter_config config = ma_data_converter_config_init(
@@ -929,14 +2983,15 @@ conversion is very similar to the resampling API. Create a `ma_data_converter` o
);
ma_data_converter converter;
- ma_result result = ma_data_converter_init(&config, &converter);
+ ma_result result = ma_data_converter_init(&config, NULL, &converter);
if (result != MA_SUCCESS) {
// An error occurred...
}
```
-In the example above we use `ma_data_converter_config_init()` to initialize the config, however there's many more properties that can be configured, such as
-channel maps and resampling quality. Something like the following may be more suitable depending on your requirements:
+In the example above we use `ma_data_converter_config_init()` to initialize the config, however
+there's many more properties that can be configured, such as channel maps and resampling quality.
+Something like the following may be more suitable depending on your requirements:
```c
ma_data_converter_config config = ma_data_converter_config_init_default();
@@ -946,14 +3001,14 @@ channel maps and resampling quality. Something like the following may be more su
config.channelsOut = outputChannels;
config.sampleRateIn = inputSampleRate;
config.sampleRateOut = outputSampleRate;
- ma_get_standard_channel_map(ma_standard_channel_map_flac, config.channelCountIn, config.channelMapIn);
+ ma_channel_map_init_standard(ma_standard_channel_map_flac, config.channelMapIn, sizeof(config.channelMapIn)/sizeof(config.channelMapIn[0]), config.channelCountIn);
config.resampling.linear.lpfOrder = MA_MAX_FILTER_ORDER;
```
Do the following to uninitialize the data converter:
```c
- ma_data_converter_uninit(&converter);
+ ma_data_converter_uninit(&converter, NULL);
```
The following example shows how data can be processed
@@ -970,33 +3025,42 @@ The following example shows how data can be processed
// of output frames written.
```
-The data converter supports multiple channels and is always interleaved (both input and output). The channel count cannot be changed after initialization.
+The data converter supports multiple channels and is always interleaved (both input and output).
+The channel count cannot be changed after initialization.
-Sample rates can be anything other than zero, and are always specified in hertz. They should be set to something like 44100, etc. The sample rate is the only
-configuration property that can be changed after initialization, but only if the `resampling.allowDynamicSampleRate` member of `ma_data_converter_config` is
-set to `MA_TRUE`. To change the sample rate, use `ma_data_converter_set_rate()` or `ma_data_converter_set_rate_ratio()`. The ratio must be in/out. The
-resampling algorithm cannot be changed after initialization.
+Sample rates can be anything other than zero, and are always specified in hertz. They should be set
+to something like 44100, etc. The sample rate is the only configuration property that can be
+changed after initialization, but only if the `resampling.allowDynamicSampleRate` member of
+`ma_data_converter_config` is set to `MA_TRUE`. To change the sample rate, use
+`ma_data_converter_set_rate()` or `ma_data_converter_set_rate_ratio()`. The ratio must be in/out.
+The resampling algorithm cannot be changed after initialization.
-Processing always happens on a per PCM frame basis and always assumes interleaved input and output. De-interleaved processing is not supported. To process
-frames, use `ma_data_converter_process_pcm_frames()`. On input, this function takes the number of output frames you can fit in the output buffer and the number
-of input frames contained in the input buffer. On output these variables contain the number of output frames that were written to the output buffer and the
-number of input frames that were consumed in the process. You can pass in NULL for the input buffer in which case it will be treated as an infinitely large
-buffer of zeros. The output buffer can also be NULL, in which case the processing will be treated as seek.
+Processing always happens on a per PCM frame basis and always assumes interleaved input and output.
+De-interleaved processing is not supported. To process frames, use
+`ma_data_converter_process_pcm_frames()`. On input, this function takes the number of output frames
+you can fit in the output buffer and the number of input frames contained in the input buffer. On
+output these variables contain the number of output frames that were written to the output buffer
+and the number of input frames that were consumed in the process. You can pass in NULL for the
+input buffer in which case it will be treated as an infinitely large
+buffer of zeros. The output buffer can also be NULL, in which case the processing will be treated
+as seek.
-Sometimes it's useful to know exactly how many input frames will be required to output a specific number of frames. You can calculate this with
-`ma_data_converter_get_required_input_frame_count()`. Likewise, it's sometimes useful to know exactly how many frames would be output given a certain number of
-input frames. You can do this with `ma_data_converter_get_expected_output_frame_count()`.
+Sometimes it's useful to know exactly how many input frames will be required to output a specific
+number of frames. You can calculate this with `ma_data_converter_get_required_input_frame_count()`.
+Likewise, it's sometimes useful to know exactly how many frames would be output given a certain
+number of input frames. You can do this with `ma_data_converter_get_expected_output_frame_count()`.
-Due to the nature of how resampling works, the data converter introduces some latency if resampling is required. This can be retrieved in terms of both the
-input rate and the output rate with `ma_data_converter_get_input_latency()` and `ma_data_converter_get_output_latency()`.
+Due to the nature of how resampling works, the data converter introduces some latency if resampling
+is required. This can be retrieved in terms of both the input rate and the output rate with
+`ma_data_converter_get_input_latency()` and `ma_data_converter_get_output_latency()`.
-7. Filtering
-============
+11. Filtering
+=============
-7.1. Biquad Filtering
----------------------
+11.1. Biquad Filtering
+----------------------
Biquad filtering is achieved with the `ma_biquad` API. Example:
```c
@@ -1011,28 +3075,33 @@ Biquad filtering is achieved with the `ma_biquad` API. Example:
ma_biquad_process_pcm_frames(&biquad, pFramesOut, pFramesIn, frameCount);
```
-Biquad filtering is implemented using transposed direct form 2. The numerator coefficients are b0, b1 and b2, and the denominator coefficients are a0, a1 and
-a2. The a0 coefficient is required and coefficients must not be pre-normalized.
+Biquad filtering is implemented using transposed direct form 2. The numerator coefficients are b0,
+b1 and b2, and the denominator coefficients are a0, a1 and a2. The a0 coefficient is required and
+coefficients must not be pre-normalized.
-Supported formats are `ma_format_s16` and `ma_format_f32`. If you need to use a different format you need to convert it yourself beforehand. When using
-`ma_format_s16` the biquad filter will use fixed point arithmetic. When using `ma_format_f32`, floating point arithmetic will be used.
+Supported formats are `ma_format_s16` and `ma_format_f32`. If you need to use a different format
+you need to convert it yourself beforehand. When using `ma_format_s16` the biquad filter will use
+fixed point arithmetic. When using `ma_format_f32`, floating point arithmetic will be used.
Input and output frames are always interleaved.
-Filtering can be applied in-place by passing in the same pointer for both the input and output buffers, like so:
+Filtering can be applied in-place by passing in the same pointer for both the input and output
+buffers, like so:
```c
ma_biquad_process_pcm_frames(&biquad, pMyData, pMyData, frameCount);
```
-If you need to change the values of the coefficients, but maintain the values in the registers you can do so with `ma_biquad_reinit()`. This is useful if you
-need to change the properties of the filter while keeping the values of registers valid to avoid glitching. Do not use `ma_biquad_init()` for this as it will
-do a full initialization which involves clearing the registers to 0. Note that changing the format or channel count after initialization is invalid and will
-result in an error.
+If you need to change the values of the coefficients, but maintain the values in the registers you
+can do so with `ma_biquad_reinit()`. This is useful if you need to change the properties of the
+filter while keeping the values of registers valid to avoid glitching. Do not use
+`ma_biquad_init()` for this as it will do a full initialization which involves clearing the
+registers to 0. Note that changing the format or channel count after initialization is invalid and
+will result in an error.
-7.2. Low-Pass Filtering
------------------------
+11.2. Low-Pass Filtering
+------------------------
Low-pass filtering is achieved with the following APIs:
+---------+------------------------------------------+
@@ -1057,16 +3126,18 @@ Low-pass filter example:
ma_lpf_process_pcm_frames(&lpf, pFramesOut, pFramesIn, frameCount);
```
-Supported formats are `ma_format_s16` and` ma_format_f32`. If you need to use a different format you need to convert it yourself beforehand. Input and output
-frames are always interleaved.
+Supported formats are `ma_format_s16` and` ma_format_f32`. If you need to use a different format
+you need to convert it yourself beforehand. Input and output frames are always interleaved.
-Filtering can be applied in-place by passing in the same pointer for both the input and output buffers, like so:
+Filtering can be applied in-place by passing in the same pointer for both the input and output
+buffers, like so:
```c
ma_lpf_process_pcm_frames(&lpf, pMyData, pMyData, frameCount);
```
-The maximum filter order is limited to `MA_MAX_FILTER_ORDER` which is set to 8. If you need more, you can chain first and second order filters together.
+The maximum filter order is limited to `MA_MAX_FILTER_ORDER` which is set to 8. If you need more,
+you can chain first and second order filters together.
```c
for (iFilter = 0; iFilter < filterCount; iFilter += 1) {
@@ -1074,19 +3145,22 @@ The maximum filter order is limited to `MA_MAX_FILTER_ORDER` which is set to 8.
}
```
-If you need to change the configuration of the filter, but need to maintain the state of internal registers you can do so with `ma_lpf_reinit()`. This may be
-useful if you need to change the sample rate and/or cutoff frequency dynamically while maintaing smooth transitions. Note that changing the format or channel
-count after initialization is invalid and will result in an error.
+If you need to change the configuration of the filter, but need to maintain the state of internal
+registers you can do so with `ma_lpf_reinit()`. This may be useful if you need to change the sample
+rate and/or cutoff frequency dynamically while maintaing smooth transitions. Note that changing the
+format or channel count after initialization is invalid and will result in an error.
-The `ma_lpf` object supports a configurable order, but if you only need a first order filter you may want to consider using `ma_lpf1`. Likewise, if you only
-need a second order filter you can use `ma_lpf2`. The advantage of this is that they're lighter weight and a bit more efficient.
+The `ma_lpf` object supports a configurable order, but if you only need a first order filter you
+may want to consider using `ma_lpf1`. Likewise, if you only need a second order filter you can use
+`ma_lpf2`. The advantage of this is that they're lighter weight and a bit more efficient.
-If an even filter order is specified, a series of second order filters will be processed in a chain. If an odd filter order is specified, a first order filter
-will be applied, followed by a series of second order filters in a chain.
+If an even filter order is specified, a series of second order filters will be processed in a
+chain. If an odd filter order is specified, a first order filter will be applied, followed by a
+series of second order filters in a chain.
-7.3. High-Pass Filtering
-------------------------
+11.3. High-Pass Filtering
+-------------------------
High-pass filtering is achieved with the following APIs:
+---------+-------------------------------------------+
@@ -1097,12 +3171,12 @@ High-pass filtering is achieved with the following APIs:
| ma_hpf | High order high-pass filter (Butterworth) |
+---------+-------------------------------------------+
-High-pass filters work exactly the same as low-pass filters, only the APIs are called `ma_hpf1`, `ma_hpf2` and `ma_hpf`. See example code for low-pass filters
-for example usage.
+High-pass filters work exactly the same as low-pass filters, only the APIs are called `ma_hpf1`,
+`ma_hpf2` and `ma_hpf`. See example code for low-pass filters for example usage.
-7.4. Band-Pass Filtering
-------------------------
+11.4. Band-Pass Filtering
+-------------------------
Band-pass filtering is achieved with the following APIs:
+---------+-------------------------------+
@@ -1112,13 +3186,14 @@ Band-pass filtering is achieved with the following APIs:
| ma_bpf | High order band-pass filter |
+---------+-------------------------------+
-Band-pass filters work exactly the same as low-pass filters, only the APIs are called `ma_bpf2` and `ma_hpf`. See example code for low-pass filters for example
-usage. Note that the order for band-pass filters must be an even number which means there is no first order band-pass filter, unlike low-pass and high-pass
-filters.
+Band-pass filters work exactly the same as low-pass filters, only the APIs are called `ma_bpf2` and
+`ma_hpf`. See example code for low-pass filters for example usage. Note that the order for
+band-pass filters must be an even number which means there is no first order band-pass filter,
+unlike low-pass and high-pass filters.
-7.5. Notch Filtering
---------------------
+11.5. Notch Filtering
+---------------------
Notch filtering is achieved with the following APIs:
+-----------+------------------------------------------+
@@ -1128,7 +3203,7 @@ Notch filtering is achieved with the following APIs:
+-----------+------------------------------------------+
-7.6. Peaking EQ Filtering
+11.6. Peaking EQ Filtering
-------------------------
Peaking filtering is achieved with the following APIs:
@@ -1139,8 +3214,8 @@ Peaking filtering is achieved with the following APIs:
+----------+------------------------------------------+
-7.7. Low Shelf Filtering
-------------------------
+11.7. Low Shelf Filtering
+-------------------------
Low shelf filtering is achieved with the following APIs:
+-------------+------------------------------------------+
@@ -1149,11 +3224,12 @@ Low shelf filtering is achieved with the following APIs:
| ma_loshelf2 | Second order low shelf filter |
+-------------+------------------------------------------+
-Where a high-pass filter is used to eliminate lower frequencies, a low shelf filter can be used to just turn them down rather than eliminate them entirely.
+Where a high-pass filter is used to eliminate lower frequencies, a low shelf filter can be used to
+just turn them down rather than eliminate them entirely.
-7.8. High Shelf Filtering
--------------------------
+11.8. High Shelf Filtering
+--------------------------
High shelf filtering is achieved with the following APIs:
+-------------+------------------------------------------+
@@ -1162,18 +3238,20 @@ High shelf filtering is achieved with the following APIs:
| ma_hishelf2 | Second order high shelf filter |
+-------------+------------------------------------------+
-The high shelf filter has the same API as the low shelf filter, only you would use `ma_hishelf` instead of `ma_loshelf`. Where a low shelf filter is used to
-adjust the volume of low frequencies, the high shelf filter does the same thing for high frequencies.
+The high shelf filter has the same API as the low shelf filter, only you would use `ma_hishelf`
+instead of `ma_loshelf`. Where a low shelf filter is used to adjust the volume of low frequencies,
+the high shelf filter does the same thing for high frequencies.
-8. Waveform and Noise Generation
-================================
+12. Waveform and Noise Generation
+=================================
-8.1. Waveforms
---------------
-miniaudio supports generation of sine, square, triangle and sawtooth waveforms. This is achieved with the `ma_waveform` API. Example:
+12.1. Waveforms
+---------------
+miniaudio supports generation of sine, square, triangle and sawtooth waveforms. This is achieved
+with the `ma_waveform` API. Example:
```c
ma_waveform_config config = ma_waveform_config_init(
@@ -1195,11 +3273,12 @@ miniaudio supports generation of sine, square, triangle and sawtooth waveforms.
ma_waveform_read_pcm_frames(&waveform, pOutput, frameCount);
```
-The amplitude, frequency, type, and sample rate can be changed dynamically with `ma_waveform_set_amplitude()`, `ma_waveform_set_frequency()`,
-`ma_waveform_set_type()`, and `ma_waveform_set_sample_rate()` respectively.
+The amplitude, frequency, type, and sample rate can be changed dynamically with
+`ma_waveform_set_amplitude()`, `ma_waveform_set_frequency()`, `ma_waveform_set_type()`, and
+`ma_waveform_set_sample_rate()` respectively.
-You can invert the waveform by setting the amplitude to a negative value. You can use this to control whether or not a sawtooth has a positive or negative
-ramp, for example.
+You can invert the waveform by setting the amplitude to a negative value. You can use this to
+control whether or not a sawtooth has a positive or negative ramp, for example.
Below are the supported waveform types:
@@ -1214,8 +3293,8 @@ Below are the supported waveform types:
-8.2. Noise
-----------
+12.2. Noise
+-----------
miniaudio supports generation of white, pink and Brownian noise via the `ma_noise` API. Example:
```c
@@ -1237,13 +3316,16 @@ miniaudio supports generation of white, pink and Brownian noise via the `ma_nois
ma_noise_read_pcm_frames(&noise, pOutput, frameCount);
```
-The noise API uses simple LCG random number generation. It supports a custom seed which is useful for things like automated testing requiring reproducibility.
-Setting the seed to zero will default to `MA_DEFAULT_LCG_SEED`.
+The noise API uses simple LCG random number generation. It supports a custom seed which is useful
+for things like automated testing requiring reproducibility. Setting the seed to zero will default
+to `MA_DEFAULT_LCG_SEED`.
-The amplitude, seed, and type can be changed dynamically with `ma_noise_set_amplitude()`, `ma_noise_set_seed()`, and `ma_noise_set_type()` respectively.
+The amplitude, seed, and type can be changed dynamically with `ma_noise_set_amplitude()`,
+`ma_noise_set_seed()`, and `ma_noise_set_type()` respectively.
-By default, the noise API will use different values for different channels. So, for example, the left side in a stereo stream will be different to the right
-side. To instead have each channel use the same random value, set the `duplicateChannels` member of the noise config to true, like so:
+By default, the noise API will use different values for different channels. So, for example, the
+left side in a stereo stream will be different to the right side. To instead have each channel use
+the same random value, set the `duplicateChannels` member of the noise config to true, like so:
```c
config.duplicateChannels = MA_TRUE;
@@ -1261,10 +3343,11 @@ Below are the supported noise types.
-9. Audio Buffers
-================
-miniaudio supports reading from a buffer of raw audio data via the `ma_audio_buffer` API. This can read from memory that's managed by the application, but
-can also handle the memory management for you internally. Memory management is flexible and should support most use cases.
+13. Audio Buffers
+=================
+miniaudio supports reading from a buffer of raw audio data via the `ma_audio_buffer` API. This can
+read from memory that's managed by the application, but can also handle the memory management for
+you internally. Memory management is flexible and should support most use cases.
Audio buffers are initialised using the standard configuration system used everywhere in miniaudio:
@@ -1287,11 +3370,14 @@ Audio buffers are initialised using the standard configuration system used every
ma_audio_buffer_uninit(&buffer);
```
-In the example above, the memory pointed to by `pExistingData` will *not* be copied and is how an application can do self-managed memory allocation. If you
-would rather make a copy of the data, use `ma_audio_buffer_init_copy()`. To uninitialize the buffer, use `ma_audio_buffer_uninit()`.
+In the example above, the memory pointed to by `pExistingData` will *not* be copied and is how an
+application can do self-managed memory allocation. If you would rather make a copy of the data, use
+`ma_audio_buffer_init_copy()`. To uninitialize the buffer, use `ma_audio_buffer_uninit()`.
-Sometimes it can be convenient to allocate the memory for the `ma_audio_buffer` structure and the raw audio data in a contiguous block of memory. That is,
-the raw audio data will be located immediately after the `ma_audio_buffer` structure. To do this, use `ma_audio_buffer_alloc_and_init()`:
+Sometimes it can be convenient to allocate the memory for the `ma_audio_buffer` structure and the
+raw audio data in a contiguous block of memory. That is, the raw audio data will be located
+immediately after the `ma_audio_buffer` structure. To do this, use
+`ma_audio_buffer_alloc_and_init()`:
```c
ma_audio_buffer_config config = ma_audio_buffer_config_init(
@@ -1312,13 +3398,18 @@ the raw audio data will be located immediately after the `ma_audio_buffer` struc
ma_audio_buffer_uninit_and_free(&buffer);
```
-If you initialize the buffer with `ma_audio_buffer_alloc_and_init()` you should uninitialize it with `ma_audio_buffer_uninit_and_free()`. In the example above,
-the memory pointed to by `pExistingData` will be copied into the buffer, which is contrary to the behavior of `ma_audio_buffer_init()`.
+If you initialize the buffer with `ma_audio_buffer_alloc_and_init()` you should uninitialize it
+with `ma_audio_buffer_uninit_and_free()`. In the example above, the memory pointed to by
+`pExistingData` will be copied into the buffer, which is contrary to the behavior of
+`ma_audio_buffer_init()`.
-An audio buffer has a playback cursor just like a decoder. As you read frames from the buffer, the cursor moves forward. The last parameter (`loop`) can be
-used to determine if the buffer should loop. The return value is the number of frames actually read. If this is less than the number of frames requested it
-means the end has been reached. This should never happen if the `loop` parameter is set to true. If you want to manually loop back to the start, you can do so
-with with `ma_audio_buffer_seek_to_pcm_frame(pAudioBuffer, 0)`. Below is an example for reading data from an audio buffer.
+An audio buffer has a playback cursor just like a decoder. As you read frames from the buffer, the
+cursor moves forward. The last parameter (`loop`) can be used to determine if the buffer should
+loop. The return value is the number of frames actually read. If this is less than the number of
+frames requested it means the end has been reached. This should never happen if the `loop`
+parameter is set to true. If you want to manually loop back to the start, you can do so with with
+`ma_audio_buffer_seek_to_pcm_frame(pAudioBuffer, 0)`. Below is an example for reading data from an
+audio buffer.
```c
ma_uint64 framesRead = ma_audio_buffer_read_pcm_frames(pAudioBuffer, pFramesOut, desiredFrameCount, isLooping);
@@ -1327,8 +3418,8 @@ with with `ma_audio_buffer_seek_to_pcm_frame(pAudioBuffer, 0)`. Below is an exam
}
```
-Sometimes you may want to avoid the cost of data movement between the internal buffer and the output buffer. Instead you can use memory mapping to retrieve a
-pointer to a segment of data:
+Sometimes you may want to avoid the cost of data movement between the internal buffer and the
+output buffer. Instead you can use memory mapping to retrieve a pointer to a segment of data:
```c
void* pMappedFrames;
@@ -1344,23 +3435,30 @@ pointer to a segment of data:
}
```
-When you use memory mapping, the read cursor is increment by the frame count passed in to `ma_audio_buffer_unmap()`. If you decide not to process every frame
-you can pass in a value smaller than the value returned by `ma_audio_buffer_map()`. The disadvantage to using memory mapping is that it does not handle looping
-for you. You can determine if the buffer is at the end for the purpose of looping with `ma_audio_buffer_at_end()` or by inspecting the return value of
-`ma_audio_buffer_unmap()` and checking if it equals `MA_AT_END`. You should not treat `MA_AT_END` as an error when returned by `ma_audio_buffer_unmap()`.
+When you use memory mapping, the read cursor is increment by the frame count passed in to
+`ma_audio_buffer_unmap()`. If you decide not to process every frame you can pass in a value smaller
+than the value returned by `ma_audio_buffer_map()`. The disadvantage to using memory mapping is
+that it does not handle looping for you. You can determine if the buffer is at the end for the
+purpose of looping with `ma_audio_buffer_at_end()` or by inspecting the return value of
+`ma_audio_buffer_unmap()` and checking if it equals `MA_AT_END`. You should not treat `MA_AT_END`
+as an error when returned by `ma_audio_buffer_unmap()`.
-10. Ring Buffers
+14. Ring Buffers
================
-miniaudio supports lock free (single producer, single consumer) ring buffers which are exposed via the `ma_rb` and `ma_pcm_rb` APIs. The `ma_rb` API operates
-on bytes, whereas the `ma_pcm_rb` operates on PCM frames. They are otherwise identical as `ma_pcm_rb` is just a wrapper around `ma_rb`.
+miniaudio supports lock free (single producer, single consumer) ring buffers which are exposed via
+the `ma_rb` and `ma_pcm_rb` APIs. The `ma_rb` API operates on bytes, whereas the `ma_pcm_rb`
+operates on PCM frames. They are otherwise identical as `ma_pcm_rb` is just a wrapper around
+`ma_rb`.
-Unlike most other APIs in miniaudio, ring buffers support both interleaved and deinterleaved streams. The caller can also allocate their own backing memory for
-the ring buffer to use internally for added flexibility. Otherwise the ring buffer will manage it's internal memory for you.
+Unlike most other APIs in miniaudio, ring buffers support both interleaved and deinterleaved
+streams. The caller can also allocate their own backing memory for the ring buffer to use
+internally for added flexibility. Otherwise the ring buffer will manage it's internal memory for
+you.
-The examples below use the PCM frame variant of the ring buffer since that's most likely the one you will want to use. To initialize a ring buffer, do
-something like the following:
+The examples below use the PCM frame variant of the ring buffer since that's most likely the one
+you will want to use. To initialize a ring buffer, do something like the following:
```c
ma_pcm_rb rb;
@@ -1370,39 +3468,53 @@ something like the following:
}
```
-The `ma_pcm_rb_init()` function takes the sample format and channel count as parameters because it's the PCM varient of the ring buffer API. For the regular
-ring buffer that operates on bytes you would call `ma_rb_init()` which leaves these out and just takes the size of the buffer in bytes instead of frames. The
-fourth parameter is an optional pre-allocated buffer and the fifth parameter is a pointer to a `ma_allocation_callbacks` structure for custom memory allocation
-routines. Passing in `NULL` for this results in `MA_MALLOC()` and `MA_FREE()` being used.
+The `ma_pcm_rb_init()` function takes the sample format and channel count as parameters because
+it's the PCM varient of the ring buffer API. For the regular ring buffer that operates on bytes you
+would call `ma_rb_init()` which leaves these out and just takes the size of the buffer in bytes
+instead of frames. The fourth parameter is an optional pre-allocated buffer and the fifth parameter
+is a pointer to a `ma_allocation_callbacks` structure for custom memory allocation routines.
+Passing in `NULL` for this results in `MA_MALLOC()` and `MA_FREE()` being used.
-Use `ma_pcm_rb_init_ex()` if you need a deinterleaved buffer. The data for each sub-buffer is offset from each other based on the stride. To manage your
-sub-buffers you can use `ma_pcm_rb_get_subbuffer_stride()`, `ma_pcm_rb_get_subbuffer_offset()` and `ma_pcm_rb_get_subbuffer_ptr()`.
+Use `ma_pcm_rb_init_ex()` if you need a deinterleaved buffer. The data for each sub-buffer is
+offset from each other based on the stride. To manage your sub-buffers you can use
+`ma_pcm_rb_get_subbuffer_stride()`, `ma_pcm_rb_get_subbuffer_offset()` and
+`ma_pcm_rb_get_subbuffer_ptr()`.
-Use `ma_pcm_rb_acquire_read()` and `ma_pcm_rb_acquire_write()` to retrieve a pointer to a section of the ring buffer. You specify the number of frames you
-need, and on output it will set to what was actually acquired. If the read or write pointer is positioned such that the number of frames requested will require
-a loop, it will be clamped to the end of the buffer. Therefore, the number of frames you're given may be less than the number you requested.
+Use `ma_pcm_rb_acquire_read()` and `ma_pcm_rb_acquire_write()` to retrieve a pointer to a section
+of the ring buffer. You specify the number of frames you need, and on output it will set to what
+was actually acquired. If the read or write pointer is positioned such that the number of frames
+requested will require a loop, it will be clamped to the end of the buffer. Therefore, the number
+of frames you're given may be less than the number you requested.
-After calling `ma_pcm_rb_acquire_read()` or `ma_pcm_rb_acquire_write()`, you do your work on the buffer and then "commit" it with `ma_pcm_rb_commit_read()` or
-`ma_pcm_rb_commit_write()`. This is where the read/write pointers are updated. When you commit you need to pass in the buffer that was returned by the earlier
-call to `ma_pcm_rb_acquire_read()` or `ma_pcm_rb_acquire_write()` and is only used for validation. The number of frames passed to `ma_pcm_rb_commit_read()` and
-`ma_pcm_rb_commit_write()` is what's used to increment the pointers, and can be less that what was originally requested.
+After calling `ma_pcm_rb_acquire_read()` or `ma_pcm_rb_acquire_write()`, you do your work on the
+buffer and then "commit" it with `ma_pcm_rb_commit_read()` or `ma_pcm_rb_commit_write()`. This is
+where the read/write pointers are updated. When you commit you need to pass in the buffer that was
+returned by the earlier call to `ma_pcm_rb_acquire_read()` or `ma_pcm_rb_acquire_write()` and is
+only used for validation. The number of frames passed to `ma_pcm_rb_commit_read()` and
+`ma_pcm_rb_commit_write()` is what's used to increment the pointers, and can be less that what was
+originally requested.
-If you want to correct for drift between the write pointer and the read pointer you can use a combination of `ma_pcm_rb_pointer_distance()`,
-`ma_pcm_rb_seek_read()` and `ma_pcm_rb_seek_write()`. Note that you can only move the pointers forward, and you should only move the read pointer forward via
-the consumer thread, and the write pointer forward by the producer thread. If there is too much space between the pointers, move the read pointer forward. If
+If you want to correct for drift between the write pointer and the read pointer you can use a
+combination of `ma_pcm_rb_pointer_distance()`, `ma_pcm_rb_seek_read()` and
+`ma_pcm_rb_seek_write()`. Note that you can only move the pointers forward, and you should only
+move the read pointer forward via the consumer thread, and the write pointer forward by the
+producer thread. If there is too much space between the pointers, move the read pointer forward. If
there is too little space between the pointers, move the write pointer forward.
-You can use a ring buffer at the byte level instead of the PCM frame level by using the `ma_rb` API. This is exactly the same, only you will use the `ma_rb`
-functions instead of `ma_pcm_rb` and instead of frame counts you will pass around byte counts.
+You can use a ring buffer at the byte level instead of the PCM frame level by using the `ma_rb`
+API. This is exactly the same, only you will use the `ma_rb` functions instead of `ma_pcm_rb` and
+instead of frame counts you will pass around byte counts.
-The maximum size of the buffer in bytes is `0x7FFFFFFF-(MA_SIMD_ALIGNMENT-1)` due to the most significant bit being used to encode a loop flag and the internally
-managed buffers always being aligned to MA_SIMD_ALIGNMENT.
+The maximum size of the buffer in bytes is `0x7FFFFFFF-(MA_SIMD_ALIGNMENT-1)` due to the most
+significant bit being used to encode a loop flag and the internally managed buffers always being
+aligned to `MA_SIMD_ALIGNMENT`.
-Note that the ring buffer is only thread safe when used by a single consumer thread and single producer thread.
+Note that the ring buffer is only thread safe when used by a single consumer thread and single
+producer thread.
-11. Backends
+15. Backends
============
The following backends are supported by miniaudio.
@@ -1428,28 +3540,36 @@ The following backends are supported by miniaudio.
Some backends have some nuance details you may want to be aware of.
-11.1. WASAPI
+15.1. WASAPI
------------
-- Low-latency shared mode will be disabled when using an application-defined sample rate which is different to the device's native sample rate. To work around
- this, set `wasapi.noAutoConvertSRC` to true in the device config. This is due to IAudioClient3_InitializeSharedAudioStream() failing when the
- `AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM` flag is specified. Setting wasapi.noAutoConvertSRC will result in miniaudio's internal resampler being used instead
- which will in turn enable the use of low-latency shared mode.
+- Low-latency shared mode will be disabled when using an application-defined sample rate which is
+ different to the device's native sample rate. To work around this, set `wasapi.noAutoConvertSRC`
+ to true in the device config. This is due to IAudioClient3_InitializeSharedAudioStream() failing
+ when the `AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM` flag is specified. Setting wasapi.noAutoConvertSRC
+ will result in miniaudio's internal resampler being used instead which will in turn enable the
+ use of low-latency shared mode.
-11.2. PulseAudio
+15.2. PulseAudio
----------------
- If you experience bad glitching/noise on Arch Linux, consider this fix from the Arch wiki:
- https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting#Glitches,_skips_or_crackling. Alternatively, consider using a different backend such as ALSA.
+ https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting#Glitches,_skips_or_crackling.
+ Alternatively, consider using a different backend such as ALSA.
-11.3. Android
+15.3. Android
-------------
-- To capture audio on Android, remember to add the RECORD_AUDIO permission to your manifest: ``
-- With OpenSL|ES, only a single ma_context can be active at any given time. This is due to a limitation with OpenSL|ES.
-- With AAudio, only default devices are enumerated. This is due to AAudio not having an enumeration API (devices are enumerated through Java). You can however
- perform your own device enumeration through Java and then set the ID in the ma_device_id structure (ma_device_id.aaudio) and pass it to ma_device_init().
-- The backend API will perform resampling where possible. The reason for this as opposed to using miniaudio's built-in resampler is to take advantage of any
- potential device-specific optimizations the driver may implement.
+- To capture audio on Android, remember to add the RECORD_AUDIO permission to your manifest:
+ ``
+- With OpenSL|ES, only a single ma_context can be active at any given time. This is due to a
+ limitation with OpenSL|ES.
+- With AAudio, only default devices are enumerated. This is due to AAudio not having an enumeration
+ API (devices are enumerated through Java). You can however perform your own device enumeration
+ through Java and then set the ID in the ma_device_id structure (ma_device_id.aaudio) and pass it
+ to ma_device_init().
+- The backend API will perform resampling where possible. The reason for this as opposed to using
+ miniaudio's built-in resampler is to take advantage of any potential device-specific
+ optimizations the driver may implement.
-11.4. UWP
+15.4. UWP
---------
- UWP only supports default playback and capture devices.
- UWP requires the Microphone capability to be enabled in the application's manifest (Package.appxmanifest):
@@ -1463,28 +3583,49 @@ Some backends have some nuance details you may want to be aware of.
```
-11.5. Web Audio / Emscripten
+15.5. Web Audio / Emscripten
----------------------------
- You cannot use `-std=c*` compiler flags, nor `-ansi`. This only applies to the Emscripten build.
-- The first time a context is initialized it will create a global object called "miniaudio" whose primary purpose is to act as a factory for device objects.
-- Currently the Web Audio backend uses ScriptProcessorNode's, but this may need to change later as they've been deprecated.
-- Google has implemented a policy in their browsers that prevent automatic media output without first receiving some kind of user input. The following web page
- has additional details: https://developers.google.com/web/updates/2017/09/autoplay-policy-changes. Starting the device may fail if you try to start playback
- without first handling some kind of user input.
+- The first time a context is initialized it will create a global object called "miniaudio" whose
+ primary purpose is to act as a factory for device objects.
+- Currently the Web Audio backend uses ScriptProcessorNode's, but this may need to change later as
+ they've been deprecated.
+- Google has implemented a policy in their browsers that prevent automatic media output without
+ first receiving some kind of user input. The following web page has additional details:
+ https://developers.google.com/web/updates/2017/09/autoplay-policy-changes. Starting the device
+ may fail if you try to start playback without first handling some kind of user input.
-12. Miscellaneous Notes
+16. Optimization Tips
+=====================
+
+16.1. High Level API
+--------------------
+- If a sound does not require doppler or pitch shifting, consider disabling pitching by
+ initializing the sound with the `MA_SOUND_FLAG_NO_PITCH` flag.
+- If a sound does not require spatialization, disable it by initialzing the sound with the
+ `MA_SOUND_FLAG_NO_SPATIALIZATION` flag. It can be renabled again post-initialization with
+ `ma_sound_set_spatialization_enabled()`.
+
+
+
+17. Miscellaneous Notes
=======================
-- Automatic stream routing is enabled on a per-backend basis. Support is explicitly enabled for WASAPI and Core Audio, however other backends such as
- PulseAudio may naturally support it, though not all have been tested.
-- The contents of the output buffer passed into the data callback will always be pre-initialized to silence unless the `noPreZeroedOutputBuffer` config variable
- in `ma_device_config` is set to true, in which case it'll be undefined which will require you to write something to the entire buffer.
-- By default miniaudio will automatically clip samples. This only applies when the playback sample format is configured as `ma_format_f32`. If you are doing
- clipping yourself, you can disable this overhead by setting `noClip` to true in the device config.
-- The sndio backend is currently only enabled on OpenBSD builds.
-- The audio(4) backend is supported on OpenBSD, but you may need to disable sndiod before you can use it.
+- Automatic stream routing is enabled on a per-backend basis. Support is explicitly enabled for
+ WASAPI and Core Audio, however other backends such as PulseAudio may naturally support it, though
+ not all have been tested.
+- The contents of the output buffer passed into the data callback will always be pre-initialized to
+ silence unless the `noPreSilencedOutputBuffer` config variable in `ma_device_config` is set to
+ true, in which case it'll be undefined which will require you to write something to the entire
+ buffer.
+- By default miniaudio will automatically clip samples. This only applies when the playback sample
+ format is configured as `ma_format_f32`. If you are doing clipping yourself, you can disable this
+ overhead by setting `noClip` to true in the device config.
- Note that GCC and Clang requires `-msse2`, `-mavx2`, etc. for SIMD optimizations.
-- When compiling with VC6 and earlier, decoding is restricted to files less than 2GB in size. This is due to 64-bit file APIs not being available.
+- The sndio backend is currently only enabled on OpenBSD builds.
+- The audio(4) backend is supported on OpenBSD, but you may need to disable sndiod before you can
+ use it.
+- When compiling with VC6 and earlier, decoding is restricted to files less than 2GB in size. This
+ is due to 64-bit file APIs not being available.
*/
-
diff --git a/vendor/miniaudio/effects.odin b/vendor/miniaudio/effects.odin
new file mode 100644
index 000000000..e86d670d9
--- /dev/null
+++ b/vendor/miniaudio/effects.odin
@@ -0,0 +1,300 @@
+package miniaudio
+
+import c "core:c/libc"
+
+when ODIN_OS == .Windows {
+ foreign import lib "lib/miniaudio.lib"
+} else when ODIN_OS == .Linux {
+ foreign import lib "lib/miniaudio.a"
+} else {
+ foreign import lib "system:miniaudio"
+}
+
+/*
+Delay
+*/
+delay_config :: struct {
+ channels: u32,
+ sampleRate: u32,
+ delayInFrames: u32,
+ delayStart: b32, /* Set to true to delay the start of the output; false otherwise. */
+ wet: f32, /* 0..1. Default = 1. */
+ dry: f32, /* 0..1. Default = 1. */
+ decay: f32, /* 0..1. Default = 0 (no feedback). Feedback decay. Use this for echo. */
+}
+
+delay :: struct {
+ config: delay_config,
+ cursor: u32, /* Feedback is written to this cursor. Always equal or in front of the read cursor. */
+ bufferSizeInFrames: u32, /* The maximum of config.startDelayInFrames and config.feedbackDelayInFrames. */
+ pBuffer: [^]f32,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ delay_config_init :: proc(channels, sampleRate, delayInFrames: u32, decay: f32) -> delay_config ---
+
+ delay_init :: proc(pConfig: ^delay_config, pAllocationCallbacks: ^allocation_callbacks, pDelay: ^delay) -> result ---
+ delay_uninit :: proc(pDelay: ^delay, pAllocationCallbacks: ^allocation_callbacks) ---
+ delay_process_pcm_frames :: proc(pDelay: ^delay, pFramesOut, pFramesIn: rawptr, frameCount: u32) -> result ---
+ delay_set_wet :: proc(pDelay: ^delay, value: f32) ---
+ delay_get_wet :: proc(pDelay: ^delay) -> f32 ---
+ delay_set_dry :: proc(pDelay: ^delay, value: f32) ---
+ delay_get_dry :: proc(pDelay: ^delay) -> f32 ---
+ delay_set_decay :: proc(pDelay: ^delay, value: f32) ---
+ delay_get_decay :: proc(pDelay: ^delay) -> f32 ---
+}
+
+
+/* Gainer for smooth volume changes. */
+gainer_config :: struct {
+ channels: u32,
+ smoothTimeInFrames: u32,
+}
+
+gainer :: struct {
+ config: gainer_config,
+ t: u32,
+ pOldGains: [^]f32,
+ pNewGains: [^]f32,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ gainer_config_init :: proc(channels, smoothTimeInFrames: u32) -> gainer_config ---
+
+ gainer_get_heap_size :: proc(pConfig: ^gainer_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ gainer_init_preallocated :: proc(pConfig: ^gainer_config, pHeap: rawptr, pGainer: ^gainer) -> result ---
+ gainer_init :: proc(pConfig: ^gainer_config, pAllocationCallbacks: ^allocation_callbacks, pGainer: ^gainer) -> result ---
+ gainer_uninit :: proc(pGainer: ^gainer, pAllocationCallbacks: ^allocation_callbacks) ---
+ gainer_process_pcm_frames :: proc(pGainer: ^gainer, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
+ gainer_set_gain :: proc(pGainer: ^gainer, newGain: f32) -> result ---
+ gainer_set_gains :: proc(pGainer: ^gainer, pNewGains: [^]f32) -> result ---
+}
+
+
+/* Stereo panner. */
+pan_mode :: enum c.int {
+ balance = 0, /* Does not blend one side with the other. Technically just a balance. Compatible with other popular audio engines and therefore the default. */
+ pan, /* A true pan. The sound from one side will "move" to the other side and blend with it. */
+}
+
+panner_config :: struct {
+ format: format,
+ channels: u32,
+ mode: pan_mode,
+ pan: f32,
+}
+
+panner :: struct {
+ format: format,
+ channels: u32,
+ mode: pan_mode,
+ pan: f32, /* -1..1 where 0 is no pan, -1 is left side, +1 is right side. Defaults to 0. */
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ panner_config_init :: proc(format: format, channels: u32) -> panner_config ---
+
+ panner_init :: proc(pConfig: ^panner_config, pPanner: ^panner) -> result ---
+ panner_process_pcm_frames :: proc(pPanner: ^panner, pFramesOut, pFramesIn: rawptr, frameCount: u64) -> result ---
+ panner_set_mode :: proc(pPanner: ^panner, mode: pan_mode) ---
+ panner_get_mode :: proc(pPanner: ^panner) -> pan_mode ---
+ panner_set_pan :: proc(pPanner: ^panner, pan: f32) ---
+ panner_get_pan :: proc(pPanner: ^panner) -> f32 ---
+}
+
+
+/* Fader. */
+fader_config :: struct {
+ format: format,
+ channels: u32,
+ sampleRate: u32,
+}
+
+fader :: struct {
+ config: fader_config,
+ volumeBeg: f32, /* If volumeBeg and volumeEnd is equal to 1, no fading happens (ma_fader_process_pcm_frames() will run as a passthrough). */
+ volumeEnd: f32,
+ lengthInFrames: u64, /* The total length of the fade. */
+ cursorInFrames: u64, /* The current time in frames. Incremented by ma_fader_process_pcm_frames(). */
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ fader_config_init :: proc(format: format, channels, sampleRate: u32) -> fader_config ---
+
+ fader_init :: proc(pConfig: ^fader_config, pFader: ^fader) -> result ---
+ fader_process_pcm_frames :: proc(pFader: ^fader, pFramesOut, pFramesIn: rawptr, frameCount: u64) -> result ---
+ fader_get_data_format :: proc(pFader: ^fader, pFormat: ^format, pChannels, pSampleRate: ^u32) ---
+ fader_set_fade :: proc(pFader: ^fader, volumeBeg, volumeEnd: f32, lengthInFrames: u64) ---
+ fader_get_current_volume :: proc(pFader: ^fader) -> f32 ---
+}
+
+
+/* Spatializer. */
+vec3f :: struct {
+ x: f32,
+ y: f32,
+ z: f32,
+}
+
+attenuation_model :: enum c.int {
+ none, /* No distance attenuation and no spatialization. */
+ inverse, /* Equivalent to OpenAL's AL_INVERSE_DISTANCE_CLAMPED. */
+ linear, /* Linear attenuation. Equivalent to OpenAL's AL_LINEAR_DISTANCE_CLAMPED. */
+ exponential, /* Exponential attenuation. Equivalent to OpenAL's AL_EXPONENT_DISTANCE_CLAMPED. */
+}
+
+positioning :: enum c.int {
+ absolute,
+ relative,
+}
+
+handedness :: enum c.int {
+ right,
+ left,
+}
+
+spatializer_listener_config :: struct {
+ channelsOut: u32,
+ pChannelMapOut: [^]channel,
+ handedness: handedness, /* Defaults to right. Forward is -1 on the Z axis. In a left handed system, forward is +1 on the Z axis. */
+ coneInnerAngleInRadians: f32,
+ coneOuterAngleInRadians: f32,
+ coneOuterGain: f32,
+ speedOfSound: f32,
+ worldUp: vec3f,
+}
+
+spatializer_listener :: struct {
+ config: spatializer_listener_config,
+ position: vec3f, /* The absolute position of the listener. */
+ direction: vec3f, /* The direction the listener is facing. The world up vector is config.worldUp. */
+ velocity: vec3f,
+ isEnabled: b32,
+
+ /* Memory management. */
+ _ownsHeap: b32,
+ _pHeap: rawptr,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ spatializer_listener_config_init :: proc(channelsOut: u32) -> spatializer_listener_config ---
+
+ spatializer_listener_get_heap_size :: proc(pConfig: ^spatializer_listener_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ spatializer_listener_init_preallocated :: proc(pConfig: ^spatializer_listener_config, pHeap: rawptr, pListener: ^spatializer_listener) -> result ---
+ spatializer_listener_init :: proc(pConfig: ^spatializer_listener_config, pAllocationCallbacks: ^allocation_callbacks, pListener: ^spatializer_listener) -> result ---
+ spatializer_listener_uninit :: proc(pListener: ^spatializer_listener, pAllocationCallbacks: ^allocation_callbacks) ---
+ spatializer_listener_get_channel_map :: proc(pListener: ^spatializer_listener) -> ^channel ---
+ spatializer_listener_set_cone :: proc(pListener: ^spatializer_listener, innerAngleInRadians, outerAngleInRadians, outerGain: f32) ---
+ spatializer_listener_get_cone :: proc(pListener: ^spatializer_listener, pInnerAngleInRadians, pOuterAngleInRadians, pOuterGain: ^f32) ---
+ spatializer_listener_set_position :: proc(pListener: ^spatializer_listener, x, y, z: f32) ---
+ spatializer_listener_get_position :: proc(pListener: ^spatializer_listener) -> vec3f ---
+ spatializer_listener_set_direction :: proc(pListener: ^spatializer_listener, x, y, z: f32) ---
+ spatializer_listener_get_direction :: proc(pListener: ^spatializer_listener) -> vec3f ---
+ spatializer_listener_set_velocity :: proc(pListener: ^spatializer_listener, x, y, z: f32) ---
+ spatializer_listener_get_velocity :: proc(pListener: ^spatializer_listener) -> vec3f ---
+ spatializer_listener_set_speed_of_sound :: proc(pListener: ^spatializer_listener, speedOfSound: f32) ---
+ spatializer_listener_get_speed_of_sound :: proc(pListener: ^spatializer_listener) -> f32 ---
+ spatializer_listener_set_world_up :: proc(pListener: ^spatializer_listener, x, y, z: f32) ---
+ spatializer_listener_get_world_up :: proc(pListener: ^spatializer_listener) -> vec3f ---
+ spatializer_listener_set_enabled :: proc(pListener: ^spatializer_listener, isEnabled: b32) ---
+ spatializer_listener_is_enabled :: proc(pListener: ^spatializer_listener) -> b32 ---
+}
+
+spatializer_config :: struct {
+ channelsIn: u32,
+ channelsOut: u32,
+ pChannelMapIn: [^]channel,
+ attenuationModel: attenuation_model,
+ positioning: positioning,
+ handedness: handedness, /* Defaults to right. Forward is -1 on the Z axis. In a left handed system, forward is +1 on the Z axis. */
+ minGain: f32,
+ maxGain: f32,
+ minDistance: f32,
+ maxDistance: f32,
+ rolloff: f32,
+ coneInnerAngleInRadians: f32,
+ coneOuterAngleInRadians: f32,
+ coneOuterGain: f32,
+ dopplerFactor: f32, /* Set to 0 to disable doppler effect. */
+ directionalAttenuationFactor: f32, /* Set to 0 to disable directional attenuation. */
+ gainSmoothTimeInFrames: u32, /* When the gain of a channel changes during spatialization, the transition will be linearly interpolated over this number of frames. */
+}
+
+spatializer :: struct {
+ channelsIn: u32,
+ channelsOut: u32,
+ pChannelMapIn: [^]channel,
+ attenuationModel: attenuation_model,
+ positioning: positioning,
+ handedness: handedness, /* Defaults to right. Forward is -1 on the Z axis. In a left handed system, forward is +1 on the Z axis. */
+ minGain: f32,
+ maxGain: f32,
+ minDistance: f32,
+ maxDistance: f32,
+ rolloff: f32,
+ coneInnerAngleInRadians: f32,
+ coneOuterAngleInRadians: f32,
+ coneOuterGain: f32,
+ dopplerFactor: f32, /* Set to 0 to disable doppler effect. */
+ directionalAttenuationFactor: f32, /* Set to 0 to disable directional attenuation. */
+ gainSmoothTimeInFrames: u32, /* When the gain of a channel changes during spatialization, the transition will be linearly interpolated over this number of frames. */
+ position: vec3f,
+ direction: vec3f,
+ velocity: vec3f, /* For doppler effect. */
+ dopplerPitch: f32, /* Will be updated by ma_spatializer_process_pcm_frames() and can be used by higher level functions to apply a pitch shift for doppler effect. */
+ gainer: gainer, /* For smooth gain transitions. */
+ pNewChannelGainsOut: [^]f32, /* An offset of _pHeap. Used by ma_spatializer_process_pcm_frames() to store new channel gains. The number of elements in this array is equal to config.channelsOut. */
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ spatializer_config_init :: proc(channelsIn, channelsOut: u32) -> spatializer_config ---
+
+ spatializer_get_heap_size :: proc(pConfig: ^spatializer_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ spatializer_init_preallocated :: proc(pConfig: ^spatializer_config, pHeap: rawptr, pSpatializer: ^spatializer) -> result ---
+ spatializer_init :: proc(pConfig: ^spatializer_config, pAllocationCallbacks: ^allocation_callbacks, pSpatializer: ^spatializer) -> result ---
+ spatializer_uninit :: proc(pSpatializer: ^spatializer, pAllocationCallbacks: ^allocation_callbacks) ---
+ spatializer_process_pcm_frames :: proc(pSpatializer: ^spatializer, pListener: ^spatializer_listener, pFramesOut, pFramesIn: rawptr, frameCount: u64) -> result ---
+ spatializer_get_input_channels :: proc(pSpatializer: ^spatializer) -> u32 ---
+ spatializer_get_output_channels :: proc(pSpatializer: ^spatializer) -> u32 ---
+ spatializer_set_attenuation_model :: proc(pSpatializer: ^spatializer, attenuationModel: attenuation_model) ---
+ spatializer_get_attenuation_model :: proc(pSpatializer: ^spatializer) -> attenuation_model ---
+ spatializer_set_positioning :: proc(pSpatializer: ^spatializer, positioning: positioning) ---
+ spatializer_get_positioning :: proc(pSpatializer: ^spatializer) -> positioning ---
+ spatializer_set_rolloff :: proc(pSpatializer: ^spatializer, rolloff: f32) ---
+ spatializer_get_rolloff :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_min_gain :: proc(pSpatializer: ^spatializer, minGain: f32) ---
+ spatializer_get_min_gain :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_max_gain :: proc(pSpatializer: ^spatializer, maxGain: f32) ---
+ spatializer_get_max_gain :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_min_distance :: proc(pSpatializer: ^spatializer, minDistance: f32) ---
+ spatializer_get_min_distance :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_max_distance :: proc(pSpatializer: ^spatializer, maxDistance: f32) ---
+ spatializer_get_max_distance :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_cone :: proc(pSpatializer: ^spatializer, innerAngleInRadians, outerAngleInRadians, outerGain: f32) ---
+ spatializer_get_cone :: proc(pSpatializer: ^spatializer, pInnerAngleInRadians, pOuterAngleInRadians, pOuterGain: ^f32) ---
+ spatializer_set_doppler_factor :: proc(pSpatializer: ^spatializer, dopplerFactor: f32) ---
+ spatializer_get_doppler_factor :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_directional_attenuation_factor :: proc(pSpatializer: ^spatializer, directionalAttenuationFactor: f32) ---
+ spatializer_get_directional_attenuation_factor :: proc(pSpatializer: ^spatializer) -> f32 ---
+ spatializer_set_position :: proc(pSpatializer: ^spatializer, x, y, z: f32) ---
+ spatializer_get_position :: proc(pSpatializer: ^spatializer) -> vec3f ---
+ spatializer_set_direction :: proc(pSpatializer: ^spatializer, x, y, z: f32) ---
+ spatializer_get_direction :: proc(pSpatializer: ^spatializer) -> vec3f ---
+ spatializer_set_velocity :: proc(pSpatializer: ^spatializer, x, y, z: f32) ---
+ spatializer_get_velocity :: proc(pSpatializer: ^spatializer) -> vec3f ---
+ spatializer_get_relative_position_and_direction :: proc(pSpatializer: ^spatializer, pListener: ^spatializer_listener, pRelativePos, pRelativeDir: ^vec3f) ---
+}
diff --git a/vendor/miniaudio/encoding.odin b/vendor/miniaudio/encoding.odin
index 9b84108dc..ee396466a 100644
--- a/vendor/miniaudio/encoding.odin
+++ b/vendor/miniaudio/encoding.odin
@@ -19,14 +19,14 @@ Encoders do not perform any format conversion for you. If your target format doe
************************************************************************************************************************************************************/
-encoder_write_proc :: proc "c" (pEncoder: ^encoder, pBufferIn: rawptr, bytesToWrite: c.size_t) -> c.size_t /* Returns the number of bytes written. */
-encoder_seek_proc :: proc "c" (pEncoder: ^encoder, byteOffset: c.int, origin: seek_origin) -> b32
+encoder_write_proc :: proc "c" (pEncoder: ^encoder, pBufferIn: rawptr, bytesToWrite: c.size_t, pBytesWritten: ^c.size_t) -> result
+encoder_seek_proc :: proc "c" (pEncoder: ^encoder, offset: i64, origin: seek_origin) -> result
encoder_init_proc :: proc "c" (pEncoder: ^encoder) -> result
-encoder_uninit_proc :: proc "c" (pEncoder: ^encoder)
-encoder_write_pcm_frames_proc :: proc "c" (pEncoder: ^encoder, pFramesIn: rawptr, frameCount: u64) -> u64
+encoder_uninit_proc :: proc "c" (pEncoder: ^encoder)
+encoder_write_pcm_frames_proc :: proc "c" (pEncoder: ^encoder, pFramesIn: rawptr, frameCount: u64, pFramesWritten: ^u64) -> result
encoder_config :: struct {
- resourceFormat: resource_format,
+ encodingFormat: encoding_format,
format: format,
channels: u32,
sampleRate: u32,
@@ -42,16 +42,23 @@ encoder :: struct {
onWritePCMFrames: encoder_write_pcm_frames_proc,
pUserData: rawptr,
pInternalEncoder: rawptr, /* <-- The drwav/drflac/stb_vorbis/etc. objects. */
- pFile: rawptr, /* FILE*. Only used when initialized with ma_encoder_init_file(). */
+ data: struct #raw_union {
+ vfs: struct {
+ pVFS: ^vfs,
+ file: vfs_file,
+ },
+ },
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
- encoder_config_init :: proc(resourceFormat: resource_format, format: format, channels: u32, sampleRate: u32) -> encoder_config ---
+ encoder_config_init :: proc(encodingFormat: encoding_format, format: format, channels: u32, sampleRate: u32) -> encoder_config ---
encoder_init :: proc(onWrite: encoder_write_proc, onSeek: encoder_seek_proc, pUserData: rawptr, pConfig: ^encoder_config, pEncoder: ^encoder) -> result ---
+ encoder_init_vfs :: proc(pVFS: ^vfs, pFilePath: cstring, pConfig: ^encoder_config, pEncoder: ^encoder) -> result ---
+ encoder_init_vfs_w :: proc(pVFS: ^vfs, pFilePath: [^]c.wchar_t, pConfig: ^encoder_config, pEncoder: ^encoder) -> result ---
encoder_init_file :: proc(pFilePath: cstring, pConfig: ^encoder_config, pEncoder: ^encoder) -> result ---
encoder_init_file_w :: proc(pFilePath: [^]c.wchar_t, pConfig: ^encoder_config, pEncoder: ^encoder) -> result ---
encoder_uninit :: proc(pEncoder: ^encoder) ---
- encoder_write_pcm_frames :: proc(pEncoder: ^encoder, FramesIn: rawptr, frameCount: u64) -> u64 ---
+ encoder_write_pcm_frames :: proc(pEncoder: ^encoder, FramesIn: rawptr, frameCount: u64, pFramesWritten: ^u64) -> result ---
}
diff --git a/vendor/miniaudio/engine.odin b/vendor/miniaudio/engine.odin
new file mode 100644
index 000000000..935d54744
--- /dev/null
+++ b/vendor/miniaudio/engine.odin
@@ -0,0 +1,341 @@
+package miniaudio
+
+import "core:c"
+
+when ODIN_OS == .Windows {
+ foreign import lib "lib/miniaudio.lib"
+} else when ODIN_OS == .Linux {
+ foreign import lib "lib/miniaudio.a"
+} else {
+ foreign import lib "system:miniaudio"
+}
+
+/************************************************************************************************************************************************************
+
+Engine
+
+************************************************************************************************************************************************************/
+
+/* Sound flags. */
+sound_flags :: enum c.int {
+ STREAM = 0x00000001, /* MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_STREAM */
+ DECODE = 0x00000002, /* MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_DECODE */
+ ASYNC = 0x00000004, /* MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_ASYNC */
+ WAIT_INIT = 0x00000008, /* MA_RESOURCE_MANAGER_DATA_SOURCE_FLAG_WAIT_INIT */
+ NO_DEFAULT_ATTACHMENT = 0x00000010, /* Do not attach to the endpoint by default. Useful for when setting up nodes in a complex graph system. */
+ NO_PITCH = 0x00000020, /* Disable pitch shifting with ma_sound_set_pitch() and ma_sound_group_set_pitch(). This is an optimization. */
+ NO_SPATIALIZATION = 0x00000040, /* Disable spatialization. */
+}
+
+ENGINE_MAX_LISTENERS :: 4
+
+LISTENER_INDEX_CLOSEST :: 255
+
+engine_node_type :: enum c.int {
+ sound,
+ group,
+}
+
+engine_node_config :: struct {
+ pEngine: ^engine,
+ type: engine_node_type,
+ channelsIn: u32,
+ channelsOut: u32,
+ sampleRate: u32, /* Only used when the type is set to ma_engine_node_type_sound. */
+ isPitchDisabled: b8, /* Pitching can be explicitly disable with MA_SOUND_FLAG_NO_PITCH to optimize processing. */
+ isSpatializationDisabled: b8, /* Spatialization can be explicitly disabled with MA_SOUND_FLAG_NO_SPATIALIZATION. */
+ pinnedListenerIndex: u8, /* The index of the listener this node should always use for spatialization. If set to MA_LISTENER_INDEX_CLOSEST the engine will use the closest listener. */
+}
+
+/* Base node object for both ma_sound and ma_sound_group. */
+engine_node :: struct {
+ baseNode: node_base, /* Must be the first member for compatiblity with the ma_node API. */
+ pEngine: ^engine, /* A pointer to the engine. Set based on the value from the config. */
+ sampleRate: u32, /* The sample rate of the input data. For sounds backed by a data source, this will be the data source's sample rate. Otherwise it'll be the engine's sample rate. */
+ fader: fader,
+ resampler: linear_resampler, /* For pitch shift. */
+ spatializer: spatializer,
+ panner: panner,
+ pitch: f32, /*atomic*/
+ oldPitch: f32, /* For determining whether or not the resampler needs to be updated to reflect the new pitch. The resampler will be updated on the mixing thread. */
+ oldDopplerPitch: f32, /* For determining whether or not the resampler needs to be updated to take a new doppler pitch into account. */
+ isPitchDisabled: b32, /*atomic*/ /* When set to true, pitching will be disabled which will allow the resampler to be bypassed to save some computation. */
+ isSpatializationDisabled: b32, /*atomic*/ /* Set to false by default. When set to false, will not have spatialisation applied. */
+ pinnedListenerIndex: u32, /*atomic*/ /* The index of the listener this node should always use for spatialization. If set to MA_LISTENER_INDEX_CLOSEST the engine will use the closest listener. */
+
+ /* Memory management. */
+ _ownsHeap: b8,
+ _pHeap: rawptr,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ engine_node_config_init :: proc(pEngine: ^engine, type: engine_node_type, flags: u32) -> engine_node_config ---
+
+ engine_node_get_heap_size :: proc(pConfig: ^engine_node_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ engine_node_init_preallocated :: proc(pConfig: ^engine_node_config, pHeap: rawptr, pEngineNode: ^engine_node) -> result ---
+ engine_node_init :: proc(pConfig: ^engine_node_config, pAllocationCallbacks: ^allocation_callbacks, pEngineNode: ^engine_node) -> result ---
+ engine_node_uninit :: proc(pEngineNode: ^engine_node, pAllocationCallbacks: ^allocation_callbacks) ---
+}
+
+
+SOUND_SOURCE_CHANNEL_COUNT :: 0xFFFFFFFF
+
+sound_config :: struct {
+ pFilePath: cstring, /* Set this to load from the resource manager. */
+ pFilePathW: [^]c.wchar_t, /* Set this to load from the resource manager. */
+ pDataSource: ^data_source, /* Set this to load from an existing data source. */
+ pInitialAttachment: ^node, /* If set, the sound will be attached to an input of this node. This can be set to a ma_sound. If set to NULL, the sound will be attached directly to the endpoint unless MA_SOUND_FLAG_NO_DEFAULT_ATTACHMENT is set in `flags`. */
+ initialAttachmentInputBusIndex: u32, /* The index of the input bus of pInitialAttachment to attach the sound to. */
+ channelsIn: u32, /* Ignored if using a data source as input (the data source's channel count will be used always). Otherwise, setting to 0 will cause the engine's channel count to be used. */
+ channelsOut: u32, /* Set this to 0 (default) to use the engine's channel count. Set to MA_SOUND_SOURCE_CHANNEL_COUNT to use the data source's channel count (only used if using a data source as input). */
+ flags: u32, /* A combination of MA_SOUND_FLAG_* flags. */
+ initialSeekPointInPCMFrames: u64, /* Initializes the sound such that it's seeked to this location by default. */
+ rangeBegInPCMFrames: u64,
+ rangeEndInPCMFrames: u64,
+ loopPointBegInPCMFrames: u64,
+ loopPointEndInPCMFrames: u64,
+ isLooping: b32,
+ pDoneFence: ^fence, /* Released when the resource manager has finished decoding the entire sound. Not used with streams. */
+}
+
+sound :: struct {
+ engineNode: engine_node, /* Must be the first member for compatibility with the ma_node API. */
+ pDataSource: ^data_source,
+ seekTarget: u64, /*atomic*/ /* The PCM frame index to seek to in the mixing thread. Set to (~(ma_uint64)0) to not perform any seeking. */
+ atEnd: b32, /*atomic*/
+ ownsDataSource: b8,
+
+ /*
+ We're declaring a resource manager data source object here to save us a malloc when loading a
+ sound via the resource manager, which I *think* will be the most common scenario.
+ */
+ pResourceManagerDataSource: ^resource_manager_data_source,
+}
+
+/* Structure specifically for sounds played with ma_engine_play_sound(). Making this a separate structure to reduce overhead. */
+sound_inlined :: struct {
+ sound: sound,
+ pNext: ^sound_inlined,
+ pPrev: ^sound_inlined,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ sound_config_init :: proc() -> sound_config ---
+
+ sound_init_from_file :: proc(pEngine: ^engine, pFilePath: cstring, flags: u32, pGroup: ^sound_group, pDoneFence: ^fence, pSound: ^sound) -> result ---
+ sound_init_from_file_w :: proc(pEngine: ^engine, pFilePath: [^]c.wchar_t, flags: u32, pGroup: ^sound_group, pDoneFence: ^fence, pSound: ^sound) -> result ---
+ sound_init_copy :: proc(pEngine: ^engine, pExistingSound: ^sound, flags: u32, pGroup: ^sound_group, pSound: ^sound) -> result ---
+ sound_init_from_data_source :: proc(pEngine: ^engine, pDataSource: ^data_source, flags: u32, pGroup: ^sound_group, pSound: ^sound) -> result ---
+ sound_init_ex :: proc(pEngine: ^engine, pConfig: ^sound_config, pSound: ^sound) -> result ---
+ sound_uninit :: proc(pSound: ^sound) ---
+ sound_get_engine :: proc(pSound: ^sound) -> ^engine ---
+ sound_get_data_source :: proc(pSound: ^sound) -> ^data_source ---
+ sound_start :: proc(pSound: ^sound) -> result ---
+ sound_stop :: proc(pSound: ^sound) -> result ---
+ sound_set_volume :: proc(pSound: ^sound, volume: f32) ---
+ sound_get_volume :: proc(pSound: ^sound) -> f32 ---
+ sound_set_pan :: proc(pSound: ^sound, pan: f32) ---
+ sound_get_pan :: proc(pSound: ^sound) -> f32 ---
+ sound_set_pan_mode :: proc(pSound: ^sound, panMode: pan_mode) ---
+ sound_get_pan_mode :: proc(pSound: ^sound) -> pan_mode ---
+ sound_set_pitch :: proc(pSound: ^sound, pitch: f32) ---
+ sound_get_pitch :: proc(pSound: ^sound) -> f32 ---
+ sound_set_spatialization_enabled :: proc(pSound: ^sound, enabled: b32) ---
+ sound_is_spatialization_enabled :: proc(pSound: ^sound) -> b32 ---
+ sound_set_pinned_listener_index :: proc(pSound: ^sound, listenerIndex: u32) ---
+ sound_get_pinned_listener_index :: proc(pSound: ^sound) -> u32 ---
+ sound_get_listener_index :: proc(pSound: ^sound) -> u32 ---
+ sound_get_direction_to_listener :: proc(pSound: ^sound) -> vec3f ---
+ sound_set_position :: proc(pSound: ^sound, x, y, z: f32) ---
+ sound_get_position :: proc(pSound: ^sound) -> vec3f ---
+ sound_set_direction :: proc(pSound: ^sound, x, y, z: f32) ---
+ sound_get_direction :: proc(pSound: ^sound) -> vec3f ---
+ sound_set_velocity :: proc(pSound: ^sound, x, y, z: f32) ---
+ sound_get_velocity :: proc(pSound: ^sound) -> vec3f ---
+ sound_set_attenuation_model :: proc(pSound: ^sound, attenuationModel: attenuation_model) ---
+ sound_get_attenuation_model :: proc(pSound: ^sound) -> attenuation_model ---
+ sound_set_positioning :: proc(pSound: ^sound, positioning: positioning) ---
+ sound_get_positioning :: proc(pSound: ^sound) -> positioning ---
+ sound_set_rolloff :: proc(pSound: ^sound, rolloff: f32) ---
+ sound_get_rolloff :: proc(pSound: ^sound) -> f32 ---
+ sound_set_min_gain :: proc(pSound: ^sound, minGain: f32) ---
+ sound_get_min_gain :: proc(pSound: ^sound) -> f32 ---
+ sound_set_max_gain :: proc(pSound: ^sound, maxGain: f32) ---
+ sound_get_max_gain :: proc(pSound: ^sound) -> f32 ---
+ sound_set_min_distance :: proc(pSound: ^sound, minDistance: f32) ---
+ sound_get_min_distance :: proc(pSound: ^sound) -> f32 ---
+ sound_set_max_distance :: proc(pSound: ^sound, maxDistance: f32) ---
+ sound_get_max_distance :: proc(pSound: ^sound) -> f32 ---
+ sound_set_cone :: proc(pSound: ^sound, innerAngleInRadians, outerAngleInRadians, outerGain: f32) ---
+ sound_get_cone :: proc(pSound: ^sound, pInnerAngleInRadians, pOuterAngleInRadians, pOuterGain: ^f32) ---
+ sound_set_doppler_factor :: proc(pSound: ^sound, dopplerFactor: f32) ---
+ sound_get_doppler_factor :: proc(pSound: ^sound) -> f32 ---
+ sound_set_directional_attenuation_factor :: proc(pSound: ^sound, directionalAttenuationFactor: f32) ---
+ sound_get_directional_attenuation_factor :: proc(pSound: ^sound) -> f32 ---
+ sound_set_fade_in_pcm_frames :: proc(pSound: ^sound, volumeBeg, volumeEnd: f32, fadeLengthInFrames: u64) ---
+ sound_set_fade_in_milliseconds :: proc(pSound: ^sound, volumeBeg, volumeEnd: f32, fadeLengthInMilliseconds: u64) ---
+ sound_get_current_fade_volume :: proc(pSound: ^sound) -> f32 ---
+ sound_set_start_time_in_pcm_frames :: proc(pSound: ^sound, absoluteGlobalTimeInFrames: u64) ---
+ sound_set_start_time_in_milliseconds :: proc(pSound: ^sound, absoluteGlobalTimeInMilliseconds: u64) ---
+ sound_set_stop_time_in_pcm_frames :: proc(pSound: ^sound, absoluteGlobalTimeInFrames: u64) ---
+ sound_set_stop_time_in_milliseconds :: proc(pSound: ^sound, absoluteGlobalTimeInMilliseconds: u64) ---
+ sound_is_playing :: proc(pSound: ^sound) -> b32 ---
+ sound_get_time_in_pcm_frames :: proc(pSound: ^sound) -> u64 ---
+ sound_set_looping :: proc(pSound: ^sound, isLooping: b32) ---
+ sound_is_looping :: proc(pSound: ^sound) -> b32 ---
+ sound_at_end :: proc(pSound: ^sound) -> b32 ---
+ sound_seek_to_pcm_frame :: proc(pSound: ^sound, frameIndex: u64) -> result --- /* Just a wrapper around ma_data_source_seek_to_pcm_frame(). */
+ sound_get_data_format :: proc(pSound: ^sound, pFormat: ^format, pChannels, pSampleRate: ^u32, pChannelMap: ^channel, channelMapCap: c.size_t) -> result ---
+ sound_get_cursor_in_pcm_frames :: proc(pSound: ^sound, pCursor: ^u64) -> result ---
+ sound_get_length_in_pcm_frames :: proc(pSound: ^sound, pLength: ^u64) -> result ---
+ sound_get_cursor_in_seconds :: proc(pSound: ^sound, pCursor: ^f32) -> result ---
+ sound_get_length_in_seconds :: proc(pSound: ^sound, pLength: ^f32) -> result ---
+}
+
+
+/* A sound group is just a sound. */
+sound_group_config :: distinct sound_config
+sound_group :: distinct sound
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ sound_group_config_init :: proc() -> sound_group_config ---
+
+ sound_group_init :: proc(pEngine: ^engine, flags: u32, pParentGroup, pGroup: ^sound_group) -> result ---
+ sound_group_init_ex :: proc(pEngine: ^engine, pConfig: ^sound_group_config, pGroup: ^sound_group) -> result ---
+ sound_group_uninit :: proc(pGroup: ^sound_group) ---
+ sound_group_get_engine :: proc(pGroup: ^sound_group) -> ^engine ---
+ sound_group_start :: proc(pGroup: ^sound_group) -> result ---
+ sound_group_stop :: proc(pGroup: ^sound_group) -> result ---
+ sound_group_set_volume :: proc(pGroup: ^sound_group, volume: f32) ---
+ sound_group_get_volume :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_pan :: proc(pGroup: ^sound_group, pan: f32) ---
+ sound_group_get_pan :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_pan_mode :: proc(pGroup: ^sound_group, panMode: pan_mode) ---
+ sound_group_get_pan_mode :: proc(pGroup: ^sound_group) -> pan_mode ---
+ sound_group_set_pitch :: proc(pGroup: ^sound_group, pitch: f32) ---
+ sound_group_get_pitch :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_spatialization_enabled :: proc(pGroup: ^sound_group, enabled: b32) ---
+ sound_group_is_spatialization_enabled :: proc(pGroup: ^sound_group) -> b32 ---
+ sound_group_set_pinned_listener_index :: proc(pGroup: ^sound_group, listenerIndex: u32) ---
+ sound_group_get_pinned_listener_index :: proc(pGroup: ^sound_group) -> u32 ---
+ sound_group_get_listener_index :: proc(pGroup: ^sound_group) -> u32 ---
+ sound_group_get_direction_to_listener :: proc(pGroup: ^sound_group) -> vec3f ---
+ sound_group_set_position :: proc(pGroup: ^sound_group, x, y, z: f32) ---
+ sound_group_get_position :: proc(pGroup: ^sound_group) -> vec3f ---
+ sound_group_set_direction :: proc(pGroup: ^sound_group, x, y, z: f32) ---
+ sound_group_get_direction :: proc(pGroup: ^sound_group) -> vec3f ---
+ sound_group_set_velocity :: proc(pGroup: ^sound_group, x, y, z: f32) ---
+ sound_group_get_velocity :: proc(pGroup: ^sound_group) -> vec3f ---
+ sound_group_set_attenuation_model :: proc(pGroup: ^sound_group, attenuationModel: attenuation_model) ---
+ sound_group_get_attenuation_model :: proc(pGroup: ^sound_group) -> attenuation_model ---
+ sound_group_set_positioning :: proc(pGroup: ^sound_group, positioning: positioning) ---
+ sound_group_get_positioning :: proc(pGroup: ^sound_group) -> positioning ---
+ sound_group_set_rolloff :: proc(pGroup: ^sound_group, rolloff: f32) ---
+ sound_group_get_rolloff :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_min_gain :: proc(pGroup: ^sound_group, minGain: f32) ---
+ sound_group_get_min_gain :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_max_gain :: proc(pGroup: ^sound_group, maxGain: f32) ---
+ sound_group_get_max_gain :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_min_distance :: proc(pGroup: ^sound_group, minDistance: f32) ---
+ sound_group_get_min_distance :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_max_distance :: proc(pGroup: ^sound_group, maxDistance: f32) ---
+ sound_group_get_max_distance :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_cone :: proc(pGroup: ^sound_group, innerAngleInRadians, outerAngleInRadians, outerGain: f32) ---
+ sound_group_get_cone :: proc(pGroup: ^sound_group, pInnerAngleInRadians, pOuterAngleInRadians, pOuterGain: ^f32) ---
+ sound_group_set_doppler_factor :: proc(pGroup: ^sound_group, dopplerFactor: f32) ---
+ sound_group_get_doppler_factor :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_directional_attenuation_factor :: proc(pGroup: ^sound_group, directionalAttenuationFactor: f32) ---
+ sound_group_get_directional_attenuation_factor :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_fade_in_pcm_frames :: proc(pGroup: ^sound_group, volumeBeg, volumeEnd: f32, fadeLengthInFrames: u64) ---
+ sound_group_set_fade_in_milliseconds :: proc(pGroup: ^sound_group, volumeBeg, volumeEnd: f32, fadeLengthInMilliseconds: u64) ---
+ sound_group_get_current_fade_volume :: proc(pGroup: ^sound_group) -> f32 ---
+ sound_group_set_start_time_in_pcm_frames :: proc(pGroup: ^sound_group, absoluteGlobalTimeInFrames: u64) ---
+ sound_group_set_start_time_in_milliseconds :: proc(pGroup: ^sound_group, absoluteGlobalTimeInMilliseconds: u64) ---
+ sound_group_set_stop_time_in_pcm_frames :: proc(pGroup: ^sound_group, absoluteGlobalTimeInFrames: u64) ---
+ sound_group_set_stop_time_in_milliseconds :: proc(pGroup: ^sound_group, absoluteGlobalTimeInMilliseconds: u64) ---
+ sound_group_is_playing :: proc(pGroup: ^sound_group) -> b32 ---
+ sound_group_get_time_in_pcm_frames :: proc(pGroup: ^sound_group) -> u64 ---
+}
+
+
+engine_config :: struct {
+ pResourceManager: ^resource_manager, /* Can be null in which case a resource manager will be created for you. */
+ pContext: ^context_type,
+ pDevice: ^device, /* If set, the caller is responsible for calling ma_engine_data_callback() in the device's data callback. */
+ pPlaybackDeviceID: ^device_id, /* The ID of the playback device to use with the default listener. */
+ pLog: ^log, /* When set to NULL, will use the context's log. */
+ listenerCount: u32, /* Must be between 1 and MA_ENGINE_MAX_LISTENERS. */
+ channels: u32, /* The number of channels to use when mixing and spatializing. When set to 0, will use the native channel count of the device. */
+ sampleRate: u32, /* The sample rate. When set to 0 will use the native channel count of the device. */
+ periodSizeInFrames: u32, /* If set to something other than 0, updates will always be exactly this size. The underlying device may be a different size, but from the perspective of the mixer that won't matter.*/
+ periodSizeInMilliseconds: u32, /* Used if periodSizeInFrames is unset. */
+ gainSmoothTimeInFrames: u32, /* The number of frames to interpolate the gain of spatialized sounds across. If set to 0, will use gainSmoothTimeInMilliseconds. */
+ gainSmoothTimeInMilliseconds: u32, /* When set to 0, gainSmoothTimeInFrames will be used. If both are set to 0, a default value will be used. */
+ allocationCallbacks: allocation_callbacks,
+ noAutoStart: b32, /* When set to true, requires an explicit call to ma_engine_start(). This is false by default, meaning the engine will be started automatically in ma_engine_init(). */
+ noDevice: b32, /* When set to true, don't create a default device. ma_engine_read_pcm_frames() can be called manually to read data. */
+ monoExpansionMode: mono_expansion_mode, /* Controls how the mono channel should be expanded to other channels when spatialization is disabled on a sound. */
+ pResourceManagerVFS: ^vfs, /* A pointer to a pre-allocated VFS object to use with the resource manager. This is ignored if pResourceManager is not NULL. */
+}
+
+engine :: struct {
+ nodeGraph: node_graph, /* An engine is a node graph. It should be able to be plugged into any ma_node_graph API (with a cast) which means this must be the first member of this struct. */
+ pResourceManager: ^resource_manager,
+ pDevice: ^device, /* Optionally set via the config, otherwise allocated by the engine in ma_engine_init(). */
+ pLog: ^log,
+ sampleRate: u32,
+ listenerCount: u32,
+ listeners: [ENGINE_MAX_LISTENERS]spatializer_listener,
+ allocationCallbacks: allocation_callbacks,
+ ownsResourceManager: b8,
+ ownsDevice: b8,
+ inlinedSoundLock: spinlock, /* For synchronizing access so the inlined sound list. */
+ pInlinedSoundHead: ^sound_inlined, /* The first inlined sound. Inlined sounds are tracked in a linked list. */
+ inlinedSoundCount: u32, /*atomic*/ /* The total number of allocated inlined sound objects. Used for debugging. */
+ gainSmoothTimeInFrames: u32, /* The number of frames to interpolate the gain of spatialized sounds across. */
+ monoExpansionMode: mono_expansion_mode,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ engine_config_init :: proc() -> engine_config ---
+
+ engine_init :: proc(pConfig: ^engine_config, pEngine: ^engine) -> result ---
+ engine_uninit :: proc(pEngine: ^engine) ---
+ engine_read_pcm_frames :: proc(pEngine: ^engine, pFramesOut: rawptr, frameCount: u64, pFramesRead: ^u64) -> result ---
+ engine_get_node_graph :: proc(pEngine: ^engine) -> ^node_graph ---
+ engine_get_resource_manager :: proc(pEngine: ^engine) -> ^resource_manager ---
+ engine_get_device :: proc(pEngine: ^engine) -> ^device ---
+ engine_get_log :: proc(pEngine: ^engine) -> ^log ---
+ engine_get_endpoint :: proc(pEngine: ^engine) -> ^node ---
+ engine_get_time :: proc(pEngine: ^engine) -> u64 ---
+ engine_set_time :: proc(pEngine: ^engine, globalTime: u64) -> result ---
+ engine_get_channels :: proc(pEngine: ^engine) -> u32 ---
+ engine_get_sample_rate :: proc(pEngine: ^engine) -> u32 ---
+
+ engine_start :: proc(pEngine: ^engine) -> result ---
+ engine_stop :: proc(pEngine: ^engine) -> result ---
+ engine_set_volume :: proc(pEngine: ^engine, volume: f32) -> result ---
+ engine_set_gain_db :: proc(pEngine: ^engine, gainDB: f32) -> result ---
+
+ engine_get_listener_count :: proc(pEngine: ^engine) -> u32 ---
+ engine_find_closest_listener :: proc(pEngine: ^engine, absolutePosX, absolutePosY, absolutePosZ: f32) -> u32 ---
+ engine_listener_set_position :: proc(pEngine: ^engine, listenerIndex: u32, x, y, z: f32) ---
+ engine_listener_get_position :: proc(pEngine: ^engine, listenerIndex: u32) -> vec3f ---
+ engine_listener_set_direction :: proc(pEngine: ^engine, listenerIndex: u32, x, y, z: f32) ---
+ engine_listener_get_direction :: proc(pEngine: ^engine, listenerIndex: u32) -> vec3f ---
+ engine_listener_set_velocity :: proc(pEngine: ^engine, listenerIndex: u32, x, y, z: f32) ---
+ engine_listener_get_velocity :: proc(pEngine: ^engine, listenerIndex: u32) -> vec3f ---
+ engine_listener_set_cone :: proc(pEngine: ^engine, listenerIndex: u32, innerAngleInRadians, outerAngleInRadians, outerGain: f32) ---
+ engine_listener_get_cone :: proc(pEngine: ^engine, listenerIndex: u32, pInnerAngleInRadians, pOuterAngleInRadians, pOuterGain: ^f32) ---
+ engine_listener_set_world_up :: proc(pEngine: ^engine, listenerIndex: u32, x, y, z: f32) ---
+ engine_listener_get_world_up :: proc(pEngine: ^engine, listenerIndex: u32) -> vec3f ---
+ engine_listener_set_enabled :: proc(pEngine: ^engine, listenerIndex: u32, isEnabled: b32) ---
+ engine_listener_is_enabled :: proc(pEngine: ^engine, listenerIndex: u32) -> b32 ---
+
+ engine_play_sound_ex :: proc(pEngine: ^engine, pFilePath: cstring, pNode: ^node, nodeInputBusIndex: u32) -> result ---
+ engine_play_sound :: proc(pEngine: ^engine, pFilePath: cstring, pGroup: ^sound_group) -> result --- /* Fire and forget. */
+}
diff --git a/vendor/miniaudio/filtering.odin b/vendor/miniaudio/filtering.odin
index 9949f6338..b8175c372 100644
--- a/vendor/miniaudio/filtering.odin
+++ b/vendor/miniaudio/filtering.odin
@@ -1,5 +1,7 @@
package miniaudio
+import c "core:c/libc"
+
when ODIN_OS == .Windows {
foreign import lib "lib/miniaudio.lib"
} else when ODIN_OS == .Linux {
@@ -19,14 +21,14 @@ biquad_coefficient :: struct #raw_union {
}
biquad_config :: struct {
- format: format,
+ format: format,
channels: u32,
- b0: f64,
- b1: f64,
- b2: f64,
- a0: f64,
- a1: f64,
- a2: f64,
+ b0: f64,
+ b1: f64,
+ b2: f64,
+ a0: f64,
+ a1: f64,
+ a2: f64,
}
biquad :: struct {
@@ -37,17 +39,25 @@ biquad :: struct {
b2: biquad_coefficient,
a1: biquad_coefficient,
a2: biquad_coefficient,
- r1: [MAX_CHANNELS]biquad_coefficient,
- r2: [MAX_CHANNELS]biquad_coefficient,
+ pR1: ^biquad_coefficient,
+ pR2: ^biquad_coefficient,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
biquad_config_init :: proc(format: format, channels: u32, b0, b1, b2, a0, a1, a2: f64) -> biquad_config ---
- biquad_init :: proc(pConfig: ^biquad_config, pBQ: ^biquad) -> result ---
+ biquad_get_heap_size :: proc(pConfig: ^biquad_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ biquad_init_preallocated :: proc(pConfig: ^biquad_config, pHeap: rawptr, pBQ: ^biquad) -> result ---
+ biquad_init :: proc(pConfig: ^biquad_config, pAllocationCallbacks: ^allocation_callbacks, pBQ: ^biquad) -> result ---
+ biquad_uninit :: proc(pBQ: ^biquad, pAllocationCallbacks: ^allocation_callbacks) ---
biquad_reinit :: proc(pConfig: ^biquad_config, pBQ: ^biquad) -> result ---
- biquad_process_pcm_frames :: proc(pBQ: ^biquad, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
+ biquad_clear_cache :: proc(pBQ: ^biquad) -> result ---
+ biquad_process_pcm_frames :: proc(pBQ: ^biquad, pFramesOut, pFramesIn: rawptr, frameCount: u64) -> result ---
biquad_get_latency :: proc(pBQ: ^biquad) -> u32 ---
}
@@ -70,7 +80,11 @@ lpf1 :: struct {
format: format,
channels: u32,
a: biquad_coefficient,
- r1: [MAX_CHANNELS]biquad_coefficient,
+ pR1: ^biquad_coefficient,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
lpf2 :: struct {
@@ -91,8 +105,12 @@ lpf :: struct {
sampleRate: u32,
lpf1Count: u32,
lpf2Count: u32,
- lpf1: [1]lpf1,
- lpf2: [MAX_FILTER_ORDER/2]lpf2,
+ pLPF1: ^lpf1,
+ pLPF2: ^lpf2,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@@ -101,20 +119,32 @@ foreign lib {
lpf1_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64) -> lpf1_config ---
lpf2_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency, q: f64) -> lpf2_config ---
- lpf1_init :: proc(pConfig: ^lpf1_config, pLPF: ^lpf1) -> result ---
+ lpf1_get_heap_size :: proc(pConfig: ^lpf1_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ lpf1_init_preallocated :: proc(pConfig: ^lpf1_config, pHeap: rawptr, pLPF: ^lpf1) -> result ---
+ lpf1_init :: proc(pConfig: ^lpf1_config, pAllocationCallbacks: ^allocation_callbacks, pLPF: ^lpf1) -> result ---
+ lpf1_uninit :: proc(pLPF: ^lpf1, pAllocationCallbacks: ^allocation_callbacks) ---
lpf1_reinit :: proc(pConfig: ^lpf1_config, pLPF: ^lpf1) -> result ---
+ lpf1_clear_cache :: proc(pLPF: ^lpf1) -> result ---
lpf1_process_pcm_frames :: proc(pLPF: ^lpf1, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
lpf1_get_latency :: proc(pLPF: ^lpf1) -> u32 ---
- lpf2_init :: proc(pConfig: ^lpf2_config, pLPF: ^lpf2) -> result ---
+ lpf2_get_heap_size :: proc(pConfig: ^lpf2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ lpf2_init_preallocated :: proc(pConfig: ^lpf2_config, pHeap: rawptr, pHPF: ^lpf2) -> result ---
+ lpf2_init :: proc(pConfig: ^lpf2_config, pAllocationCallbacks: ^allocation_callbacks, pLPF: ^lpf2) -> result ---
+ lpf2_uninit :: proc(pLPF: ^lpf2, pAllocationCallbacks: ^allocation_callbacks) ---
lpf2_reinit :: proc(pConfig: ^lpf2_config, pLPF: ^lpf2) -> result ---
+ lpf2_clear_cache :: proc(pLPF: ^lpf2) -> result ---
lpf2_process_pcm_frames :: proc(pLPF: ^lpf2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
lpf2_get_latency :: proc(pLPF: ^lpf2) -> u32 ---
lpf_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64, order: u32) -> lpf_config ---
- lpf_init :: proc(pConfig: ^lpf_config, pLPF: ^lpf) -> result ---
+ lpf_get_heap_size :: proc(pConfig: ^lpf_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ lpf_init_preallocated :: proc(pConfig: ^lpf_config, pHeap: rawptr, pLPF: ^lpf) -> result ---
+ lpf_init :: proc(pConfig: ^lpf_config, pAllocationCallbacks: ^allocation_callbacks, pLPF: ^lpf) -> result ---
+ lpf_uninit :: proc(pLPF: ^lpf, pAllocationCallbacks: ^allocation_callbacks) ---
lpf_reinit :: proc(pConfig: ^lpf_config, pLPF: ^lpf) -> result ---
+ lpf_clear_cache :: proc(pLPF: ^lpf) -> result ---
lpf_process_pcm_frames :: proc(pLPF: ^lpf, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
lpf_get_latency :: proc(pLPF: ^lpf) -> u32 ---
}
@@ -138,7 +168,11 @@ hpf1 :: struct {
format: format,
channels: u32,
a: biquad_coefficient,
- r1: [MAX_CHANNELS]biquad_coefficient,
+ pR1: ^biquad_coefficient,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
hpf2 :: struct {
@@ -159,8 +193,12 @@ hpf :: struct {
sampleRate: u32,
hpf1Count: u32,
hpf2Count: u32,
- hpf1: [1]hpf1,
- hpf2: [MAX_FILTER_ORDER/2]hpf2,
+ pHPF1: ^hpf1,
+ pHPF2: ^hpf2,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@@ -169,19 +207,28 @@ foreign lib {
hpf1_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64) -> hpf1_config ---
hpf2_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency, q: f64) -> hpf2_config ---
- hpf1_init :: proc(pConfig: ^hpf1_config, pHPF: ^hpf1) -> result ---
+ hpf1_get_heap_size :: proc(pConfig: ^hpf1_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ hpf1_init_preallocated :: proc(pConfig: ^hpf1_config, pHeap: rawptr, pLPF: ^hpf1) -> result ---
+ hpf1_init :: proc(pConfig: ^hpf1_config, pAllocationCallbacks: ^allocation_callbacks, pHPF: ^hpf1) -> result ---
+ hpf1_uninit :: proc(pHPF: ^hpf1, pAllocationCallbacks: ^allocation_callbacks) ---
hpf1_reinit :: proc(pConfig: ^hpf1_config, pHPF: ^hpf1) -> result ---
hpf1_process_pcm_frames :: proc(pHPF: ^hpf1, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
hpf1_get_latency :: proc(pHPF: ^hpf1) -> u32 ---
- hpf2_init :: proc(pConfig: ^hpf2_config, pHPF: ^hpf2) -> result ---
+ hpf2_get_heap_size :: proc(pConfig: ^hpf2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ hpf2_init_preallocated :: proc(pConfig: ^hpf2_config, pHeap: rawptr, pHPF: ^hpf2) -> result ---
+ hpf2_init :: proc(pConfig: ^hpf2_config, pAllocationCallbacks: ^allocation_callbacks, pHPF: ^hpf2) -> result ---
+ hpf2_uninit :: proc(pHPF: ^hpf2, pAllocationCallbacks: ^allocation_callbacks) ---
hpf2_reinit :: proc(pConfig: ^hpf2_config, pHPF: ^hpf2) -> result ---
hpf2_process_pcm_frames :: proc(pHPF: ^hpf2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
hpf2_get_latency :: proc(pHPF: ^hpf2) -> u32 ---
hpf_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64, order: u32) -> hpf_config ---
- hpf_init :: proc(pConfig: ^hpf_config, pHPF: ^hpf) -> result ---
+ hpf_get_heap_size :: proc(pConfig: ^hpf_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ hpf_init_preallocated :: proc(pConfig: ^hpf_config, pHeap: rawptr, pLPF: ^hpf) -> result ---
+ hpf_init :: proc(pConfig: ^hpf_config, pAllocationCallbacks: ^allocation_callbacks, pHPF: ^hpf) -> result ---
+ hpf_uninit :: proc(pHPF: ^hpf, pAllocationCallbacks: ^allocation_callbacks) ---
hpf_reinit :: proc(pConfig: ^hpf_config, pHPF: ^hpf) -> result ---
hpf_process_pcm_frames :: proc(pHPF: ^hpf, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
hpf_get_latency :: proc(pHPF: ^hpf) -> u32 ---
@@ -217,21 +264,31 @@ bpf :: struct {
format: format,
channels: u32,
bpf2Count: u32,
- bpf2: [MAX_FILTER_ORDER/2]bpf2,
+ pBPF2: ^bpf2,
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@(default_calling_convention="c", link_prefix="ma_")
foreign lib {
bpf2_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64, q: f64) -> bpf2_config ---
- bpf2_init :: proc(pConfig: ^bpf2_config, pBPF: ^bpf2) -> result ---
+ bpf2_get_heap_size :: proc(pConfig: ^bpf2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ bpf2_init_preallocated :: proc(pConfig: ^bpf2_config, pHeap: rawptr, pBPF: ^bpf2) -> result ---
+ bpf2_init :: proc(pConfig: ^bpf2_config, pAllocationCallbacks: ^allocation_callbacks, pBPF: ^bpf2) -> result ---
+ bpf2_uninit :: proc(pBPF: ^bpf2, pAllocationCallbacks: ^allocation_callbacks) ---
bpf2_reinit :: proc(pConfig: ^bpf2_config, pBPF: ^bpf2) -> result ---
bpf2_process_pcm_frames :: proc(pBPF: ^bpf2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
bpf2_get_latency :: proc(pBPF: ^bpf2) -> u32 ---
bpf_config_init :: proc(format: format, channels: u32, sampleRate: u32, cutoffFrequency: f64, order: u32) -> bpf_config ---
- bpf_init :: proc(pConfig: ^bpf_config, pBPF: ^bpf) -> result ---
+ bpf_get_heap_size :: proc(pConfig: ^bpf_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ bpf_init_preallocated :: proc(pConfig: ^bpf_config, pHeap: rawptr, pBPF: ^bpf) -> result ---
+ bpf_init :: proc(pConfig: ^bpf_config, pAllocationCallbacks: ^allocation_callbacks, pBPF: ^bpf) -> result ---
+ bpf_uninit :: proc(pBPF: ^bpf, pAllocationCallbacks: ^allocation_callbacks) ---
bpf_reinit :: proc(pConfig: ^bpf_config, pBPF: ^bpf) -> result ---
bpf_process_pcm_frames :: proc(pBPF: ^bpf, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
bpf_get_latency :: proc(pBPF: ^bpf) -> u32 ---
@@ -260,7 +317,10 @@ notch2 :: struct {
foreign lib {
notch2_config_init :: proc(format: format, channels: u32, sampleRate: u32, q: f64, frequency: f64) -> notch2_config ---
- notch2_init :: proc(pConfig: ^notch2_config, pFilter: ^notch2) -> result ---
+ notch2_get_heap_size :: proc(pConfig: ^notch2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ notch2_init_preallocated :: proc(pConfig: ^notch2_config, pHeap: rawptr, pFilter: ^notch2) -> result ---
+ notch2_init :: proc(pConfig: ^notch2_config, pAllocationCallbacks: ^allocation_callbacks, pFilter: ^notch2) -> result ---
+ notch2_uninit :: proc(pFilter: ^notch2, pAllocationCallbacks: ^allocation_callbacks) ---
notch2_reinit :: proc(pConfig: ^notch2_config, pFilter: ^notch2) -> result ---
notch2_process_pcm_frames :: proc(pFilter: ^notch2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
notch2_get_latency :: proc(pFilter: ^notch2) -> u32 ---
@@ -290,7 +350,10 @@ peak2 :: struct {
foreign lib {
peak2_config_init :: proc(format: format, channels: u32, sampleRate: u32, gainDB, q, frequency: f64) -> peak2_config ---
- peak2_init :: proc(pConfig: ^peak2_config, pFilter: ^peak2) -> result ---
+ peak2_get_heap_size :: proc(pConfig: ^peak2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ peak2_init_preallocated :: proc(pConfig: ^peak2_config, pHeap: rawptr, pFilter: ^peak2) -> result ---
+ peak2_init :: proc(pConfig: ^peak2_config, pAllocationCallbacks: ^allocation_callbacks, pFilter: ^peak2) -> result ---
+ peak2_uninit :: proc(pFilter: ^peak2, pAllocationCallbacks: ^allocation_callbacks) ---
peak2_reinit :: proc(pConfig: ^peak2_config, pFilter: ^peak2) -> result ---
peak2_process_pcm_frames :: proc(pFilter: ^peak2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
peak2_get_latency :: proc(pFilter: ^peak2) -> u32 ---
@@ -320,7 +383,10 @@ loshelf2 :: struct {
foreign lib {
loshelf2_config_init :: proc(format: format, channels: u32, sampleRate: u32, gainDB, shelfSlope, frequency: f64) -> loshelf2_config ---
- loshelf2_init :: proc(pConfig: ^loshelf2_config, pFilter: ^loshelf2) -> result ---
+ loshelf2_get_heap_size :: proc(pConfig: ^loshelf2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ loshelf2_init_preallocated :: proc(pConfig: ^loshelf2_config, pHeap: rawptr, pFilter: ^loshelf2) -> result ---
+ loshelf2_init :: proc(pConfig: ^loshelf2_config, pAllocationCallbacks: ^allocation_callbacks, pFilter: ^loshelf2) -> result ---
+ loshelf2_uninit :: proc(pFilter: ^loshelf2, pAllocationCallbacks: ^allocation_callbacks) ---
loshelf2_reinit :: proc(pConfig: ^loshelf2_config, pFilter: ^loshelf2) -> result ---
loshelf2_process_pcm_frames :: proc(pFilter: ^loshelf2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
loshelf2_get_latency :: proc(pFilter: ^loshelf2) -> u32 ---
@@ -350,7 +416,10 @@ hishelf2 :: struct {
foreign lib {
hishelf2_config_init :: proc(format: format, channels: u32, sampleRate: u32, gainDB, shelfSlope, frequency: f64) -> hishelf2_config ---
- hishelf2_init :: proc(pConfig: ^hishelf2_config, pFilter: ^hishelf2) -> result ---
+ hishelf2_get_heap_size :: proc(pConfig: ^hishelf2_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ hishelf2_init_preallocated :: proc(pConfig: ^hishelf2_config, pHeap: rawptr, pFilter: ^hishelf2) -> result ---
+ hishelf2_init :: proc(pConfig: ^hishelf2_config, pAllocationCallbacks: ^allocation_callbacks, pFilter: ^hishelf2) -> result ---
+ hishelf2_uninit :: proc(pFilter: ^hishelf2, pAllocationCallbacks: ^allocation_callbacks) ---
hishelf2_reinit :: proc(pConfig: ^hishelf2_config, pFilter: ^hishelf2) -> result ---
hishelf2_process_pcm_frames :: proc(pFilter: ^hishelf2, pFramesOut: rawptr, pFramesIn: rawptr, frameCount: u64) -> result ---
hishelf2_get_latency :: proc(pFilter: ^hishelf2) -> u32 ---
diff --git a/vendor/miniaudio/generation.odin b/vendor/miniaudio/generation.odin
index 97b7d453c..305090c7d 100644
--- a/vendor/miniaudio/generation.odin
+++ b/vendor/miniaudio/generation.odin
@@ -56,14 +56,18 @@ noise :: struct {
lcg: lcg,
state: struct #raw_union {
pink: struct {
- bin: [MAX_CHANNELS][16]f64,
- accumulation: [MAX_CHANNELS]f64,
- counter: [MAX_CHANNELS]u32,
+ bin: ^[^]f64,
+ accumulation: [^]f64,
+ counter: [^]u32,
},
brownian: struct {
- accumulation: [MAX_CHANNELS]f64,
+ accumulation: [^]f64,
},
},
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
}
@(default_calling_convention="c", link_prefix="ma_")
@@ -72,7 +76,7 @@ foreign lib {
waveform_init :: proc(pConfig: ^waveform_config, pWaveform: ^waveform) -> result ---
waveform_uninit :: proc(pWaveform: ^waveform) ---
- waveform_read_pcm_frames :: proc(pWaveform: ^waveform, pFramesOut: rawptr, frameCount: u64) -> u64 ---
+ waveform_read_pcm_frames :: proc(pWaveform: ^waveform, pFramesOut: rawptr, frameCount: u64, pFramesRead: ^u64) -> result ---
waveform_seek_to_pcm_frame :: proc(pWaveform: ^waveform, frameIndex: u64) -> result ---
waveform_set_amplitude :: proc(pWaveform: ^waveform, amplitude: f64) -> result ---
waveform_set_frequency :: proc(pWaveform: ^waveform, frequency: f64) -> result ---
@@ -81,10 +85,12 @@ foreign lib {
noise_config_init :: proc(format: format, channels: u32, type: noise_type, seed: i32, amplitude: f64) -> noise_config ---
- noise_init :: proc(pConfig: ^noise_config, pNoise: ^noise) -> result ---
- noise_uninit :: proc(pNoise: ^noise) ---
- noise_read_pcm_frames :: proc(pNoise: ^noise, pFramesOut: rawptr, frameCount: u64) -> u64 ---
- noise_set_amplitude :: proc(pNoise: ^noise, amplitude: f64) -> result ---
- noise_set_seed :: proc(pNoise: ^noise, seed: i32) -> result ---
- noise_set_type :: proc(pNoise: ^noise, type: noise_type) -> result ---
+ noise_get_heap_size :: proc(pConfig: ^noise_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ noise_init_preallocated :: proc(pConfig: ^noise_config, pHeap: rawptr, pNoise: ^noise) -> result ---
+ noise_init :: proc(pConfig: ^noise_config, pAllocationCallbacks: ^allocation_callbacks, pNoise: ^noise) -> result ---
+ noise_uninit :: proc(pNoise: ^noise, pAllocationCallbacks: ^allocation_callbacks) ---
+ noise_read_pcm_frames :: proc(pNoise: ^noise, pFramesOut: rawptr, frameCount: u64, pFramesRead: ^u64) -> result ---
+ noise_set_amplitude :: proc(pNoise: ^noise, amplitude: f64) -> result ---
+ noise_set_seed :: proc(pNoise: ^noise, seed: i32) -> result ---
+ noise_set_type :: proc(pNoise: ^noise, type: noise_type) -> result ---
}
diff --git a/vendor/miniaudio/job_queue.odin b/vendor/miniaudio/job_queue.odin
new file mode 100644
index 000000000..99899fdbd
--- /dev/null
+++ b/vendor/miniaudio/job_queue.odin
@@ -0,0 +1,239 @@
+package miniaudio
+
+import c "core:c/libc"
+
+when ODIN_OS == .Windows {
+ foreign import lib "lib/miniaudio.lib"
+} else when ODIN_OS == .Linux {
+ foreign import lib "lib/miniaudio.a"
+} else {
+ foreign import lib "system:miniaudio"
+}
+
+/*
+Slot Allocator
+--------------
+The idea of the slot allocator is for it to be used in conjunction with a fixed sized buffer. You use the slot allocator to allocator an index that can be used
+as the insertion point for an object.
+
+Slots are reference counted to help mitigate the ABA problem in the lock-free queue we use for tracking jobs.
+
+The slot index is stored in the low 32 bits. The reference counter is stored in the high 32 bits:
+
+ +-----------------+-----------------+
+ | 32 Bits | 32 Bits |
+ +-----------------+-----------------+
+ | Reference Count | Slot Index |
+ +-----------------+-----------------+
+*/
+slot_allocator_config :: struct {
+ capacity: u32, /* The number of slots to make available. */
+}
+
+slot_allocator_group :: struct {
+ bitfield: u32, /*atomic*/ /* Must be used atomically because the allocation and freeing routines need to make copies of this which must never be optimized away by the compiler. */
+}
+
+slot_allocator :: struct {
+ pGroups: [^]slot_allocator_group, /* Slots are grouped in chunks of 32. */
+ pSlots: [^]u32, /* 32 bits for reference counting for ABA mitigation. */
+ count: u32, /* Allocation count. */
+ capacity: u32,
+
+ /* Memory management. */
+ _ownsHeap: b32,
+ _pHeap: rawptr,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ slot_allocator_config_init :: proc(capacity: u32) -> slot_allocator_config ---
+
+ slot_allocator_get_heap_size :: proc(pConfig: ^slot_allocator_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ slot_allocator_init_preallocated :: proc(pConfig: ^slot_allocator_config, pHeap: rawptr, pAllocator: ^slot_allocator) -> result ---
+ slot_allocator_init :: proc(pConfig: ^slot_allocator_config, pAllocationCallbacks: ^allocation_callbacks, pAllocator: ^slot_allocator) -> result ---
+ slot_allocator_uninit :: proc(pAllocator: ^slot_allocator, pAllocationCallbacks: ^allocation_callbacks) ---
+ slot_allocator_alloc :: proc(pAllocator: ^slot_allocator, pSlot: ^u64) -> result ---
+ slot_allocator_free :: proc(pAllocator: ^slot_allocator, slot: u64) -> result ---
+}
+
+/*
+Callback for processing a job. Each job type will have their own processing callback which will be
+called by ma_job_process().
+*/
+job_proc :: proc "c" (pJob: ^job)
+
+/* When a job type is added here an callback needs to be added go "g_jobVTable" in the implementation section. */
+job_type :: enum c.int {
+ /* Miscellaneous. */
+ QUIT = 0,
+ CUSTOM,
+
+ /* Resource Manager. */
+ RESOURCE_MANAGER_LOAD_DATA_BUFFER_NODE,
+ RESOURCE_MANAGER_FREE_DATA_BUFFER_NODE,
+ RESOURCE_MANAGER_PAGE_DATA_BUFFER_NODE,
+ RESOURCE_MANAGER_LOAD_DATA_BUFFER,
+ RESOURCE_MANAGER_FREE_DATA_BUFFER,
+ RESOURCE_MANAGER_LOAD_DATA_STREAM,
+ RESOURCE_MANAGER_FREE_DATA_STREAM,
+ RESOURCE_MANAGER_PAGE_DATA_STREAM,
+ RESOURCE_MANAGER_SEEK_DATA_STREAM,
+
+ /* Device. */
+ DEVICE_AAUDIO_REROUTE,
+
+ /* Count. Must always be last. */
+ COUNT,
+}
+
+job :: struct {
+ toc: struct #raw_union { /* 8 bytes. We encode the job code into the slot allocation data to save space. */
+ breakup: struct {
+ code: u16, /* Job type. */
+ slot: u16, /* Index into a ma_slot_allocator. */
+ refcount: u32,
+ },
+ allocation: u64,
+ },
+ next: u64, /*atomic*/ /* refcount + slot for the next item. Does not include the job code. */
+ order: u32, /* Execution order. Used to create a data dependency and ensure a job is executed in order. Usage is contextual depending on the job type. */
+
+ data: struct #raw_union {
+ /* Miscellaneous. */
+ custom: struct {
+ proc_: job_proc,
+ data0: uintptr,
+ data1: uintptr,
+ },
+
+ /* Resource Manager */
+ resourceManager: struct #raw_union {
+ loadDataBufferNode: struct {
+ pResourceManager: rawptr /*ma_resource_manager**/,
+ pDataBufferNode: rawptr /*ma_resource_manager_data_buffer_node**/,
+ pFilePath: cstring,
+ pFilePathW: [^]c.wchar_t,
+ flags: u32, /* Resource manager data source flags that were used when initializing the data buffer. */
+ pInitNotification: ^async_notification, /* Signalled when the data buffer has been initialized and the format/channels/rate can be retrieved. */
+ pDoneNotification: ^async_notification, /* Signalled when the data buffer has been fully decoded. Will be passed through to MA_JOB_TYPE_RESOURCE_MANAGER_PAGE_DATA_BUFFER_NODE when decoding. */
+ pInitFence: ^fence, /* Released when initialization of the decoder is complete. */
+ pDoneFence: ^fence, /* Released if initialization of the decoder fails. Passed through to PAGE_DATA_BUFFER_NODE untouched if init is successful. */
+ },
+ freeDataBufferNode: struct {
+ pResourceManager: rawptr /*ma_resource_manager**/,
+ pDataBufferNode: rawptr /*ma_resource_manager_data_buffer_node**/,
+ pDoneNotification: ^async_notification,
+ pDoneFence: ^fence,
+ },
+ pageDataBufferNode: struct {
+ pResourceManager: rawptr /*ma_resource_manager**/,
+ pDataBufferNode: rawptr /*ma_resource_manager_data_buffer_node**/,
+ pDecoder: rawptr /*ma_decoder**/,
+ pDoneNotification: ^async_notification, /* Signalled when the data buffer has been fully decoded. */
+ pDoneFence: ^fence, /* Passed through from LOAD_DATA_BUFFER_NODE and released when the data buffer completes decoding or an error occurs. */
+ },
+
+ loadDataBuffer: struct {
+ pDataBuffer: rawptr /*ma_resource_manager_data_buffer**/,
+ pInitNotification: ^async_notification, /* Signalled when the data buffer has been initialized and the format/channels/rate can be retrieved. */
+ pDoneNotification: ^async_notification, /* Signalled when the data buffer has been fully decoded. */
+ pInitFence: ^fence, /* Released when the data buffer has been initialized and the format/channels/rate can be retrieved. */
+ pDoneFence: ^fence, /* Released when the data buffer has been fully decoded. */
+ rangeBegInPCMFrames: u64,
+ rangeEndInPCMFrames: u64,
+ loopPointBegInPCMFrames: u64,
+ loopPointEndInPCMFrames: u64,
+ isLooping: u32,
+ },
+ freeDataBuffer: struct {
+ pDataBuffer: rawptr /*ma_resource_manager_data_buffer**/,
+ pDoneNotification: ^async_notification,
+ pDoneFence: ^fence,
+ },
+
+ loadDataStream: struct {
+ pDataStream: rawptr /*ma_resource_manager_data_stream**/,
+ pFilePath: cstring, /* Allocated when the job is posted, freed by the job thread after loading. */
+ pFilePathW: [^]c.wchar_t, /* ^ As above ^. Only used if pFilePath is NULL. */
+ initialSeekPoint: u64,
+ pInitNotification: ^async_notification, /* Signalled after the first two pages have been decoded and frames can be read from the stream. */
+ pInitFence: ^fence,
+ },
+ freeDataStream: struct {
+ pDataStream: rawptr /*ma_resource_manager_data_stream**/,
+ pDoneNotification: ^async_notification,
+ pDoneFence: ^fence,
+ },
+ pageDataStream: struct {
+ pDataStream: rawptr /*ma_resource_manager_data_stream**/,
+ pageIndex: u32, /* The index of the page to decode into. */
+ },
+ seekDataStream: struct {
+ pDataStream: rawptr /*ma_resource_manager_data_stream**/,
+ frameIndex: u64,
+ },
+ },
+
+ /* Device. */
+ device: struct #raw_union {
+ aaudio: struct #raw_union {
+ reroute: struct {
+ pDevice: rawptr /*ma_device**/,
+ deviceType: u32 /*ma_device_type*/,
+ },
+ },
+ },
+ },
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ job_init :: proc(code: u16) -> job ---
+ job_process :: proc(pJob: ^job) -> result ---
+}
+
+
+/*
+When set, ma_job_queue_next() will not wait and no semaphore will be signaled in
+ma_job_queue_post(). ma_job_queue_next() will return MA_NO_DATA_AVAILABLE if nothing is available.
+
+This flag should always be used for platforms that do not support multithreading.
+*/
+job_queue_flags :: enum c.int {
+ NON_BLOCKING = 0x00000001,
+}
+
+job_queue_config :: struct {
+ flags: u32,
+ capacity: u32, /* The maximum number of jobs that can fit in the queue at a time. */
+}
+
+USE_EXPERIMENTAL_LOCK_FREE_JOB_QUEUE :: false
+
+job_queue :: struct {
+ flags: u32, /* Flags passed in at initialization time. */
+ capacity: u32, /* The maximum number of jobs that can fit in the queue at a time. Set by the config. */
+ head: u64, /*atomic*/ /* The first item in the list. Required for removing from the top of the list. */
+ tail: u64, /*atomic*/ /* The last item in the list. Required for appending to the end of the list. */
+ sem: (struct {} when NO_THREADING else semaphore), /* Only used when MA_JOB_QUEUE_FLAG_NON_BLOCKING is unset. */
+ allocator: slot_allocator,
+ pJobs: [^]job,
+ lock: (struct {} when USE_EXPERIMENTAL_LOCK_FREE_JOB_QUEUE else spinlock),
+
+ /* Memory management. */
+ _pHeap: rawptr,
+ _ownsHeap: b32,
+}
+
+@(default_calling_convention="c", link_prefix="ma_")
+foreign lib {
+ job_queue_config_init :: proc(flags, capacity: u32) -> job_queue_config ---
+
+ job_queue_get_heap_size :: proc(pConfig: ^job_queue_config, pHeapSizeInBytes: ^c.size_t) -> result ---
+ job_queue_init_preallocated :: proc(pConfig: ^job_queue_config, pHeap: rawptr, pQueue: ^job_queue) -> result ---
+ job_queue_init :: proc(pConfig: ^job_queue_config, pAllocationCallbacks: ^allocation_callbacks, pQueue: ^job_queue) -> result ---
+ job_queue_uninit :: proc(pQueue: ^job_queue, pAllocationCallbacks: ^allocation_callbacks) ---
+ job_queue_post :: proc(pQueue: ^job_queue, pJob: ^job) -> result ---
+ job_queue_next :: proc(pQueue: ^job_queue, pJob: ^job) -> result --- /* Returns MA_CANCELLED if the next job is a quit job. */
+}
diff --git a/vendor/miniaudio/lib/miniaudio.lib b/vendor/miniaudio/lib/miniaudio.lib
index 3d7c8327f6b3432b3c9fc8054061d0b9dc5c07c8..400cb9608cb9090e57467eb2fc0beb292eb2f139 100644
GIT binary patch
literal 2767136
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%0Ar_2;=kL}#vW|1GF*Wp$YtK_8X#DH^
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