This tutorial will teach you how to initialize, release, and utilize DirectX Audio. You will learn to load and play WAVs and MIDIs. This tutorial does not cover 3D sound, and does not assume any knowledge of sound or sound programming.
Remember to link dsound.lib and include the headers dmusici.h and dsound.h.
[size="5"][b]Initializing DirectX Audio[/b][/size]
Before we can actually play sounds with DirectX audio, though, we must initialize it. There are three steps to initializing DirectX Audio (as written in [url="http://glbook.gamedev.net"]OpenGL Game Programming[/url]):
[list=1][*]Initialize COM[*]Create and initialize the performance object[*]Create the loader[/list] [size="3"][b]1. Initialize COM[/b][/size]
Unlike other components of DirectX, DirectAudio is pure COM. This means that you have to create the com objects yourself, mostly using the function CoCreateInstance(). Initializing the actual COM system, however, is very easy:
[indent][code]CoInitialize(NULL);[/code][/indent] What, you were expecting something harder? This simple function call allows you to use COM to create the DirectAudio objects.
[size="3"][b]2. Create and initialize the performance object[/b][/size]
First of all, let's talk about the performance object. The performance object handles all data flow from the sound segments to the synthesizer that plays the sounds. Basically, it is the master interface of DirectX Audio. The performance object can be made by creating an IDirectMusicPerformance8 interface object. Then, you must create the object by calling CoCreateInstance.
[indent][code]IDirectMusicPerformacne8* g_performance = NULL;
CoCreateInstance(CLSID_DirectMusicPerformance, NULL, CLSCTX_INPROC,
IID_IDirectMusicPerformance8, (void**) &g_performance);[/code][/indent] The previous code declares an IDirectMusicPerformance8 object and creates it. Now we have to initialize it. The IDirectMusicPerformance8 interface uses the member function InitAudio to initialize itself. Let's take a look at the function:
DMUS_AUDIOPARAMS pParams);[/code][/indent] Now let's show a working example of this function.
[indent][code]g_performance->InitAudio(NULL, // no interface needed
NULL, // no interface needed
g_hWND, // handle to the window
DMUS_APATH_SHARED_STEREOPLUSREVERB, // default audiopath
64, // 64 channels allocated to the audiopath
DMUS_AUDIOF_ALL, // allow all synthesizer features
NULL); // default audio parameters[/code][/indent] [size="3"][b]3. Create the loader[/b][/size]
The loader object, as its name implies, loads all audio content, such as MIDIs and WAVs, into segments that hold the data. The loader is represented in the IDirectMusicLoader8 interface. Creating the object requires a simple call to, you guessed it, CoCreateInstance.
[indent][code]IDirectMusicLoader8* g_loader = NULL;
CoCreateInstance(CLSID_IDirectMusicLoader, NULL, CLSCTX_INPROC,
IID_IDirectMusicLoader8, (void**) &g_loader);[/code][/indent]
Now that we've gotten DirectX Audio ready to go, we need something to play. Next item on the list: creating a segment. Let's see what we have to do:
[list=1][*]Create a segment[*]Load the segment[*]Download the band[*]Play the segment[/list] [size="3"][b]1. Create a segment[/b][/size]
You might be wondering what a segment is. A segment is an object that encapsulates the sound data that is loaded from a sound file. Any sound that is played in DirectX Audio is in the form of a segment, just about. If you've been following along, you probably already know that the segment object is the form of the IDirectMusicSegment8 interface and is initialized through a COM call.
[indent][code]IDirectMusicSegment8* g_segment = NULL;
CoCreateInstance(CLSID_IDirectMusicSegment, NULL, CLSCTX_INPROC,
IID_IDirectMusicSegment8, (void**) &g_segment);[/code][/indent] [size="3"][b]2. Load the segment[/b][/size]
Now that you have a segment, you must load it with sound content. This is where the loader comes in. first, you want to set the search directory for the loader. This can be accomplished using the IDirectMusicLoader8::SetSearchDirectory function.
BOOL fClear);[/code][/indent] Chances are, you just want to set the search directory to the directory your program is in. This shows how you would do that
MultiByteToWideChar(CP_ACP, 0, searchPath, -1, wSearchPath, MAX_PATH);
g_loader->SetSearchDirectory(GUID_DirectMusicAllTypes, wSearchPath, FALSE);[/code][/indent] The previous code snippet first declares a normal and a wide character array. The GetCurrentDirectory function retrieves the directory which the program is in. The MultiByteToWideChar function converts the regular character array into a WCHAR array. If you use dxutil.h | cpp, the DXUtil_ConvertGenericStringToWide function just uses MultiByteToWideChar, only it looks better. Finally, we call SetSearchDirectory with the predefined GUID that enables all music types to be read. Now that we've set the search path, we want to actually load a file. This can be accomplished with one function call:
void **ppObject);[/code][/indent] Here's how you would load a file named test.wav:
[indent][code]char filename[MAX_PATH] = "test.wav";
MultiByteToWideChar(CP_ACP, 0, filename, -1, wFilename, MAX_PATH);
(void**) &g_segment);[/code][/indent] [size="3"][b]3. Download the band[/b][/size]
In order to be able to play the sound, you have to download the sound's band into the synthesizer. This can be done with the IDirectMusicSegment8::Download function.
[indent][code]HRESULT IDirectMusicSegment8::Download(Iunknown *pAudioPath);[/code][/indent] That wasn't very exciting, was it? All you have to do is download the band to the performance object, like so:
[indent][code]g_segment->Download(g_performance);[/code][/indent] [size="3"][b]4. Play the segment[/b][/size]
Finally, the real stuff. Playing the sound, like most operations in DirectX Audio, only takes one function to complete. You can either use PlaySegment or PlaySegmentEx. Since PlaySegmentEx offers more functionality, we will be using it. Here is the prototype:
IUnknown* pAudioPath);[/code][/indent] Even though it looks a little complicated, it is actually very simple to use. Only a couple of the parameters are of importance to us. pSource is the sound data that you are going to play. In this case, you will be playing g_segment. i64StartTime is the performance time at which the song will start playing. Normally, you sill set this to zero so that the song will play immediately. Notice that this is a function of the IDirectMusicPerformance8 interface. This is because IDirectMusicSegment only handles sound data and playing information. IDirectMusicPerformance8 handles all manipulation of the segment, including playing and stopping. Now let's finally play some music.
[indent][code]g_performance->PlaySegmentEx(g_segment, NULL, NULL, 0, 0, NULL, NULL, NULL);[/code][/indent]
Now you can load and play songs with DirectX Audio. Now you need some more control over your music. The only thing as important as starting your music is stopping it. That's simple enough:
DWORD dwFlags);[/code][/indent] You can use either one to stop a sound. For the last two parameters, both have the same functionality. The second to last parameter indicates when to stop the sound. If you want to stop the sound immediately, that value should be 0. dwFlags is when the stop should occur in the segment, which should also be set to 0. But, StopEx offers extra functionality because it can stop a segment or an audiopath. For stopping one sound, we'll use that.
[indent][code]g_performance->StopEx(g_segment, 0, 0);[/code][/indent] Simple. What if you want to stop all sounds that are playing? You don't have to keep track of which song is playing. Just use the Stop function.
[indent][code]g_performance->Stop(NULL, NULL, 0, 0);[/code][/indent] When you pass NULL as the segment to stop, the function stops all playing sounds. I tried it with StopEx, but the program crashes.
Another point: What if we want to check and see whether a song is playing or not? Use the IsPlaying function:
IDirectMusicSegmentState* pSegState);[/code][/indent] The function returns S_OK if the segment is still playing.
[indent][code]if (g_performance->IsPlaying(g_segment) == S_OK)
// do something because the song is still playing
}[/code][/indent] The last function I want to talk about before we conclude is SetRepeats.
DWORD dwRepeats);[/code][/indent] This function, as the name implies, sets the number of times that the sound repeats. If you're playing background music, for example, and you want it to loop forever, pass DMUS_SEG_REPEAT_INFINITE as the parameter and the sound will loop until you explicitly stop it.
We've had our fun, but now we need to shut down the program. First thing we do is stop all the sounds that are playing with the Stop function mentioned above. Then we call IDirectMusicPerformance8::CloseDown, which takes no parameters. Next, we release all objects with their Release function, which also takes no parameters. Lastly, we shut down COM with CoUninitialize, which takes no paramerters.
[indent][bquote]Hawkins, Kevin; Astle, Dave, [url="http://glbook.gamedev.net/"]OpenGL Game Programming[/url]
DirectX Documentation[/bquote][/indent] If you found this tutorial helpful, or you encounter any bugs or questions, please email me at [email="email@example.com"]firstname.lastname@example.org[/email].