carb::audio::SoundDataLoadDesc

Defined in carb/audio/IAudioData.h

struct SoundDataLoadDesc

a descriptor for the sound data to be loaded.

This is a flexible loading method that allows sound data to be loaded from file, memory, streamed from disk, loaded as raw PCM data, loaded from a proprietary data format, decoded or decompressed at load time, or even created as an empty sound buffer. The loading method depends on the flags used. For data loaded from file or a blob in memory, the data format can be auto detected for known supported formats.

Not all members in this object are used on each loading path. For example, the data format information will be ignored when loading from a file that already contains format information in its header. Regardless of whether a particular value is ignored, it is still the caller’s responsibility to appropriately initialize all members of this object.

Sound data is loaded using this descriptor through a single loader function. Because there are more than 60 possible combinations of flags that can be used when loading sound data, it’s not feasible to create a separate loader function for each possible method.

Public Members

DataFlags flags = 0

flags to control how the sound data is loaded and decoded (if at all).

This is a combination of zero or more of the fDataFlag* flags. By default, the sound data’s format will attempt to be auto detected and will be fully loaded and decoded into memory. This value must be initialized before calling createData().

uint32_t padding1 = {0}

Dummy member to enforce padding.

const char *name = nullptr

filename or asset name for the new object.

This may be specified regardless of whether the fDataFlagInMemory flag is used. When that flag is used, this can be used to give an asset name to the sound object. The name will not be used for any purpose except as a way to identify it to a user in that case. When loading the data from a file, this represents the filename to load from. When the fDataFlagInMemory flag is not used, this must be the filename to load from. This may be nullptr only if the audio data is being loaded from a blob in memory.

const void *dataBlob = nullptr

when the fDataFlagInMemory flag is used, this is the blob of data to load from memory.

If the flag is not specified, this value will be ignored. When loading from memory, the dataBlobLengthInBytes will indicate the size of the data blob in bytes. Specifying a data blob with fDataFlagFormatRaw with a pointer that is misaligned for its sample type is allowed; the effects of fDataFlagUserMemory will be disabled so a properly aligned local buffer can be allocated. The effects of fDataFlagUserMemory will also be disabled when specifying a wave file blob where the data chunk is misaligned for its sample type (this is only possible for 32 bit formats).

size_t dataBlobLengthInBytes = 0

when the fDataFlagInMemory flag is used, this value specifies the size of the data blob to load in bytes.

When the flag is not used, this value is ignored.

size_t channels = kDefaultChannelCount

the number of channels to create the sound data with.

This value is ignored if the sound data itself contains an embedded channel count (ie: when loading from file). This must be initialized to a non-zero value when the fDataFlagFormatRaw, fDataFlagEmpty, or fDataFlagUserDecode flags are used. If fDataFlagUserDecode is used and encodedFormat is a non-PCM format, this will be ignored.

SpeakerMode channelMask = kSpeakerModeDefault

a mask that maps speaker channels to speakers.

All channels in the stream are interleaved according to standard SMPTE order. This mask indicates which of those channels are present in the stream. This may be kSpeakerModeDefault to allow a standard speaker mode to be chosen from the given channel count.

size_t frameRate = kDefaultFrameRate

the rate in frames per second that the sound was originally mastered at.

This will be the default rate that it is processed at. This value is ignored if the sound data itself contains an embedded frame rate value (ie: when loading from file). This must be initialized to a non-zero value when the fDataFlagFormatRaw, fDataFlagEmpty, or fDataFlagUserDecode flags are used. If fDataFlagUserDecode is used and encodedFormat is a non-PCM format, this will be ignored.

SampleFormat encodedFormat = SampleFormat::eDefault

the data format of each sample in the sound.

This value is ignored if the sound data itself contains an embedded data format value (ie: when loading from file). This must be initialized to a non-zero value when the fDataFlagFormatRaw, fDataFlagEmpty, or fDataFlagUserDecode flags are used. This represents the encoded sample format of the sound.

If the fDataFlagUserDecode flag is used, this will be the format produced by the user decode callback. Note that PCM data produced from a user decode callback must be raw PCM data rather than a WAVE file blob. The user decode callback does not need to provide whole frames/blocks of this sample type, since this effectively acts as an arbitrary data source. This allows you to specify that the user decode callback returns data in a non-PCM format and have it decoded to the PCM format specified by pcmFormat.

If the fDataFlagEmpty flag is used and this is set to SampleFormat::eDefault, this will be set to the same sample format as the pcmFormat format.

