carb::audio::IAudioGroup

struct IAudioGroup

Sound group management interface.

See these pages for more detail:

Public Members

Group *(*createGroup)(const GroupDesc *desc)

creates a new sound group.

Remark

This creates a new sound group object. A sound group may contain zero or more sound data objects. The group may be initially populated by one or more sound data objects that are specified in the descriptor or it may be created empty.

Note

Access to the group object is not thread safe. It is the caller’s responsibility to ensure that all accesses that may occur simultaneously are properly protected with a lock.

Param desc: [in] a descriptor of the new group to be created. This may be nullptr to create a new, empty, unnamed group.
Return: the new group object if successfully created. This must be destroyed with a call to destroyGroup() when it is no longer needed.
Return: nullptr if the new group could not be created.

void (*destroyGroup)(Group *group)

destroys a sound group.

Remark

This destroys a sound group object. Each sound data object in the group at the time of destruction will have one reference removed from it. The group object will no longer be valid upon return.

Param group: [in] the group to be destroyed. This must not be nullptr.
Return: no return value.

size_t (*getSize)(const Group *group)

retrieves the number of sound data objects in a group.

Param group: [in] the group to retrieve the sound data object count for. This must not be nullptr.
Return: the total number of sound data objects in the group.
Return: 0 if the group is empty.

const char *(*getName)(const Group *group)

retrieves the name of a group.

Remark

This retrieves the name of a group. The returned string will be valid until the group’s name is changed with setGroupName() or the group is destroyed. It is highly recommended that the returned string be copied if it needs to persist.

Param group: [in] the group to retrieve the name for. This must not be nullptr.
Return: the name of the group.
Return: nullptr if the group does not have a name.

void (*setName)(Group *group, const char *name)

sets the new name of a group.

Remark

This sets the new name for a group. This will invalidate any names that were previously returned from getGroupName() regardless of whether the new name is different.

Param group: [in] the group to set the name for. This must not be nullptr.
Param name: [in] the new name to set for the group. This may be nullptr to remove the group’s name.
Return: no return value.

size_t (*addSound)(Group *group, SoundData *sound)

adds a new sound data object to a group.

Remark

This adds a new sound data object to a group. The group will take a reference to the sound data object when it is successfully added. There will be no checking to verify that the sound data object is not already a member of the group. The initial relative probability for any new sound added to a group will be 1.0. This may be changed later with setProbability().

Note

This returned index is only returned for the convenience of immediately changing the sound’s other attributes within the group (ie: the relative probability). This index should not be stored for extended periods since it may be invalidated by any calls to removeSound*(). If changes to a sound in the group need to be made at a later time, the index should either be known ahead of time (ie: from a UI that is tracking the group’s state), or the group’s members should be enumerated to first find the index of the desired sound.

Param group: [in] the group to add the new sound data object to. This must not be nullptr.
Param sound: [in] the sound data object to add to the group. This must not be nullptr.
Retval kGroupIndexInvalid: if the new sound could not be added to the group.
Return: the index of the new sound in the group if it is successfully added.

size_t (*addSoundWithRegion)(Group *group, const SoundEntry *sound)

adds a new sound data object with a play region to a group.

Remark

This adds a new sound data object with a play range to a group. The group will take a reference to the sound data object when it is successfully added. There will be no checking to verify that the sound data object is not already a member of the group. The play region for the sound may indicate the full sound or only a small portion of it. The initial relative probability for any new sound added to a group will be 1.0. This may be changed later with setProbability().

Note

This returned index is only returned for the convenience of immediately changing the sound’s other attributes within the group (ie: the relative probability). This index should not be stored for extended periods since it may be invalidated by any calls to removeSound*(). If changes to a sound in the group need to be made at a later time, the index should either be known ahead of time (ie: from a UI that is tracking the group’s state), or the group’s members should be enumerated to first find the index of the desired sound.

Param group: [in] the group to add the new sound data object to. This must not be nullptr.
Param sound: [in] the sound data object and play range data to add to the group. This must not be nullptr.
Retval kGroupIndexInvalid: if the new sound could not be added to the group.
Return: the index of the new sound in the group if it is successfully added.

