JavaScript EditorFree JavaScript Editor     Ajax Editor 

Main Page
  Previous Section Next Section

Starting Up DirectMusic

DirectMusic is the first component of DirectX that is totally pure COM (Component Object Model), meaning that there aren't any helper functions in an import library to create the COM objects for you. Alas, you must create the COM objects yourself with calls to the COM library. So the only files any application needs are the DirectMusic header files. There isn't any import .LIB file. The header files are


Just make sure to include these in your applications, and COM will take care of the rest. Let's take a look at the entire sequence.

Initializing COM

First you have to initialize COM with a call to CoInitialize():

// initialize COM
if (FAILED(CoInitialize(NULL)))
   // Terminate the application.
   }   // end if

This should happen at the beginning of your application, before you make any direct COM calls. If you have other pure COM calls and already have called it, don't worry about it.

Creating the Performance

The next step is to create the master interface, which is the DirectMusic performance. Creation of this interface will also create an internal IDirectMusic interface, but you won't need it, so it's hidden away. To create an interface based on pure COM, use the CoCreateInstance() function with the interface ID and the class ID, along with storage for the new interface pointer. Take a look at the following call:

// the directmusic performance manager
IDirectMusicPerformance    *dm_perf = NULL;

// create the performance
if (FAILED(CoCreateInstance(CLSID_DirectMusicPerformance,
   // return null
   } // end if

Looks a bit cryptic, but within reason. After this call, dm_perf is ready to go and you can make calls to the interface functions. The first call you need to make is to initialize the performance with IDirectMusicPerformance::Init(). Here's the prototype for it:

HRESULT Init(IDirectMusic** ppDirectMusic,
             LPDIRECTSOUND pDirectSound,
             HWND hWnd);

ppDirectMusic is the address of the IDirectMusic interface if you explicitly created one. You haven't, so make it NULL. pDirectSound is a pointer to the IDirectSound object.


This is important, so read carefully: If you want to use DirectSound and DirectMusic together, you must start up DirectSound first and then pass the IDirectSound object in the call to Init(). However, if you're using DirectMusic alone, pass NULL and DirectMusic will create an IDirectSound object itself. This is needed because DirectMusic ultimately goes through DirectSound, as shown in Figure 10.14.

Figure 10.14. Relationship between DirectMusic and DirectSound.


The moral of the story is that you must pass the main DirectSound object pointer, or NULL if you aren't using DirectSound. You'll do the later for illustrative purposes. Finally, you must send the window handle. That's pretty easy—here's the code:

// initialize the performance, check if directsound is on-line if so, use
// the directsound object, otherwise create a new one
if (FAILED(dm_perf->Init(NULL, NULL, main_window_handle)))
   return(0);// Failure -- performance not initialized
   } // end if

Adding a Port to the Performance

The next step to get DirectMusic up and running is creating a port for the digital data to be streamed to. If you like, you can query DirectMusic via enumeration for all valid ports, or you can just use the Microsoft Software Synthesizer as the default. That's my style—keep it simple. To add a port to the performance, use the IDirectMusicPerformance::AddPort(). Its prototype is shown here:

HRESULT AddPort(IDirectMusicPort* pPort);

Here, pPort is a pointer to a previously created port that you want to play from. However, just use NULL and the default software synthesizer will be used:

// add the port to the performance
if (FAILED(dm_perf->AddPort(NULL)))
   return(0);// Failure -- port not initialized
   } // end if
      Previous Section Next Section

    JavaScript EditorAjax Editor     JavaScript Editor