carb::audio::IAudioData

struct IAudioData

interface to manage audio data in general.

This includes loading audio data from multiple sources (ie: file, memory, raw data, user-decoded, etc), writing audio data to file, streaming audio data to file, decoding audio data to PCM, and changing its sample format. All audio data management should go through this interface.

See these pages for more detail:

Public Members

SoundData *(*createData)(const SoundDataLoadDesc *desc)

creates a new sound data object.

Remark

This creates a new sound data object from a requested data source. This single creation point manages the loading of all types of sound data from all sources. Depending on the flags used, the loaded sound data may or may not be decoded into PCM data.

Param desc: [in] a descriptor of how and from where the audio data should be loaded. This may not be nullptr.
Return: the newly created sound data object if it was successfully loaded or parsed. When this object is no longer needed, it must be freed with release().
Return: nullptr if the sound data could not be successfully loaded.

SoundData *(*acquire)(SoundData *sound)

acquires a new reference to a sound data object.

Remark

This grabs a new reference to a sound data object. Each reference that is taken must be released at some point when it is no longer needed. Note that the createData() function returns the new sound data object with a single reference on it. This final reference must also be released at some point to destroy the object.

Param sound: [in] the sound data object to take a reference to. This may not be nullptr.
Return: the sound data object with an additional reference taken on it. This new reference must later be released with release().

size_t (*release)(SoundData *sound)

releases a reference to a sound data object.

Remark

This releases a single reference to sound data object. If all references have been released, the object will be destroyed. Each call to grab a new reference with acquire() must be balanced by a call to release that reference. The object’s final reference that came from createData() must also be released in order to destroy it.

Param sound: [in] the sound data object to release a reference on. This may not be nullptr.
Return: the new reference count for the sound data object.
Return: 0 if the sound data object was destroyed (ie: all references were released).

DataFlags (*getFlags)(const SoundData *sound)

retrieves the creation time flags for a sound data object.

Param sound: [in] the sound data object to retrieve the creation time flags for.
Return: the flags that were used when creating the sound object. Note that if the sound data object was duplicated through a conversion operation, the data format flags may no longer be accurate.
Return: 0 if sound is nullptr.

const char *(*getName)(const SoundData *sound)

retrieves the name of the file this object was loaded from (if any).

Param sound: [in] the sound data object to retrieve the filename for.
Return: the original filename if the object was loaded from a file.
Return: nullptr if the object does not have a name.
Return: nullptr sound is nullptr.

size_t (*getLength)(const SoundData *sound, UnitType units)

retrieves the length of a sound data object’s buffer.

Remark

This retrieves the length of a sound data object’s buffer in the requested units. The length of the buffer represents the total amount of audio data that is represented by the object. Note that if this object was created to stream data from file or the data is stored still encoded or compressed, this will not reflect the amount of memory actually used by the object. Only non-streaming PCM formats will be able to convert their length into an amount of memory used.

Param sound: [in] the sound to retrieve the buffer length for. This may not be nullptr.
Param units: [in] the units to retrieve the buffer length in. Note that if the buffer length in milliseconds is requested, the length may not be precise.
Return: the length of the sound data object’s buffer in the requested units.

bool (*setValidLength)(SoundData *sound, size_t length, UnitType units)

sets the current ‘valid’ size of an empty buffer.

Remark

This sets the current amount of data in the sound data object buffer that is considered ‘valid’ by the caller. This should only be used on sound data objects that were created with the fDataFlagEmpty flag. If the host app decides to write data to the empty buffer, it must also set the amount of valid data in the buffer before that new data can be decoded successfully. When the object’s encoded format is not a PCM format, it is the caller’s responsibility to set both the valid byte and valid frame count since that may not be able to be calculated without creating a decoder state for the sound. When the object’s encoded format is a PCM format, both the frames and byte counts will be updated in a single call regardless of which one is specified.

