carb::audio::ConversionDesc

struct ConversionDesc

a descriptor of a data type conversion operation.

This provides the information needed to convert a sound data object from its current format to another data format. Not all data formats may be supported as destination formats. The conversion operation will fail if the destination format is not supported for encoding. The conversion operation may either be performed in-place on the sound data object itself or it may output a copy of the sound data object converted to the new format.

Note that this conversion operation will not change the length (mostly), frame rate, or channel count of the data, just its sample format. The length of the stream may increase by a few frames for some block oriented compression or encoding formats so that the stream can be block aligned in length. PCM data will always remain the same length as the input since the frames per block count for PCM data is always 1.

Public Members

ConvertFlags flags = 0

flags to control how the conversion proceeds.

This may be zero or more of the fConvertFlag* flags.

SoundData *soundData

the sound data to be converted.

This object may or may not be modified depending on which flags are used. The converted data will be equivalent to the original data, just in the new requested format. Note that some destination formats may cause some information to be lost due to their compression or encoding methods. The converted data will contain at least the same number of frames and channels as the original data. Some block oriented compression formats may pad the stream with silent frames so that a full block can be written out. This may not be nullptr.

SampleFormat newFormat = SampleFormat::eDefault 

the requested destination format for the conversion operation.

For some formats, this may result in data or quality loss. If this format is not supported for encoding, the operation will fail. This can be SampleFormat::eDefault to use the same as the original format. This is useful when also using the fConvertFlagCopy to duplicate a sound data object.

Note that if this new format matches the existing format this will be a no-op unless the fConvertFlagCopy flag is specified. If the ‘copy’ flag is used, this will simply duplicate the existing object. The new object will still need to be destroyed with release() when it is no longer needed.

void *encoderSettings = nullptr

additional output format dependent encoder settings.

This should be nullptr for PCM data formats. Additional objects will be defined for encoder formats that require additional parameters (optional or otherwise). For formats that require additional settings, this may not be nullptr. Use getCodecFormatInfo() to retrieve the info for the codec to find out if the additional settings are required or not.

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 was used when creating the sound data object being converted.

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. This is intended to be used in cases where the SoundData is using some resource that needs to be released after the SoundData is destroyed.

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 *ext = nullptr

reserved for future expansion.

This must be set to nullptr.