carb::audio::IAudioUtils

Defined in carb/audio/IAudioUtils.h

struct IAudioUtils

General audio utilities.

This interface contains a bunch of miscellaneous audio functionality that many audio applications can make use of.

Public Members

bool (*clearToSilence)(SoundData *sound)

clears a sound data object to silence.

Note

this will remove the SDO from user memory.

Note

this will clear the entire buffer, not just the valid portion.

Note

this will be a lossy operation for some formats.

Param sound: [in] the sound data object to clear. This may not be nullptr.
Return: true if the clearing operation was successful.
Return: false if the clearing operation was not successful.

bool (*saveToFile)(const SoundDataSaveDesc *desc)

save a sound data object to a file.

Remark

This attempts to save a sound data object to file. The destination data format in the file does not necessarily have to match the original sound data object. However, if the destination format does not match, the encoder for that format must be supported otherwise the operation will fail. Support for the requested encoder format may be queried with isCodecFormatSupported() to avoid exposing user facing functionality for formats that cannot be encoded.

Param desc: [in] a descriptor of how the sound data should be saved to file and which data format it should be written in. This may not be nullptr.
Return: true if the sound data is successfully written out to file.
Return: false if the sound data could not be written to file. This may include being unable to open or create the file, or if the requested output format could not be supported by the encoder.

OutputStream *(*openOutputStream)(const OutputStreamDesc *desc)

opens a new output stream object.

Remark

This opens a new output stream and prepares it to receive buffers of data from the stream. The header will be written to the file, but it will initially represent an empty stream. The destination data format in the file does not necessarily have to match the original sound data object. However, if the destination format does not match, the encoder for that format must be supported otherwise the operation will fail. Support for the requested encoder format may be queried with isCodecFormatSupported() to avoid exposing user facing functionality for formats that cannot be encoded.

Param desc: [in] a descriptor of how the stream should be opened. This may not be nullptr.
Return: a new output stream handle if successfully created. This object must be closed with closeOutputStream() when it is no longer needed.
Return: nullptr if the output stream could not be created. This may include being unable to open or create the file, or if the requested output format could not be supported by the encoder.

void (*closeOutputStream)(OutputStream *stream)

closes an output stream.

Remark

This closes an output stream object. The header for the file will always be updated so that it reflects the actual written stream size. Any additional updates for the chosen data format will be written to the file before closing as well.

Param stream: [in] the stream to be closed. This may not be nullptr. This must have been returned from a previous call to openOutputStream(). This object will no longer be valid upon return.
Return: no return value.

bool (*writeDataToStream)(OutputStream *stream, const void *data, size_t lengthInFrames)

writes a single buffer of data to an output stream.

Remark

This writes a single buffer of data to an open output stream. It is the caller’s responsibility to ensure this new buffer is the logical continuation of any of the previous buffers that were written to the stream. The buffer will always be encoded and written to the stream in its entirety. If any extra frames of data do not fit into one of the output format’s blocks, the remaining data will be cached in the encoder and added to by the next buffer. If the stream ends and the encoder still has a partial block waiting, it will be padded with silence and written to the stream when it is closed.

Param stream: [in] the stream to write the buffer to. This handle must have been returned by a previous call to openOutputStream() and must not have been closed yet. This may not be nullptr.
Param data: [in] the buffer of data to write to the file. The data in this buffer is expected to be in data format specified when the output stream was opened. This buffer must be block aligned for the given input format. This may not be nullptr.
Param lengthInFrames: [in] the size of the buffer to write in frames. All frames in the buffer must be complete. Partial frames will neither be detected nor handled.
Return: true if the buffer is successfully encoded and written to the stream.
Return: false if the buffer could not be encoded or an error occurs writing it to the stream.

carb::audio::SoundData *(*convert)(const ConversionDesc *desc)

converts a sound data object from one format to another.

Remark

This converts a sound data object from one format to another or duplicates an object. The conversion operation may be performed on the same sound data object or it may create a new object. The returned sound data object always needs to be released with release() when it is no longer needed. This is true whether the original object was copied or not.

Note

The destruction callback is not copied to the returned SoundData even if an in-place conversion is requested.

Note

If fConvertFlagInPlace is passed and the internal buffer of the input SoundData is being replaced, the original destruction callback on the input SoundData will be called.

Param desc: [in] the descriptor of how the conversion operation should be performed. This may not be nullptr.
Return: the converted sound data object.
Return: nullptr if the conversion could not occur.

carb::audio::SoundData *(*duplicate)(const SoundData *sound)

duplicates a sound data object.

Remark

This duplicates a sound data object. The new object will have the same format and data content as the original. If the original referenced user memory, the new object will get a copy of its data, not the original pointer. If the new object should reference the original data instead, convert() should be used instead.

Param sound: [in] the sound data object to duplicate. This may not be nullptr.
Return: the duplicated sound data object. This must be destroyed when it is no longer needed with a call to release().

bool (*transcodePcm)(const TranscodeDesc *desc)

A helper function to transcode between PCM formats.

Remark

This function is a simpler alternative to decodeData() for cases where it is known that both the input and output formats are PCM formats.

Note

There is no requirement for the alignment of TranscodeDesc::inBuffer or TranscodeDesc::outBuffer, but the operation is most efficient when both are 32 byte aligned (e.g. (static_cast<uintptr_t>(inBuffer) & 0x1F) == 0).

Note

It is valid for TranscodeDesc::inFormat to be the same as TranscodeDesc::outFormat; this is equivalent to calling memcpy().

Param desc: [in] The descriptor of how the conversion operation should be performed. This may not be nullptr.
Return: true if the data is successfully transcoded.
Return: false if an invalid parameter is passed in or the conversion was not possible.
Return: false if the input buffer or the output buffer are misaligned for their specified sample format. createData() be used in cases where a misaligned buffer needs to be used (for example when reading raw PCM data from a memory-mapped file).

bool (*drawWaveform)(const AudioImageDesc *desc)

Render a SoundData’s waveform as an image.

Remark

This function can be used to visualize the audio samples in a sound buffer as an uncompressed RGBA8888 image.

Param desc: [in] The descriptor for the audio waveform input and output.
Return: true if visualization was successful.
Return: false if no sound was specified.
Return: false if the input image dimensions corresponded to a 0-size image or the buffer for the image was nullptr.
Return: false if the region of the sound to visualize was 0 length.
Return: false if the image pitch specified was non-zero and too small to fit an RGBA888 image of the desired width.
Return: false if the specified channel to visualize was invalid.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.