Note: it is assumed that you are using Visual Basic 5 or 6 and that you have DirectX 8 or higher installed on your computer to follow along with this article. You can also download the source code for this project/article.

DirectX is a set of multi-media libraries that Microsoft offers to game developers for free. The libraries allow developers to create robust and entertaining games. The first release of DirectX came out with Windows 95 and it was called the "Games SDK." Since Windows 95, more than eight new versions of DirectX have been released.

Although Microsoft kept releasing new versions of the APIs, they were primarily for C and c++ programmers, which meant an entire group of developers, were being left in the dust. Other programmers using different programming languages, such as Visual Basic or Delphi, had problems using the libraries and there was no easy access or interface to DirectX for these developers.

Microsoft finally began to address this issue in DirectX 7 and provided official support for Visual Basic by creating an interface for VB developers called the “DirectX 7 for visual basic type library”. This interface/dll let VB developers access most parts of DirectX 7.

In DirectX 8, Microsoft bettered this type library and created the “DirectX 8 for visual basic type library.” This enhanced interface to DirectX 8 now let Visual Basic programmers have a deeper set of DirectX tools to create competitive products/games.

The “DirectX 8 for visual basic type library” gave Visual Basic programmers access to Direct3D and Direct3DX, graphic libraries that game developers use to create graphics in their games, DirectInput, a library to let you trap input devices such as keyboards, mice, and joysticks, DirectPlay, the library that lets you program online multi-play games and voice chatting, DirectMusic, the library that lets you compose music primarily via midi files, and the library we are interested in DirectSound which lets you play sound effects via wav files.

DirectSound is a library that we DirectBlindies use. DirectSound lets us play multiple sound effects via wav files at the same time. Think of DirectSound like a CD player, DirectSound lets you play, pause, stop, rewind, fast forward, stereo position, and adjust pitch and volume of sound effects in your games. It lets us do more than that, but for this series, I will only be focusing on those aspects. As a blind or VI programmer, DirectSound will be one of the core libraries you will want to master since it will comprise 80% of your game.

DirectSound is used to play wav files. It cannot play mp3 files. There is a library called DirectShow that is used to play mp3 files but that is way out of the scope of this tutorial. So how does DirectSound actually work?

DirectSound loads wav files into your computers memory. Once loaded into memory, it is referred to as a sound buffer. The sound buffer has properties that let you adjust volume, frequency (pitch), pan, and so forth.

In order to begin to work with DirectSound and wav files, you have to setup your Visual Basic 6 project to use the master library DirectX. To do this, follow these steps:

• 1. Open up Visual Basic 6, or Visual Basic 5, and select standard exe for the type of project.
• 2. Press alt+p for the project pull down menu then arrow to references and press enter on it.
• 3. Down arrow, or press the letter d repeatedly, until you find and entry "DirectX 8 for visual basic type library"
• 4. Press your space bar to check the box then tab to the ok button and press enter.

If you cannot locate "DirectX 8 for visual basic type library" in the list, make certain you have DirectX 8 or higher installed on your computer. To pick up a copy of DirectX, go to www.microsoft.com/directx/ . Note: DirectX 9 contains both DirectX 7 and DirectX 8 for Visual Basic type libraries. If you have DirectX 8 or higher installed on your computer, but cannot locate "DirectX 8 for visual basic type library" in the list of references, in the project references screen, tab to the browse button and press your space bar. Manually browse for the file named Dx8VB.dll. On windows 98/ME computers, you can find it in the system folder. On computers running windows 2000 or any version of xp, you can find it in your system32 folder. Press enter on the file then tab to the ok button on the project references screen and press enter to set the reference and return to your vb 6 project.

Now you will want to save your project. Press alt+f then the letter v for save all. Save all the files in a folder on your hard drive. Further on in the tutorial, we will need a wav file so at this point, copy any wav file to your project folder and name it tone.wav. To rename the file, just be positioned on it and press f2 then type the new name tone.wav and press enter.

Now that we have a reference set to the master library DirectX, in other words, the box is checked to use DirectX 8 for visual basic type library, we now have to tap into DirectX objects via variables we will define. This syntax might seem difficult at first, but it really isn't that bad. I'll do my best to explain so buckle up and get ready.

These are the objects and variables we will need. Open up the code editor for form1. If you are viewing form1, press f7 to open up the code editor. Place these declarations in the general section of your form; it should be named form1 unless you renamed it. The General section of your form is directly below the word Option Explicit at the top of the document. I.E general section of the form simply means the line below the word option explicit. Just down arrow once off the word Option Explicit and bam! you are in the general section of the form. I have used the word private to preface a variable but I could have used dim instead. Both are fine. Copy and paste the following code in that spot:

