XNACS1Lib:
Tutorial 4: Working With Audio

Reference: This is the forth tutorial on how to work with the XNACS1Lib library. It is assumed you have read and understand the previous three tutorials:

• First Tutorial : XNACS1Lib application structure;
• Second Tutorial: Working with primitives; and
• Third Tutorial : Working with PrimitiveSet

Goals : This tutorial concentrates on describing how to work with audio:

void PlayACue( String cueName)   void PlayBackgroundAudio( String bgAudioName, float level )

• cueName: is the name of the cue to be played.
• bgAudioName : is the name of the background music file to be played, and
• level: is how loudly you want to play the background music (1.0 being the loudest, and 0.0 being completely switched off).

1. Obtain the example code

• Here is the zip file to the source files and compiled executable of this example.
• Here is the keyboard mapping for the XBOX 360 controller.  
• Here is the main tutorial page for working with XNACS1Lib, and here is the complete documentation of the library: html-page or compiled html help file.

2. The Source Code Files/Structure

Take a look at the ExampleProgram folder that you have unzipped and you will see a structure almost identical to that of previous tutorial. The only notable difference is a new Audio subfolder in the Content/Resources folder:

3. The Solution Explorer:

Now double click on the *.sln file in the ExampleProgram folder, to start the project in the IDE. Notice the structure of the SolutionExplorer follows the source code folder structure we have examined:
As illustrated in the above figure, you will notice the Audio folder and the collection of *.wav files. The process of including the *.wav files into the project works identical to that of *.jpg Texture files, where you would right-mouse-button click on the Resources folder and add the existing Audio folder. Any *.wav files can be included in this folder (and thus into your project). For example the Left.wav and Right.wav files are recorded words of "Left" and "Right" from the Microsoft Audio Recording utility software.

3a. Cues: in the
       PlayACue( String cueName) and
       PlayBackgroundAudio( String cueName, ...) 
functions, the cueName refers to names of these *.wav files. Notice that as in the case of jpg image files where we identify the images by their names without the extension. In this case, we will also refer the audio cues by their file names without the .wav extension.

3b. Limitations: Limited audio bank support : We have a very simple audio support where you can only play up to 8 audio cues at the same time.

3d. Hints on working with Audio Cues: Our simple audio architecture support means we have limited audio resources to work with. We should use this resource carefully and strategically to maximize support for feedback to our users (students).

1. Use it as a hint to events : Use audio cues to inform users that something has happened (e.g., the soccer ball has touched the window boundary).
2. Use one cue at a time : it can be confusing to the user when more than one cues are playing at the same time, i.e., be mindful when calling PlayACue() more than once during a single UpdateWorld() function. For example, in your application a hero is walking and encountered a gold nugget during the UpdateWorld() function. It may be your desired to play a cue to represent the hero walking, and a separate cue to represent the encountering of the gold nugget. In this case, you should weigh the importance and probably only play one of the cues.
3. Use shorter cues rather than longer cues: The audio support will honor the requested duration of a cue even if the cue span multiple UpdateWorld() functions. This means, if you start a five minute audio effect, within this five minutes interval other audio effects will be mixed and can cause confusion. In general multiple short audio snippets corresponding to significant events is much more informative than one significant audio segment representing one of the significant events. For example, if five collisions occurred over a period of one seconds. In this case it is much more informative for the user to hear five distinct audio cues (each can be 0.1 seconds in length), than for the user to hear a single one-second audio segment that accurately represents one of the five collisions. With our simple library support, each of your audio cues should probably be less than one second.

4. Examine the Game1.cs source file:

We are finally ready to examine our source code playing of the cues. In this case, when comparing to the source code from the third tutorial, no new instance variables are necessary and no extra code is necessary in the InitializeWorld() function. We simple call PlayBackgroundAodio() in the beginning and call PlayACue() funciton in the UpdateWorld() function when " interesting " events occur:

protected override void UpdateWorld() {      ...      #region   A. Update the Rotating ladder      #region B. Update the soccer ball, make sure it bounces off the window bounds           ...           BoundCollideStatus collideStatus = CollideWorldBound(m_SoccerBall);           switch (collideStatus) {               case BoundCollideStatus .CollideTop:                case BoundCollideStatus .CollideBottom:                     ...                     PlayACue( "CollideWorld" );                     break ;                case BoundCollideStatus .CollideLeft:                     ...                     PlayACue( "Left" );                     break ;                case BoundCollideStatus .CollideRight:                     ...                     PlayACue( "Right" );                     break ;            }      #endregion      ...      please refer to the source file for the rest of the PlayACue() calls.

	This work is supported in part by a grant from Microsoft Research under the Computer Gaming Curriculum in Computer Science RFP, Award Number 15871 and 16531.
2/8/2010