How To: Integrate X3DAudio with XACT

  • Article

XACT supports 3D audio output on cues using the X3DAudio library. This section describes how to get started using X3DAudio and its associated XACT helper functions to add 3D positioning to an XACT-enabled title.

Introduction

The X3DAudio library is a 3D audio geometry library that provides positional audio calculation between sound emitters and sound listeners. XACT uses X3DAudio to calculate and apply 3D positional information to cues and their associated sound playback. This means users will hear sounds, in stereo or 5.1 configurations, with realistic positioning effects.

XACT also uses the 3D information to set the values of implicit variables on cues. The audio designer can create effects based on positional information such as attenuation of volume based on distance between emitter and listener.

X3DAudio is strictly a 3D math library with no signal processing capability. In order to easily integrate the X3DAudio library into XACT so that positional information can be calculated and applied to cues, XACT provides three helper functions:

  • XACT3DInitialize, which initializes X3DAudio using settings from the XACT engine.

  • XACT3DCalculate, which calculates positional information between a single emitter and a single listener.

  • XACT3DApply, which applies a calculation received from XACT3DCalculate to a cue, so that the cue will play with positional effects.

To use X3DAudio to apply 3D sounds to an XACT cue, follow these steps:

  1. Initialize the X3DAudio Engine

  2. Initialize X3DAudio Structures

  3. Set Up Emitters/Listener

  4. Call XACT3DCalculate and XACT3DApply

Initialize the X3DAudio Engine

The X3DAudio engine is initialized by calling the XACT3DInitialize helper function. The function takes a pointer to an XACT engine instance and an X3DAudio handle. The XACT engine pointer is used to determine the settings used to initialize X3DAudio. The X3DAudio handle is used to return a reference to the initialized X3DAudio engine.

X3DAUDIO_HANDLE xact3dInstance;
XACT3DInitialize(pXACT3Engine,xact3dInstance);

Initialize X3DAudio Structures

To calculate 3D positional information, X3DAudio must be given initial data about the configuration of the sound channels held by the sound emitter, and the number of sound channels held by the listener. These two values, stored in the X3DAUDIO_DSP_SETTINGS structure as SrcChannelCount and DstChannelCount determine how the calculations will be mapped to the listener's sound output format (such as stereo or 5.1 sound).

Once the count has been set, a matrix of coefficients must be allocated. The matrix must be large enough to hold the mapping data from the source channels to the destination channels. This matrix is one-dimensional, and must contain a number of elements equal to SrcChannelCount x DstChannelCount. The matrix should not be filled in with values manually, as this will be done when XACT3DCalculate is called.

The following code configures a X3DAUDIO_DSP_SETTINGS structure with mappings for either stereo or 5.1 destination sound, from either a mono or stereo source:

X3DAUDIO_DSP_SETTINGS DSPSettings = {0};
WAVEFORMATEXTENSIBLE format;
pXACT3Engine->GetFinalMixFormat(&format);

DSPSettings.SrcChannelCount = srcChannelCount;
DSPSettings.DstChannelCount = format.Format.nChannels;    
DSPSettings.pMatrixCoefficients = new FLOAT32[DSPSettings.SrcChannelCount * DSPSettings.DstChannelCount];

Set Up Emitters/Listener

X3DAudio functions by calculating positional information between emitters and listeners. The XACT implementation of X3DAudio uses one emitter and one listener for every call to XACT3DCalculate.

Your title must provide the positioning information that will be used to fill in the emitter and listener structures. The following code sets up a simple emitter and listener:

X3DAUDIO_EMITTER emitter = {0};
X3DAUDIO_LISTENER listener = {0};
listener.OrientFront = Z_AXIS_VECTOR;
listener.OrientTop = Y_AXIS_VECTOR;
listener.Position = positionVector;
listener.Velocity = ZERO_VECTOR;


// the following need to be orthonormal
emitter.OrientFront = Z_AXIS_VECTOR;
emitter.OrientTop = Y_AXIS_VECTOR;

emitter.Position = ZERO_VECTOR;
emitter.Velocity = ZERO_VECTOR; // needs to not be zero if you want to hear Doppler effect

// emitter ChannelCount and DSP Setting's SrcChannelCount must match
emitter.ChannelCount = 1;   

// this will be set by XACT3DCalculate if ChannelCount > 1.
emitter.ChannelRadius = 0.0f;   

// will be set by XACT3DCalculate
emitter.pChannelAzimuths = NULL;

// will be set by XACT3DCalculate
emitter.pVolumeCurve = emitter.pLFECurve
        = emitter.pLPFDirectCurve
        = emitter.pLPFReverbCurve
        = emitter.pReverbCurve
        = NULL;
    
emitter.CurveDistanceScaler = 1.0;
emitter.DopplerScaler = 1.0f;

Note that several fields of the emitter are set to NULL to use default values, or values provided by the XACT3DCalculate function.

Call XACT3DCalculate and XACT3DApply

The final steps are to call XACT3DCalculate to calculate the final channel mapping that will be applied. Then call XACT3DApply to apply this mapping to a cue, and copy over 3D information, such as distance, to the cue's implicit variables.

The following code assumes the XACT engine is initialized, and a cue is available:

XACT3DCalculate( xact3dInstance, &listener, &emitter, &DSPSettings );
XACT3DApply( &DSPSettings, pCue);

Implicit Variable Settings

When a call to XACT3DApply is successful, the cue that is the target of the call will be updated by XACT with values for several of its implicit variables:

Variable Meaning
Distance The distance from the emitter to the listener. Corresponds with the value of X3DAUDIO_DSP_SETTINGS.EmitterToListenerDistance returned by XACT3DCalculate.
OrientationAngle The interior angle from emitter to listener, expressed in degrees with respect to the emitter's front orientation. Corresponds with the value of X3DAUDIO_DSP_SETTINGS.EmitterToListenerAngle returned by XACT3DCalculate, converted to degrees.
DopplerPitchScalar The Doppler shift factor between the source and the emitter. Corresponds with the value of X3DAUDIO_DSP_SETTINGS.DopplerFactor returned by XACT3DCalculate.

If XACT's 3D functionality is to be used in a title, the audio designer can use RPCs to relate the changes in these implicit variables to values of sound parameters such as pitch or volume.