Param sound: [in] the sound data object to set the new valid length for. This may not be nullptr.
Param length: [in] the new length of valid data in the units specified by units. This valid data length may not be specified in time units (ie: UnitType::eMilliseconds or UnitType::eMicroseconds) since it would not be an exact amount and would be likely to corrupt the end of the stream. This length must be less than or equal to the creation time length of the buffer.
Param units: [in] the units to interpret length in. This must be in frames or bytes.
Return: true if the new valid data length is successfully updated.
Return: false if the new length value was out of range of the buffer size or the sound data object was not created as empty.

size_t (*getValidLength)(const SoundData *sound, UnitType units)

retrieves the current ‘valid’ size of an empty buffer.

Remark

This retrieves the current valid data length for a sound data object. For sound data objects that were created without the fDataFlagEmpty flag, this will be the same as the value returned from getLength(). For an object that was created as empty, this will be the length that was last on the object with a call to setValidLength().

Param sound: [in] the sound data object to retrieve the valid data length for. This may not be nullptr.
Param units: [in] the units to retrieve the current valid data length in. Note that if a time unit is requested, the returned length may not be accurate.
Return: the valid data length for the object in the specified units.
Return: 0 if the buffer does not have any valid data.

void *(*getBuffer)(const SoundData *sound)

retrieves the data buffer for a sound data object.

Remark

This retrieves the data buffer for a sound data object. This is intended for cases such as empty sounds where data needs to be written into the buffer of sound. getReadBuffer() should be used for cases where writing to the buffer is not necessary, since not all sound will have a writable buffer. In-memory streaming sounds without fDataFlagUserMemory will return a buffer here; that buffer contains the full in-memory file, so writing to it will most likely corrupt the sound.

Param sound: [in] the sound to retrieve the data buffer for. This may not be nullptr.
Return: the data buffer for the sound data object.
Return: nullptr if sound does not have a writable buffer. This can occur for sounds created with fDataFlagUserMemory. In that case, the caller either already has the buffer address (ie: shared the memory block to save on memory or memory copy operations), or the memory exists in a location that should not be modified (ie: a sound bank or sound atlas).
Return: nullptr if the sound object is invalid.
Return: nullptr if sound is streaming from disk, since a sound streaming from disk will not have a buffer.

const void *(*getReadBuffer)(const SoundData *sound)

Retrieves the read-only data buffer for a sound data object.

Remark

This retrieves the data buffer for a sound data object. Any decoded SoundData will return a buffer of raw PCM data that can be directly played. getValidLength() should be used to determine the length of a decoded buffer. Any in-memory streaming SoundData will also return the raw file blob; this needs to be decoded before it can be played.

Param sound: [in] the sound to retrieve the data buffer for. This may not be nullptr.
Return: the data buffer for the sound data object.
Return: nullptr if the sound object is invalid.
Return: nullptr if sound is streaming from disk, since a sound streaming from disk will not have a buffer.

size_t (*getMemoryUsed)(const SoundData *sound)

retrieves the amount of memory used by a sound data object.

Remark

This retrieves the amount of memory used by a single sound data object. This will include all memory required to store the audio data itself, to store the object and all its parameters, and the original filename (if any). This information is useful for profiling purposes to investigate how much memory the audio system is using for a particular scene.

Param sound: [in] the sound data object to retrieve the memory usage for.
Return: the total number of bytes used to store the sound data object.
Return: 0 if sound is nullptr.

void (*getFormat)(const SoundData *sound, CodecPart type, SoundFormat *format)

Retrieves the format information for a sound data object.

Remark

This retrieves the format information for a sound data object. The format information will remain constant for the object’s lifetime so it can be safely cached once retrieved. Note that the encoded format information may not be sufficient to do all calculations on sound data of non-PCM formats.