SampleFormat pcmFormat = SampleFormat::eDefault

the decoded or preferred intermediate PCM format of the sound.

This value should be set to SampleFormat::eDefault to allow the intermediate format to be chosen by the decoder. Otherwise, this should be set to one of the SampleFormat::ePcm* formats to force the decoder to use a specific intermediate or internal representation of the sound. This is useful for saving memory on large decoded sounds by forcing a smaller format.

When the fDataFlagDecode flag is used, this will be the PCM format that the data is decoded into.

When the fDataFlagEmpty flag is used and this is set to SampleFormat::eDefault, the decoder will choose the PCM format. If the encodedFormat value is also set to SampleFormat::eDefault, it will also use the decoder’s preferred PCM format.

size_t bufferLength = 0

specifies the desired length of an empty sound data buffer, a raw buffer, or user decode buffer.

This value is interpreted according to the units in bufferLengthType. This value is ignored if the sound data itself contains embedded length information (ie: when loading from file). This must be initialized to a non-zero value when either the fDataFlagFormatRaw, fDataFlagEmpty, or fDataFlagUserDecode flags are used. When using this with fDataFlagEmpty, the sound data object will initially be marked as containing zero valid frames of data. If played, this will always decode silence. If the host app writes new data into the buffer, it must also update the valid data size with setValidLength() so that the new data can be played.

UnitType bufferLengthType = UnitType::eFrames

determines how the bufferLength value should be interpreted.

This value is ignored in the same cases bufferLength are ignored in. For fDataFlagEmpty, this may be any valid unit type. For fDataFlagFormatRaw and fDataFlagUserDecode, this may only be UnitType::eFrames or UnitType::eBytes.

uint32_t padding2 = {0}

Dummy member to enforce padding.

SoundDataReadCallback readCallback = nullptr

a callback function to provide decoded PCM data from a user-decoded data format.

This value is ignored unless the fDataFlagUserDecode flag is used. This callback is responsible for decoding its data into the PCM format specified by the rest of the information in this descriptor. The callback function or caller are responsible for knowing the decoded format before calling createData() and providing it in this object.

SoundDataSetPosCallback setPosCallback = nullptr

an optional callback function to provide a way to reposition the decoder in a user decoded stream.

This value is ignored unless the fDataFlagUserDecode flag is used. Even when the flag is used, this callback is only necessary if the fDataFlagStream flag is also used and the voice playing it expects to either loop the sound or be able to reposition it on command during playback. If this callback is not provided, attempts to play this sound on a looping voice or attempts to change the streaming playback position will simply fail.

void *readCallbackContext = nullptr

an opaque context value that will be passed to the readCallback and setPosCallback functions each time they are called.

This value is a caller-specified object that is expected to contain the necessary decoding state for a user decoded stream. This value is only necessary if the fDataFlagUserDecode flag is used. This value will only be used at load time on a user decoded stream if the fDataFlagDecode flag is used (ie: causing the full sound to be decoded into memory at load time). If the sound is created to be streamed, this will not be used.

SoundDataDestructionCallback destructionCallback = nullptr

An optional callback that gets fired when the SoundData’s final reference is released.

This is intended to make it easier to perform cleanup of a SoundData in cases where fDataFlagUserMemory is used.

void *destructionCallbackContext = nullptr

An opaque context value that will be passed to destructionCallback when the last reference to the SoundData is released.

This will not be called if the SoundData is not created successfully.

void *encoderSettings = nullptr

Reserved for future expansion for options to be used when fDataFlagDecode is specified.

uint32_t maxInstances = kInstancesUnlimited

the maximum number of simultaneous playing instances that this sound can have.

This can be kInstancesUnlimited to indicate that there should not be a play limit. This can be any other value to limit the number of times this sound can be played at any one time.

uint32_t padding3 = {0}

Dummy member to enforce padding.

size_t autoStreamThreshold = 0

the size in bytes at which to decide whether to decode or stream this sound.

This will only affect compressed non-PCM sound formats. This value will be ignored for any PCM format regardless of size. This can be zero to just decide to stream or decode based on the fDataFlagDecode or fDataFlagStream flags. If this is non-zero, the sound will be streamed if its PCM size is larger than this limit. The sound will be fully decoded if its PCM size is smaller than this limit. In this case, the fDataFlagDecode flag and fDataFlagStream flag will be ignored.

Note that if this is non-zero, this will always override the stream and decode flags’ behavior.

void *ext = nullptr

reserved for future expansion.

This must be set to nullptr.