bool (*removeSound)(Group *group, SoundData *sound)

removes a sound data object from a group.

Remark

This removes a single sound data object from a group. Only the first instance of the requested sound will be removed from the group. If the sound is present in the group multiple times, additional explicit calls to remove the sound must be made to remove all of them.

Note

Once a sound is removed from a group, the ordering of sounds within the group may change. The relative probabilities of each remaining sound will still be unmodified.

Param group: [in] the group to remove the sound from. This must not be nullptr.
Param sound: [in] the sound to be removed from the group. This may be nullptr to remove all sound data objects from the group.
Return: true if the sound is a member of the group and it is successfully removed.
Return: false if the sound is not a member of the group.

bool (*removeSoundAtIndex)(Group *group, size_t index)

removes a sound data object from a group by its index.

Note

Once a sound is removed from a group, the ordering of sounds within the group may change. The relative probabilities of each remaining sound will still be unmodified.

Param group: [in] the group to remove the sound from. This must not be nullptr.
Param index: [in] the zero based index of the sound to remove from the group. This may be kGroupIndexAll to clear the entire group. This must not be kGroupIndexInvalid.
Return: true if the sound is a member of the group and it is successfully removed.
Return: false if the given index is out of range of the size of the group.

bool (*setSoundRegion)(Group *group, size_t index, const SoundEntry *region)

sets the current sound play region for an entry in the group.

Remark

This modifies the play region values for a single sound entry in the group. This will not replace the sound data object at the requested entry. Only the play region (start, length, and units) will be updated for the entry. It is the caller’s responsibility to ensure the new play region values are within the range of the sound data object’s current valid region.

Param group: [in] the group to modify the play region for a sound in. This must not be nullptr.
Param index: [in] the zero based index of the sound entry to update the region for. This must not be kGroupIndexInvalid or kGroupIndexAll.
Param region: [in] the specification of the new region to set on the sound. The sound member will be ignored and assumed that it either matches the sound data object already at the given index or is nullptr. All other members must be valid. This must not be nullptr.
Return: true if the play region for the selected sound is successfully updated.
Return: false if the index was out of range of the size of the group.

SoundData *(*getSound)(const Group *group, size_t index)

retrieves the sound data object at a given index in a group.

Param group: [in] the group to retrieve a sound from. This must not be nullptr.
Param index: [in] the index of the sound data object to retrieve. This must not be kGroupIndexInvalid or kGroupIndexAll.
Return: the sound data object at the requested index in the group. An extra reference to this object will not be taken and therefore does not have to be released. This object will be valid as long as it is still a member of the group.
Return: nullptr if the given index was out of range of the size of the group.

bool (*getSoundEntry)(const Group *group, size_t index, SoundEntry *entry)

retrieves the sound data object and region information at a given index in a group.

Param group: [in] the group to retrieve a sound from. This must not be nullptr.
Param index: [in] the index of the sound data object information to retrieve. This must not be kGroupIndexInvalid or kGroupIndexAll.
Param entry: [out] receives the information for the sound entry at the given index in the group. This not be nullptr.
Return: true if the sound data object and its region information are successfully retrieved. The sound data object returned in entry will not have an extra reference taken to it and does not need to be released.
Return: false if the given index was out of range of the group.

void (*setProbability)(Group *group, const ProbabilityDesc *desc)

sets the new relative probability for a sound being selected from a sound group.

Remark

This sets the new relative probability for choosing a sound within a sound group. Each sound in the group gets a relative probability of 1 assigned to it when it is first added to the group (ie: giving a uniform distribution initially). These relative probabilities can be changed later by setting a new value for individual sounds in the group. The actual probability of a particular sound being chosen from the group depends on the total sum of all relative probabilities within the group as a whole. For example, if a group of five sounds has been assigned the relative probabilities 1, 5, 7, 6, and 1, there is a 1/20 chance of the first or last sounds being chosen, a 1/4 chance of the second sound being chosen, a 7/20 chance of the third sound being chosen, and a 6/20 chance of the fourth sound being chosen.

Param group: [in] the sound group to change the relative probabilities for. This must not be nullptr.
Param desc: [in] the descriptor of the sound within the group to be changed and the new relative probability for it. This must not be nullptr.
Return: no return value.

