• 05/21/04 11:55 AM
    Sign in to follow this  

    A Quick Guide to FMOD

    General and Gameplay Programming

    Myopic Rhino
    [b] [size=5]What is FMOD?[/size][/b]

    FMOD is an easy to use crossplatform audio engine, available on the Windows, Windows CE, Linux, Macintosh, GameCube, Playstation 2 and XBox platforms. It can be used with C/C++, Visual Basic,Delphi and MASM. So, if you use one of those languages on one of these platforms and you want to use sound in your application, FMOD is made for you. The examples below will be in C although thebasic principles should be the same across all platforms.

    [b] [size=5]Alternatives[/size][/b]

    One alternative might be [url="http://www.openal.org"]OpenAL[/url]. OpenAL is another crossplatform audio API which is available for Windows, Linux and Macintosh and can be used with C/C++,Delphi and Java. The style is similar to OpenGL (for example, the extensions technique is also used here).
    A Windows-specific alternative would be DirectSound which is part of Microsoft's DirectX.

    [b][size=5]What does it cost?[/size][/b]

    The developers of FMOD have a nice philosophy; if you don't intend to make any money with your project, you can use it for free. So as long as you don't make any profit with your program you don'thave to pay anything. However if turns out that you will sell your product you would then have to buy a license, starting at $100 for shareware products. For more details have a look the officiallicence price list at fmod.org.

    [b] [size=5]From where can I get it?[/size][/b]

    To use FMOD in your application you need the headers and the library which can be downloaded from [url="http://www.fmod.org"]http://www.fmod.org[/url]. At this time the recent version is 3.70. Beaware that this version is not backwards compatible any more!

    [size=5][b] Getting Started[/b][/size]

    After unpacking the archive, you should copy the FMOD.DLL into your working directory or better still, into the directory where your executable file will be.

    Before we can really start we have to do one last thing.

    [size=4][b] For C users[/b][/size]

    Now you only have to include the header "fmod.h" and depending on your compiler, the right import library:[list]
    [*]fmodvc.lib for Microsoft Visual C++ and Codewarrior
    [*]fmodbc.lib for Borland
    [*]fmodwc.lib for Watcom
    [*]fmodcc.lib for LCC-Win32
    [*]libfmod.a for MingW and CygWin
    [*]fmod-3-7.lib for GCC
    [/list]
    [size=4][b] For Delphi users[/b][/size]

    Include the unit FMOD in your uses clause.

    [size=4][b] For Visual Basic users[/b][/size]

    Add fmod.bas to your project.

    [size=5][b] Initialization[/b][/size]

    Before we can use FMOD to play some sounds for us we need to initialize it. This is pretty simple:

    [code]FSOUND_Init (44100, 32, 0);[/code]
    The first parameter is our output rate in hertz. In our example it's equal to 44100. The second parameter is our maximum number of software channels. It doesn't matter if you choose a highernumber due to the fact that it won't affect your cpu usage as long as you don't really use them. However 32 should be more than enough for this short introduction.

    In the third parameter can we specify some flags if we want to. We leave this parameter as 0.

    That's it. Now we are ready to play some sounds. But in which format do we have out sounds? Is it a song, a sample or a stream?

    [size=5][b] Songs, Samples and Streams[/b][/size]

    Now it's time to mention that FMOD is subdivided in two APIs; FSOUND and FMUSIC. Which one you should use depends on the files you want to play.

    Sequenced music files like .MOD, .S3M, .XM, .IT, .MID, .RMI, .SGT or .FSB are called songs and are supported by the FMUSIC api.

    On the other hand, the FSOUND api is for PCM based or compressed files like .WAV, .MP2, .MP3, .OGG or .RAW. They can be treated as either samples or streams. If you want to play a short sound / asmall file like a gunshot then you treat the file as an sample. Samples will be decompressed into memory before being played and can be played multiple times. When you want to play a bigger file likecontinuous background music then you handle the file as a stream. This will result in more cpu usage because the file will be streamed from the disk in realtime, but also needs less memory as aresult. Another thing to note is that streams cannot be played multiple times at once.

    [size=5][b] FMUSIC[/b][/size]

    Let's rock! To play a song you need a FMUSIC_MODULE variable for the handle and following two lines:

    [code]handle=FMUSIC_LoadSong("YourFileName");
    FMUSIC_PlaySong(handle);[/code]
    You will notice that from now on almost every function needs the handle as the first parameter.

    [size=4][b] Let's get loud[/b][/size]

    Now, that your song is playing you can manipulate it in several ways. To make it louder you use:

    [code]FMUSIC_SetMasterVolume (handle, 256);[/code]
    With 256 we set the volume to the maximum. If we would have passed 0 we would have have silence. To pause our song we use:

    [code]FMUSIC_SetPaused (handle, true);[/code]
    and

    [code]FMUSIC_SetPaused (handle, false);[/code]
    when we want to unpause it.

    For background music it would be nice if our music would play in an endless loop. No problem:

    [code]FMUSIC_SetLooping (handle, true);[/code]
    And when we are tired of hearing the music we will stop it with:

    [code]FMUSIC_StopSong (handle);[/code]
    [size=4][b] Cleaning Up[/b][/size]

    To free the allocated memory from a song you should simply call:

    [code]FMUSIC_FreeSong (handle);[/code]
    and we're done. Pretty easy, isn't it?

    [size=4][b] A small simple console example[/b][/size]

    In this example (for Windows compilers) we'll play a file called 'canyon.mid' and wait until the user hits a key to exit the program. Remember to link the correct library and use the right pathsfor the header and the midi file.

    [code]#include
    #include "inc/fmod.h"

    FMUSIC_MODULE* handle;

    int main ()
    {
    // init FMOD sound system
    FSOUND_Init (44100, 32, 0);

    // load song
    handle=FMUSIC_LoadSong ("canyon.mid");

    // play song only once
    // when you want to play a midi file you have to disable looping
    // BEFORE playing the song else this command has no effect!
    FMUSIC_SetLooping (handle, false);

    // play song
    FMUSIC_PlaySong (handle);

    // wait until the users hits a key to end the app
    while (!_kbhit())
    {
    }

    //clean up
    FMUSIC_FreeSong (handle);
    FSOUND_Close();
    }[/code]
    [size=5][b] FSOUND[/b][/size]

    Due to the fact that you have more possibilities while using FSOUND it's a little bit more complicated. For instance, you have several channels which you can use simultaneously. But in this shortintroduction we will only be using one. First we have a look at samples, and afterwards we move on to streams.

    [size=4][b] Samples[/b][/size]

    [size=3][b] Let's rock![/b][/size]

    To play a sample you need a FSOUND_SAMPLE variable for the handle and following two lines:

    [code]handle=FSOUND_Sample_Load (0,"YourFileName",0,0,0);
    FSOUND_PlaySound (0,handle);[/code]
    The first command loads the sample. For the beginning only the second parameter is relevant - the name of the file you want to play! The rest is important when you want to use more than onesample, play a file from memory, etc. The second command plays the actual sample. The first parameter is the channel number you want to use and the second one the handle of the sound to play. Takecare that the file that you want to play is not that big! Otherwise, it will take a while until the file will be played because it is first loaded completely into memory.

    [size=3][b] Let's get loud[/b][/size]

    Now, that your sample is playing you can manipulate it in several ways.

    To make it louder you use:

    [code]FSOUND_SetVolume (handle, 255);[/code]
    With 255 we set the volume to the maximum. As with the music, if we had had passed 0 we would have had silence. You can adjust the volume for a sample by passing a handle, or you can also adjust achannel by passing the relevant channel number instead of a handle.

    To pause our sample we use:

    [code]FSOUND_SetPaused (handle, true);[/code]
    and

    [code]FSOUND_SetPaused (handle, false);[/code]
    if we want to unpause it. Again the first parameter can be a channel number.

    When we want to stop the sample we just use:

    [code]FSOUND_StopSound (handle);[/code]
    And once again can the parameter be a channel number.

    [size=3][b] Cleaning up[/b][/size]

    To unload the sample a simple

    [code]FSOUND_Sample_Free (handle);[/code]
    is enough.

    [size=3][b] A small simple console example[/b][/size]

    Nothing fancy here. This snippet just plays the file sample.mp3.

    [code]#include
    #include "inc/fmod.h"

    FSOUND_SAMPLE* handle;

    int main ()
    {
    // init FMOD sound system
    FSOUND_Init (44100, 32, 0);

    // load and play sample
    handle=FSOUND_Sample_Load (0,"sample.mp3",0, 0, 0);
    FSOUND_PlaySound (0,handle);

    // wait until the users hits a key to end the app
    while (!_kbhit())
    {
    }

    // clean up
    FSOUND_Sample_Free (handle);
    FSOUND_Close();
    }[/code]
    [size=4][b] Streams[/b][/size]

    [size=3][b] Let's rock![/b][/size]

    To play a stream you need a FSOUND_STREAM variable for the handle and the following two lines:

    [code]handle=FSOUND_Stream_Open("YourFileName",0, 0, 0);
    FSOUND_Stream_Play (0,handle);[/code]
    It's pretty much the same as samples so nothing more to say here.

    Note: Take care that you're using at least version 3.7. In earlier versions the command for opening a stream was different!

    [size=3][b] Let's get loud[/b][/size]

    Here you can use the same functions as listed with the samples. I just want to mention one additional function here:

    To stop a stream you use:

    [code]FSOUND_Stream_Stop (handle);[/code]
    [size=3][b] Cleaning up[/b][/size]

    To unload the stream a simple

    [code]FSOUND_Stream_Close(handle);[/code]
    is enough.

    [size=3][b] A small simple console example[/b][/size]

    This small example streams the file sample.mp3.

    [code]#include
    #include "inc/fmod.h"

    FSOUND_STREAM* handle;

    void main ()
    {
    //init FMOD sound system
    FSOUND_Init (44100, 32, 0);

    //load and play sample
    handle=FSOUND_Stream_Open("sample.mp3",0, 0, 0);
    FSOUND_Stream_Play (0,handle);

    //wait until the users hits a key to end the app
    while (!_kbhit())
    {
    }

    //clean up
    FSOUND_Stream_Close(handle);
    FSOUND_Close();
    }[/code]
    [size=5][b] Shutting Down[/b][/size]

    To shut down the FMOD sound system just call at the end of your program:

    [code]FSOUND_Close ();[/code]
    [size=5][b] What's coming next?[/b][/size]

    Of course are there more things you can do with FMOD. 3D sound, handling CDs and effects are just a few to mention. All in all it's not that complicated but it is definitely pretty powerful. So,it should be easy to read through the help file and find what you need.

    [size=5][b] Final Words[/b][/size]

    I wrote this short article after I saw [url="http://www.gamedev.net/reference/articles/article2008.asp"]the article about OpenAL by Lee Winder[/url] at [url="http://www.gamedev.net"]Gamedev.net[/url]. A short time later the question about how to play sound in an application came up in the forum. Even though the FMOD API comes complete with some examplesand brief tutorials these might not seem as simple at the first glance. I hope this article was useful for you. For any comments, questions, feedback, etc. send me an email at [email="webmaster@joachimrohde.de"]webmaster@joachimrohde.de[/email].

    Joachim Rohde


      Report Article
    Sign in to follow this  


    User Feedback

    Create an account or sign in to leave a review

    You need to be a member in order to leave a review

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now


    Ectara

    Report ·

      

    Share this review


    Link to review
    Daaark

    Report ·

      

    Share this review


    Link to review