Param sound: [in] The sound data object to retrieve the format information for. This may not be nullptr.
Param type: [in] The type of format information to retrieve. For sounds that were decoded on load, this parameter doesn’t have any effect, so it can be set to either value. For streaming sounds, CodecPart::eDecoder will cause the returned format to be the format that the audio will be decoded into (e.g. when decoding Vorbis to float PCM, this will return SampleFormat::ePcmFloat). For streaming sounds, CodecPart::eEncoder will cause the returned format to be the format that the audio is being decoded from (e.g. when decoding Vorbis to float PCM, this will return SampleFormat::eVorbis). In short, when you are working with decoded audio data, you should be using CodecPart::eDecoder; when you are displaying audio file properties to a user, you should be using CodecPart::eEncoder.
Param format: [out] Receives the format information for the sound data object. This format information will remain constant for the lifetime of the sound data object.
Return: No return value.

bool (*getPeakLevel)(const SoundData *sound, PeakVolumes *peaks)

retrieves or calculates the peak volume levels for a sound if possible.

Remark

This retrieves the peak volume level information for a sound. This information is either loaded from the sound’s original source file or is calculated if the sound is decoded into memory at load time. This information will not be calculated if the sound is streamed from disk or memory.

Param sound: [in] the sound data object to retrieve the peak information for. This may not be nullptr.
Param peaks: [out] receives the peak volume information for the sound data object sound. Note that only the entries corresponding to the number of channels in the sound data object will be written. The contents of the remaining channels is undefined.
Return: true if the peak volume levels are available or could be calculated.
Return: false if the peak volume levels were not calculated or loaded when the sound was created.

size_t (*getEventPoints)(const SoundData *sound, EventPoint *events, size_t maxEvents)

retrieves embedded event point information from a sound data object.

Remark

This retrieves event point information that was embedded in the sound file that was used to create a sound data object. The event points are optional in the data file and may not be present. If they are parsed from the file, they will also be saved out to any destination file that the same sound data object is written to, provided the destination format supports embedded event point information.

Param sound: [in] the sound data object to retrieve the event point information from. This may not be nullptr.
Param events: [out] receives the event point information. This may be nullptr if only the number of event points is required.
Param maxEvents: [in] the maximum number of event points that will fit in the events buffer. This must be 0 if events is nullptr.
Return: the number of event points written to the buffer events if it was not nullptr.
Return: if the buffer is not large enough to store all the event points, the maximum number that will fit is written to the buffer and the total number of event points is returned. This case can be detected by checking if the return value is larger than maxEvents.
Return: the number of event points contained in the sound object if the buffer is nullptr.

const EventPoint *(*getEventPointById)(const SoundData *sound, EventPointId id)

retrieves a single event point object by its identifier.

Note

Access to this event point information is not thread safe. It is the caller’s responsibility to ensure access to the event points on a sound data object is appropriately locked.

Param sound: [in] the sound data object to retrieve the named event point from. This may not be nullptr.
Param id: [in] the identifier of the event point to be retrieved.
Return: the information for the event point with the requested identifier if found. The returned object is only valid until the event point list for the sound is modified. This should not be stored for extended periods since its contents may be invalidated at any time.
Return: nullptr if no event point with the requested identifier is found.

const EventPoint *(*getEventPointByIndex)(const SoundData *sound, size_t index)

retrieves a single event point object by its index.

Note

Access to this event point information is not thread safe. It is the caller’s responsibility to ensure access to the event points on a sound data object is appropriately locked.

Param sound: [in] the sound data object to retrieve the event point from. This may not be nullptr.
Param index: [in] the zero based index of the event point to retrieve.
Return: the information for the event point at the requested index. The returned object is only valid until the event point list for the sound is modified. This should not be stored for extended periods since its contents may be invalidated at any time.
Return: nullptr if the requested index is out of range of the number of event points in the sound.

const EventPoint *(*getEventPointByPlayIndex)(const SoundData *sound, size_t playIndex)

retrieves a single event point object by its playlist index.

Note

