Carbonite Sound Group Interface


The carb::audio::IAudioGroup interface is used to collect similar sounds into a single group. The group may be used to select a sound to be played. A sound group typically contains one or more sounds that have a similar purpose, for example a group of slightly different footstep sounds. The group can be used to select sounds to be played to give some variety to a scene instead of always playing just one sound for a purpose.

As many sound group objects as are needed may be created from this interface. Each group has an optional name, an instance limit, and a user data pointer. The group’s name is simply used for identification purposes, usually in an editor setting. The name has no other functional effect on the group object. The instance limit allows too many individual instances of the sounds from the group to be played simultaneously. This is useful when the group contains sounds that are played frequently. After a certain number of simultaneous instances of the sounds from the group, playing one more doesn’t add anything to the scene, but just uses up processing time and resources. The group’s user data pointer simply allows the host app to attach its own data object to the group. The group will never access the user data object itself, but simply store and retrieve it for the host app.

Each group may contain one or more sound data objects. There is no set limit on the number of sound data objects that may be added to a group. Each sound data object in a group will have a single reference taken on it. A single sound data object may be added to a group multiple times as well. In this case, multiple references will be taken on the sound data object. When adding a sound data object to a group, it can be set to play the entire sound or just a small region of it. Each sound in the group may also have a probability associated with it (more on this later).

Main Operations

The main operations for a sound group are adding, removing, or retrieving a sound from the group, and choosing a sound from the group. New sounds may be added either as a whole (ie: play the entire sound when chosen), or only a region of the sound. Sounds may be removed by sound data object or index. Sounds may be retrieved as just the sound data object at a given index or as the full entry with the play region at a given index. Sounds may be chosen from the group in one of many modes:

  • first or last: choose the first or last sound data object in the group.

  • next or previous: choose the next or previous sound in the group from the last choose operation. If the last or first sound is reached, it will wrap around for the next chosen sound.

  • random: choose a random sound from the group. By default, a uniform probability will be used for choosing each sound in the group. Each sound in the group may however be given a custom relative probability to modify the probability of choosing each one.

Sound Probabilities

The probabilities for choosing each sound are defined as ‘relative’ probabilities. When a sound is first added to a group, it is given a relative probability of 1.0. When none of the probabilities have been modified, this will lead to a uniform probability of selecting each sound in the group. The probability of selecting a given sound from the group can be increased by increasing its relative probability value. The actual probability of choosing any given sound from the group will always be equal to the relative probability for that sound divided by the return value of carb::audio::IAudioGroup::getProbabilityTotal. The value of carb::audio::IAudioGroup::getProbabilityTotal is simply the sum of all relative probabilities for each sound in the group.

For example, if a group contains five sounds and each has a relative probability of 1.0, the probability of choosing any of them will be 1/5. However, if the second sound has a relative probability of 8, the first and third through fifth sounds will have a probability of being chosen of 1/12, while the second sound will have a probability of 3/4.

Typical Usage