API CHANGE: Add onProp callback to ma_data_source_vtable.

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

extras/decoders/libopus/miniaudio_libopus.c

@@ -30,19 +30,38 @@ static ma_result ma_libopus_ds_seek(ma_data_source* pDataSource, ma_uint64 frame
     return ma_libopus_seek_to_pcm_frame((ma_libopus*)pDataSource, frameIndex);
 }
 
-static ma_result ma_libopus_ds_get_data_format(ma_data_source* pDataSource, ma_format* pFormat, ma_uint32* pChannels, ma_uint32* pSampleRate, ma_channel* pChannelMap, size_t channelMapCap)
+static ma_result ma_libopus_ds_prop(ma_data_source* pDataSource, int prop, void* pData)
 {
-    return ma_libopus_get_data_format((ma_libopus*)pDataSource, pFormat, pChannels, pSampleRate, pChannelMap, channelMapCap);
-}
+    ma_libopus* pOpus = (ma_libopus*)pDataSource;
 
-static ma_result ma_libopus_ds_get_cursor(ma_data_source* pDataSource, ma_uint64* pCursor)
-{
-    return ma_libopus_get_cursor_in_pcm_frames((ma_libopus*)pDataSource, pCursor);
-}
+    switch (prop)
+    {
+        case MA_DATA_SOURCE_GET_DATA_FORMAT:
+        {
+            ma_data_source_data_format* pDataFormat = (ma_data_source_data_format*)pData;
 
-static ma_result ma_libopus_ds_get_length(ma_data_source* pDataSource, ma_uint64* pLength)
-{
-    return ma_libopus_get_length_in_pcm_frames((ma_libopus*)pDataSource, pLength);
+            return ma_libopus_get_data_format(pOpus, &pDataFormat->format, &pDataFormat->channels, &pDataFormat->sampleRate, NULL, 0);
+        }
+
+        case MA_DATA_SOURCE_GET_CHANNEL_MAP:
+        {
+            return ma_libopus_get_data_format(pOpus, NULL, NULL, NULL, (ma_channel*)pData, MA_MAX_CHANNELS);
+        }
+
+        case MA_DATA_SOURCE_GET_CURSOR:
+        {
+            return ma_libopus_get_cursor_in_pcm_frames(pOpus, (ma_uint64*)pData);
+        }
+
+        case MA_DATA_SOURCE_GET_LENGTH:
+        {
+            return ma_libopus_get_length_in_pcm_frames(pOpus, (ma_uint64*)pData);
+        }
+
+        default: break;
+    }
+
+    return MA_NOT_IMPLEMENTED;
 }
 
 static ma_data_source_vtable ma_gDataSourceVTable_libopus =
@@ -52,10 +71,7 @@ static ma_data_source_vtable ma_gDataSourceVTable_libopus =
     NULL,   /* onCopy. Copying is not supported. */
     ma_libopus_ds_read,
     ma_libopus_ds_seek,
-    ma_libopus_ds_get_data_format,
-    ma_libopus_ds_get_cursor,
-    ma_libopus_ds_get_length,
-    NULL    /* onSetLooping */
+    ma_libopus_ds_prop
 };