Access to this event point information is not thread safe. It is the caller’s responsibility to ensure access to the event points on a sound data object is appropriately locked.

Param sound: [in] The sound data object to retrieve the event point from. This may not be nullptr.
Param playIndex: [in] The playlist index of the event point to retrieve. Playlist indexes may range from 1 to SIZE_MAX. 0 is not a valid playlist index. This function is intended to be called in a loop with values of playIndex between 1 and the return value of getEventPointMaxPlayIndex(). The range of valid event points will always be contiguous, so nullptr should not be returned within this range.
Return: the information for the event point at the requested playlist index. The returned object is only valid until the event point list for the sound is modified. This should not be stored for extended periods since its contents may be invalidated at any time.
Return: nullptr if playIndex is 0.
Return: nullptr if no event point has a playlist index of playIndex.

size_t (*getEventPointMaxPlayIndex)(const SoundData *sound)

Retrieve the maximum play index value for the sound.

Param sound: [in] The sound data object to retrieve the event point index from. This may not be nullptr.
Return: This returns the max play index for this sound. This will be 0 if no event points have a play index. This is also the number of event points with playlist indexes, since the playlist index range is contiguous.

bool (*setEventPoints)(SoundData *sound, const EventPoint *eventPoints, size_t count)

modifies, adds, or removes event points in a sound data object.

Remark

This modifies, adds, or removes one or more event points in a sound data object. An event point will be modified if one with the same ID already exists. A new event point will be added if it has an ID that is not already present in the sound data object and its frame offset is valid. An event point will be removed if it has an ID that is present in the sound data object but the frame offset for it is set to kEventPointInvalidFrame. Any other event points with invalid frame offsets (ie: out of the bounds of the stream) will be skipped and cause the function to fail.

Note

When adding a new event point or changing a string in an event point, the strings will always be copied internally instead of referencing the caller’s original buffer. The caller can therefore clean up its string buffers immediately upon return. The user data object (if any) however must persist since it will be referenced instead of copied. If the user data object needs to be cleaned up, an appropriate destructor function for it must also be provided.

Note

If an event point is modified or removed such that the playlist indexes of the event points are no longer contiguous, this function will adjust the play indexes of all event points to prevent any gaps.

Note

The playIndex fields on eventPoints must be within the region of [0, count + getEventPoints(sound, nullptr, 0)]. Trying to set playlist indexes outside this range is an error.

Param sound: [inout] the sound data object to update the event point(s) in. This may not be nullptr.
Param eventPoints: [in] the event point(s) to be modified or added. The operation that is performed for each event point in the table depends on whether an event point with the same ID already exists in the sound data object. The event points in this table do not need to be sorted in any order. This may be kEventPointTableClear to indicate that all event points should be removed.
Param count: [in] the total number of event points in the eventPoint table. This must be 0 if eventPoints is nullptr.
Return: true if all of the event points in the table are updated successfully.
Return: false if not all event points could be updated. This includes a failure to allocate memory or an event point with an invalid frame offset. Note that this failing doesn’t mean that all the event points failed. This just means that at least failed to be set properly. The new set of event points may be retrieved and compared to the list set here to determine which one failed to be updated.

uint32_t (*getMaxInstances)(const SoundData *sound)

retrieves the maximum simultaneously playing instance count for a sound.

Remark

This retrieves the current maximum instance count for a sound. This limit is used to prevent too many instances of a sound from being played simultaneously. With the limit set to unlimited, playing too many instances can result in serious performance penalties and serious clipping artifacts caused by too much constructive interference.

Param sound: [in] the sound to retrieve the maximum instance count for. This may not be nullptr.
Retval kInstancesUnlimited: if the instance count is unlimited.
Return: the maximum instance count for the sound if it is limited.

void (*setMaxInstances)(SoundData *sound, uint32_t limit)

sets the maximum simultaneously playing instance count for a sound.

Remark

