carb::audio::ContextParams

Defined in carb/audio/IAudioPlayback.h

struct ContextParams

context parameters block.

This can potentially contain all of a context’s parameters and their current values. This is used to both set and retrieve one or more of a context’s parameters in a single call. The set of fContextParam* flags that are passed to getContextParameter() or setContextParameter() indicates which values in the block are guaranteed to be valid.

Public Members

float speedOfSound

the speed of sound for the context.

This is valid when the fContextParamSpeedOfSound flag is used. This is measured in meters per second. This will affect the calculation of Doppler shift factors and interaural time difference for spatial voices. The default value is kDefaultSpeedOfSound m/s. This value can be changed at any time to affect Doppler calculations globally. This should only change when the sound environment itself changes (ie: move from air into water).

float unitsPerMeter

the number of arbitrary world units per meter.

This is valid when the fContextParamWorldUnitScale flag is used. World units are arbitrary and often determined by the level/world designers. For example, if the world units are in feet, this value would need to be set to 3.28. All spatial audio calculations are performed in SI units (ie: meters for distance, seconds for time). This provides a conversion factor from arbitrary world distance units to SI units. This conversion factor will affect all audio distance and velocity calculations. This defaults to 1.0, indicating that the world units are assumed to be measured in meters. This must not be 0.0 or negative.

float dopplerScale

the global Doppler scale value for this context.

This is applied to all calculated Doppler factors to enhance or diminish the effect of the Doppler factor. A value of 1.0 will leave the calculated Doppler levels unmodified. A value lower than 1.0 will have the result of diminishing the Doppler effect. A value higher than 1.0 will have the effect of enhancing the Doppler effect. This is useful for handling global time warping effects. This parameter is a unit less scaling factor. This defaults to 1.0.

float dopplerLimit

the global Doppler limit value for this context.

This will cap the calculated Doppler factor at the high end. This is to avoid excessive aliasing effects for very fast moving emitters or listener. When the relative velocity between the listener and an emitter is nearing the speed of sound, the calculated Doppler factor can approach ~11 million. Accurately simulating this would require a very large scale anti-aliasing or filtering pass on all resampling operations on the emitter. That is unfortunately not possible in general. Clamping the Doppler factor to something relatively small like 16 will still result in the effect being heard but will reduce the resampling artifacts related to high frequency ratios. A Doppler factor of 16 represents a relative velocity of ~94% the speed of sound so there shouldn’t be too much of a loss in the frequency change simulation. This defaults to 16. This should not be negative or zero.

float virtualizationThreshold

the effective volume level at which a voice will become virtual.

A virtual voice will not decode any data and will perform only minimal update tasks when needed. This is expressed as a linear volume value from 0.0 (silence) to 1.0 (full volume). The default volume is 0.0.

float spatialFrequencyRatio

the global frequency ratio to apply to all active spatial voices.

This should only be used to handle time dilation effects on the voices, not to deal with pitch changes (ie: record a sound at a high frequency to save on storage space and load time, but then always play it back at a reduced pitch). If this is used for pitch changes, it will interfere with distance delay calculations and possibly lead to other undesirable behavior. This will not affect any non-spatial voices. This defaults to 1.0.

float nonSpatialFrequencyRatio

the global frequency ratio to apply to all active non-spatial voices.

This can be used to perform a pitch change (and as a result play time change) on all non-spatial voices, or it can be used to simulate a time dilation effect on all non-spatial voices. This will not affect any spatial voices. This defaults to 1.0.

float masterVolume

the global master volume for this context.

This will only affect the volume level of the final mixed output signal. It will not directly affect the relative volumes of each voice being played. No individual voice will be able to produce a signal louder than this volume level. This is set to 0.0 to silence all output. This defaults to 1.0 (ie: full volume). This should not be set beyond 1.0.

float spatialVolume

the relative volume of all spatial voices.

This will be the initial volume level of any new spatial voice. The volume specified in that voice’s parameters will be multiplied by this volume. This does not affect the volume level of non-spatial voices. This is set to 0.0 to silence all spatial voices. This defaults to 1.0 (ie: full volume). This should not be set beyond 1.0. This volume is independent of the masterVolume value but will effectively be multiplied by it for the final output.

float nonSpatialVolume

the relative volume of all non-spatial voices.

This will be the initial volume level of any new non-spatial voice. The volume specified in that voice’s parameters will be multiplied by this volume. This does not affect the volume level of spatial voices. This is set to 0.0 to silence all non-spatial voices. This defaults to 1.0 (ie: full volume). This should not be set beyond 1.0. This volume is independent of the masterVolume value but will effectively be multiplied by it for the final output.

ListenerAttributes listener

attributes of the listener.

This is valid when the fContextParamListener flag is used. Only the values that have their corresponding fEntityFlag* flags set will be updated on a set operation. Any values that do not have their corresponding flag set will just be ignored and the previous value will remain current. This can be used to (for example) only update the position for the listener but leave its orientation and velocity unchanged. The flags would also indicate whether the orientation vectors need to be normalized or made perpendicular before continuing. Fixing up these orientation vectors should only be left up to this call if it is well known that the vectors are not already correct.

It is the caller’s responsibility to decide on the listener’s appropriate position and orientation for any given situation. For example, if the listener is represented by a third person character, it would make the most sense to set the position to the character’s head position, but to keep the orientation relative to the camera’s forward and up vectors (possibly have the camera’s forward vector projected onto the character’s forward vector). If the character’s orientation were used instead, the audio may jump from one speaker to another as the character rotates relative to the camera.

PlaybackModeFlags defaultPlaybackMode

defines the default playback mode flags for the context.

These will provide ‘default’ behavior for new voices. Any new voice that uses the fPlaybackModeDefault* flags in its voice parameters block will inherit the default playback mode behavior from this value. Note that only specific playback modes are supported in these defaults. This also provides a means to either ‘force on’ or ‘force off’ certain features for each voice. This value is a collection of zero or more of the fPlaybackModeDefault* flags, and flags that have been returned from either getForceOffPlaybackModeFlags() or getForceOnPlaybackModeFlags(). This may not include any of the other fPlaybackMode* flags that are not part of the fPlaybackModeDefault* set. If the other playback mode flags are used, the results will be undefined. This defaults to 0.

ContextParamFlags flags

flags to control the behavior of the context.

This is zero or more of the ContextParamFlags flags. This defaults to 0.

void *ext = nullptr

Reserved for future expansion.

This must be set to nullptr unless a ContextParams2 object is also being passed in.