|
|
The Microsoft Cross-Platform Audio Creation Tool (XACT) variables allow a title to control its audio output (for example, volume levels) through parameters that reflect the activity taking place in the title.
This topic covers the essential information you need to know about variables, and the steps to create them.
Understanding some terminology is essential for working effectively with XACT variables. Variables have a scope that is either global or specific to a cue, as well as being implicitly or explicitly part of an XACT project.
All variables must be declared as either global or cue-instance.
Global variables are accessible to every cue and persistent throughout the title.
Programmers can set or read these values through the IXACTEngine::SetGlobalVariable and IXACTEngine::GetGlobalVariable functions.
Cue-Instance variables are limited in scope to the created cue and they exist only for the life of that cue instance. Cue-instance variables are useful when multiple instantiations of a single cue (and its associated sounds) are required (for example, a "car" cue where there may be more than one car at any given time). While a global variable allows multiple audio elements to be controlled in unison, a cue instance variable grants discrete control of each instance of a cue, even for each copy of the same cue.
Programmers can set or read these values per instance through the IXACTCue::GetVariableIndex and IXACTCue::GetVariable methods.
Variables that are automatically included with every XACT project are called implicit variables. Variables that you create are called explicit variables. Both implicit and explicit variables can be declared to be global or cue-instance, although the audio designer can change this setting only for explicit variables.
Implicit variables are inherent within the XACT engine and available to the sound designer for use.
| Variable Name | Type | Description |
|---|---|---|
| NumCueInstances | Cue Instance | Contains the number of currently playing instances of the cue. |
| AttackTime | Cue Instance | Counts the amount of time elapsed since the start of playback. This counter begins at zero and continues to increment until the cue is stopped. |
| ReleaseTime | Cue Instance | Counts the amount of time elapsed since a non-immediate request to stop playback. A stop request can occur either from programmer control or from a Stop event. This counter begins at zero and continues to increment until the cue is retriggered. |
| Distance | Cue Instance | Represents the current distance from the sound source to the listener. If the cue instance has no distance associated with it, the value of Distance is 0. Set by XACT3DApply. |
| OrientationAngle | Cue Instance | Represents a cue instance's orientation to the listener, expressed in degrees from -180 to 180. Set by XACT3DApply. |
| DopplerPitchScalar | Cue Instance | Represents the amount of pitch modification on a cue instance created by doppler shift between the cue instance and the listener, expressed as a number between 0 and 4. Set by XACT3DApply. |
| SpeedOfSound | Global | Speed of sound constant used in doppler shift calculations, expressed as a number between 0 and 1,000,000. Used by XACT3DCalculate in doppler shift calculations. |
For more information on AttackTime and ReleaseTime, see XACT Time Variables.
For more information on Distance, OrientationAngle, DopplerPitchScalar, and SpeedOfSound, see Using X3DAudio with XACT.
Explicit variables are those that are created by the sound designer. For example, the designer may define a variable EngineRPM, to control engine volume based on the speed of the car.
While you cannot create new implicit variables, you can create new explicit variables.
To create a new explicit variable
Right-click the Variables item in the XACT project tree.
Select either the New Global Variable or New Cue Instance Variable option that is presented.
Figure 1. Creating a new explicit variable
A new global variable has the default name "Global." A new cue-instance variable has the default name "Cue Instance."
Select the new variable.
Press F2 and enter a more descriptive name for the variable, or if you prefer, change the Name property of the variable in the properties frame of the authoring tool.
When a new variable is created or an existing variable is selected in the project tree, its properties are displayed in the property frame. The same values, however, may also be set in the Variable Settings dialog box, which is displayed when you double-click the name of the new variable.
Figure 2. Variable Settings dialog box
The Variable Settings dialog box allows you to change the following settings:
Local variables can be set using the XACT GUI, and their values are visible to the GUI user. This is the default setting when the variable is created.
Monitored (external) variables can NOT be set using the XACT GUI. Control of this variable is presumed to be done by the game. The values of monitored variables are updated or visible to the GUI user.
Non-monitored (external) variables can NOT be set using the XACT GUI. Control of this variable is presumed to be done by the game. The values of non-monitored variables are NOT updated or visible to the GUI user. This is the default when the XACT GUI is connected to an application other than Audio Console.
Use of non-monitored global variables minimizes network traffic for improved performance.
To delete a variable, right-click the variable as it is displayed in the project tree, then select Delete. Alternatively, you may select the variable and press the DEL key, or click Delete Variable in the Variable Settings dialog box.
If the variable is in use (for example, assigned to a run-time parameter control), a delete action is disallowed.