This sets the new maximum playing instance count for a sound. This limit will prevent the sound from being played until another instance of it finishes playing or simply cause the play request to be ignored completely. This should be used to limit the use of frequently played sounds so that they do not cause too much of a processing burden in a scene or cause too much constructive interference that could lead to clipping artifacts. This is especially useful for short sounds that are played often (ie: gun shots, foot steps, etc). At some [small] number of instances, most users will not be able to tell if a new copy of the sound played or not.

Param sound: [in] the sound to change the maximum instance count for. This may not be nullptr.
Param limit: [in] the new maximum instance limit for the sound. This may be kInstancesUnlimited to remove the limit entirely.
Return: no return value.

void *(*getUserData)(const SoundData *sound)

retrieves the user data pointer for a sound data object.

Remark

This retrieves the user data pointer for the requested sound data object. This is used to associate any arbitrary data with a sound data object. It is the caller’s responsibility to ensure access to data is done in a thread safe manner.

Param sound: [in] the sound data object to retrieve the user data pointer for. This may not be nullptr.
Return: the stored user data pointer.
Return: nullptr if no user data has been set on the requested sound.

void (*setUserData)(SoundData *sound, const UserData *userData)

sets the user data pointer for a sound data object.

Remark

This sets the user data pointer for this sound data object. This is used to associate any arbitrary data with a sound data object. It is the caller’s responsibility to ensure access to this table is done in a thread safe manner.

Note

The user data object must not hold a reference to the sound data object that it is attached to. Doing so will cause a cyclical reference and prevent the sound data object itself from being destroyed.

Note

The sound data object that this user data object is attached to must not be accessed from the destructor. If the sound data object is being destroyed when the user data object’s destructor is being called, its contents will be undefined.

Param sound: [in] the sound data object to set the user data pointer for. This may not be nullptr.
Param userData: [in] the new user data pointer to set. This may include an optional destructor if the user data object needs to be cleaned up. This may be nullptr to indicate that the user data pointer should be cleared out.
Return: no return value.

const CodecInfo *(*getCodecFormatInfo)(SampleFormat encodedFormat, SampleFormat pcmFormat)

retrieves information about a supported codec.

Remark

This retrieves the information about a single codec. This can be used to check if an encoding or decoding operation to or from a requested format pair is possible and to retrieve some information suitable for display or UI use for the format.

Param encodedFormat: [in] the encoded format to retrieve the codec information for. This may not be SampleFormat::eDefault or SampleFormat::eRaw. This is the format that the codec either decodes from or encodes to.
Param pcmFormat: [in] the PCM format for the codec that the information would be retrieved for. This may be SampleFormat::eDefault to retrieve the information for the codec for the requested encoded format that decodes to the preferred PCM format. This may not be SampleFormat::eRaw.
Return: the info block for the codec that can handle the requested operation if found.
Return: nullptr if no matching codec for encodedFormat and pcmFormat could be found.

CodecState *(*createCodecState)(const CodecStateDesc *desc)

creates a new decoder or encoder state for a sound data object.

Remark

This creates a new decoder or encoder state instance for a sound object. This will encapsulate all the information needed to perform the operation on the stream as efficiently as possible. Note that the output format of the decoder will always be a PCM variant (ie: one of the SampleFormat::ePcm* formats). Similarly, the input of the encoder will always be a PCM variant. The input of the decoder and output of the encoder may be any format.

Remark

The decoder will treat the sound data object as a stream and will decode it in chunks from start to end. The decoder’s read cursor will initially be placed at the start of the stream. The current read cursor can be changed at any time by calling setCodecPosition(). Some compressed or block based formats may adjust the new requested position to the start of the nearest block.

Remark

The state is separated from the sound data object so that multiple playing instances of each sound data object may be decoded and played simultaneously regardless of the sample format or decoder used. Similarly, when encoding this prevents any limitation on the number of targets a sound could be streamed or written to.

