Scripting


Scripting is the key to creating interactivity with DirectMusic. The script drives the music in response to calls to its routines from the DMX control. You have to create script routines for all of the hooks defined previously. You may find "under-the-hood" routines useful in controlling automated functions and in testing conditions for other routines.

Getting the script right is vital for properly functioning music. The slightest error can cause a routine, or even the whole script, to fail. Having said this, AudioVBScript is a very simple scripting language. Microsoft designed an easy-to-learn system for people without a programming background. I learned how to use AudioVBScript quickly, with no programming experience. This section provides some useful pointers in relation to scripting a web site project.

Creating the Script

Consider in advance what routines your script requires. For our site, we need routines to trigger the motifs Loz1.sgp to Loz6.sgp, WideLogo.sgp, WipeUp.sgp, and WipeDown.sgp, the transitions between the primary Segments, and the volume controls. Additionally, the DMX control must trigger the "start" routine automatically once the content loads. Name these routines clearly early on; this way, you can easily identify which routines the script uses in performing various tasks when we add the calls into our HTML. I like to go through the site, writing down the names of the routines I will use for each interaction as I come across it.

You must make the content files available to the script before it can use them. Do this by dragging the files from the project tree into either the Embed Runtime or Reference Runtime containers in the Script object. Each approach has advantages and disadvantages. Dragging a Segment into the Embed Runtime container embeds the Segment into the run-time version of the script file. In other words, you do not need to include the run-time Segment file when you deliver the final content files. This method is attractive, as it reduces the number of files required for delivery. On the other hand, embedding run-time files often involves complicated dependencies of embedded files, especially where you use multiple scripts.

The Reference Runtime container does exactly what it says. You must include the run-time Segment file along with the script file. The script file references the Segment file at run time. The appeal of this approach is that you do not need to worry about dependencies, as long as all files are present. It also allows you to update a single component file without changing any of the other files, which is often useful in the final stages of testing.

Drag the content files into the Reference Runtime container; then create the routines required to play them. A sensible starting point is the start routine that the DMX control calls once everything loads.

This script creates a basic start routine:

 sub Start    Intro.play end sub 

Although it is not required for the site, it is always useful to have a "stop" routine in the script while testing. The following stop routine halts any looping Segments. You do not need to include the short, non-looping motifs, as they never continue more than a second or so after the primary and secondary Segments stop.

 sub Stop    Front.stop AtImmediate    Intro.stop AtImmediate    Minimal.stop AtImmediate    Guitar.stop AtImmediate    ClickFilt1.stop AtImmediate    Scr.stop AtImmediate end sub 

The AtImmediate flag ensures that the Segments stop right away, regardless of their boundary settings.

Any routines in the script appear in the list to the right of the script (see Figure 18-14). Double-clicking on a routine in this list executes that routine. By entering one routine at a time, you build the script up gradually until all the required functionality is present.


Figure 18-14: Routines and variables displayed in the Script Designer window.

Creating an AudioPath Object

In DirectMusic Producer, Segments play back on the AudioPath selected in the AudioPath list, shown below. If you want to use a custom AudioPath at run time, you must specify the AudioPath in your script.


Figure 18-15: The AudioPath list.

Create an AudioPath object when the script starts and specify that object each time a Segment plays. This ensures that the run-time version uses the correct custom AudioPath.

 sub CreateAudioPath    if AudioPathLoaded <> 1 then       AudioPathLoaded = 1       FlashPath.load       set AudioPath1 = FlashPath.create    end if end sub 

The routine above, when run for the first time, loads the AudioPath FlashPath and defines the variable AudioPath1 as FlashPath.create. Adding the parameter AudioPath1 to a play command now ensures that the Segment plays back on the correct AudioPath.

 sub Start    CreateAudioPath    Intro.play 0, AudioPath1 end sub 

This version of the start routine initializes the AudioPath and plays Intro back on the correct AudioPath by running CreateAudioPath.

Working with Variables

Scripts often require variables for retrieving, setting, and storing integer values such as Master Volume or for conditional statements. Variables exist within an individual routine, or they can be global and thus available to any routine. Define global variables at the top of the script by typing dim VariableName. Once you define the global variables, they appear in the variable list (below the routine list — see Figure 18-14). This list displays the current value of global variables and allows you to edit them manually for testing.

The Script Volume.spp, which is dedicated to the site's volume controls, uses the global variable Vol to track the master volume of the Performance. Calling Down first uses GetMasterVolume to retrieve the current master volume and then sets the variable Vol accordingly. Down uses Vol in a conditional statement to determine whether the master volume is at or above its minimum value. If the master volume is not at the minimum value, Down reduces Vol by 500 and uses SetMasterVolume to set the master volume to the newly reduced value of Vol (an attenuation of 5 dB).

 sub Down    Vol = GetMasterVolume    if Vol > -9600 then       Vol = Vol - 500    end if    SetMasterVolume Vol end sub 

Volume exists as a separate script because I like to keep mechanisms such as volume controls as easily accessible chunks of script. This is a habit that I acquired from working on much more complex game projects, and it is arguably unnecessary in such a small project. Communication between the scripts is straightforward. Simply add the name of the target script to the routine call in the parent script, as shown in the following example.

 sub VolDown    Volume.Down end sub 

Variables can also be set and retrieved between scripts in the same way.

Achieving desired functionality often requires complex interactions between multiple routines and variables, especially in situations where the result of a particular routine differs depending on the currently playing Segments. For example, when a transition occurs, you may want to lock out certain motifs or prevent another transition from occurring until the first one finishes. In these situations, you may need to use several variables to track exactly what happens at any given moment. You may also need to use conditional statements to determine whether to start the new transition or motif or initiate a queuing or locking mechanism. Our little web site happily lacks such complexities, but DirectMusic scripting can cope with most things that you care to throw at it if necessary!

Even with a simple project, keep scripts clear and tidy. There are likely to be logical groupings of routines, and maintaining clarity makes editing, testing, and bug fixing considerably quicker and easier. Any text that comes after an apostrophe is a comment (see below). Comments are useful for explanatory notes or disabling bits of script while testing.

 sub Lozenge1    Loz1.play IsSecondary, AudioPath1' This is a comment end sub ' sub Lozenge2    ' Loz2.play IsSecondary, AudioPath1 This whole routine is commented out ' end sub 

As with any interactive system, it is impossible to overemphasize the value of thorough testing. Test constantly throughout the scripting process, and thoroughly check the script after any changes — no matter how isolated they are.

Delivery

Once everything checks out in DirectMusic Producer, test the system as part of the web site. First, create the run-time versions of the DirectMusic files.

You can save all the run-time files at once from the File menu (see Figure 18-16). The default destination is a folder called RuntimeFiles created in the Project folder. If you embed the content files rather than reference them, it may not be necessary to save run-time versions of every file. Avoid duplicating files or including obsolete files that increase the total size of the download.


Figure 18-16: Saving run-time files from DirectMusic Producer.

Packaging of Run-time Files

The DMX control downloads a compressed .cab archive file and expands it to temporary files. This means only a single file needs to download, and a final stage of compression applies to the content files.

Using a compression utility such as WinAce (see Figure 18-17), add the run-time files to an archive with "Normal" compression. Our archive is WSMain1.cab and resides in the site structure in /music/.


Figure 18-17: Compression settings in WinAce.




DirectX 9 Audio Exposed(c) Interactive Audio Development
DirectX 9 Audio Exposed: Interactive Audio Development
ISBN: 1556222882
EAN: 2147483647
Year: 2006
Pages: 170

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net