Articles - Blue Dino Code

MixBox Quick Guide

Prerequisites: C++ classes and a small bit of SDL

MixBox is a set of C++ classes that makes it easy to add sound and music to your games. The MixBox class is the main one. It holds all the sound and music data and has functions that access just about everything you'd want. The other classes, SoundID, MusicID, and ChannelID, are all subclasses of MixID. Each of these classes has functions that roughly duplicate what the MixBox class can do for that type of object, but having them lets you choose how best to work MixBox into your game.

Typical usage of MixBox follows these steps: Open the mixer, load a sound, close the mixer, then free the sound.
Here's a quick example of the simplest usage of MixBox. You can grab the full example source and sample sounds here. Link this program with SDLmain, SDL, and SDL_mixer:

#include "SDL.h"
#include "MixBox.h"

int main(int argc, char* argv[])
{
    using namespace MB; // MixBox's namespace

    // Get the MixBox for future use
    MixBox& mixer = MixBox::instance();

    // Open the mixer
    mixer.openMixer();

    // Load a sound
    SoundID hit = mixer.loadSound("hit.wav");

    if(hit.isBad())
        printf("Error loading sound file.\n");

    // Play the sound
    hit.play();

    while(mixer.isPlaying())
    {
        SDL_Delay(1);
    }

    // Close the mixer
    mixer.closeMixer();

    // Delete the sound
    mixer.freeSounds();


    // All done
    SDL_Quit();
    return 0;
}

Really straightforward, right? Before you can do anything with this example, though, you need to have sound files to play. There are some in the above link, but you'll need more, of course. If you need somewhere to start, I recommend DrPetter's sfxr. It's a great tool for quickly making retro and placeholder sounds.

The examples just have the basics of MixBox. Here's a brief overview of some other functions MixBox has. Since playing sounds and music is not too complex, I'll just explain the odd ones. There's more than this in MixBox. All the functions can easily be found in MixBox.h, where there are better descriptions of what they do. Be sure to check it out!

MixBox setup: Initialize and close MixBox.

static MixBox& instance();
- Returns the singleton MixBox.
void setAudioFormat(Uint16 format);
void setAudioRate(unsigned int rate);
void setNumOutputs(unsigned int num);
- Sets the number of output (not mixing) channels (e.g. 1 for mono, 2 for stereo)
void setBufferSize(unsigned int size);
unsigned int setNumChannels(unsigned int numChannels);
- Sets the number of mixing channels
bool openMixer();
void closeMixer();

MixBox loading: Load and delete sounds and music.

SoundID loadSound(const char* filename);
MusicID loadMusic(const char* filename);
void freeSounds();
void free(const SoundID& id);
void freeMusic();
void free(const MusicID& id);

MixBox sound controls:

bool swapStereo();
ChannelID play(const SoundID& id, int loops = 0);
void stop();
ChannelID playPan2D(const SoundID& id, float x, float y, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y) is from (0, 0).
ChannelID playPan3D(const SoundID& id, float x, float y, float z, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y, z) is from (0, 0, 0).
bool isPlaying() const;
- Tells you if any channel is playing a sound. There are other functions that work with specific channels.

MixBox music controls:

void play(const MusicID& id, int loops = -1);
bool isMusicPlaying() const;
void stopMusic();
void pauseMusic();
bool isMusicPaused() const;
void rewindMusic();
void resumeMusic();
bool skipMusic(double position);
bool fadeInMusic(const MusicID& id, unsigned int milliseconds, double skipPosition = 0, int loops = -1);
bool fadeOutMusic(unsigned int milliseconds);

SoundID:

bool isBad() const;
- Tells you if the sound loaded incorrectly.
void setVolume(float volume = 1.0f);
float getVolume() const;
ChannelID play(int loops = 0);
ChannelID playPan2D(float x, float y, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y) is from (0, 0).
ChannelID playPan3D(float x, float y, float z, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y, z) is from (0, 0, 0).

MusicID:

bool isBad() const;
- Tells you if the music loaded incorrectly.
void setVolume(float volume = 1.0f);
float getVolume() const;
void play(int loops = -1);

ChannelID:

bool isBad() const;
- Tells you if the ID represents a viable channel.
void setVolume(float volume = 1.0f);
float getVolume() const;
bool isPlaying() const;
void play(const SoundID& sound, int loops = 0);
void stop();
void pause();
bool isPaused() const;
void resume();
void playPan2D(const SoundID& id, float x, float y, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y) is from (0, 0).
void playPan3D(const SoundID& id, float x, float y, float z, float maxRange, int loops = 0);
- Plays a sound with stereo panning and volume that depend on how far (x, y, z) is from (0, 0, 0).

And that's how easy it is to add sound and music to your games! Remember that there's more in the header file, MixBox.h. There's also a demo program included with the MixBox source. If you have any questions, suggestions, or contributions, drop me an email.

Jonny D