Now in the form load event, we need to initialize DirectX and DirectSound. You have to setup DirectX first before you can do anything else. So, down arrow until you hear form load then get inside of that sub. If you can not locate it, press control+f2 and you will be taken to a combo box. Down or up arrow until you hear form. Next, tab once and you will be in a new box, down or up arrow until you hear load and press enter. Now you will be in the form load event. Here is the code for the form load event and then a description after it of what we are doing:

Step 1 in the form load is the most important. You have to create an instance of DirectX, the master object, so that you can use the other libraries within it such as DirectSound, DirectInput, DirectPlay, and so forth. So DirectX contains all the other DirectX systems that you will use in your games. In order to access those other systems, or objects in fancy terms, you have to create a variable to be the master DirectX object. Above, we called it dx and set it to be a master DirectX object with this line of code:

Set DX = New DirectX8

So now the variable dx is a master DirectX object we can use in our source code. Since we now have a variable holding DirectX, we can now create any sub-system, or child object, of DirectX such as DirectSound, DirectInput, DirectMusic, or even DirectPlay.

Now in step 2, we create a DirectSound 8 object with this syntax:

Set DS = DX.DirectSoundCreate("")

And we called the variable ds in our source code. Now ds is a variable, or object, in our source code that lets us use all DirectSound features to play sound effects.

So to recap, we create dx, a master DirectX variable/object, and then we created ds, a Direct Sound variable/object since once we create dx, the master DirectX variable/object, we are allowed to create any sub-system of DirectX and DirectSound is a sub-system of DirectX. Make sense? I knew it would *smile*. If it doesn't, re-read this section until it clicks.

Once we have assigned our ds variable to a default sound card, we do the only required DirectSound initialization, which is setting DirectSound's cooperative level. Simply put, this just tells DirectSound how to manage its resources and how to interact with the rest of windows. After all, if someone is playing our super slick game, we don't want some other stage hog program playing sounds and keeping us from blowing up the enemy in our game, right?

It is always possible that other programs, including windows itself, will be running while your game is running and what do we do if they want to play a sound effect? This is what setting the cooperative level does. It tells whether or not other programs and Windows can play the sound effects while your game is running.

If we set the cooperative level to DSSCL_NORMAL, this means that if our game/window has focus, and if Windows or another open stage hog oink oink program tries to play a sound, it will not be able to. However, if we alt+tab away from our game, to another program, and if that program wants to play a sound effect, it can since we set DirectSound to use a cooperative level of DSSCL_NORMAL.

So what do we do if we want to be the master stage hog and let no programs, including windows, play sound effects while we are playing our game? We would set the cooperative level to DSSCL_PRIORITY which means any program or even Windows itself, will not be able to play sound effects, only our game. As an aside, most game developers do not set DirectSound's cooperative level to DSSCL_PRIORITY, they mostly set it to DSSCL_NORMAL.

So how does the Windows operating system know when our game has focus or not? Simple, Windows looks for our handle. What is a handle? Nothing more than an identifier. Think of it like your name. How do you know who you are? By your handle, Jack the Gamer. We tell DirectSound to use our handle by using this line of code and notice the hwnd, which stands for handle:

DS.SetCooperativeLevel Me.hWnd, DSSCL_NORMAL

So to speak this in English, it would look like this:

Hey DirectSound, look at this form, and lets set the cooperative level to normal.

In the syntax above, the me key word stands for "this form". In other words, me. Hey Windows, notice "Me" and my handle here. Ya Windows, it is Me and my handle that wants to play sounds Me.Hwnd.

Well, at this point we really haven't' done much accept setup DirectX and DirectSound. You could run the project at this point by pressing f5 but it would just show form1 and that is all. You actually have all the code you need to setup DirectX and DirectSound in any project so you could copy/paste the code into any new game project you started.

However, now it is time to play a sound and create our first sound buffer! The code to do this isn't that difficult but will require a little explaining. We first create a DirectSoundSecondaryBuffer8 object and then load in some audio data from our tone.wav file.

We can also describe the parameters of the buffer for DirectSound by using our desc variable we declared earlier. We assign the desc variable flags, or settings, to use when creating the buffer. There are a couple of important flags that we should specify, but the other flags, or settings to use on the sound buffer, are optional such as - stereo/mono, 8/16 bit, frequency (22khz/44khz) and so forth. if we don't specify these parameters then DirectSound will use those stored in the sound file.

