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 removes the allocation callbacks parameter. These are now managed
internally. This is in preparation for some future changes to data
source management.
This includes API changes that affect custom backends.
`ma_backend_callbacks` has been renamed to `ma_device_backend_vtable`.
The reason for this change is to to be consistent with the naming
convention used in other parts of the library. In addition, using the
term "device backend" rather than just "backend" removes ambiguity with
decoding backends.
A change has been made to the way backends manage their internal state,
and some functions in the vtable have been updated to reflect this.
Previously internal state for stock backends were located directly in
the `ma_device` structure. This works fine if stock backends are the
only backends to be concerned about, but it falls apart when you need
to consider how to manage the internal state of custom backends since
they cannot modify the `ma_device` structure. In order to simplify and
unify state management between stock and custom backends, the decision
was made to change the backend system such that backends now manage
their own internal state.
When the context is initialized with `onContextInit`, the backend must
now allocate an internal state object and output a pointer to it via
an output parameter. Typically you would do something like this:
ma_result custom_context_init(..., void** ppContextState)
{
ctx_state_t* state = malloc(...);
...
*ppContextState = state;
return MA_SUCCESS;
}
miniaudio will store a pointer to the state object internally. When you
need to access this later in other backend callbacks, you can retrieve
it straight from the context with `ma_context_get_backend_state()`:
state = (ctx_state_t*)ma_context_get_backend_state(pContext);
The same idea applies to devices and `onDeviceInit`. You can use
`ma_device_get_backend_state()` to get a pointer to the internal state
object.
When a context and device is initialized, backend-specific
configurations can be supplied. The way these configs are provided to
`onContextInit` and `onDeviceInit` has been changed. Previously, these
callbacks would take a `ma_context/device_config` object. These have
been replaced with a `const void*` which points to a backend-specific
config object which is defined by the backend. All stock backends have
their own backend-specific config object:
struct ma_context_config_wasapi
struct ma_context_config_pulseaudio
etc.
struct ma_device_config_wasapi
struct ma_device_config_pulseaudio
etc.
You can cast the config object inside the relevant callbacks:
ma_result custom_context_init(..., const void* pBackendConfig, ...)
{
ctx_config_t* pCustomConfig = (ctx_config_t*)pBackendConfig;
}
The backend itself defines whether or not a config is required. None of
the stock backends require a config. If the config is NULL, it'll use
defaults. It's recommended custom backends follow this convention.
In addition to the above, `onContextUninit` and `onDeviceUninit` have
been updated to return void instead of `ma_result`.
The last change to the backend vtable is a new callback called
`onBackendInfo`. This is used to fill the `ma_device_backend_info`
structure.
In addition to the backend vtable, some changes have been made to the
public API to make it much easier to support plugging in custom
backends.
Previously, plugging in more than one custom backend was a complete
mess. It was possible, but you had to use a stupid wrapper thing to
make it work, and you had no control over prioritization. The entire
thing was just aweful, so it's now been stripped out and replaced with
a brand new system.
When a context or device is initialized, it is done so with a config
which is standard across the entire library. A complication to this is
that backends can sometimes require their own backend-specific configs.
But since miniaudio cannot possibly know about custom backends, it
cannot put their config options inside `ma_context/device_config`. The
functions for initializing a context and device have been updated to
allow plugging in backend-specific configs.
When initializing a context, instead of passing in an array of
`ma_backend` enums, an array of `ma_device_backend_config` objects is
passed in instead. This object has two members: A pointer to a backend
vtable, and a pointer to a config object. It can be initialized
something like this:
ma_context_config_custom customContextConfig;
... initialize the custom backend config if necessary ...
ma_device_backend_config backends[] =
{
{ ma_device_backend_custom, &customContextConfig },
{ ma_device_backend_wasapi, NULL },
{ ma_device_backend_pulseaudio, NULL }
};
ma_context_init(backends, backendCount, ...);
Here `ma_device_backend_custom` is our custom backend. You can see how
the config is mapped to the backend. For stock backends (WASAPI and
PulseAudio in this example), you can pass in NULL and just set the
relevant config options straight in `ma_context_config` exactly how it
was done before:
ma_context_config contextConfig = ma_context_config_init();
contextConfig.pulseaudio.pApplicationName = "My App";
Here we are just using the standard `ma_context_config` object for
configuring the stock PulseAudio backend. This is possible for all
stock backends, but for custom backends an explicit config object will
be required. You can still use a separate explicit config object for
stock backends if you prefer that style:
ma_context_config_pulseaudio paContextConfig;
paContextConfig = ma_context_config_pulseaudio_init();
paContextConfig.pApplicationName = "My App";
ma_device_backend_config backends[] =
{
{ ma_device_backend_pulseaudio, &paContextConfig }
};
Note that if you do not use custom backends, you can still pass in NULL
for the backends in which case defaults will be used like how it's
always worked in the past.
As with contexts, devices can also have their own backend-specific
configs associated with them. These work exactly the same way, except
these configs are passed into the main `ma_device_config` object. (A
future commit may make this consistent between contexts and devices).
ma_device_backend_config deviceBackendConfigs[] =
{
{ ma_device_backend_custom, &customDeviceConfig }
};
deviceConfig.pBackendConfigs = deviceBackendConfigs;
deviceConfig.backendConfigCount = backendCount;
ma_device_init(&deviceConfig, &device);
This commit is just the start of many backend related changes. Future
commits will be cleaning up a lot of residual code from the old system,
such as removing `ma_backend`.
These decoders have been moved into their own subfolders under the
extras/decoders folder:
extras/decoders/libvorbis
extras/decoders/libopus
In addition to being relocated, they have also been split into separate
.c/h pairs. They now work like a more conventional library. The
implementation of these libraries have also been decoupled from the
miniaudio implementation which means they depend only on the header
section of miniaudio.h now.
With this change the custom_decoder and custom_decoder_engine examples
have been updated. To compile these you now need to link in the
miniaudio_libvorbis.c and miniaudio_libopus.c files via your build
tool. For your own code, you can still include the .c files directly
into your code if you want to compile as a single translation unit.
The data source implementation of a ma_pcm_rb could possibly return a
frame count of 0 which would in turn result in
ma_data_source_read_pcm_frames() returning MA_AT_END which does not
make sense for a ring buffer since it has no notion of an end.
David Reid
RainRat