Runtime parameters for initialization of the XACT engine.
Xbox 360 |
---|
Memory for this member must be allocated using XMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
Windows |
---|
Memory for this member must be allocated using CoTaskMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
Value | Description |
---|---|
XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT should free the buffer pointed to by pGlobalSettingsBuffer when initialization is complete. Note XACT will not attempt to free the memory if the buffer allocation fails. ? |
Xbox 360 |
---|
This member is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in globalSettingsFlags, so that XMemFree can receive the correct values when XACT frees the buffer. Otherwise, globalSettingsAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer pointed to by pGlobalSettingsBuffer was allocated. |
Windows |
---|
This parameter has no relevance and is ignored. |
Xbox 360 |
---|
This parameter is undefined. |
Retrieves the properties of the cue.
[Content-driven]
GetProperties will allocate memory for the
Xbox 360 |
---|
GetProperties performs memory allocation using XMemAlloc. The caller should free the memory using XMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Windows |
---|
The caller should free the memory using CoTaskMemAlloc. The caller should free the memory using CoTaskMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Plays a prepared cue.
[Content-driven]
Returns
Stops a cue.
[Content-driven]
Value | Description |
---|---|
Indicates the cue should stop immediately, ignoring any release phase or transition specified in the content.? |
Note |
---|
Specifying a value of 0 causes Stop to account for the release phase and/or transition specified in the XACT. |
Returns
Retrieves the current operating state of a cue.
[Content-driven]
Value | Description |
---|---|
Created, but nothing else? | |
Preparing to play? | |
Prepared, but not yet played? | |
Playing, but can be paused? | |
Stopping? | |
Stopped? | |
Paused? |
Note |
---|
States represented by these flags are not necessarily mutually exclusive. Therefore, test states using the & (and) operation rather than the == (equals) operation. |
Returns
This function informs the caller what activity the cue is performing at the moment the call is made. The state returned from GetState indicates only the current condition.
Only
Destroys the cue.
[Content-driven]
Sets the volume level that each source channel of the cue should play in each of its destination channels.
[Content-driven]
Returns
The SetMatrixCoefficients method is primarily used for creating the illusion of the cue being played at some position in 3D space. However, it is recommended to use the XACT methods provided for interacting with X3DAudio instead of calling SetMatrixCoefficients directly. The XACT's X3DAudio helper methods handle calculating and applying a cue's matrix coefficients by calling SetMatrixCoefficients. See How To: Integrate X3DAudio with XACT for more information.
Retrieves the corresponding index for a variable name string.
[Content-driven]
The index of the variable if it exists, or XACTVARIABLEINDEX_INVALID otherwise.
Stores a new value to a variable, referenced by its index.
[Content-driven]
Returns
If the variable is private or read-only, SetVariable returns XACTENGINE_E_INVALIDVARIABLEINDEX.
If nValue falls outside of it's assigned range (or XACTVARIABLEVALUE_MIN to XACTVARIABLEVALUE_MAX), SetVariable returns E_FAIL. In this case, the variable is clamped within valid range and a warning message is sent to the debugger.
Retrieves the value of a variable by its index.
[Content-driven]
Retrieves the properties of the cue.
[Content-driven]
GetProperties will allocate memory for the
Xbox 360 |
---|
GetProperties performs memory allocation using XMemAlloc. The caller should free the memory using XMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Windows |
---|
The caller should free the memory using CoTaskMemAlloc. The caller should free the memory using CoTaskMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Sets the volume level of each channel of the final output for the voice. These channels are mapped to the input channels of a specified destination voice.
Note |
---|
If the voice sends to a single target voice specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
Output | Left Input | Right Input |
---|---|---|
Left | 1.0 | 0.0 |
Right | 0.0 | 1.0 |
Front Center | 0.0 | 0.0 |
LFE | 0.0 | 0.0 |
Rear Left | 0.8 | 0.0 |
Rear Right | 0.0 | 0.8 |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
Volume levels are expressed as floating-point amplitude multipliers between -
Retrieves the current operating state of a cue.
[Content-driven]
This function informs the caller what activity the cue is performing at the moment the call is made. The state returned from GetState indicates only the current condition.
Only
Retrieves the properties of the cue.
[Content-driven]
GetProperties will allocate memory for the
Xbox 360 |
---|
GetProperties performs memory allocation using XMemAlloc. The caller should free the memory using XMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Windows |
---|
The caller should free the memory using CoTaskMemAlloc. The caller should free the memory using CoTaskMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
This section contains information about the methods used with the
Retrieves information about a specific renderer.
Xbox 360 |
---|
This method is not supported on the Xbox 360 platform. |
[Content-driven]
Initializes the XACT engine.
[Content-driven]
Returns
This function creates the XACT engine and data structures. It should be called in an application only once per
If a title passes an instance of the XAudio2 engine to Initialize and uses auditioning the XAudio2 mastering voice must have a volume meter XAPO attached to it. See XAudio2CreateVolumeMeter for information on creating the volume meter and SetEffectChain for information on attaching the volume meter.
Shuts down the XACT engine and frees any resources in use.
[Content-driven]
Returns
This method destroys all existing cues, sound banks, and wave banks. It blocks until all cues are destroyed. The method also flushes all pending notifications and unregisters all notification descriptions. No XACT API or method calls can be made after calling this function.
Performs periodic work that is required by the XACT engine.
[Code-driven]
[Content-driven]
Returns
This method drives the XACT engine and is typically called every 30 to 100 milliseconds (about once every one to four frames).
Creates a sound bank for use by the XACT engine.
[Content-driven]
Xbox 360 |
---|
Memory for this member must be allocated by using XMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. Xbox 360 sound banks must be allocated from physical memory (and not the heap). The XALLOC_MEMTYPE_PHYSICAL memory type must be specified as dwMemoryType when memory is allocated through XMemAlloc. |
Windows |
---|
Memory for this member must be allocated by using CoTaskMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
Value | Description |
---|---|
XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT should free the buffer that the pvBuffer parameter points to, when the sound bank data is released. Note XACT does not attempt to free the memory if the buffer allocation fails. ? |
Xbox 360 |
---|
This parameter is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in dwFlags. This is so that XMemFree can receive the correct values when the XACT frees the buffer. Otherwise, dwAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer that pvBuffer points to was allocated. |
Windows |
---|
This parameter has no relevance and is ignored. |
Returns
Creates an in-memory wave bank for use by the XACT engine.
[Code-driven]
[Content-driven]
Xbox 360 |
---|
Memory for this member must be allocated by using XMemAlloc when you specify the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. Xbox 360 wavebanks must be created with caching enabled. The PAGE_WRITECOMBINE and PAGE_NOCACHE flags must not be used when calling XMemAlloc. Xbox 360 wavebanks must be allocated from physical memory (and not the heap). The XALLOC_MEMTYPE_PHYSICAL memory type must be specified as dwMemoryType when memory is allocated through XMemAlloc. |
Windows |
---|
Memory for this member must be allocated by using CoTaskMemAlloc when you specify the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
Value | Description |
---|---|
XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT frees the buffer that the pvBuffer parameter points to, when the wave bank data is released. Note XACT does not attempt to free the memory if the buffer allocation fails. ? |
Xbox 360 |
---|
This parameter is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in dwFlags. This is so that XMemFree can receive the correct values when the XACT engine frees the buffer. Otherwise, dwAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer that pvBuffer points to was allocated. |
Windows |
---|
This parameter has no relevance and is ignored. |
Returns
Creates an
[Code-driven]
[Content-driven]
Returns
Do not use a sound that is associated with a streaming wave bank unless you know that the wave bank is prepared.
To ascertain that the wave bank is prepared, do one of the following:
Create an XACTNOTIFICATIONTYPE_WAVEBANKPREPARED notification by using
?or?
Issue a query about the state of the wave bank by using
Prepares a wave object from a standard PCM, XMA (Xbox 360) file.
[Code-driven]
Value | Description |
---|---|
XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music.Xbox 360 This flag is supported only on the Xbox 360 platform. ? |
XACT_FLAG_UNITS_MS | Indicates that the units passed in are measured in milliseconds.? |
XACT_FLAG_UNITS_SAMPLES | Indicates that the units passed in are in samples.? |
Returns
If this API is used to prepare XMA content, the content must be encoded by using 64K block size.
PrepareWave does not support xWMA. xWMA content can be prepared using one of the following methods:
Creates an in-memory
[Code-driven]
Returns
The application must make sure that the any buffers passed in (data, seek table) are valid through the lifetime of this wave.
Xbox 360 |
---|
If this API is used to prepare XMA content, the content must be encoded with 64K block size. When using XMAEncode, specify "/b 64" on the command line to create 64K blocks. |
Creates a streaming wave object for the file handle that is passed in.
[Code-driven]
Value | Description |
---|---|
XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music. Xbox 360 This flag is supported only on the Xbox 360 platform.? |
XACT_FLAG_UNITS_MS | Indicates that the units passed in are measured in milliseconds.? |
XACT_FLAG_UNITS_SAMPLES | Indicates that the units passed in are in samples.? |
Returns
If this API is used to prepare XMA content, the content must be encoded with 64K block size. ADPCM files are currently not supported.
Registers an event notification.
[Content-driven]
Returns
Cancels registration of an event notification.
[Content-driven]
Note |
---|
Attempting to unregister a notification that has not been registered has no effect. |
Returns
Retrieves the sound category index that corresponds to a friendly name string.
[Content-driven]
Returns a category index for the friendly name if successful. Otherwise, XACTCATEGORY_INVALID.
Sets the volume of a sound category.
[Content-driven]
Returns
The volume is a floating point scale where 0.0 means -96db, 1.0 means 0db, and 2.0 means +6db.
Pauses or resumes playback of a category.
[Content-driven]
Returns
A stopping or stopped cue cannot be paused.
Retrieves the corresponding index for a global variable name string.
[Content-driven]
The index of the global variable if it exists. Otherwise, XACTVARIABLEINDEX_INVALID.
Stores a new value to a global variable, which is referenced by its index.
[Content-driven]
Returns
Retrieves the value of a global variable by its index.
[Content-driven]
Wave bank segment identifiers.
Plays a cue. Optionally, returns an instance handle to the cue object for further control.
[Content-driven]
Retrieves a sound cue index based on a string that represents the friendly name of the cue.
[Content-driven]
Note |
---|
This string is case sensitive. |
Returns the cue index that is associated with szFriendlyName. If the cue index is not found, XACTINDEX_INVALID is returned.
Retrieves the number of cues in the sound bank.
[Content-driven]
Returns
Retrieves the properties of a cue.
[Content-driven]
Prepares a cue instance for playback.
[Content-driven]
This method returns a valid cue instance that is ready to be played. All allocations and stream priming, if necessary, are performed by this method.
Plays a cue. Optionally, returns an instance handle to the cue object for further control.
[Content-driven]
Stops a cue.
[Content-driven]
Note |
---|
All instances of the cue that are specified by nCueIndex are stopped. |
Value | Description |
---|---|
XACT_FLAG_SOUNDBANK_STOP_IMMEDIATE | Cue stops immediately. It ignores any release phase or transition that is specified in the content.? |
Returns
Destroys the sound bank.
[Content-driven]
Retrieves the current state of the sound bank.
[Content-driven]
Value | Description |
---|---|
XACT_SOUNDBANKSTATE_INUSE | Indicates that the sound bank is referenced by at least one valid cue instance or other client. For example, the game itself might reference the sound bank.? |
Returns
Retrieves the number of cues in the sound bank.
[Content-driven]
Sets the volume value for each output of a wave.
[Code-driven]
The final output volume of any channel is the matrix coefficient volume multiplied by the value that is specified by
Stops the wave.
[Code-driven]
Value | Description |
---|---|
XACT_FLAG_STOP_RELEASE | Plays the wave to completion, then stops. For looping waves, this flag plays the current iteration to completion, then stops (ignoring any subsequent iterations). In either case, any release or tail is played. To stop the wave immediately, use the XACT_FLAG_STOP_IMMEDIATE flag.? |
XACT_FLAG_STOP_IMMEDIATE | Stops the playback immediately.? |
Returns
Returns the state of the wave object.
[Code-driven]
Value | Description |
---|---|
XACT_STATE_CREATED | Created, but nothing else.? |
XACT_STATE_PREPARING | In the middle of preparing.? |
XACT_STATE_PREPARED | Prepared, but not yet played.? |
XACT_STATE_PLAYING | Playing, but can be paused.? |
XACT_STATE_STOPPING | Stopping.? |
XACT_STATE_STOPPED | Stopped.? |
XACT_STATE_PAUSED | Paused. Can be combined with some of the other state flags.? |
XACT_STATE_INUSE | Object is in use. Used by wave banks and sound banks.? |
XACT_STATE_PREPAREFAILED | Object preparation failed.? |
Returns
Sets the pitch of a wave.
[Code-driven]
Returns
The value of pitch may be between XACTPITCH_MIN (-1200) and XACTPITCH_MAX (1200), which is approximately one semitone.
Sets the volume of a wave.
[Code-driven]
Returns
Sets the volume value for each output of a wave.
[Code-driven]
Returns
The final output volume of any channel is the matrix coefficient volume multiplied by the value that is specified by
Retrieves the properties of the wave object.
[Code-driven]
Returns
Returns the state of the wave object.
[Code-driven]
Sets the pitch of a wave.
[Code-driven]
The value of pitch may be between XACTPITCH_MIN (-1200) and XACTPITCH_MAX (1200), which is approximately one semitone.
Sets the volume of a wave.
[Code-driven]
Retrieves the properties of the wave object.
[Code-driven]
This section contains information about the methods used with the
Destroys the wave bank.
[Content-driven]
Returns the number of wave entries in the wave bank.
[Code-driven]
Returns
Returns the wave index for the friendly name of a wave in a wave bank.
[Code-driven]
Wave index for the friendly name of a wave within a wave bank.
If the wave bank does not contain the friendly name, or if an entry does not exist for the name that is passed in, the method returns XACTINDEX_INVALID.
Gets the properties of a specific wave in a wave bank.
[Code-driven]
Returns
Starts the playback for a wave that is indicated by the wave index.
[Code-driven]
Value | Description |
---|---|
XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music.Xbox 360 This flag is supported only on the Xbox 360 platform.? |
XACT_FLAG_UNITS_MS | Indicates that the units that are passed in are measured in milliseconds.? |
XACT_FLAG_UNITS_SAMPLES | Indicates that the units that are passed in are in samples.? |
Retrieves the current state of the wave bank.
[Content-driven]
Value | Description |
---|---|
XACT_WAVEBANKSTATE_INUSE | Indicates that the wave bank is referenced by at least one valid cue instance or other client. For example, the game itself might reference the wave bank.? |
XACT_WAVEBANKSTATE_PREPARED | Indicates that the wave is prepared for use by a cue instance.? |
Returns
Returns the number of wave entries in the wave bank.
[Code-driven]
Retrieves the current state of the wave bank.
[Content-driven]
Reports cue properties back to the client.
This structure returns the non-instance specific cue properties for a cue. That is, it returns the properties shared across all instances of a cue.
File I/O Callbacks
Notification structure for all XACT cue notifications.
Provides descriptions for registering, unregistering, and flushing notifications.
Value | Supported Fields |
---|---|
XACTNOTIFICATIONTYPE_CUEPREPARED | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_CUEPLAY | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_CUESTOP | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_CUEDESTROYED | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_MARKER | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_SOUNDBANKDESTROYED | None, sound bank |
XACTNOTIFICATIONTYPE_WAVEBANKDESTROYED | None, wave bank |
XACTNOTIFICATIONTYPE_LOCALVARIABLECHANGED | None, sound bank, sound bank and cue index, cue instance |
XACTNOTIFICATIONTYPE_GLOBALVARIABLECHANGED | None |
XACTNOTIFICATIONTYPE_GUICONNECTED | None |
XACTNOTIFICATIONTYPE_GUIDISCONNECTED | None |
XACTNOTIFICATIONTYPE_WAVEPREPARED | None, wave bank and wave index, wave instance |
XACTNOTIFICATIONTYPE_WAVEPLAY | None, sound bank, sound bank and cue index, cue instance, wave bank |
XACTNOTIFICATIONTYPE_WAVESTOP | None, sound bank, sound bank and cue index, cue instance, wave bank |
XACTNOTIFICATIONTYPE_WAVELOOPED | None, sound bank, sound bank and cue index, cue instance, wave bank, wave instance |
XACTNOTIFICATIONTYPE_WAVEDESTROYED | None, wave bank and wave index, wave instance |
XACTNOTIFICATIONTYPE_WAVEBANKPREPARED | None, wave bank |
XACTNOTIFICATIONTYPE_WAVEBANKSTREAMING_INVALIDCONTENT | None, wave bank |
Value | Description |
---|---|
XACT_FLAG_NOTIFICATION_PERSIST | Sets the notification to persist. If this flag is not set, the user receives no more than one notification of the type registered.? |
Notification structure for all GUI notifications.
Notification structure for all marker notifications.
Notification structure for all sound bank notifications.
Notification structure for all variable notifications.
Notification structure for all wave notifications.
Notification structure for all wave bank notifications.
Returns information about a particular renderer.
Note |
---|
The friendly name is useful in presenting the audio devices that are available to the end user. However, the renderer id can be passed in the |
Returns the properties for a sound that is referenced by the active variation.
The following is an example of iterating through the track properties represented by the arrTrackProperties member:
void EnumerateTrackProperties(LPXACT_SOUND_PROPERTIES pSoundProperties) { for (XACTINDEX nIndex = 0; nIndex < pSoundProperties->numTracks; ++nIndex) { // Do something with pSoundProperties->arrTrackProperties[nIndex]; } }
Returns the properties of the sound variation that is currently active in a cue instance.
Streaming parameters for a wave bank.
Xact.h also includes the following constant declaration:
typedef const XACT_WAVEBANK_STREAMING_PARAMETERS *LPCXACT_WAVEBANK_STREAMING_PARAMETERS;
Windows |
---|
The file that is referenced by this handle must be opened with the following CreateFile flags: FILE_FLAG_OVERLAPPED | FILE_FLAG_NO_BUFFERING. |
The size of a DVD sector is 2048 bytes. Therefore, setting this value to 2 results in a packet size of 4096 bytes. Setting it to 3 specifies packets of 6144 bytes, setting it to 4 specifies packets of 8192 bytes, and so on.
The optimal DVD size is a multiple of 16 (1 DVD block = 16 DVD sectors).
Returns the properties of a track in an active sound variation in a cue instance.
These properties are timing dependent. They may change when the
Returns the properties for the variation that is currently active in a cue instance.
Contains the entry information from an XACT wave bank.
DWORD value representing both the flags and duration.
Flags for the wave bank entry. Can be the following values.
Value | Description |
---|---|
WAVEBANKENTRY_FLAGS_READAHEAD | Indicates stream read-ahead is enabled.? |
WAVEBANKENTRY_FLAGS_LOOPCACHE | Indicates one or more looping sounds use this wave.? |
WAVEBANKENTRY_FLAGS_REMOVELOOPTAIL | Indicates removal of data after the end of the loop region.? |
Duration of the wave, in units of one sample. For instance, a ten second long wave sampled at 48KHz would have a duration of 480,000. This value is not affected by the number of channels, the number of bits per sample, or the compression format of the wave.
Contains the header information from an XACT wave bank.
Contains the mini-wave format for an XACT wave bank.
Format of the wave file. Can be one of the values in the following table.
Value | Description |
---|---|
Specifies PCM wave format.? | |
Specifies XMA2 format.? | |
Specifies ADPCM wave format.? | |
Specifies xWMA format.? |
Number of channels in the wave file. Can be a value from 1 to 6.
Sampling rate of the wave file or sample rate of the decoded audio for compressed formats.
Block alignment index. For xWMA the lower 6 bits are the block alignment index and the upper 2 bits are the bytes per second index.
Bit depth of the wave file. Can be one of the values in the following table.
Value | Description |
---|---|
WAVEBANKMINIFORMAT_BITDEPTH_8 | Specifies 8-bit data. (PCM only)? |
WAVEBANKMINIFORMAT_BITDEPTH_16 | Specifies 16-bit data. (PCM, XMA, ADPCM).? |
For xWMA this field indicates whether the format is in the WMA format (0) or the WMA Pro format (1).
Contains the region information for an XACT wave bank.
Returns the properties that are common to all waves.