A new callback called `onProp` has been added to
`ma_data_source_vtable`. This replaces the following callbacks:
onGetDataFormat
onGetCursor
onGetLength
onSetLooping
This new callback is for retrieving and setting various properties
relating to the data source. It takes a `prop` parameter which is an ID
for the property being handled, and a `void*` pointer for
property-specific data.
Typically onProp implementations would discriminate on the property type
using a switch. The example below shows how to handle the old callbacks:
switch (prop)
{
// Replaces onGetDataFormat (format/channels/rate).
case MA_DATA_SOURCE_GET_DATA_SOURCE:
{
ma_data_source_data_format* pDataFormat =
(ma_data_source_data_format*)pData;
pDataFormat->format = pCustomDataSource->format;
pDataFormat->channels = pCustomDataSource->channels;
pDataFormat->sampleRate = pCustomDataSource->sampleRate;
return MA_SUCCESS;
}
// Replaces onGetDataFormat (channel map)
case MA_DATA_SOURCE_GET_CHANNEL_MAP:
{
ma_channel_map_init_standard(
ma_standard_channel_map_default,
(ma_channel*)pData,
MA_MAX_CHANNELS,
pCustomDataSource->channels);
return MA_SUCCESS;
}
// Replaces onGetCursor
case MA_DATA_SOURCE_GET_CURSOR:
{
*((ma_uint64*)pData) = pCustomDataSource->cursor;
return MA_SUCCESS;
}
// Replaces onGetLength
case MA_DATA_SOURCE_GET_LENGTH:
{
*((ma_uint64*)pData) = pCustomDataSource->length;
return MA_SUCCESS;
}
// Replaces onSetLooping
case MA_DATA_SOURCE_SET_LOOPING:
{
pCustomDataSource->isLooping = *((ma_bool32*)pData);
return MA_SUCCESS;
}
// Mandatory when MA_DATA_SOURCE_SET_LOOPING is implemented.
case MA_DATA_SOURCE_GET_LOOPING:
{
*((ma_bool32*)pData) = pCustomDataSource->isLooping;
return MA_SUCCESS;
}
// Return MA_NOT_IMPLEMENTED for any ignored properties.
default: return MA_NOT_IMPLEMENTED;
}
Note how the format/channels/rate and channel map properties have been
split across two separate properties, `MA_DATA_SOURCE_GET_DATA_SOURCE`
and `MA_DATA_SOURCE_GET_CHANNEL_MAP`. Along with this change, the
channel map parameters have been removed from
`ma_data_source_get_data_format()` and a new function called
`ma_data_source_get_channel_map()` has been added.
New properties have also been added for handling ranges and loop points.
This allows the data source implementation itself to handle it rather
than miniaudio doing it at a higher level. Where this is useful is if
your data source is a wrapper around another data source and you want to
route ranges and loop points to the internal data source.
The reason for this change is that it allows for properties to be added
without having to break the build due to yet another callback being
added. It also hides away the more niche properties that the majority of
data sources do not care about. For example, rarely does a data source
need to handle the `onSetLooping` callback, yet every data source needed
to add a `NULL` entry to their vtables just for this one extremely niche
property.
See documentation for further details.
Tag: release-notes
Tag: api-change
This has been renamed to ma_audio_buffer_init_and_copy_data(). This is
to free up the old name for a new purpose (creating a copy of the whole
`ma_audio_buffer` object).
The copying of the data source is now done generically through the new
data source copying system rather than being restricted to just the
resource manager.
This is used for making a copy of a data source.
Data sources are not required to support copying, in which case this
callback can be set to NULL, or it can return MA_NOT_IMPLEMENTED.
This commit just sets up the infrastructure. As of this commit, no data
sources actually implement this, however future commits will be
introducing support in stages.
This should return the size of the implementations struct. For example,
`ma_decoder` would return `sizeof(ma_decoder)`.
This is in preparation for future work to support copying data sources.
This removes the onInitFile and onInitFileW callbacks from
ma_decoding_backend_vtable. This means decoding backends can no longer
implement a specialized initialization routine for loading from a file.
What this does is enforces all file IO to go through the same code path,
that being the `ma_decoder` and `ma_vfs` infrastructure. It also
simplifies the backend vtable.
The ability to initialize from memory (the onInitMemory callback) is
still available and there are not plans to remove this.
This makes the following APIs public:
ma_allocation_callbacks_init_default()
ma_allocation_callbacks_init_copy()
This is required to allow things like custom data sources and backends
to be able to track allocation callbacks if necessary.
This removes the allocation callbacks parameter. These are now managed
internally. This is in preparation for some future changes to data
source management.
These have been renamed to the following:
ma_data_source_init > ma_data_source_base_init
ma_data_source_uninit > ma_data_source_base_uninit
The new naming scheme makes it clearer that you're initializing the
base data source structure.
For some reason, 64-bit pointer arguments are casted to Numbers
in Emscripten's type handling (which causes conversion errors when
passing them back to native code)
David Reid
Echo J
Yuri Khrustalev
amaldika