float (*getProbability)(const Group *group, size_t index)

retrieves a relative probability for a sound being selected from a sound group.

Remark

This retrieves the relative probability of the requested sound within a group being chosen by the chooseSound() function when using the ChooseType::eRandom selection type. Note that this will always the relative probability value that was either assigned when the sound was added to the group (ie: 1.0) or the one that was most recently set using a call to the setProbability() function.

Note

This is intended to be called in an editor situation to retrieve the relative probability values that are currently set on a group for display purposes.

Param group: [in] the group to retrieve a relative probability for.
Param index: [in] the index of the sound in the group to retrieve the relative probability for. If this is out of range of the size of the group, the call will fail. This must not be kGroupIndexAll or kGroupIndexInvalid.
Return: the relative probability of the requested sound within the group.
Return: 0.0 if the requested index was out of range of the group’s size.

float (*getProbabilityTotal)(const Group *group)

gets the relative probability total for all sounds in the group.

Remark

This retrieves the total of all relative probabilities for all sounds in a group. This can be used to calculate the absolute probability of each sound in the group. This is done by retrieving each sound’s relative probability with getProbability(), then dividing it by the value returned here.

Param group: [in] the group to retrieve the relative probabilities total for. This must not be nullptr.
Return: the sum total of the relative probabilities of each sound in the group.
Return: 0.0 if the group is empty or all sounds have a zero relative probability. It is the caller’s responsibility to check for this before using it as a divisor.

bool (*chooseSound)(Group *group, ChooseType type, PlaySoundDesc *play)

chooses a sound from a sound group.

Remark

This chooses a sound from a group according to the given algorithm. When choosing a random sound, the sound is chosen using the relative probabilities of each of the sounds in the group. When choosing the next or previous sound, the sound in the group either after or before the last one that was most recently returned from chooseSound() will be returned. This will never fail unless the group is empty.

Param group: [in] the group to select a sound from. This must not be nullptr.
Param type: [in] the specific algorithm to use when choosing the sound.
Param play: [out] receives the play descriptor for the chosen sound. On success, this will be filled in with enough information to play the chosen sound and region once as a non-spatial sound. It is the caller’s responsibility to fill in any additional parameters (ie: voice callback function, additional voice parameters, spatial sound information, etc). This must not be nullptr. This object is assumed to be uninitialized and all members will be filled in.
Return: true if a sound if chosen and the play descriptor play is valid.
Return: false if the group is empty.
Return: false if the maximum number of sound instances from this group are already playing. This may be tried again later and will succeed when the playing instance count drops below the limit.

uint32_t (*getMaxInstances)(const Group *group)

retrieves the maximum simultaneously playing instance count for sounds in a group.

Remark

This retrieves the current maximum instance count for the sounds in a group. This limit is used to prevent too many instances of sounds in this group 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 group: [in] the group to retrieve the maximum instance count for. This must not be nullptr.
Retval kInstancesUnlimited: if the instance count is unlimited.
Return: the maximum instance count for the group if it is limited.

void (*setMaxInstances)(Group *group, uint32_t limit)

sets the maximum simultaneously playing instance count for sounds in a group.

Remark

This sets the new maximum playing instance count for sounds in a group. This limit only affects the results of chooseSound(). When the limit is exceeded, calls to chooseSound() will start failing until some sound instances in the group finish playing. This instance limit is also separate from the maximum instance count for each sound in the group. Individual sound data objects also have their own maximum instance counts and will limit themselves when they are attempted to be played. Note that these two limits may however interact with each other if the group’s instance limit is not hit but the instance limit for the particular chosen sound has been reached. It is the caller’s responsibility to ensure the various instance limits are set in such a way this interaction is minimized.

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

void *(*getUserData)(const Group *group)

retrieves the user data pointer for a sound group object.

Remark

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

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

void (*setUserData)(Group *group, const UserData *userData)

sets the user data pointer for a sound group.

Remark

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

Note

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

Param group: [in] the sound group to set the user data pointer for. This must 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 entirely and no new object stored.
Return: no return value.

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.