The GMSound Object

The GMSound object lets you open and play WAV audio files in your program. For simple applications, you can just use the PlayWave function in the GMMachine object. (GMMachine actually uses a GMSound object for the PlayWave function.) But for better memory management and overlapping sounds, the GMSound object gives you much more control.

Note that GMSound currently works with traditional Microsoft .WAV files. Many of the "WAV" files now found on the Internet are actually MP3 files in disguise, with the extension changed from "MP3" to "WAV". These will not work. (Yet.) There are also a few, less common formats of the older WAV files that don't work properly.

Volunteers to update this object for compatibility with more formats are welcome. Contact Mark.

GMSound Functions

Creating a GMSound | Open | Close
Play | Stop | Volume | Pan
SoundLoaded | Playing

Sample Programs

See the "Bells and Whistles" versions of the GMCollision examples.

picture

Constructor
GMSound(GMMachine &m[, char *filename, int howmany])
GMSound(GMMachine *m[, char *filename, int howmany])

Minimally, the constructor needs to be told about the GMMachine object. If you provide the filename and howmany parameters, the constructor also performs the Open function automatically. See the Open function below for details.

void Open(char *filename[, int howmany])

Each GMSound object is associated with a single WAV audio file. The Open function loads the WAV file into memory. filename is the name of the WAV file. The optional howmany parameter lets you open several duplicate buffers of the WAV, allowing you to play simultaneous, overlapping instances of the sound. The default value for howmany is 1.

void Close()

Close stops the WAV if it is playing, and unloads it from memory, freeing the buffer area(s) used for the sound. If you want to be sure the sound is finished playing before unloading it, check the return value of the Playing function before you call Close.

void Play( [int mode=0, int pan=0, int volume=-1])

Here's the function that actually plays the sound. All the parameters are optional. If you call this function with no parameters, the WAV is played once, centered between the speakers, at full volume.

If you set the mode parameter to 1, the sound will keep repeating until you use the Stop or Close function. If you set mode to 2, the sound plays once, but the function does not return until the sound is finished playing. The default mode is 0, which plays the sound once and returns immediately so your program can do other things while the sound plays.

Note: mode 2 will not pause if you've got more than one sound buffer for this file and at least one buffer is already playing. If the other buffer had already been set to loop, mode 2 would hang the program in an infinite waiting loop!

The pan parameter orients the sound from left to right. It can be from -10000 (left speaker only) to 10000 (right speaker only). The default is 0, centered between the two speakers. The volume parameter can be from 10000 (full volume) to 0 (silence). The default is 10000.

If the sound is already playing and you've opened multiple sound buffers (howmany > 1 in the Open function), Play will start a second instance of the sound overlapping with the first. If there is only one sound buffer and it is playing, Play stops the sound and starts it again at the beginning. If there are multiple sound buffers and all are playing, Play will stop the oldest one and start it from the beginning.

void Stop()

This stops the sound from playing. Important: if more than one simultaneous instance of this sound is playing, this will stop them all.

void Volume(int v)

This sets the volume for the sound to the value you give, from 10000 (full volume) to 0 (silence). If you set the volume using this function, and then omit the volume parameter in the Play function, the Play function will use this volume instead of the normal default.

Important: if there are multiple sound buffers for this sound, the Volume function affects them all, even the ones that are currently playing.

void Pan(int p)

This sets the left-right pan value for this sound while the sound is playing. -10000 is full left, 0 is centered, and 10000 is full right. If there are multiple sound buffers for this sound, Pan affects all the ones that are playing.

BOOL SoundLoaded()

This function returns True or False, telling whether a WAV file has been properly loaded into this GMSound object.

int Playing()

This function returns the number of sound buffers in this GMSound that are currently playing. You can consider the return value as True (non-zero) if any sound is playing, and False (0) if none are playing. For multiple concurrent instances of this sound, this function also tells you exactly how many of them are currently playing.

picture