Previously this was restricted to 2 input buses and 2 output buses, but
this has been lifted to 254. When the number exceeds 2, internal data
structures will be allocated on the heap, otherwise they'll use a local
array contained within the ma_node structure.
This commit changes the node configuration. Previously there was a
fixed sized array for specifying the channel counts for each bus. This
array must now be defined outside of the config by the caller. The
following config variables have been renamed:
* inputChannels > pInputChannels
* outputChannels > pOutputChannels
This commit also adds the ability to configure input and output bus
counts on a per-instance basis rather than via the node vtable. To do
this, set the bus count in the vtable to MA_NODE_BUS_COUNT_UNKNOWN.
This will tell miniaudio to look at the node config to determine the
bus count rather than the vtable. It's an error to specify this in the
node config if the vtable specifies anything other than
MA_NODE_BUS_COUNT_UNKNOWN.
* The old logging callback has been deprecated and will be removed in
version 0.11.
* MA_LOG_LEVEL_DEBUG has been added and MA_LOG_LEVEL_VERBOSE
deprecated.
* The MA_LOG_LEVEL option has been deprecated. All log levels are now
posted to the logging callbacks, except for MA_LOG_LEVEL_DEBUG
which is only posted if MA_DEBUG_OUTPUT is enabled.
The new logging system works by creating a `ma_log` object. You then
register callbacks that will be fired when a log message is posted. You
can register up to 4 callbacks. You the specify a pointer to this log
object in the context config. This replaces the `logCallback` variable.
The old logging system was specific to context's and device's, however
with the introduction of new APIs this is no longer appropriate. The
new logging system is completely generic with a simple user-data
pointer being used for application-specific data.
This commit adds some helper APIs for retrieving a pointer to the
context's log object:
* ma_context_get_log()
* ma_device_get_log()
* ma_device_get_context()
The MA_DEBUG_OUTPUT option has been improved for Android builds. With
the new system, __android_log_print() will be used instead of printf().
These changes expand on the notification system which allows a program
to be notified on when a sound has reached various stages in the async
loading process. There are two stages:
1) Decoder initialization
2) Completion of decoding
The previous system has the following problems:
* There's no way to wait on only the decoder initialization
* The callback doesn't work well if you want to pass it through
multiple layers. Example:
- Client wants to wait for the sound to complete
- Pass the callback into ma_sound_init_from_file(), which passes
it into ma_resource_manager_data_source_init(). The latter will
fire the callback, but will do so before ma_sound_init_from_file()
has returned. The client will think the sound has finished
loading and will reference the `ma_sound` object before it's
completed initialization.
* It's not easy to wait on object in bulk. Clients may want to pump a
bunch of ASYNC sounds in one go, and then just have a single
notification for the group.
The new system introduces the notion of a "fence". A fence contains a
counter which is incremented and decremented from anywhere. It also has
a wait routine which will block until the counter hits zero:
ma_fence_acquire() - Increments the counter
ma_fence_release() - Decrements the counter
ma_fence_wait() - Blocks until the counter is 0.
The fence system can be used to wait for a number of sounds to finish
decoding rather than only one at a time, which is the case with the
previous system. Example:
```
/* Fences must be initialized before use. */
ma_fence_init(&fence);
/* Loop over each sound and start loading them, passing in the fence. */
for each sound in sounds
{
flags = MA_DATA_SOURCE_FLAG_DECODE | MA_DATA_SOURCE_FLAG_ASYNC;
ma_sound_init_from_file(&engine, pFilePath, flags, &group, &fence, &sound);
}
... do some other stuff while sounds are loading ...
/* Wait for sounds to finish loading. */
ma_fence_wait(&fence);
ma_fence_uninit(&fence);
```
The above example initializes a sound, but it can also be used by
resource managed data sources. When loading data sources directly from
the resource manager, you can specify a second fence which is used to
only wait until the internal decoder has been initialized.
David Reid