Managing XACT Resources and Notifications

The Microsoft Cross-Platform Audio Creation Tool (XACT) has always provided a great deal of freedom and flexibility with regard to resource management and notifications. With the July 2005 XDK release, XACT resources and notifications can be managed more easily than ever before.

IXACTSoundBank, IXACTWaveBank, and IXACTCue no longer support AddRef and Release methods. Instead, titles should free resources by calling these interfaces' respective Destroy methods. Destroy calls will synchronously destroy the object (stopping the playback immediately) and free up the resources allocated for that object.
- Destroying a cue will immediately stop the playback (if it's playing) and delete all its contained sounds, etc.
- Destroying a soundbank will destroy all its cues.
- Destroying a wavebank will cause any cues that were using this wavebank to be destroyed.
XACTDestroyNotification, XACTFlushNotification, and XACTGetNotification have been removed. Instead, titles should implement an XACT_NOTIFICATION_CALLBACK routine and pass the function pointer to IXACTEngine::Initialize as a member of the XACT_RUNTIME_PARAMETERS structure.
Notification callbacks take place as soon as the event that needs the notification takes place. Titles should minimize the amount of time spent in these callbacks to avoid glitching.
XACT no longer makes allocations for notifications and hence titles do not need to call destroy notification APIs to free them. This means that it's no longer safe for a title to keep the notification pointers passed in the callbacks. As soon as the callback returns, the pointer is invalid.
The IXACTEngine::RegisterNotification and IXACTEngine::UnRegisterNotification APIs will return failure if the notification callback function pointer was not passed in the XACT_RUNTIME_PARAMETERS structure during XACT initialization.
Certain API calls (any that allocate/deallocate memory) are not allowed to be called from the notification callbacks. See the tables listed under XACT_NOTIFICATION_CALLBACK that enumerate all the APIs that are allowed or prohibited from the notification callbacks.
Interface pointers sent to titles in notifications are for reference only. Titles can make some calls on these interfaces in the callback, but should not depend on these pointers being valid after the callback returns.
Notification callbacks can take place on any thread, DoWork, ProcessEvents or the application thread.
- Callbacks for Cue Prepared notification occur on the ProcessEvents thread.
- Callbacks for Cue Destroyed notification can occur on either DoWork or the application thread. (Fire and forget cues are destroyed on the DoWork thread as soon as they finish playing).
- Callbacks for Cue playing and Cue Stopped notification will take place on the ProcessEvents thread.
- Callbacks for Sound Bank Destroyed notification will occur on the application thread when either IXACTSoundBank::Destroy or IXACTEngine::ShutDown is called.
- Callbacks for Wave Bank Prepared notification will occur on either the DoWork thread or on the application thread when IXACTEngine::CreateInMemoryWaveBank or IXACTEngine::CreateStreamingWaveBank is called.
- Callbacks for Wave Bank Destroyed notification will occur on the application thread when either IXACTWaveBank::Destroy or IXACTEngine::ShutDown is called.
- Callbacks for Local Variable Changed and Global Variable Changed notification will occur on the ProcessEvents or the application thread (when IXACTCur::SetVariable or IXACTEngine::SetGlobalVariable APIs are called).
- Callbacks for GUI connected and GUI disconnected notifications take place only when auditioning is enabled and take place on the auditioning thread or the application thread (when IXACTEngine::Shutdown is called).
- Callbacks for Wave Playing and Wave Stopped can take place on the ProcessEvents thread, the renderer callback thread (notifying packet completion) or on the application thread when IXACTEngine::Shutdown or IXACTWaveBank::Destroy is called.

Managing XACT Resources and Notifications

See Also