Lets add the desc variable to our form load event as step 4, and assign three flags, or parameters, to it… frequency, pan, and volume. Those three items we want to be able to adjust on the sound buffer so we will set those flags. Once we set the flags, then we can load our sound buffer as step 5. It will look like this:

If you ran the project right now by pressing f5, the tone.wav file would be loaded into your computer's memory and ready for you to play, stop, pause, adjust the frequency of the buffer, pan it left/right, or adjust the volume of it. However, at this point, nothing would happen since we don't have the code in place to adjust the properties of the dsToneBuffer. Now that we've loaded our sound into memory, we can now play it. It is a good idea to turn off any CD Audio, Winamp or any similar programs while you run and test your program. They can sometimes cause DirectSound to fail initialization.

Seeing that we are blind or VI programmers, I think we will use the form key down event to trap keyboard presses and use simple keystrokes to show you how to play/pause/stop/pan/adjust volume and so forth on the buffer. I.E we will press p for play, s for stop, a for pause, l for loop sound, etc. That is easier to me than working with adding a bunch of command buttons on the form, positioning them, sizing them, and so forth. For us to trap keyboard presses, we have to set the form's KeyPreview property to true. To do this, first press control+r for the project explorer, down arrow until you hear form1 then press f4 to bring up the properties window for form1.

Once the properties window opens up, down arrow until you hear KeyPreview and tab once into the edit box and press your up or down arrow until it says true. This property of the form, KeyPreview, if set to true, will trap all key presses in the form key down and form key up events. Once you set it to true, press control+f4 to close the properties window. Now go back to the code editor so we can begin to code some more. A way to do this is press control+r to bring up the project explorer, down arrow until you hear form1, then press shift+enter.

Now that we are back in the code editor, lets get in the form key down event. To do this, press control+f2 and then down or up arrow until you hear form. Once on form, tab once to the next combo box and down arrow until you hear key down and press enter. Bam, we are now in the key down event and ready to add our code to play/pause/stop the buffer. We will use a select case statement to trap the various keyboard presses. Here is what it will look like, you can copy/paste it into your project.

Go ahead and run the project at this point by pressing f5 and experiment. In the code above, you'll notice that both pause and stop use the dsToneBuffer.Stop method. This stops the buffer at the current position, which is good for pause, but to get the effect of a true stop, meaning stop the sound and start it back at the beginning, , we must set the current position of the sound buffer back to 0, the beginning.

If you want to loop the sound or disable looping it, stop the sound first by pressing the s key, then press l to toggle the loop/normal play, then press p to play the sound again. If you take a look at the play code, you will see that the sound buffers play property can be set to DSBPLAY_DEFAULT, play the sound one time, or to DSBPLAY_LOOPING, which means loop the sound buffer continuously.

If you want to play multiple sound effects at the same time, go for it! That is why we blind or VI developers use DirectSound, it lets us do that. You could loop background music, have two buffers for footsteps, another buffer for your characters gun, a shot sound, and so forth. However, one concept to keep in mind is that you don't want to load lots of sound buffers into memory since slower systems will bog down so only load the sound buffers you need when you need them. For example, do you really need the main menu sound buffers in memory when you are playing the game? No, you don't.

Now that we can load and play a sound buffer, we will want to adjust the properties of the sound buffer. We will be adjusting panning, frequency, and volume. As you recall, in the desc variable in the form load event, we set the desc variable/flags to let us adjust pan, frequency, and volume. Once we set those flags, then we loaded the dsToneBuffer with the wav file data. Refer back to the form load event and reflect on that code for a minute.

The first property we will adjust is pan. To pan our sound buffer left or right, we will use the left and right arrow keys and trap them in the form key down event just like we trapped the p, s, and a key presses. The range for panning a sound is, -10,000, completely left, 0, centered, and 10,000 is completely right. Notice it isn't +10000 and just 10000 for the positive range. You can adjust the pan on the sound buffer to any number within that stereo range, -10000 to 10000 with 0 being the center.

Now lets add this code to our form key down event. I'll put our new editions for pan at the top of the select case and you will want to notice I test for -9000 and +9000 and will explain why after the code.

You will notice that we first test to see if we are at our max values for left or right. However, I set the max and min values to be -9000 for the left and +9000 for the right instead of the -10000 and +10000. The reason I did this is to catch a potential runtime. To explain, each arrow press increments by 500. So, using the left arrow for an example, if you hit the left arrow, it moves you from 0, center, to -500 left. If you hit the left arrow again, you are taken to -1000 left and so on clear up to -9000. If I did not keep the increment at a 500 interval, I would run the risk of going beyond -10000 and causing a runtime error.

