carb::audio::SpeakerDirectionDesc

struct SpeakerDirectionDesc

a descriptor of the direction from the [real biological] user to all speakers in the user’s sound setup.

This is specified by the direction vector from the user’s position (assumed to be at the origin) to each speaker. This speaker direction set given here must always match the speaker mode for the current device and the user’s speaker layout, otherwise the output results will be undefined. These speaker directions are used to calculate all spatial sounds for a context so that they map as accurately as possible to the user’s specific speaker setup.

Public Members

SpeakerDirectionFlags flags = 0

flags to control the behavior of the speaker positioning operation.

No flags are currently defined. This must be set to 0.

SpeakerMode speakerMode

the audio engine’s output speaker mode that was selected at either context creation time or device opening time.

If the speaker mode was set to kSpeakerModeDefault at context creation time, this will be set to the channel mask of the device that was selected. Each set bit in this mask must have a corresponding vector set in the directions table. All other vectors will be ignored. This channel mask can be retrieved from getContextCaps() for the currently selected device. Note that selecting a new device with setOutput() will always reset the channel mask back to the defaults for the new device.

SpeakerDirection directions[kMaxChannels]

the direction vectors from the user to each speaker.

This does not need to be normalized. Note that when this information is retrieved with getContextCaps(), the speaker direction vectors may not match the original values that were set since they may have already been normalized internally. Each entry in this table is indexed by a Speaker name. For speaker modes that have more than Speaker::eCount speakers, the specific mapping and positioning for each speaker is left entirely up to the caller (ie: a set of custom speaker directions must be specified for each channel for all contexts). Each valid vector in this set, except for Speaker::eLowFrequencyEffect, should have a non-zero direction. The LFE speaker is always assumed to be located at the origin.

void *ext = nullptr

provides an extended information block.

This is reserved for future expansion and should be set to nullptr.