Managing XACT Resources and Notifications

  • Article

Managing XACT Resources and Notifications

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.

  • IXACT3SoundBank, IXACT3WaveBank, and IXACT3Cue 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, and so on.

    • Destroying a sound bank will destroy all its cues.

    • Destroying a wave bank will cause any cues that were using this wave bank 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 IXACT3Engine::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 IXACT3Engine::RegisterNotification and IXACT3Engine::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 IXACT3SoundBank::Destroy or IXACT3Engine::ShutDown is called.

    • Callbacks for Wave Bank Prepared notification will occur on either the DoWork thread or on the application thread when IXACT3Engine::CreateInMemoryWaveBank or IXACT3Engine::CreateStreamingWaveBank is called.

    • Callbacks for Wave Bank Destroyed notification will occur on the application thread when either IXACT3WaveBank::Destroy or IXACT3Engine::ShutDown is called.

    • Callbacks for Local Variable Changed and Global Variable Changed notification will occur on the ProcessEvents or the application thread (when IXACT3Cur::SetVariable or IXACT3Engine::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 IXACT3Engine::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 IXACT3Engine::Shutdown or IXACT3WaveBank::Destroy is called.

See Also

XACT Overviews, XACT3 Reference, XACT,

IXACT3Cue::GetState, IXACT3SoundBank::GetState, IXACT3WaveBank::GetState,

IXACT3Cue::Destroy, IXACT3SoundBank::Destroy, IXACT3WaveBank::Destroy