for example, if I had the increment be -1500 for each left arrow press, and reached -9000, the next tap of the left arrow would put us at 10500 which is past the limit of -10000 and would blow up the program and raise a runtime error. So, I test to see if we are greater than -9000 or equal to -9000. If we go over -9000, we won't runtime since it would only be -9500 and we catch that, drop to the else branch of the test, and set the pan to -9000 again so each time the user hits left, we just keep setting it to -9000 so the program can never runtime. This is an important lesson when working with pan… know your limits and catch them! I apply this same concept for pressing the right arrow, which you can review in the code.

The next property we will look at is volume. DirectSound handles volume quite strangely but it makes sense if you understand why it does what it does. It doesn't ever amplify the volume of the sound buffer, the only thing it can do is lower the volume. So, whatever volume your wav file is recorded at, DirectSound uses that for the max value for the volume and sets the max volume value to 0. So, if you set the sound buffers volume to 0, it is the loudest. The lowest value you can set the volume at is -10000. Really, right around -3000 the sound buffer is nearly muted. However, that is my opinion and you can play around with it to see what you think.

For adjusting the volume of the sound buffer up or down, in our key down event, we will use the up and down arrows. I will add the new code to the top of the select case so you can quickly see it. Here is what it will look like:

You will notice that I use the same testing logic for volume as I did for pan. I test for the min or max volume and if it is reached, I drop to the else branch and set the volume accordingly so the program will not runtime.

Ok, last property we have to cover is frequency. For a cool effect, you can adjust the frequency of a sound buffer up, make the sound higher in pitch, or adjust the frequency down, make the sound lower in pitch. If it was a person talking, the higher you make the frequency, the more they would sound like a chipmunk. The lower you made the frequency, the more the voice would sound like a monster.

A sound buffers frequency is measured internally in hertz (hz), and the lowest it can go is 100 (hz) and the highest it can go is 100000 (hz) which is really 100khz. You will find that most sounds are recorded at 11, 22, or 44 khz. So, for example, if you had a voice over that said "easy" recorded at 44 khz, you could adjust the frequency of the sound buffer up to 100000 khz and the voice would sound extremely high pitched. Likewise, you could adjust the frequency down to 3000 khz and it would sound so low pitched it would not be understandable. Hint hint, so how did we make space ships fall down to the earth in Troopanum? Now you know!

We will add the frequency code in the form key down event. To adjust the frequency up, we will press the letter u. To adjust the frequency down, we will press the letter d. Here is what the code will look like, I will place the new key presses at the top of the key down event so you can quickly view it.

Notice that I used the same testing logic for frequency as I used for pan and volume. Since I am incrementing frequency by 1000, I test for greater or equal to -2000 even though I could go to -100. Just a precaution so I won't runtime and really, anything below -2000 is garbled and hard to understand. Here is a pop quiz for you, in troopanum, how did we know if a ship landed? What would we test for?

You now know the basics of sound buffers, playing sound buffers, and adjusting properties of sound buffers. Really at this point, the sky is the limit. You can certainly learn more about DirectSound and sound buffers, adding special effects to buffers, working with 3d surround sound, etc. but really, this is all you need to know to get up and running and creating some cool games for the VI community. So, what are you waiting for? Go for it! You can be that next great accessible game developer! The sky is the limit! Or should I say, sound buffers and your computer's system resources are the limit?

Let me wet your appetite for a minute. Think of it for a moment. Your game starts and you loop an erie background theme. Your character walks around as you hit left arrow, right arrow, down arrow, and up arrow. You play dsFootStep each arrow press which plays a cool sounding footstep. An enemy is in range to be shot because dsEnemy pan is at 0, centered where you are so hurry up and shoot him! Another enemy down the hall is approaching slowly, his volume is at -3500 and when he reaches a volume of -100, he can kill you if you don't shoot him first with the control key. Hit the control key and boom, dsGunShot plays and then your enemy dies and dsEnemyKills is played and you hear him hit the floor. Can you catch what I am saying here? Good luck and have fun!

Note: developers do not use the form key down event or form key up event to write games. The form key down event lets you hold down arrow keys and cheat in games. To get around this, developers use DirectInput, the library in DirectX that lets you trap keyboard presses, the mouse, joysticks, etc. DirectInput does not let you hold down keys and cheat. For some sample code on how to use DirectInput, download our chopper patrol sample project.

You can download the source code for this article by clicking here

Did you find this resource helpful? If so, why not let us know about it. Send us an email to ResourceCenter@BscGames.com.

Copyright (c) 2002 - 2009 BSC Games a division of blindsoftware.com LLC all rights reserved