carb::audio::PlaySoundDesc

Defined in carb/audio/IAudioPlayback.h

struct PlaySoundDesc

descriptor of how to play a single sound.

At the very least, the sound value must be specified.

Public Members

PlayFlags flags = 0

flags to describe the way to allocate the voice and play the sound.

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

SoundData *sound

the sound data object to be played.

This may not be nullptr. The sound’s data buffer will provide the data for the voice. By default, the whole sound will be played. If a non-zero value for playStart and playLength are also given, only a portion of the sound’s data will be played.

VoiceParamFlags validParams = 0

the set of voice parameters that are valid.

This can be fVoiceParamAll if all of the parameters in the block are valid. It may be a combination of other fVoiceParam* flags if only certain parameters are valid. If set to 0, the parameters block in params will be ignored and the default parameters used instead.

VoiceParams *params = nullptr

the initial parameters to set on the voice.

This may be nullptr to use the default parameters for the voice. Note that the default parameters for spatial sounds will not necessarily be positioned appropriately in the world. If needed, only a portion of the parameter block may be specified by listing only the flags for the valid parameters in validParams.

LoopPointDesc loopPoint = {}

descriptor of an optional loop point to set for the voice.

This may be changed at a later point on the voice with setLoopPoint() as well. This will identify the region to be played after the initial play region from playStart through playLength completes, or after the previous loop completes.

VoiceCallback callback = nullptr

the callback function to bind to the voice.

This provides notifications of the sound ending, loops starting on the sound, and event points getting hit in the sound. This callback will occur during an update() call if the fPlayFlagRealtimeCallbacks flag is not used in flags. This will occur on the engine thread if the flag is set. Note that if the callback is executing on the engine thread, it must complete its task as quickly as possible so that it doesn’t stall the engine’s processing operations. In most cases, it should just flag that the event occurred and return. The flagged event should then be handled on another thread. Blocking the engine thread can result in audio dropouts or popping artifacts in the stream. In general, if a real-time callback takes more than ~1ms to execute, there is a very high possibility that it could cause an audio dropout. This may be nullptr if no callbacks are needed.

void *callbackContext = nullptr

the opaque user context value that will be passed to the callback function any time it is called.

This value is ignored if callback is nullptr.

size_t playStart = 0

the offset in the sound to start the initial playback at.

The units of this value are specified in playUnits. If this is set to 0, playback will start from the beginning of the sound data object. It is the caller’s responsibility to ensure that this starting point occurs at a zero crossing in the data (otherwise a popping artifact will occur). This starting offset must be within the range of the sound data object’s buffer. This may be outside of any chosen loop region. This region of the sound will be played before the loop region plays. This initial play region (starting at this offset and extending through playLength) does not count as one of the loop iterations.

size_t playLength = 0

the length of the initial play region.

The units of this value are specified in playUnits. This may be set to 0 to indicate that the remainder of the sound data object’s buffer should be played starting from playStart. This length plus the starting offset must be within the range of the sound data object’s buffer.

UnitType playUnits = UnitType::eFrames

the units that the playStart and playLength values are given in.

This may be any unit, but the use of time units could result in undesirable artifacts since they are not accurate units.

void *ext = nullptr

reserved for future expansion.

This must be set to nullptr unless it is pointing to a PlaySoundDesc2 object.