carb::audio::SoundDataReadCallback

Defined in carb/audio/IAudioData.h

typedef AudioResult (*carb::audio::SoundDataReadCallback)(const SoundData *soundData, void *data, size_t *dataLength, void *context)

callback function prototype for reading data for fDataFlagUserDecode sound data objects.

Remark

This is used to either decode data that is in a proprietary format or to produce dynamic data as needed. The time and frequency at which this callback is performed depends on the flags that were originally passed to createData() when the sound data object was created. If the fDataFlagDecode flag is used, this would only be performed at load time to decode the entire stream.

Remark

When using a decoding callback, the data written to the buffer must be PCM data in the format expected by the sound data object. It is the host app’s responsibility to know the sound format information before calling createData() and to fill that information into the SoundDataLoadDesc object.

Param soundData

[in] the sound object to read the sound data for. This object will be valid and can be accessed to get information about the decoding format. The object’s data buffer should not be accessed from the callback, but the provided data buffer should be used instead. This may not be nullptr.

Param data

[out] the buffer that will receive the decoded audio data. This buffer will be large enough to hold dataLength bytes. This may be nullptr to indicate that the remaining number of bytes in the stream should be returned in dataLength instead of the number of bytes read.

Param dataLength

[inout] on input, this contains the length of the data buffer in bytes. On output, if data was not nullptr, this will contain the number of bytes actually written to the buffer. If data was nullptr, this will contain the number of bytes remaining to be read in the stream. All data written to the buffer must be frame aligned.

Param context

[in] the callback context value specified in the SoundDataLoadDesc object. This is passed in unmodified.

Return

AudioResult.eOk if the read operation is successful.

Return

AudioResult.eTryAgain if the read operation was not able to fill an entire buffer and should be called again. This return code should be used when new data is not yet available but is expected soon.

Return

AudioResult.eOutOfMemory if the full audio stream has been decoded (if it decides not to loop). This indicates that there is nothing left to decode.

Return

an AudioResult.* error code if the callback could not produce its data for any other reason.