This makes ma_decoder_read_pcm_frames() consistent with other data
sources. It now returns a result code and outputs the number of frames
read via an output parameter.
The previous version only allowed in-place clipping, whereas the new
one supports clipping into a separate buffer. The input and output
buffers can point to the same buffer in which case the clip will be
performed in-place.
This is work towards using the heap for storing per-channel data so we
can get rid of upper channel count limit and remove MA_MAX_CHANNELS or
at the very least stop MA_MAX_CHANNELS from affecting overall memory
usage.
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.
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