Remark

The encoder state is used to manage the encoding of a single stream of data to a single target. An encoder will always be able to be created for an operation where the source and destination formats match. For formats that do not support encoding, this will fail. More info about each encoder format can be queried with getCodecFormatInfo().

Remark

The stream being encoded is expected to have the same number of channels as the chosen output target.

Param desc: [in] a descriptor of the decoding or encoding operation that will be performed. This may not be nullptr.
Return: the new state object if the operation is valid and the state was successfully initialized. This must be destroyed with destroyCodecState() when it is no longer needed.
Return: nullptr if the operation is not valid or the state could not be created or initialized.

void (*destroyCodecState)(CodecState *decodeState)

destroys a codec state object.

Remark

This destroys a decoder or encoder state object that was previously returned from createCodecState(). For a decoder state, any partially decoded data stored in the state object will be lost. For an encoder state, all pending data will be written to the output target (padded with silence if needed). If the encoder was targeting an output stream, the stream will not be closed. If the encoder was targeting a sound data object, the stream size information will be updated. The buffer will not be trimmed in size if it is longer than the actual stream.

Param state: [in] the codec state to destroy. This call will be ignored if this is nullptr.
Return: no return value.

const void *(*decodeData)(CodecState *decodeState, void *buffer, size_t framesToDecode, size_t *framesDecoded)

decodes a number of frames of data into a PCM format.

Remark

This decodes a requested number of frames of data into an output buffer. The data will always be decoded into a PCM format specified by the decoder when the sound data object is first created. If the sound data object already contains PCM data in the requested format, nothing will be written to the destination buffer, but a pointer into the data buffer itself will be returned instead. The returned pointer must always be used instead of assuming that the decoded data was written to the output buffer. Similarly, the framesToDecode count must be used instead of assuming that exactly the requested number of frames were successfully decoded.

Param decodeState: [in] the decoder state to use for the decoding operation. This may not be nullptr.
Param buffer: [out] receives the decoded PCM data. This buffer must be at least large enough to hold framesToDecode frames of data in the sound data object’s stream. This may not be nullptr.
Param framesToDecode: [in] the requested number of frames to decode. This is taken as a suggestion. Up to this many frames will be decoded if it is available in the stream. If the stream ends before this number of frames is read, the remainder of the buffer will be left unmodified.
Param framesDecoded: [out] receives the number of frames that were actually decoded into the output buffer. This will never be larger than the framesToDecode value. This may not be nullptr.
Return: buffer if the decode operation is successful and the decoded data was copied into the output buffer.
Return: a non-nullptr value if the sound data object already contains PCM data in the requested decoded format.
Return: nullptr if the decode operation failed for any reason.
Return: nullptr if framesToDecode is 0.

size_t (*getDecodeAvailable)(const CodecState *decodeState, UnitType units)

retrieves the amount of data available to decode in a sound data object.

Remark

This retrieves the amount of data left to decode from the current read cursor to the end of the stream. Some formats may not be able to calculate the amount of available data.

Param decodeState: [in] the decode state to retrieve the amount of data that is available from the current read cursor position to the end of the stream. This may not be nullptr.
Param units: [in] the units to retrieve the available data count in. Note that if time units are requested (ie: milliseconds), the returned value will only be an estimate of the available data.
Return: the amount of available data in the requested units.
Return: 0 if no data is available or it could not be calculated.

size_t (*getCodecPosition)(const CodecState *decodeState, UnitType units)

retrieves the current cursor position for a codec state.

Remark

This retrieves the current cursor position for a codec state. Some formats may not be able to calculate an accurate cursor position and may end up aligning it to the nearest block boundary instead.

Note

Even though the write cursor for an encoder state can be retrieved, setting it is not possible since that would cause a discontinuity in the stream and corrupt it. If the stream position needs to be rewound to the beginning, the encoder state should be recreated and the stream started again on a new output target.

