Beginning Game Audio Programming [Electronic resources] نسخه متنی

USING MIKMOD FOR TRACKED MUSIC

In this chapter, you'll learn how to use MikMod to add tracked music playback abilities to the audio engine. However, before you get to the code, you must first learn how to install MikMod.

Installing MikMod

Here's how to get MikMod up and running on your system. Note that I've already done these steps for you for this chapter's sample program; they only apply when you're working on your own code.

Inside your Goodies folder on the CD is a MikMod folder which contains the MikMod archive, libmikmod-3.1.10 (version 3.1.10 was the latest as of this writing). Unzip this file into a folder of your choosing.





Open a command window; navigate to the win32 folder underneath your main MikMod folder.





If you want to use the static version of the library, type nmake –f makefile.static. Or, if you want to use the dynamic version (which uses mikmod.dll), type nmake –f makefile.dynamic. Note that both of these makefiles output to mikmod.lib, so be careful.





If you don't have mikmod.h inside the MikMod include directory, copy win32\mikmod_build.h to include\mikmod.h in the include directory. The make file is supposed to do this for you, but on my system it didn't.

To use the MikMod library in your own applications, follow these steps:

Select Settings from the Project pull-down menu inside DevStudio.





Add the mikmod include directory to your project include path. You do this by going to the C/C++ tab, then selecting Preprocessor. Add a relative path to the MikMod include directory. For this chapter's sample program, that would be ..\..\libmikmod-3.1.10\include.





Add the mikmod library directory (which is actually the win32 directory) to your project's library path. To do this, go to the Link tab, select Input as the category, and add the relative path into the edit box labeled Additional library path. For this chapter's sample program, I entered ..\..\libmikmod-3.1.10\win32.





Add the MikMod library to your link libraries by adding mikmod.lib to the edit box labeled object/library modules.





Don't forget to include mikmod.h in whatever source files use MikMod.

MikMod Help

The MikMod API reference is contained in HTML documentation, inside your docs folder. Launch the mikmodl file, which contains all of the documentation.

Using MikMod in the Audio Engine

To integrate MikMod into the audio engine requires the creation of a new class, as well as some changes to the CAudioManager class. The following sections discuss each in more detail.

CTrackedMusic

The new CTrackedMusic class, derived from CSound like every other form of music or audio class in the engine, represents a tracked music object. Here's the class declaration:

class CTrackedMusic : public CSound
{
public: 
friend class CAudioManager;
CTrackedMusic(CAudioManager *mgr); 
virtual ~CTrackedMusic();

virtual bool Play(); 
virtual bool Stop(); 
virtual bool IsPlaying(); 
std::string GetFileName() { return(m_FileName); } 
static void FreeAllModules();
protected: 
static std::vector<CTrackedMusic *> m_AllTrackedMusicInstances; 
std::string m_FileName;
MODULE *m_Module;
};

At the core of this class is a pointer to a MODULE: m_Module. MODULE is a data type that MikMod uses; essentially, it's a handle to a tracked music song. You get a MODULE address by calling the Player_Load API call.

But I'm getting ahead of myself. There are two other members in CTrackedMusic. One is a vector of CTrackedMusic pointers. This vector keeps track of all instantiated tracked music classes—in the CTrackedMusic constructor, the code pushes its this pointer onto the vector, and in the destructor, it finds and removes its this pointer from the array. The engine uses this list to free all of the modules before it shuts down MikMod. Shutting down MikMod without freeing the modules is sloppy, so this mechanism is in place to ensure that everything gets cleaned up when the time comes.

The other member is m_FileName, which contains the filename the CTrackedMusic class was created from. There's no dire need to have it, but it's handy reference material.

The three mandatory methods, Play, Stop, and IsPlaying, are all one liners, thanks to the MikMod API. For Play, the code just calls Player_Start; for Stop, it calls Player_Stop; and for IsPlaying, it calls Player_Active.

The FreeAllModules method loops through the m_AllTrackedMusicInstances vector, calls Stop on all of the valid modules, and then frees their MODULE_ pointers via a call to Player_Free.

CAudioManager

Now that you know everything there is to know about the CTrackedMusic class, here's the other half of the story. To support MikMod requires a couple of subtle changes in CAudioManager.

For starters, there's some new code added to the Init method:

MikMod_RegisterAllDrivers(); 
MikMod_RegisterAllLoaders(); 
MikMod_Init(");

All three of these functions are requirements for setting up the MikMod library. The MikMod_RegisterAllDrivers call chooses an appropriate output driver—on Windows, this is either the driver for windows multimedia audio or the DirectX 5.0 compatible driver. Yes, this means that you can use MikMod on an older OS (say, Windows NT) that doesn't support DirectX 5.0.

The MikMod_RegisterAllLoaders function figures out which file formats (IT, S3M, MOD, and so on) the library can load. Be careful—if you forget to call this function at the beginning of your programs, you won't be able to load anything—you'll just keep getting NULL return values from Player_Load.

Finally, the call to MikMod_Init fires everything up and tells whatever driver MikMod_RegisterAllDrivers picked out to initialize and start up. The character string is where you put any options you want to pass to the driver—usually you don't need to pass anything, so just leave this as an empty string.

Usually, new code in the initialization method means new code in the un-initialization method, and this time is no exception. Here are the new lines:

CTrackedMusic::FreeAllModules(); 
Player_Stop();
MikMod_Exit();

The first call causes all of the CTrackedMusic instances to free their MODULE pointers. Next, UnInit calls Player_Stop in case something's still playing, then calls MikMod_Exit to shut everything down. As you can see, dealing with MikMod is pretty straightforward.