Using Scripting for Resource Management

DirectX Audio Scripting can also be used to allow the composer to control certain aspects of resource management, particularly when Segments are loaded, downloaded, and unloaded. Loading is the process of reading a Segment in from the disk. Downloading is the process of determining the waves (streaming or in memory) and/or DLS instruments the Segment uses and loading their wave data into memory (or, where available, transferring their wave data onto a DLS-capable hardware synthesizer, the original concept behind the term "download"). Unloading is the opposite of downloading, where DLS instruments and waves no longer in use can be freed.

By default, all of these are managed automatically; when a script loads, all of the Segments that it references or embeds are automatically loaded and downloaded. Of course, if you have one script for an entire application, that could be a fairly large resource hit. The scripter could create one script for every level or one for every group of sounds that can be inclusively loaded and unloaded. Alternatively, the scripter can opt to control when these processes occur.

Figure 7-13: You can control whether loading and downloading automatically occur via the script's properties page.

With increased control comes increased responsibility. If the script attempts to play a Segment that it has not yet loaded, an error will occur. If it attempts to play a Segment that has not been downloaded, that Segment will probably play silently. Similarly, it will be up to the scripter to free (unload) content that is no longer needed, or system resources might be unnecessarily drained. As one extra note of precaution, loading and downloading are synchronous functions, which means that the script will wait to continue executing content until the necessary disk transfers are complete.

 Sub LoadAndPlayMusic MySegment.Load MySegment.DownloadSoundData 'Downloads all DLS instruments and in-memory waves. MySegment.Play End Sub Sub FreeWaveData MySegment.UnloadSoundData 'Make sure you unload as many times as you download 'for a Segment, as wave data won't be freed until then. End Sub 

While downloaded instruments are freed via UnloadSoundData, loaded Segments are not freed until the script is freed. This is generally not much of an issue, as it is the wave data (DLS instruments and non-streamed waves) that takes significant memory and needs to be unloaded as soon as playback is completed.

Once a script has been completed, don't forget to run-time save it (right-click and choose Runtime Save As… or Runtime Save All Files from the File menu); the .spt file that is generated will embed any content that was placed in the Embed Runtime folder and knows how to use any separately delivered content that had been dragged into the Reference Runtime folder. When scripts are used in a DirectMusic application, encourage your programmer to give you the ability to manually fire off every script routine in some manner while running the application. For instance, if the bad guy music only gets triggered at the very end of a game, you probably don't want to have to go all the way through a level just to hear if the music triggered at an appropriate boundary.

DirectX Audio Scripting provides another tool to the composer or sound designer for controlling audio behavior without needing to overly involve the programmer and, more importantly, the ability to make changes without having to rebuild the entire application. While the functionality provided is a subset of the functionality made available programmatically, the functions allow for the vast majority of basic and intermediate scenarios to be handled solely by the content author.