Param state: [in] the codec state to retrieve the current read cursor position for. This may not be nullptr.
Param units: [in] the units to retrieve the current read cursor position in. Note that if time units are requested (ie: milliseconds), the returned value will only be an estimate of the current position since time units are not accurate. UnitType::eBytes is invalid if the codec being used specifies fCodecCapsCompressed.
Return: the current cursor position in the requested units. For a decoder state, this is the location in the sound’s data where the next decoding operation will start from. For an encoder state, this is effectively the amount of data that has been successfully encoded and written to the target.
Return: 0 if the cursor is at the start of the buffer or output target.
Return: 0 if the decode position could not be calculated.
Return: 0 if no data has been successfully written to an output target.

bool (*setCodecPosition)(CodecState *decodeState, size_t newPosition, UnitType units)

sets the new decoder position.

Remark

This attempts to set the decoder’s read cursor position to a new offset in the sound buffer. The new position may not be accurately set depending on the capabilities of the codec. The position may be aligned to the nearest block boundary for sound codecs and may fail for others.

Param decodeState: [in] the decoder state to set the position for. This may not be nullptr. This must be a decoder state.
Param newPosition: [in] the new offset into the sound data object’s buffer to set the read cursor to. The units of this offset depend on the value in units.
Param units: [in] the units to interpret the newPosition offset in. Note that if time units are requested (ie: milliseconds), the new position may not be accurate in the buffer. The only offset that can be guaranteed accurate in time units is 0.
Return: true if the new decoding read cursor position was successfully set.
Return: false if the new position could not be set or an encoder state was used.

size_t (*getCodecDataSizeEstimate)(const CodecState *decodeState, size_t inputBytes)

calculates the maximum amount of data that a codec produce for a given input size.

Remark

This calculates the maximum buffer size that would be needed to hold the output of the codec operation specified by the state object. This can be used to allocate or prepare a destination that is large enough to receive the operation’s full result. Note that the units of both the inputs and outputs are different depending on the type of codec state that is used. This is necessary because the size of an encoded buffer in frames cannot always be calculated for a given byte size and vice versa. Some sample formats only allow for an upper limit to be calculated for such cases.

Remark

For a decoder state, this calculates the maximum number of frames of PCM data that could be produced given a number of input bytes in the decoder state’s output format. This is used to be able to allocate a decoding buffer that is large enough to hold the results for a given input request.

Remark

For an encoder state, this calculates an estimate of the buffer size needed in order to store the encoder output for a number of input frames. For PCM formats, the returned size will be exact. For compressed formats, the returned size will be an upper limit on the size of the output stream. Note that this value is not always fully predictable ahead of time for all formats since some depend on the actual content of the stream to adapt their compression (ie: variable bit rate formats, frequency domain compression, etc).

Param state: [in] the codec state to estimate the buffer size for. This may not be nullptr. This may be either an encoder or decoder state.
Param inputSize: [in] for a decoder state, this is the number of bytes of input to estimate the output frame count for. For an encoder state, this is the number of frames of data that will be submitted to the encoder during the encoding operation.
Return: an upper limit on the number of frames that can be decoded from the given input buffer size for decoder states.
Return: an upper limit on the size of the output buffer in bytes that will be needed to hold the output for an encoder state.
Return: 0 if the frame count could not be calculated or the requested size was 0.

size_t (*encodeData)(CodecState *encodeState, const void *buffer, size_t lengthInFrames)

encodes a simple buffer of data into the output target for the operation.

Remark

This encodes a single buffer of data into an output target. The buffer is expected to be in the input sample format for the encoder. The buffer is also expected to be the logical continuation of any previous buffers in the stream.

Param encodeState: [in] the encoder state object that is managing the stream encoding operation. This may not be nullptr.
Param buffer: [in] the buffer of data to be encoded. This is expected to be in the input data format specified when the encoder state object was created. This may not be nullptr.
Param lengthInFrames: [in] the size of the input buffer in frames.
Return: the number of bytes that were successfully encoded and written to the output target.
Return: 0 if the buffer could not be encoded or the output target has become full or or fails to write (ie: the sound data object is full and is not allowed or able to expand, or writing to the output stream failed).

const char *(*getMetaDataTagName)(const SoundData *sound, size_t index, const char **value)

Retrieve the names of the metadata tags in a SoundData.

Remark

This function allows the metadata of a SoundData object to be enumerated. This function can be called with incrementing indices, starting from 0, to retrieve all of the metadata tag names. value can be used to retrieve the contents of each metadata tag, if the contents of each tag is needed.

Note

If setMetaData() is called, the order of the tags is not guaranteed to remain the same.

Param sound: [in] The sound to retrieve the metadata tag names from.
Param index: [in] The index of the metadata tag in the sound object. To enumerate all tags in sound, one should call this with index == 0, then increment until nullptr is returned from this function. Note that adding or removing tags may alter the ordering of this table, but changing the value of a tag will not.
Param value: [out] If this is non-null and a metadata tag exists at index index, the contents of the metadata tag under the returned name is assigned to value. If this is non-null and no metadata tag exists at index index, value is assigned to nullptr. This string is valid until sound is destroyed or this entry in the metadata table is changed or removed.
Return: This returns a null terminated string for the tag name, if a tag at index index exists. The returned string is valid until sound is destroyed or this entry in the metadata table is changed or removed.
Return: This returns nullptr if no tag at index exists.

const char *(*getMetaData)(const SoundData *sound, const char *tagName)

Retrieve a metadata tag from a SoundData.

Param sound: [in] The sound to retrieve the metadata tag from.
Param tagName: [in] The name of the metadata tag to retrieve. For example “artist” may retrieve the name of the artist who created the SoundData object’s contents. This may not be nullptr.
Return: This returns a null terminated string if a metadata tag under the name tagName exited in sound. The returned string is valid until sound is destroyed or this entry in the metadata table is changed or removed.
Return: This returns nullptr if no tag under the name tagName was found in sound.

bool (*setMetaData)(SoundData *sound, const char *tagName, const char *tagValue)

Set a metadata tag on a SoundData.

Note

tagName and tagValue are copied internally, so it is safe to immediately deallocate them after calling this.

Note

Metadata tag names are not case sensitive.

Note

It is not guaranteed that a given file type will be able to store arbitrary key-value pairs. RIFF files (.wav), for example, store metadata tags under 4 character codes, so only metadata tags that are known to this plugin, such as kMetaDataTagArtist or tags that are 4 characters in length can be stored. Note this means that storing 4 character tags beginning with ‘I’ runs the risk of colliding with the known tag names (e.g. ‘IART’ will collide with kMetaDataTagArtist when writing a RIFF file).

Note

tagName must not contain the character ‘=’ when the output format encodes its metadata in the Vorbis Comment format (SampleFormat::eVorbis and SampleFormat::eFlac do this). ‘=’ will be replaced with ‘_’ when encoding these formats to avoid the metadata being encoded incorrectly. Additionally, the Vorbis Comment standard states that tag names must only contain characters from 0x20 to 0x7D (excluding ‘=’) when encoding these formats.

Param sound: [in] The sound to retrieve the metadata tag from.
Param tagName: [in] The name of the metadata tag to set. For example, one may set a tag with tagName “artist” to specify the creator of the SoundData’s contents. This can be set to kMetaDataTagClearAllTags to remove all metadata tags on the sound object.
Param tagValue: [in] A null terminated string to set as the value for tagName. This can be set to nullptr to remove the tag under tagName from the object.
Return: This returns true if the tags was successfully added or changed.
Return: This returns false if tagValue is nullptr and no tag was found under the name tagName.
Return: This returns false if an error occurred which prevented the tag from being set.

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.