FMOD Documentation, Firelight Technologies Pty, Ltd.

Thank you for downloading FMOD music and sound effects system.

Within this package you will find the means to produce the most up to date and efficient

audio in your games and applications.

To find out more go to http://www.fmod.org


THE BASICS

Introduction

    This is the first place to look if you have no idea what to do when downloading FMOD, or those with some idea but need a little bit of help. It will give you a step by step introduction and tutorial on what to call, what to link and where to call stuff so you can easily get on your way to great sounding audio!

The package
    The first thing you will do is unzip fmod and find the following directory structure.

    /api

    The files you are interested in for your own projects are held here
    This holds

  • FMOD.DLL,
  • The import library (fmodvc.lib, fmodbc.lib etc) you need to link (for C users), and
  • The header (fmod.h, fmod.pas, fmod.bas depending on language) you need to include.

    • C Users
  • MSVC - #include "fmod.h" into your source code and link fmodvc.lib by putting it into your link section/makefile/project.
  • Codewarrior - #include "fmod.h" into your source code and link fmodvc.lib by putting it into your link section/makefile/project.
  • Watcom - #include "fmod.h" into your source code and link fmodwc.lib by putting it into your link section/makefile/project.
  • Borland - #include "fmod.h" into your source code and link fmodbc.lib by putting it into your link section/makefile/project.
  • LCC-WIN32 - #include "fmod.h" into your source code and link fmodlcc.lib by putting it into your link section/makefile/project.
  • Mingw and CygWin - #include "fmod.h" into your source code and link libfmod.a by putting it into your link section/makefile/project.
  • Linux / GCC - #include "fmod.h" into your source code and link with libfmod-X-Y.so (i.e gcc file.c -lfmod-3.5)

    Note there is no DJGPP support. If you ask for this you are looking in the wrong place. DJGPP is DOS only and to find a similar free WIN32 compiler try LCC-WIN32 or CygWin.

    Delphi Users
  • You need to have uses FMOD in your source code somewhere. If delphi cannot find the FMOD header you need to have the path to fmod.pas in your library path. Go to Tools\Environment Options\Library. Add the path, eg. C:\fmodapi340\api\delphi (of course, use the path that you have on your system), to Library Path and it should be happy.

    Visual Basic Users
  • Add fmod.bas to your project.

    /documentation

    You must know about this already if you are reading this!

    /media

    This directory holds some wav files and songs that the examples use. For example jbtennis.wav which contains loop points and wav sync markers that fmod can read

    /samples

    This folder is for C programmers and contains a variety of samples to demonstrate 3D sound, dsp effects, recording, streams and more
    To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.

    /samplesdelphi

    This folder is for Delphi programmers and contains a variety of samples to demonstrate using FMOD with Delphi. Written by Steve Williams
    To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.

    /samplesvb

    This folder is for Visual Basic programmers and contains examples of using FMOD with Visual Basic.
    To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.

    /tools

    This folder contains asioconfig.exe.
    This program simply configures any asio devices you have on your system by bringing up the driver's native configuration screen.
    If you run it and no entries are in the list, your asio drivers are not installed properly.
    If you select or doubleclick an entry that does exist and no config screen appears then your asio drivers are not installed correctly or you have selected the wrong driver to configure. Take note of this when selecting the device from the FMOD api.

Getting started
  • The first thing you need to do is make sure FMOD.DLL is accessable from your program. Otherwise you will get an error something like the one below when you try and run your executable.

    Copy the FMOD.DLL file out of the /api directory and into the directory where your executable will be. If they are in the same directory then it will work as expected.
    Now you are ready to start coding, you need to initialize FMOD first! You do this once at the start of your program.

  • Do this with FSOUND_Init.
    • The simplest way to do this is to tell FMOD to mix at 44100hz, and use 32 software channels. This is done like so.

    FSOUND_Init(44100, 32, 0);

    To get more detailed control please see the fmod.h file to see what pre-FSOUND_Init functions can be called to control things like mixer type, output device etc. Also FSOUND_Init itself has flags which you can find out more about in the relevant documentation.
    Note that you don't have to actually use the pre-init functions as FMOD automatically detects the best settings for you.
    If this function succeeds, (see error code if it doesnt), then FMOD is now running and some more interesting things can be done.
Samples, Streams and Songs
    You have a music file or a sound you want to play. What FMOD API should you use to load and play it?
    Here's a guide.

  • If it is a sequenced music file such as .MOD, .S3M, .XM, .IT or .MID, then use the FMUSIC API. You will want to use FMUSIC_LoadSong to load it into memory. When this gives you a valid return handle, use that handle with FMUSIC_PlaySong to play it! The handle type for this type of file when loaded is FMUSIC_MODULE.
  • If it is a PCM based or compressed file such as .WAV, .MP2, .MP3, .OGG or .RAW then you have a choice to make. Will it use too much memory if you load it in and decompress it into memory? or is it small enough to fit?
    - For small sounds such as sound effects that you want to trigger multiple times at once (for example a gunshot), then you will want to use FSOUND_Sample_Load. When it gives you a valid return handle, use that handle with FSOUND_PlaySound or FSOUND_PlaySoundEx. This is the fastest way to replay sounds, as they are decompressed into memory (at load time) first before being played. The handle type for this type of file when loaded is FSOUND_SAMPLE.
    - If the file is going to be big, and doesnt need to be played multiple times at once (note the next option cannot be played multiple times at once), then the other choice is to use FSOUND_Stream_Open. This opens a file, and prepares it for playing. When it gives you a valid return handle, use that handle with FSOUND_Stream_Play or FSOUND_Stream_PlayEx. This streams the file from the disk in realtime and decompresses the file on the fly. This option uses less memory than samples when the file is past a certain size. Note that this option uses a lot more cpu time than a sample as it has to access the disk, and if nescessary, decompress the data on the fly. FMOD decompression routines are usually fairly efficient but it can be significant on slow machines (especially CE devices), or if multiple streams are played together at once. You can of course measure this with FSOUND_GetCPUUsage or just see how it affects your framerate. The handle type for this type of file when loaded is FSOUND_STREAM.

    • Note : Use FSOUND_FREE when choosing a channel to play a sample or stream on. It makes the best choice for you. If you must use a value such as 0-31 etc, then carefully read the channel mapping/index informatiomn in the remarks section of FSOUND_PlaySound.
Manipulation
    Finally the last most basic things you might want to do are change the song's volume or speed or any other variety of attributes

  • For FMUSIC_MODULE handles you can use the FMUSIC API for commands like FMUSIC_SetPaused and FMUSIC_SetMasterVolume. See fmod.h (or equivalent) or the documentation for a list of these commands you can use.
  • For FSOUND_SAMPLE handles you can use a variety of commands on a playing sound from the channel handle returned from FSOUND_PlaySound or FSOUND_PlaySoundEx. These include such commands as FSOUND_SetVolume or FSOUND_SetFrequency or a whole host of commands.
  • For FSOUND_STREAM handles you can use a variety of commands on a playing stream, also from the channel handle returned from FSOUND_Stream_Play or FSOUND_Stream_PlayEx. Because these also use channels to play on, they can use the channel functions just as a sample would. You can pause a stream with FSOUND_SetPaused for example.


3D Sound Tutorial - Firelight Technologies Pty, Ltd.

3D SOUND AND GAME CODING

Introduction
    3D Sound in FMOD is accomplished through a various different API's which are handled transparently to you through one unified interface. These are DirectSound 3D with EAX 2.0 and EAD 3.0/HD support, or FMOD fallback software 3D stereo engine.

    It is recommended when you see an API function highlighted as a link, that you check the API reference for more detail.
Hardware Support
    Allocating samples with FSOUND_HW3D is the key to getting your sounds to use 3D hardware acceleration.
    You do this when loading wav, raw, mp3, etc samples, through the following function.

  • FSOUND_Sample_Load(int index, const char *name_or_data, unsigned int inputmode, int offset, int length); Bitwise OR in the FSOUND_HW3D flag into the mode parameter of the loading function.

    If you have the correct hardware, the sound will be loaded into hardware mode.
    If not, the sample will be loaded in software mode, transparently to the programmer, but it will not be accelerated or take advantage of advanced 3d algorithms and EAX.

    Here is an example of a wav file attempting to be loaded as a 3D Hardware buffer.
    FSOUND_Sample_Load(FSOUND_FREE, "engine.wav", FSOUND_HW3D | FSOUND_LOOP_NORMAL, 0, 0);

    Or you can force it into software by not specifying the FSOUND_HW3D flag
    FSOUND_Sample_Load(FSOUND_FREE, "engine.wav", FSOUND_LOOP_NORMAL, 0, 0);

    Or you can have it as a 2D sound (2d sounds are not affected by 3d functions, and are rendered in software), using the FSOUND_2D flag.
    FSOUND_Sample_Load(FSOUND_FREE, "engine.wav", FSOUND_2D | FSOUND_LOOP_NORMAL, 0, 0);

Typical game loop
    This would be a typical example of a game audio loop.

    do
    {
      UpdateGame(); // here the game is updated and the sources would be moved with FSOUND_SetAttributes

      FSOUND_3D_Listener_SetAttributes(listenerpos, listenervel, fx, fy, fz, tx, ty, tz); // update 'ears'
      FSOUND_Update(); // needed to update 3d engine, once per frame
    } while (gamerunning);
    Most games usually take the position,velocity and orientation from the camera's vectors and matrix.
Velocity parameter
    Velocity is only required if you want doppler effects. Otherwise you can pass NULL to both FSOUND_3D_Listener_SetAttributes and FSOUND_3D_SetAttributes for the velocity parameter, and no doppler effect will be heard

    This is stressed over and over again, but can't be stressed enough. It is important that the velocity passed to FMOD is METERS PER SECOND and NOT meters per FRAME.

    What does this mean? Use proper velocity vectors from physics code etc, and don't just subtract last frames position from the current position, as this is affected by framerate. (ie the higher the framerate the smaller the position deltas, and therefore smaller doppler effects, which is incorrect)

    If the only way you can get the velocity is to subtract this and last frame's position vectors, then remember to time adjust them from meters per frame back up to meters per second.
    This is done simply by scaling the difference vector obtained by subtracting the 2 position vectors, by one over the frame time delta.

    Here is an example
    velx = (posx-lastposx) * 1000 / timedelta;
    velz = (posy-lastposy) * 1000 / timedelta;
    velz = (posz-lastposz) * 1000 / timedelta;
     timedelta is the time since the last frame in milliseconds. This can be obtained with functions such as timeGetTime().
    So at 60fps, the timedelta would be 16.67ms. if the source moved 0.1 meters in this time, the actual velocity in meters per second would be
    vel = 0.1 * 1000 / 16.67 = 6 meters per second.
    Similarly, if we only have half the framerate of 30fps, then subtracting position deltas will gives us twice the distance that it would at 60fps (so it would have moved 0.2 meters this time)
    vel = 0.2 * 1000 / 33.33 = 6 meters per second still! phew!.
Orientation and coordinate systems
    Getting the correct orientation set up is essential if you want the source to move around you in 3d space.
    FMOD Uses a left handed coordinate system, (x = right, y = up, z = forwards), which is the same as DirectSound3D and A3D

    If you use a different coordinate system, then you will need to flip certain axis or even swap them around inside the call to FSOUND_3D_Listener_SetAttributes.
    Take the right handed coordinate system, where Z points backwards, or comes out of the screen at you. To convert this to FMOD coordinate system simply negate the Z coordinate of the listener up and forward vector.

    Just think RIGHT, UP, FORWARDS for each element of a vector (ie x,y,z), and map whatever axis fit your model into this, to generate the 2 vectors that points forwards and up.
Channel resource management and low end cards
    Some soundcards only support 4 or 8 3D hardware channels, whereas other soundcards support 32 and 96 hardware 3D channels.
    What do you do in your game? only play 4 3D hardware based sounds at once to meet the base spec? Not likely. It would be ridiculous to limit yourself to these 4 channels when you have the potential of other high end cards that can do nearly 100 hardware channels at once.

    The solution is to use FSOUND_SetMinHardwareChannels. This function is called once before calling FSOUND_Init.
    What this allows you to do is assume a number of channels will either ALL be played in hardware, or NONE in hardware (therefore in software).
    It basically says 'if the card doesn't have n number of channels, then mix all sounds in software'. This allows you to assume that you have say 16 sounds to be playing at once, and if the hardware has at least that many channels available, it will play them all in hardware. If you come across a card that only supports 4 hardware channels at once, then it fails the criteria and your sounds are played all in software.

    The best thing about this is NO PlaySound's fail because of running out of channels on unexpected cards! You can guarantee a certain number of channels available, and if the hardware is there, then all the better!
Use priorities!
    FMOD's priority system is there to be used. If you trigger lots of sounds on a limited number of channels, some might be more important than others.
    If you were doing a first person shooter, the player's gunshot sound would be one of the most important sounds. So it should have a high priority set with FSOUND_SetPriority. Other less important sounds would be rejected if the number of allocated channels became full, and that gunshot needed to be heard!


Synchronization Tutorial - Firelight Technologies Pty, Ltd.

MUSIC SYNCRHONIZATION

Introduction
    This section will describe how to synchronize graphics with sound effectively using FMOD functions.
    It usually involves either polling against a music value to trigger your effect, or getting a callback from FMOD.
Streams
    The best way to synchronize a stream, such as a wav or mp3 is by using FSOUND_Stream_SetSyncCallback.
    All you have to do is drop 'markers' into a wav editing program like SoundForge, and FMOD will automatically generate callbacks as the stream plays when the play cursor runs over the markers!.
    The strings that you label markers with are even passed into the callback.
    Note that only WAV files and MP3 with RIFF wrappers will work here. The markers are saved in a RIFF chunk.

    If you don't have this luxury or want to use a format that doesn't support this feature, then the next best way to synchronize a stream is by using custom sync points. This way you can add and remove your own points that wav markers would normally generate. See FSOUND_Stream_AddSyncPoint.
    Add your markers manually with this and set your sync point callback with FSOUND_Stream_SetSyncCallback
    Your callback could then look something like this but you can put what you like in the callback function.

    signed char endcallback(FSOUND_STREAM *stream, void *buff, int len, int param)
    {
      // end of stream callback doesn't have a 'buff' value, if it doesn't it could be a sync point.
      if (buff)
      {
        printf("\nSYNCPOINT : \"%s\"\n", buff);
      }

      return TRUE;
    }
    Remember FMOD is a real-time system and the amount of time spent in a callback has to be low, or you could cause buffer underrun or stuttering.
MODs
    To synchronize graphics with mod music, try these functions.
  • FMUSIC_SetZxxCallback
  • FMUSIC_SetRowCallback
  • FMUSIC_SetOrderCallback
  • FMUSIC_SetInstCallback
    This allows you to set callbacks on row, order, instrument or Zxx mod effect events.
    There is also a time based function FMUSIC_GetTime.


Custom Samples and Streams Tutorial - Firelight Technologies Pty, Ltd.

CUSTOM SAMPLES AND STREAMS

Introduction
    This answers some of the questions regarding how to create a custom/user stream, and a custom/user sample.
Custom Samples
    1. Declare and allocate a custom sample...
      FSOUND_SAMPLE *mysamp = FSOUND_Sample_Alloc(FSOUND_FREE, length, mode, deffreq, defvol, defpan, defpri);

      Remember 'length' is measured in *samples* not bytes, and mode is a bitfield using
      FSOUND_MODES (see the help for a description of modes to describe the sample you are allocating)
      This will create you an empty sample to upload data into.
    2. Upload your data to the sample.
      Use FSOUND_Sample_Lock()/FSOUND_Sample_Unlock() or FSOUND_Sample_Upload() to get your data into the sample.
      With FSOUND_Sample_Lock()/FSOUND_Sample_Unlock(), the data you copy in MUST be in signed format.
      FSOUND_Sample_Upload() is the favoured choice though, as you can describe the format, and it will convert it for you, but you have to pre-read the data into your own buffer first before passing it to FSOUND_Sample_Upload(), which temporarily uses more memory. This converts from all types of sources.. unsigned, delta samples, even IT compressed. more types will come in the future.
    3. Play it! :)
Custom Streams
    See FSOUND_Stream_Create. You can pass a callback function pointer and a length to this function. When you start the stream with FSOUND_Stream_Play (as you would with any other stream), you start getting callbacks.


DSP Engine - Firelight Technologies Pty, Ltd.

DSP ENGINE

Introduction
    This will briefly cover some of the essentials to using the FMOD DSP engine.
    The DSP engine allows you to read - and process the mixed sound data as it travels to the soundcard in its various phases. This will be described in more detail below.
    Why would you want to do this? It allows you to filter the data if you like. You could add your own reverb, distortion, EQ to the global FMOD sound stream or anything that you can think of that involves sound data.
    Another reason is to read it and maybe do analysis or even just plot it as an oscilloscope for effect!
What is it?
    The DSP system drives FMOD's software engine.
    Roughly every 25 milliseconds (platform dependant), FMOD mixes a batch of data to be send to the sound device.
    To do this it executes a chain of algorithms to produce the sound. This chain is executed every time and performs the various jobs such as mixing, clipping and calling user callbacks to process the sound data.
    At the low level, it is simply a linked list of callbacks. Each time one of these callbacks is called it is passed in the mixer buffer. You can see the callback of a DSP unit described here as FSOUND_DSPCALLBACK.

    Internally, FMOD uses these DSP callbacks to perform various stages of its own mixing routines. It is always working with the mixbuffer. This is simply a stereo buffer of integers or floats (depending on the mixer type set with FSOUND_SetOutput or determined with FSOUND_GetOutput. It is just long enough to mix 25ms worth of data, so you could probably calculate how many samples it would contain based on the sample rate, and 25ms, but there is a function supplied to work this out for you FSOUND_DSP_GetBufferLength

The "System" DSP Units
    The diagram above shows the system DSP units that are always present.
  • Clear Unit - All this DSP unit does is silence the mix buffer by setting it all to 0's. The next DSP units will generally fill in this data with audio by adding/accumulating to it (mixing). You can get a handle to this unit simply by calling FSOUND_DSP_GetClearUnit
  • Mix SFX Unit - This unit calls FMOD's internal optimized mixing routines and mixes any sound effects spawned by the user with FSOUND_PlaySound or FSOUND_PlaySoundEx. You can get a handle to this unit simply by calling FSOUND_DSP_GetSFXUnit
  • Mix Music Unit - This unit executes the FMUSIC music sequencing engine, and mixes the resulting channels used by the FMUSIC engine. You can get a handle to this unit simply by calling FSOUND_DSP_GetMusicUnit
  • FFT Unit - This unit performs an FFT on the mixed output so that FSOUND_DSP_GetSpectrum can be used. It is turned off by default due to the CPU expense incurred, so if you want to use the FSOUND_DSP_GetSpectrum function this needs to be turned on with FSOUND_DSP_SetActive first. You can get a handle to this unit simply by calling FSOUND_DSP_GetFFTUnit
  • Clip and Copy Unit - This is the final system unit in the FSOUND chain. You can get a handle to this unit simply by calling FSOUND_DSP_GetClipAndCopyUnit

    The system units can be disabled, enabled and shifted around in this list! You could even throw out the FSOUND software engine all together and replace it with your own!
Priorities
    Notice how in the diagram above each DSP unit had a 'priority'. This is simply a numeric value determining its order in the DSP chain. The lower the priority the earlier it gets executed. Notice how the Clear Unit has a priority of 0, as it wants to be the very first unit executed.
    This is because it wouldn't make much sense to do anything before it, as the Clear Unit will just wipe it out with zero's anyway!
    You may disagree with this, well ok! (you may want to execute some non buffer altering logic like a timer that calls PlaySound every now and then for example), so you can simply move it with FSOUND_DSP_SetPriority.
Now its your turn
    You may be thinking, well this sounds like a good place if I wanted to create my own effects such as reverb or a low pass filter for example, or maybe you just want to read the data that comes in so you can graphically plot it! Well you're right this is the place to do it.
    Just call FSOUND_DSP_Create, and give it a callback, and a priority. Set it active with FSOUND_DSP_SetActive and immediately your DSP unit will be ticking.
    Now the data passed in will be either 16bit stereo integer (-32768 to +32767) or 32bit stereo floating point (-32768.0f to +32767.0f, not 0 to 1). This can be determined by what mixer is being used at the time, with FSOUND_GetMixer. It's up to you now what you do with this data. One important thing to note is that FMOD mixes the data ahead of time, and the data you are processing is not the data that is immediately audible. If you are thinking of plotting the data to sync with the audible output, it is wise to buffer the data in a circular buffer, for the number of samples specified by FSOUND_DSP_GetBufferLengthTotal. This length is divisible by the DSP callback length (always a multiple of 25ms).
    From this point then you would plot the block of data preceding the one you are filling, which is the one playing at that point in time!
    See the FMOD example in the /samples/fmod directory for source code that does this, and many other examples of DSP processing.
FSOUND_PlaySoundEx and the 'FSOUND_DSPUNIT *dsp' parameter
    The 'dsp' parameter in this new PlaySound command, allows you to assign or 'group' a channel to a specific DSP unit. The dsp unit you assign has to be a new one and not an existing system unit, with no callback.
    A DSP unit with sound effects attached to it does nothing but execute channel mixing, as it replaces the DSP callback with its own internal mixer callback.
    One reason for doing this is having a wet/dry mix for an effect. This is demonstrated in the /samples/dsp directory. You may want to have some effects affected by reverb for example, but not others. This is part of the reason the Music Unit is separate from the SFX unit, as you likely don't want music affected by DSP effects but do want the in-game sound effects to be affected.


3D Sound Tutorial - Firelight Technologies Pty, Ltd.

SPECTRUM ANALYSIS

Introduction
    This short section reveals how easy it is to obtain the realtime spectrum graph for FMOD's DSP output as you hear it, for graphical display or even advanced signal processing!
Using it
    The spectrum analysis unit is an FMOD System DSP Unit. If you are unsure of the FMOD DSP system then see the DSP tutorial.
    By default it is turned off because it can consume a reasonable amount of cpu time and it doesn't want to be doing Fast Fourier Transform code when the spectrum isn't even being queried!
    To turn it on is quite simple. Just call.

    FSOUND_DSP_SetActive(FSOUND_DSP_GetFFTUnit, TRUE);

    To turn it off again is just as simple. Just call.

    FSOUND_DSP_SetActive(FSOUND_DSP_GetFFTUnit(), FALSE);

    When your audio is playing, this DSP unit will every 25ms, or the rate of the DSP engine, update a snapshot of the current audible spectrum.

    The range for this FFT produces a spectrum array between 1hz and Nyquist, or in other words, 1hz and the sample rate given to FSOUND_Init divided by 2.
    If you had a 44khz output it would produce results up to 22khz.

    To get the spectrum, use FSOUND_DSP_GetSpectrum. As the documentation for this function says, it returns a pointer to an array of 512 floating point values between 0.0 and 1.0.
    Simply plot these values, scaling the 0 to 1 value to the height of your spectrum display, or process them for things like beat detection etc. Values above 11khz (when initialized with 44khz) become very small and are some times graphically not very interesting. The FMOD media player only plots the first 256 entries because of this. It is up to you how you interpret the data.
    If you want a different size window beside 512 then simply interpolate, disregard or skip entries and average them to your desired range. Different window sizes for the current FFT are not planned for future releases of FMOD.

    NOTE: You can change the position of the system FFT DSP unit. It is currently positioned last in the chain of DSP units by default so that the spectrum results in feedback from everything played through the FMOD software engine. See FSOUND_DSP_PRIORITIES for the relative system DSP unit priorities. You could move it to before the music unit and after the SFX unit for example, which would exclude mods from having its input into the spectrum graph. It would be achieved like this
    FSOUND_DSP_SetPriority(FSOUND_DSP_GetFFTUnit(), 150);
What happens if I want to get a Spectrum but use FSOUND_FX? Aren't the 2 incompatible?.
    It is possible but with some limitations, See this section for more information


DX8 FSOUND_FX Tutorial - Firelight Technologies Pty, Ltd.

FSOUND FX API

Introduction
    The FSOUND_FX api allows you to do special effects processing per channel through Direct X 8 only.
    You can do such effects as chorus, compression, distortion, echo, flange, gargle, reverb, and EQ through a simple API.
Limitations
    Before using the FSOUND_FX api, there are a few limitations that must be known about because of the DirectX API.

  • FX enabled samples can only be played once at a time, not multiple times at once.
  • Samples or streams have to be created with FSOUND_HW2D or FSOUND_HW3D, and FSOUND_ENABLEFX for this to work.
  • If you are using DirectX 8, FSOUND_SetFrequency will not work any more for that sound, you cannot change the pitch of a FX enabled sound. This is a DirectX limitation. Direct X 9 does not have this limitation.
  • FSOUND_FX_Enable cannot be called if the sound is playing or locked.
  • If FSOUND_FX_Disable is not called effects will build up on top of each other every time FSOUND_FX_Enable is called.
    Once these are taken into account, you can go for it!
Using it
    You have to use the pause feature of FSOUND_PlaySoundEx for this API to work.
    The reason for this is DirectX needs a channel resource in hardware to be allocated, and so actually PLAYED (but paused) before the FX functions can succeed.

    Once you have it played but paused, you can enable multiple effects on one channel, and even the same effect multiple times on the same channel, then unpause it to hear what happens, but at this point you cannot enable more effects. It has to be paused or restarted.
    You can update the parameters of effects while they are playing or while it is paused.

    Here is an example

      int channel, echoid, echoid2;
      channel = FSOUND_PlaySoundEx(FSOUND_FREE, samp2, DrySFXUnit, TRUE);

      echoid = FSOUND_FX_Enable(channel, FSOUND_FX_ECHO); // enable echo and get the first echo handle
      echoid2 = FSOUND_FX_Enable(channel, FSOUND_FX_ECHO); // enable echo again and get the second echo handle
      FSOUND_FX_Enable(channel, FSOUND_FX_FLANGER); // enable the flange effect, don't bother with the handle, we'll just use the default parameters<

      FSOUND_SetPaused(channel, FALSE); // now start the sound playing

      FSOUND_FX_SetEcho(echoid, 80.0f, 70.0f, 100.0f, 100.0f, TRUE); // Alter the parameters of the first echo for the channel it was enabled on. This handle is unique to this effect and this channel. The 2nd echo we enabled will be unaffected

    This process must be repeated as when a sound is restarted, all FX information is reset, so effects must be enabled each time.
FX on the 'output' channel.
    This is a special feature which allows you to enable effects on the output result of the software mixed channels!
    If you specify FSOUND_INIT_ENABLESYSTEMCHANNELFXX in the flags field of FSOUND_Init.
    The channel ID to use for altering the output result is FSOUND_SYSTEMCHANNEL. Call FSOUND_SetPaused on this to enable effects. This will stop all software mixed sound effects.
FSOUND_FX + Spectrum and DSP?.
    To use the FSOUND_FX api to do fx on channels requires FSOUND_HW2D or FSOUND_HW3D (and FSOUND_ENABLEFX) flags to work.
    You may notice if you do this, you will lose the ability to do FSOUND_DSP_GetSpectrum or any DSP unit will not register, because FSOUND_FX channels play in hardware, and don't run through the FMOD DSP Engine.

    There is a way to do this though. Instead of performing EQ on a channel by channel basis, perform it on the global software mix output.

    This means you can't have per channel control, but if you are just looking for a way to do EQ on your audio for example, then use the following method.

  • Call FSOUND_SetBufferSize(100); When you call FSOUND_Init with FSOUND_INIT_ENABLESYSTEMCHANNELFX (see step 2) you will need a big enough software engine buffer to allow FX to be processed. FMOD defaults to 50 which is too small. This is a limitation of DirectSound and needs to be taken care of.
  • Use FSOUND_INIT_ENABLESYSTEMCHANNELFXin FSOUND_Init. This will ready the software engine output to have the FX api used on it.
  • Pause the software engine. You always need to pause the source when using FSOUND_FX_Enable (see step 3), so call FSOUND_SetPaused(FSOUND_SYSTEMCHANNEL, TRUE);
  • Call FSOUND_FX_Enable to create all your FX handles (EQ, distortion whatever).
  • Unpause the software engine. FSOUND_SetPaused(FSOUND_SYSTEMCHANNEL, FALSE);
  • Now you are ready! Create streams and sounds in software mode (FSOUND_NORMAL - don't use FSOUND_HW2D or FSOUND_HW3D)

    Now that all your sounds and streams are in software, you get spectrum analysis back, and also you can use the DSP engine for your own software processing or oscilliscope plotting - with the added benefit of FSOUND_FX processing!


The FSB Format - Firelight Technologies Pty, Ltd.

THE FSB FORMAT, BANKS, STREAMS AND SENTENCING

Introduction
    FMOD Introduces a new format called .FSB, or the FMOD Sample Bank format.
    This format is generated by the supplied tool. FSBank (fsbank.exe). It is mainly recommended for console formats, but can be used on any platform.
    It is especially recommended for PlayStation 2, XBox and GameCube as it is a more optimal method of loading sound data into sound ram rather than using individual sound files which is slow and inefficient when coming off CD.
Compiling the FSB file
    Creating an FSB file (or multiple fsb files!) is easy. Just open the tool called fsbank.exe provided in the tools directory. Currently this is only provided as a win32 application.
    You will find an interface looking something like this.

    FSBank is very easy to use.
    You have to first decide what type of FSB file output you want to generate. The most common is a single .FSB file containing multiple sounds. This is the default and accessible by choosing 'Generate Single FSB File' from the pull-down 'Build' menu as shown in the diagram.

    Single FSB file
    You simply take a directory of any sound files, and specify as the 'Source Directory' field. Then tell the compiler where to build the file to by choosing a 'Destination File'. Now choose a platform to build to ('Choose Target' field at the bottom of the screen), and hit the big 'Build' button.
    This generates a single .FSB file, and on top of this it also gives you a C header file to include into your program to allow indexed access to the sound data within the FSB file.

    Multiple FSB files
    This is similar to before, but now you can generate multiple fsb files instead of 1 file. This is only useful for generating multiple .FSB files to be used for streaming (Think of it as a batch build for individual streams). Note that you can use a single FSB file as described above for streaming, but it is limited during playback to only one of the sounds in the bank at a time.
    You simply take a directory of any sound files, and specify as the 'Source Directory' field. Then tell the compiler where to build the file to by choosing a 'Destination Directory'. Now choose a the platform to build too ('Choose Target' field at the bottom of the screen), and hit the big 'Build' button.
    This generates multiple .FSB files, one for each source file, and on top of this it also gives you a C header file for each output file.

    Single Interleaved FSB File
    This mode allows multiple sound files to be interleaved into 1 stream. It only generates 1 FSB entry, but as mono has 1 channel, stereo has 2 channels, these files can have up to 16 channels of interleaved audio. The data is multiplexed in units suitable to the hardware (ie PlayStation 2 will interleave data every 16 bytes, 36 bytes on XBox
    Why is this useful? Well with this feature, you could get 16 channels of playback with no seeking. If you loaded and played 16 streams individually you would notice a LOT of seeking which is inneficient, and causes stuttering or the need for huge buffersizes, using up lots of RAM. Using interleaved streams will remove seeking, and reduce stream buffersizes.
    Why would you want to have 16 tracks of sound going at once? Well this is up to the user, but the main benefits for this are
    • Interactive music.
      Because these streams are interleaved, it also means they are perfectly synchronized. You can have multiple layers of soundtrack interleaved, and for the duration of the song, the majority of the channels can be set to volume 0, so they are muted. When an event or situation arises in the game you can fade up and down different tracks to bring in a new drumbeat or overlay for example, adding mood.
    • Multichannel ambience.
      This would be purely beneficial for the technical side of streaming, reducing the amount of seeking and memory needed to play multiple individual streams. You can have many tracks of huge ambience data streaming at once, and 3d position each subchannel if you like, so stream data comes in and out depending on location in the game world for example.
    Note: These interleaved files can also be statically loaded using the FMUSIC api, and played back as 'samples' as well as streams, as long as you have enough sound ram.

    PlayStation 2
    Streams benefit immensely from FSB compiling on PlayStation 2. As .VAG (the native ps2 format) does not support stereo data natively, .FSB overcomes this by interleaving stereo vag blocks into each other, then deinterleaving it at runtime when streaming.
    This has a benefit of not having to play 2 mono streams at once (panning one left and one right), like you might have to with other playback systems.
Accessing FSB files from within your program
    Loading an .FSB file as a static sound bank into sound ram
    To do this, you use the FMUSIC_LoadSong or FMUSIC_LoadSongEx, and FMUSIC_GetSample functions. Because these functions already existed in the FMOD api for mod,s3m,xm,it,midi it seemed appropriate to use this API for FSB files, even though they are strictly not 'songs'.
    The C header generated by the FSBank tool contains #defines or indices to reference each individual sound from your code, using FMUSIC_GetSample.
    You can simply call FSOUND_PlaySound on each of these sample handles you retrieve through the FMUSIC api and manipulate them as you would with normal samples.

    Use FMUSIC_GetNumSamples to determine the number of samples in the FSB format.

    You can modify the way all sounds are loaded by using the mode parameter of the FMUSIC_LoadSongEx function. For example if you want to make all sounds hardware 3d you just specify the FSOUND_HW3D flag. You could also make them all 2d, or maybe make them all loop with FSOUND_LOOP_NORMAL.

    Opening a multisound FSB file as a stream
    This is the same as opening any other stream. Use FSOUND_Stream_Open.
    To access the subsounds within the bank is different than with samples. Because it is a stream, you can only seek from one subsound to another. This is achieved with FSOUND_Stream_SetSubStream. Because this is a seeking action, it will stop the currently playing stream, and perform the seek to the new sound. You will have to call FSOUND_Stream_Play to get it to start playing again.
Stream stitching, or sentencing
    When playing an FSB file as a stream, did you know you can stitch them together at runtime using FMOD's sentencing engine. This allows for absolutely gapless, efficient stitching of sounds, with no need for slow stopping or starting new streams, and the order of playback is determined at run time.
    This is great for voice overs, where you can string together a bunch of sounds to make a single coherent sentence.

    How is this done in code?
    That is easy. You just call FSOUND_Stream_SetSubStreamSentence before you call FSOUND_Stream_Play or FSOUND_Stream_PlayEx.
    ie, say you have a bank with multiple sounds in it, with sound snippets like "Brett", "Andrew", "Scored", "Missed", "One Point", "Two Points!", "Three Points!"

    int list[3] = { SOUND_BRETT, SOUND_SCORED, SOUND_THREEPOINTS };
    FSOUND_Stream_SetSubStreamSentence(stream, list, 3);
    FSOUND_Stream_Play(FSOUND_FREE, stream);

    This would result in a very smooth "Brett scored three points!".
Did you know?
    If you have loaded your FSB file as a static sample bank, you can call FMUSIC_PlaySong to listen to the contents of the file? It will play each subsound one by one, which is great for previews.


TroubleShooting - Firelight Technologies Pty, Ltd.

TROUBLESHOOTING

Introduction
    This will cover some of the most common problems people come across when using FMOD. Remember if you have any problems just send a mail to support@fmod.org
FSOUND_Init fails on CE devices
    This sometimes happens if the sound device is already busy, and the sound hardware will not release itself to FMOD until it finishes playing a sound.
    This can happen when activesync starts up and plays the connection noise just as FMOD is trying to initialize.
    To remedy this just initialize fmod in a loop until it succeeds, sleeping every 10 or 100ms or however long you prefer.
    It is a good idea to timeout if it never succeeds then resolve the issue through checking the error code or stopping the program that is stealing the resource.
    ie.

    int retrycount = 0;
    while (!FSOUND_Init(22050, 32, FSOUND_INIT_GLOBALFOCUS) && retrycount < 10)
    {
      Sleep(100);
      retrycount++;
    }

    if (retrycount == 10)
    {
      /* Print error */
    }
    In this example it will keep retrying for about 1 second until it exits and prints an error message.
Stuttering/Skipping sound
    More commonly known as buffer underrun/overrun, this can be 1 or a combination of factors

    Bad soundcard drivers
    This may be solved by upgrading your soundcard drivers. (Note it is recommended you get the latest drivers anyway)

    CPU issues
    Machine to slow, or whatever your are trying to do with FMOD is too cpu intensive! (ie playing 100 mp3's at once will most likely bring FMOD to its knees, or maybe a user stream callback or DSP callback is spending too much time executing).

    Mixer buffersize is set too small
    You can increase stability to combat these issues, by increasing FMOD's internal mixing buffer size. This will lead to greater stability but also larger latency on issuing commands to hearing the result.
    Call FSOUND_SetBufferSize to alter this value (in milliseconds). It must only be called before calling FSOUND_Init, it will fail otherwise.
    Please don't set this value to huge numbers like 2000 or 10000. It won't help increase stability and will consume larger amounts of CPU time and RAM.
    First try a value of 100, then 150, then 200, and no more.

    Stream buffersize is set too small
    If you are using the stream API, you might be streaming off a slow media, such as CDROM or over network, or even a fragmented harddisk, and fmod needs more time to fill its streaming backbuffer.
    For streaming buffers, fmod defaults to a 400ms stream buffersize. This is seperate to the mixer buffersize described above and not related.
    Changing this value does not alter latency. Streams are pre-buffered and always start instantly no matter what the buffersize.
    Call FSOUND_Stream_SetBufferSize to alter this value (in milliseconds). It must only be before opening a stream to take effect.
    Setting this value to large values will cause larger cpu spikes (if a compressed format) and more memory usage.
    Values around 1000 to 2000 max are recommended. Larger values are not.

    Video Card Drivers
    Yes video card drivers can affect sound output.
    Always make sure you have the latest 3d/videocard drivers, and that your users are aware of this as well.
    It has been noted that a bad VIDEO card driver can cause break ups and instability in sound output, as they are badly written and cause the bus to be taken over by the video card, not letting any sound data to be transferred to the soundcard.
    This has been noted on S3 Virge and Voodoo 1 drivers so far, so always remember first to have the LATEST video driver, and make sure you note this in your documentation as well upon distribution.

    Frame-rate is too high!
    Yes this can also affect the sound output, for the same reasons as described above. Excessive calls of the video driver can force the sound driver to not be serviced. It has been found that introducing a frame-rate limiter will solve this problem.

    Output type
    FSOUND_OUTPUT_DSOUND will provide more solid output than FSOUND_OUTPUT_WINMM in anything except NT.
    This is a problem with Windows Multimedia Services not being as realtime as it should be.
    Under NT FSOUND_OUTPUT_WINMM is more stable, as DirectSound in NT is just emulated by using WINMM itself and is actually slower and has longer latency!.
    NOTE: Please don't feel the need to use FSOUND_SetOutput if you don't need to. FMOD autodetects the best output mode based on the operating system.


FSOUND_NONBLOCKING - Firelight Technologies Pty, Ltd.

USING THE FSOUND_NONBLOCKING FLAG

Introduction
    The FSOUND_NONBLOCKING flag stops certain stream or music commands blocking the caller when being executed, by performing them in a seperate thread.
    Mainly meant for opening streams and music, to avoid the slowness of disk access generating huge pauses, this flag makes these commands return immediately without affecting the frame-rate at all!
    The flag must be specified in FSOUND_Stream_Open or FMUSIC_LoadSongEx using the mode parameter for it to work. You cannot use SetMode type functions to make it work, it must be called at the time of opening.

    This raises new issues though. You cannot just access a stream or music file that has been opened with the FSOUND_NONBLOCKING flag immediately! You have to wait for it to open!
    FMOD does not 'queue' commands to non blocking streams/musics. This could lead to mis-use and overflows, or even confusion about the state of the stream behaviour at the time, so a polling method is preferred so that the user can control exactly what occurs in what order.
Polling for success
    The key to working with nonblocking streams and music files is to wait for them to open before playing them. One method to do this is to poll the state of a stream using FSOUND_Stream_GetOpenState or FMUSIC_GetOpenState.
    Another method is to try and play the stream or access the subsounds continuously in a game loop until it succeeds.

    While a non blocking stream is opening, nearly all functions will return an error code to signify that the stream is not ready.
    This means something like FSOUND_Stream_Play will return -1 while it is trying to open the file in the background.
    When it returns a valid channel handle, you know it is ready and has succeeded!

    An example for playing a non blocking stream is provided below. This is a typical loop that should be used when trying to play a non blocking stream. You will notice, once it succeeds, it won't try and play again because channel is not -1 anymore.

    FSOUND_STREAM *stream;
    int channel = -1;

    stream = FSOUND_Stream_Open("mystream.fsb", FSOUND_NONBLOCKING, 0, 0);

    do
    {
      if (channel < 0)
      {
        channel = FSOUND_Stream_Play(FSOUND_FREE, stream);
      }

      GameCode();

    } while (1)
    Alternatively you could use the FSOUND_Stream_GetOpenState method. This is shown below.

    FSOUND_STREAM *stream;
    int channel = -1;

    stream = FSOUND_Stream_Open("mystream.fsb", FSOUND_NONBLOCKING, 0, 0);

    do
    {
      if (channel < 0 && FSOUND_Stream_GetOpenState(stream) < 0)
      {
        channel = FSOUND_Stream_Play(FSOUND_FREE, stream);
      }

      GameCode();

    } while (1)
    It is basically the same thing and slightly redundant.
FSB format, substreams and sentences.
    Setting SubStreams
     FSB has multiple sounds packed within it, so you might want to use FSOUND_Stream_SetSubStream
    You don't need to poll to get FSOUND_Stream_SetSubStream to work. It has been optimized so that it will immediately seek to the correct substream once the open has finished. This is a special case for this function, and no other functions allow this.
    This means you can call it straight away, even after a non blocking stream open.
    Here is a version of the above loop, that sets a substream.

    FSOUND_STREAM *stream;
    int channel = -1;

    stream = FSOUND_Stream_Open("mystream.fsb", FSOUND_NONBLOCKING, 0, 0);
    FSOUND_Stream_SetSubStream(stream, SOUND_4);

    do
    {
      if (channel < 0)
      {
        channel = FSOUND_Stream_Play(FSOUND_FREE, stream);
      }

      GameCode();

    } while (1)
    Note that once you call FSOUND_Stream_SetSubStream, the stream is 'not ready' again. This may not seem to be relevant if you call it after FSOUND_Stream_Open, because we already knew it was not going to be ready, but if you call it when the stream has actually finished opening and is ready (for example, you may want to set the substream long after the stream has opened, ie 30 seconds later), then you will need to remember this, but the above logic always takes care of it. You just need to set channel to -1 in the above example whenever you call FSOUND_Stream_SetSubStream and it will work.

    Setting SubStream Sentences
     Setting a sub-stream-sentence is next , and is slightly trickier. FSOUND_Stream_SetSubStreamSentence does not succeed immediately like FSOUND_Stream_SetSubStream, and will actually fail if the open is still in progress, so you cannot call it straight after FSOUND_Stream_Open like we did in the previous example.
    What you have to do is poll for the stream to be in a ready state, then execute FSOUND_Stream_SetSubStreamSentence. Alternatively you can continually call FSOUND_Stream_SetSubStreamSentence until it succeeds, a bit like we did with the call to FSOUND_Stream_Play in the previous example.
    Note the following code

    FSOUND_STREAM *stream;
    int channel = -1;
    int setsentence = 0;

    stream = FSOUND_Stream_Open("mystream.fsb", FSOUND_NONBLOCKING, 0, 0);

    do
    {
      if (!setsentence)
      {
        int sentence[2] = { SOUND_4, SOUND_5 };

        setsentence = FSOUND_Stream_SetSubStreamSentence(stream, sentence, 2);
      }
      else if (channel < 0)
      {
        channel = FSOUND_Stream_Play(FSOUND_FREE, stream);
        if (channel != -1)
        {
          FSOUND_Stream_SetMode(stream, FSOUND_LOOP_NORMAL); // This is just here as an example.
        }
      }

      GameCode();

    } while (1)

    Remember at all times, you can use FSOUND_Stream_GetOpenState just as effectively as continuously polling the command you want to succeed. It is just slightly less code using the above method.

Things to look out for

    If you suspect a file has not opened, or failed to open, poll FSOUND_Stream_GetOpenState. This will return the state of the stream, and if it has failed, it will return -3.
    Note that even though the stream has failed to open, the stream handle is still valid when opening in non-blocking mode. You will need to close it.

    The point of FSOUND_NONBLOCKING is that it takes no cpu time away from the caller. This means it cannot check the validity of a file, as that would constitute disk access, which could block and cause frames to drop from the application.
    All disk access is done from the FMOD asynchronous loading thread, so if it fails, the user cannot get immediate feedback, they have to check the status seperately.
    Don't try and close a stream before it is ready! This will cause a memory leak, as FSOUND_Stream_Close will return FALSE because it is not ready.
    Check the documentation for each stream function to see if it will fail or not due to not being ready in a non blocking state.


Co-existing with movie players - Firelight Technologies Pty, Ltd.

FMOD AND MOVIE PLAYERS

Introduction
    This section describes how to have FMOD happily coexist with various movie playback systems available.
PlayStation 2
    The main causes on conflicts between other middleware that uses audio or the IOP, and FMOD are:

  • Conflict between the SPU2 DMA channels. There are 2 of these. DMA channel 0 and DMA channel 1. By default FMOD uses SPU2 DMA channel 0 for software mixing, and DMA core 1 for uploading sample data and for streaming to. This means DMA core 1 is used when FMUSIC_LoadSong / FMUSIC_LoadSongEx is being executed to load a PS2 FSB file, or streaming using FSOUND_Stream_Open / FSOUND_Stream_Play. To work around this issue see the following tips.
    • Turn off the FMOD software mixer. This will free up DMA Channel 0. Most of the time you are not going to need this. You can do this by using FSOUND_Init with software channels set to 0.
    • Swap FMOD's mixer/upload channel usage around. If the 3rd party software still uses DMA Channel 1 (the channel FMOD uses for bank uploads and streaming), you can either change your 3rd party software to use DMA Channel 0 instead of DMA Channel 1, or tell FMOD to swap its usage around by specifying FMOD_INIT_PS2_SWAPDMACORES. If you didn't turn the software mixer off, this would make FMOD use DMA Channel 0 for streams and sample bank uploads, and DMA Channel 1 for the software mixer.

  • Conflict on the SIFCMD ports. If your middleware or your own code is using the SIFCMD sony library to communicate with the IOP, then if you dont take care to share the SIFCMD buffers and ports with FMOD, messages will get lost and unexpected behaviour will occur in FMOD and your 3rd party software.
    • If you want to initialize your 3rd party software after FMOD. Use this information if the code has a way to set up its SIFCMD usage. Note that FMOD uses SIFCMD port 0 and 1, and has a buffer size of 16.
    • If you want to initialize your 3rd party software before FMOD. If FMOD is initialized first, call FSOUND_SetSifCommandInfo from fmodps2.h. Also load your FMOD.IRX or FMODSMALL.IRX with command line parameters to allow the IOP side to get the same information. For more detailed information on this see the comment above the function prototype in fmodps2.h.

  • SPU2 ram usage and SPU2 hardware voice usage. Because FMOD and the middleware might not know about each other, they might allocate memory or use SPU2 voices without any regard for the other.
    • Use FSOUND_SPU2_Alloc / FSOUND_SPU2_GetRawAddress / FSOUND_SPU2_Free. Use these functions to allocate SPU2 memory for your 3rd party application. This way it will use FMOD's memory manager.
    • Use FSOUND_SetReserved. If the 3rd party software uses SPU2 voices, you can mark the literal SPU2 voice index as not to be used within FMOD. If the 3rd party software used SPU2 voice 0 for example FMOD would use FSOUND_SetReserved(number_of_software_channels + 0, TRUE); Note that the software channels value is mentioned because raw channel indicies are 0 to (maxnumsoftwarechannels - 1) = software voices, and after this are hardware voices. If you have the software mixer turned off, then 0 would be SPU2 voice 0 and 47 would be SPU2 voice 47.

XBOX
    The main causes on conflicts between other middleware that uses audio on the XBox, and FMOD are:

  • "DSOUND: CMcpxAPU::AllocateVoices: Error: Not enough free hardware voices". By default FMOD assumes it is in total control of the audio, so it allocates every XBox audio voice. If another 3rd party software application tries to allocate a hardware voice it will fail.
    • Use FSOUND_SetMaxHardwareChannels. To get around this issue just call FSOUND_SetMaxHardwareChannels to reduce the count. XBox has around 192 HW2D voices so you could reduce this and still have plenty of voices free.

  • DSP Image incorrect. FMOD has an internal MCP DSP image that it loads. It is stripped down to save memory, (hundreds of kilobytes) by removing unnescessary features. This may conflict with other 3rd party software that relies on a standard DSP image such as Microsoft's dsstdfx.bin.
    • Use FSOUND_SpecifyEffectsImage. If the 3rd party middleware has a dsp image file that it relies on you can use FSOUND_SpecifyEffectsImage (found in fmodxbox.h) to make FMOD use that image.
    • Make the other software use FMOD's image. You can get a handle to FMOD's internal dsp image structure by calling FSOUND_GetEffectImageDesc (found in fmodxbox.h) if the 3rd party has such a facility to allow this sort of external image to be used.

  • Needs access to the XBox LPDIRECTSOUND handle. If the 3rd party software is initialized second, it may want to use the XBox LPDIRECTSOUND handle.
    • Use FSOUND_GetOutputHandle. If you need to get a handle to FMOD's internal DirectSound pointer, you can share it by calling FSOUND_GetOutputHandle and casting it to the appropriate pointer type.

Win32
    If you need to get a handle to FMOD's internal DirectSound pointer, you can share it by calling FSOUND_GetOutputHandle and casting it to the appropriate pointer type.
    This also goes for XBox and other platforms, and depends on th
Bink on PS2
    Here is a quick way to get FMOD PS2 and Bink to co-exist.

    Initialize FMOD first.

    FSOUND_Init(48000, 0, FSOUND_INIT_PS2_SWAPDMACORES);
    FSOUND_SetReserved(0,TRUE);

    Initialize Bink

    MovieBuffer = sceSifAllocIopHeap( RAD_IOPMemoryAmount( RAD_IOP_NEED_CORE1 ) );
    RAD_IOPMemoryAmount(RAD_IOP_NEED_CORE1) ));
    if ( !RAD_IOPStartUp( 1, 2, MovieBuffer, RAD_IOP_NEED_CORE1|RAD_IOP_NO_INIT_LIBSD ) )
    {
      sceSifFreeIopHeap(MovieBuffer);
      // error
    }
    RAD_IOPHardwareVolumes(1, 0x3fff, 0x3fff, 0x3fff, 0x3fff);
    BinkSoundUseRAD_IOP(1);


PlayStation 2 - Firelight Technologies Pty, Ltd.

PLAYSTATION 2 SPECIFIC ISSUES / FEATURES

Introduction
    This section describes how to get started with FMOD for PS2, and also some of the PS2 specific features available.
Getting Started
    This section describes what you will need to link, and what you need to call to get up and running for PS2 specifically.

    What to link and loading modules.

  • Link /api/lib/fmod.a into your project.
  • Put /api/fmod.irx into your modules directory. You have to load the IRX yourself using sceSifLoadModule. More about this follows.

    A simple PlayStation 2 application has to do the following to use FMOD.

    1.
      Load fmod.irx and sony's libsd.irx. This is done from host0 or cdrom0 or whatever file device you store your files on.
      Load libsd first, then fmod.

      eg.
        while (sceSifLoadModule(host0:modules/libsd.irx", 0, NULL) < 0)
        {
          printf("loading libsd.irx failed\n");
        }
        while (sceSifLoadModule("host0:modules/fmod.irx", 0, NULL) < 0)
        {
          printf("loading fmod.irx failed\n");
        }
      Note that the default position for libsd.irx is at /usr/local/sce/iop/modules/ but it may differ on your machine.

      What does each module do?
    • libsd.irx - This is a sony irx that contains the low level hardware routines needed by fmod.irx.
    • fmod.irx - This is the fmod library and contains the majority of the functionality.
    2.
      Remember to Initialize the IOP heap with sceSifInitIopHeap().
      This is to be called after the call to sceSifInitRpc(0) and before loading any modules.

      eg.
      sceSifInitRpc(0);
      sceSifInitIopHeap();
      WARNING! If you reboot the IOP you have to call the above again!!! Otherwise FMOD will fail to initialize.
    3.
      Call FSOUND_Init and proceed programming with the FMOD API as you would on any other platform.
      On PS2, you must call FSOUND_Update to get commands to issue.

      Mismatching fmod.a and fmod.irx versions are not tolerated.
      FMOD will fail to initialize if they are from different releases of FMOD.

    Release / Debug.

    fmod.irx and fmodD.irx have been supplied. fmodD.irx is debug, and slower, and prints out a log of FMOD progress, along with english explanations on errors if they occur.

    Stripped / Non stripped.

    You may notice there is also fmod_small.irx and fmodD_small.irx. These versions use less IOP ram than the full versions, but only because they have features removed.
    These features are removed in the _small versions.

    .MOD, .S3M, .XM, .IT, .WAV and .VAG support. Note for .VAG support, this is talking about the file format, so FSB "VAG" support still exists.

    Normal streaming (with FSB files), 3d sound and sample management remains.

    EE Thread Priority.

    Note that if the EE main thread priority is not changed from the default of 1, FMOD will change it to 32.
    No thread can start when the default priority is 1 so this is nescessary.
    FMOD uses 1 thread to receive messages from the IOP.
Formats supported - hardware / software
    FMOD PS2 supports .VAG and .WAV, although FSB is the highly recommended format, see the next section on FSB files for more information about this.
    .VAG is mixed in hardware and .WAV is mixed in software. .WAV mixing in software uses IOP processing time.
    At the moment, depending on quality settings, FMOD can only mix around 12-20 channels of PCM data at once.

    .MOD .S3M .XM and .IT music formats are supported, and are mixed in software.
    Again currently only mods with 12-20 channels or less are recommended due to the CPU strain on the 33mhz IOP processor.
    32 channel mods should be supported after more optimizations.

    Software mixing speed on the IOP.

    Using FSOUND_Mixer with one of the following controls the number of channels available in software. Remember hardware mixing is preferred so you may not have to encounter this issue.

    - FSOUND_MIXER_AUTODETECT (non interpolating stereo output - fast)
    - FSOUND_MIXER_QUALITY_AUTODETECT (high quality interpolating stereo output - slowest)
    - FSOUND_MIXER_MONO (non interpolating mono output - fastest)
    - FSOUND_MIXER_QUALITY_MONO (high quality interpolating mono output - slow)

    FSOUND_Init on the PS2 accepts 24000 or 48000. 24000 is lower quality but increases the possible channel count significantly.
    FMOD will not support other output rates! Do not try and use them! (erroneous rates just case the output rate to go to 48000)
The FSB format - The recommended format for samples and streams.
    Although .WAV and .VAG formats are supported, for loading speed, and streaming speed it is highly recommended to use .FSB files.
    FSB is hardware accelerated, WAV is not.

    These are compiled batches of native PlayStation 2 SPU2 sound data, arranged so when loaded, it is one read to load the headers first, then the raw vag data (which is continuous), which is streamed into SPU2 ram. This is the fastest way to load sound data.

Memory managment.
    IOP Memory.

    Upon calling FSOUND_Init, FMOD allocates ALL remaining memory on the IOP.
    This is so FMOD can store sounds in IOP ram if needed.
    If you want to limit FMOD's IOP memory usage, simply call FSOUND_SetMemorySystem.

    ie.
    FSOUND_SetMemorySystem(NULL, 128*1024, NULL, NULL, NULL);

    This will force FMOD to only use 128kb of IOP memory.
    Note that setting too low a value will cause FMOD to fail in its internal system memory allocations and FSOUND_Init could even fail.

    EE Memory.

    The EE memory footprint is minimal. There is no dynamic memory allocation on the EE.
    The EE library is simply a command layer wrapping all FMOD api functions, and uses nothing but static structures and memory to avoid malloc/free/new/delete issues on the EE side.
    It uses this library to pass commands to the IOP for processing on that CPU.

Reverb.
    You have access to the hardware PlayStation 2 SPU2 reverb through FMOD's FSOUND_Reverb_xxx API.
    Note that the SPU2 Reverb is a lot more primitive than I3DL2 reverb and EAX3.
    In the FSOUND_REVERB_PROPERTIES structure, only Environment, Room and Flags are supported.

    'Environment'
      This is a value between 0 and 9 mapping to the sony reverb modes.
      You will find 9 special presets for the PlayStation 2 with this environment value set accordingly.
      ie
      FSOUND_PRESET_PS2_ROOM
      FSOUND_PRESET_PS2_STUDIO_A
      FSOUND_PRESET_PS2_STUDIO_B
      FSOUND_PRESET_PS2_STUDIO_C
      FSOUND_PRESET_PS2_HALL
      FSOUND_PRESET_PS2_SPACE
      FSOUND_PRESET_PS2_ECHO
      FSOUND_PRESET_PS2_DELAY
      FSOUND_PRESET_PS2_PIPE
      The other presets will not work, except for FSOUND_PRESET_OFF.
    'Room'
      This still controls the amount of reverb mixed into the output.
      Normally it is in decibels, between -10000 (silent) and 0 (full volume), and it is the same range on the PlayStation 2, but it is a linear scale between -10000 and 0, not a logarithmic one.
    'Flags'
      This only utilizes the following fields on PlayStation 2.
      FSOUND_REVERB_FLAGS_CORE0 (hardware voices 0 to 23)
      FSOUND_REVERB_FLAGS_CORE1 (hardware voices 24 to 47)
      This tells the FMOD engine which core, or set of hardware voices to apply the reverb settings to.
      By default (in the presets) it is set to apply to both cores, but you can remove these flags to control each core seperately.

    Note that FSOUND_Reverb_SetChannelProperties is supported through the 'Room' parameter only,
    and that this value is binary, ie -10000 is 'reverb off' for the channel, and anything else is 'reverb on'.
FSOUND_SetDiskBusy
    This function is usually not optional and is essential for smooth running disk cooperation between fmod and the game.
    This function causes mutual exclusion for the cdrom or host0 so that you don't get read errors when trying to access the disk while fmod is playing a stream or accessing the disk in some manner (ie opening a bank or stream in FSOUND_NONBLOCKING mode)
    In your game code you would do something like this:

    FSOUND_SetDiskBusy(TRUE);
    sceRead(...);
    FSOUND_SetDiskBusy(FALSE);

    This will block on a semaphore in FSOUND_SetDiskBusy(TRUE) if fmod is using the disk, and if it enters and executes the sceRead/sceCdRead, fmod will not access the disk, and instead wait until it is available to use again.
    Note - if you set this for too long, audio streams may start to skip / stutter, because FMOD didnt get enough time to fill its audio buffer. Make sure you either split up your own reads into smaller chunks, or make a bigger buffersize for FMOD to use with FSOUND_Stream_SetBufferSize.
Dolby Prologic 2 output
    Use FSOUND_SetSpeakerMode(FSOUND_SPEAKERMODE_PROLOGIC2) or FSOUND_SetSpeakerMode(FSOUND_SPEAKERMODE_PROLOGIC2_INTERIOR) to enable 5.1 surround sound on ps2.
    The interior mode uses twice as many hardware voices (meaning you effectively only get 24 voices instead of 48), but allows sounds to smoothly move from left to right and vice versa, where the normal mode will 'jump' from one speaker to the other if running straight along the X axis.
    It is a tradeoff between voices and quality, if you need to, you should evaluate both methods to see which works better.
    Note on a stereo sound system, the interior 2 voice method will cause a phasing effect, which can sound odd or bad, it is really meant for a prologic 2 system.
Volume ramping
    Most games released on the ps2 (not using FMOD) make click and pop noises because the hardware doesn't support smooth volume or pan changes.
    FMOD has implemented an advanced ramping system that not many people know about or are too put off by the difficulty of the method.
    You can enable this as a flag in FSOUND_Init using the FSOUND_INIT_PS2_USEVOLUMERAMPING flag.
    Turning this on will reduce hardware clicks or remove them, producing clean sounding audio, giving you an advantage over your competitors!


XBox - Firelight Technologies Pty, Ltd.

XBOX SPECIFIC ISSUES / FEATURES

Introduction
    This section describes how to get started with FMOD for XBox, and also some of the XBox specific features available.
Getting Started
    This section describes what you will need to link, and what you need to call to get up and running for XBox specifically.

    FMOD comes with 2 libraries. One is release and one is debug. The main difference is that the debug version outputs debug information to the debug window of your debugger.
    This is useful for tracing what fmod is doing if something ever went wrong and you wanted to know where FMOD was at the time.

  • /api/lib/fmodxbox.lib - This is the library you will link to most of the time. Use this for shipping.
  • /api/lib/fmodxboxD.lib - This is debug version of FMOD. It is slower, and prints out a log of FMOD progress through the debug window, along with english explanations on errors if they occur.

Memory Management
    On FMOD XBox, you must call FSOUND_SetMemorySystem, and supply a pool of memory with a length.

    for example.

    #define AUDIO_MEMLENGTH (4*1024*1024)
    char *mem = malloc(AUDIO_MEMLENGTH);
    FSOUND_SetMemorySystem(mem, AUDIO_MEMLENGTH, NULL, NULL, NULL);
    then,

    FSOUND_Init(....);
     etc.

    The reasoning for this is for performance issues.
    FMOD must be able to access sample data within its own memory block to avoid a slowdown issue in DirectSound XBox.

    The memory provided must be enough to store all samples and extra system memory overhead for FMOD.

    You can call FSOUND_GetMemoryStats to determine what FMOD needs as a game runs.
    You could run FMOD and supply it with an unrealistically high memory pool (say 8 megabytes), and then call FSOUND_GetMemoryStats to determine the maximum amount of RAM fmod needs to store sounds and for FMOD system overhead.

    8mb Memory Limitation.

    Currently for hardware sound effects, there is an 8mb limit for sound effects.
    This is due to the XBox DirectSound architecture.

    From the XDK Documentation : "DirectSound buffers are managed in a scatter gather entry (SGE) list.
    There is a maximum of 2,047 SGEs, which each point to a 4-KB page.
    This means that a maximum of 8 MB are available for allocating or playing DirectSound buffers simultaneously"

    Future versions may have multiple 8mb pools if it is required by developers.

Special features for FMOD XBox
    FMOD is fully functional on the XBox, including wma, mp3 and ogg vorbis streaming support, and with some extra functionality to take advantage of the 5.1 Dolby Digital surround sound support.

    FSOUND_SetLevels. (See fmodxbox.h).
    This function allows you put position a sound in any of the 5.1 speaker array in dolby digital. This can be very useful, and you can even do cool things like 5.1 music with it. For example, use FSBank to produce a 6 channel, multichannel interleaved stream, then use FSOUND_GetSubChannel to position all 5 channels into their own speaker.
    ie

    channel = FSOUND_Stream_PlayEx(FSOUND_FREE, stream, 0, TRUE);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 0), 255, 0, 0, 0, 0, 0);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 1), 0, 255, 0, 0, 0, 0);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 2), 0, 0, 255, 0, 0, 0);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 3), 0, 0, 0, 255, 0, 0);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 4), 0, 0, 0, 0, 255, 0);
    FSOUND_SetLevels(FSOUND_GetSubChannel(channel, 5), 0, 0, 0, 0, 0, 255);
    FSOUND_SetPaused(channel, FALSE);

    A musician would have to product 6 wav files for each speaker in this case before it is interleaved with FSBank into one stream.

    Even if you dont go to this extent, you can do something simple like spatialize normal stereo music. Normally music is just played through the front 2 channels, so you can improve this with something like

    FSOUND_SetLevels(musicchannel, 255, 255, 255, 128, 128, 255);

    which puts it in all speakers and half volume in the rears.


GameCube - Firelight Technologies Pty, Ltd.

GAMECUBE SPECIFIC ISSUES / FEATURES

Introduction
    This section describes how to get started with FMOD for Gamecube
Compiling and linking
    Include fmod.h in your project, this is found in api/inc.

    To link FMOD to your project, there are the following files.
  • /api/lib/fmodgc.lib - Link to this file if you are using SN Systems compiler.
  • /api/lib/fmodgcD.lib - This is the debug version of fmodgc.lib and outputs a log of FMOD's progress and any error messages (in plain english) to the TTY.
  • /api/lib/fmodgc_cw.a - Link to this file if you are using the Metrowerks Codewarrior compiler.
  • /api/lib/fmodgc_cwD.a - This is the debug version of fmodgc_cw.lib and outputs a log of FMOD's progress and any error messages (in plain english) to the TTY.
Running the examples
    Simply load their .dsp files into Dev Studio and hit F7.

    NOTE: You will need to copy all files in the media directory to
      $DVDROOT/fmod. For example:

      copy media\*.* c:\DolphinSDK1.0\dvddata\fmod

Conversion tools
    dspadpcm.exe

    FMOD supports the Nintendo DSPADPCM format as output by the Nintendo tool "dspadpcm.exe". FMOD expects the file extension ".dsp" on these files.
    For clarity and consistency, FMOD refers to this format as FSOUND_GCADPCM.
    NOTE: dspadpcm.exe can only convert MONO samples!

    fsbank.exe

    This is a Windows app that creates .fsb files - FMOD's native sample bank format.
    Use it to create sample banks of either MONO or STEREO ADPCM samples suitable for playing or streaming using the GameCube ADPCM hardware.

Performance issues and Gamecube specific FMOD features.
    Hardware voice dropping

    Due to a design issue with the Gamecube hardware, the processor will drop hardware voices if it's DSP chip gets overloaded.
    Call FSOUND_Update each game cycle and FMOD will automatically reacquire voices that get dropped.
    FMOD's priority system has been linked into this, so it is likely to drop lower priority sounds that have their priority set with FSOUND_Sample_Defaults.

    Direct DVD streaming
    Use FMOD's stream API to play streams using the GameCube's DVD audio streaming capability.
    When opening a stream, simply specify a file with a .adp extension and FMOD will stream it using the GameCube's hardware straight from the DVD to the AI, completely bypassing both ARAM and MRAM.

    Gamecube extras

    Look in fmodgc.h for GameCube-specific functions relating to such things as DVD status callbacks, AUX effects, specifying a block of ARAM for FMOD to use and accessing IPL sound settings.


PlayStation Portable - Firelight Technologies Pty, Ltd.

PLAYSTATION PORTABLE SPECIFIC ISSUES / FEATURES

Introduction
    This section describes how to get started with FMOD for PSP, and also some of the PSP specific features available.
Getting Started
    This section describes what you will need to link, and what you need to call to get up and running for PSP specifically.

    What to link and loading modules.

    A simple PlayStation Portable application needs the following steps to be taken to use FMOD.

  • Link /api/lib/fmod.a into your project.

    FMOD requires the following sony libraries and modules to be used as well to get audio support. They are linked and loaded by the user.

  • Link library libsas.a into your project.
  • Link weak import stub library file libatrac3plus_stub_weak.a into your project.
  • Load module file sc_sascore.prx at runtime.

    If you require AT3 playback support, load the following sony run-time modules.

  • Load module file libatrac3plus.prx
  • Load module file libaudiocodec.prx

    Note that the default position for sc_sascore.prx and audiocodec.prx is at /usr/local/devkit/kmodule but it may differ on your machine.
    libatrac3plus.prx can be found normally at /usr/local/devkit/module.

    Loading the modules.

    For examples on how to load sony modules, see the FMOD examples.
    Load sony's sc_sascore.prx. If AT3 support is desired also load audiocodec.prx and libatrac3plus.prx. This is done from host0 or disc0 or whatever file device you store your files on.

    eg.
    /* load module */
    static SceUID load_module(const char *filename, SceKernelLMOption *lm_opt, SceKernelSMOption *sm_opt)
    {
      SceUID mid;
      int ret;

      /* load module */
      mid = sceKernelLoadModule((char *)filename, 0, lm_opt);
      if (mid < 0)
      {
        printf("fatal error : cannot load %s 0x%08x\n", filename, mid);
        return mid;
      }

      /* start module */
      if ((ret = sceKernelStartModule(mid, 0, NULL, NULL, sm_opt)) < 0)
      {
        printf("fatal error : cannot start %s 0x%08x\n", filename, ret);
        return ret;
      }

      return mid;
    }

    ...

    SceKernelLMOption kMode;
    SceUID sasMid;

    sasMid = 0;

    kMode.size = sizeof(kMode);
    kMode.mpidtext = SCE_KERNEL_PRIMARY_KERNEL_PARTITION;
    kMode.mpiddata = SCE_KERNEL_PRIMARY_KERNEL_PARTITION;
    kMode.position = SCE_KERNEL_LMWO_POS_Low;
    kMode.access = SCE_KERNEL_LMWO_ACCESS_Noseek;

    sasMid = load_module("host0:/usr/local/devkit/kmodule/sc_sascore.prx", &kMode, NULL);
    if(sasMid < 0)
    {
      printf ("fatal error : load SAS module\n");
      return -1;
    }

    Initialize FMOD.

    Call FSOUND_Init and proceed programming with the FMOD API as you would on any other platform.

    Release / Debug.

    fmod.a and fmodD.a have been supplied. fmodD is debug, and slower, and prints out a log of FMOD progress, along with english explanations on errors if they occur.

    Stripped / Non stripped.

    You may notice there is also fmod_small.a and fmodD_small.a. These versions use less ram than the full versions, but only because they have features removed.
    These features are removed in the _small versions.

    .MOD, .S3M, .XM, .IT, .WAV and .VAG support. Note for .VAG support, this is talking about the file format, so FSB "VAG" support still exists.

    Normal streaming (with FSB files), 3d sound and sample management remains.

Formats supported - hardware / software
    FMOD PSP supports .VAG and .WAV, although FSB is the highly recommended format, see the next section on FSB files for more information about this.
    .VAG is mixed in hardware and .WAV is mixed in software. .WAV mixing in software uses processing time.
    At the moment, depending on quality settings, FMOD can only mix around 12-20 channels of PCM data at once.

    .MOD .S3M .XM and .IT music formats are supported, and are mixed in software.

    Software mixing speed.

    Using FSOUND_Mixer with one of the following controls the number of channels available in software. Remember hardware mixing is preferred so you may not have to encounter this issue.

    - FSOUND_MIXER_AUTODETECT (non interpolating stereo output - fast)
    - FSOUND_MIXER_QUALITY_AUTODETECT (high quality interpolating stereo output - slowest)
    - FSOUND_MIXER_MONO (non interpolating mono output - fastest)
    - FSOUND_MIXER_QUALITY_MONO (high quality interpolating mono output - slow)

    FSOUND_Init on the PSP accepts 24000 or 48000. 24000 is lower quality but increases the possible channel count significantly.
    FMOD will not support other output rates! Do not try and use them! (erroneous rates just case the output rate to go to 48000)
The FSB format - The recommended format for samples and streams.
    Although .WAV and .VAG formats are supported, for loading speed, and streaming speed it is highly recommended to use .FSB files.
    FSB is hardware accelerated, WAV is not.

    These are compiled batches of native PlayStation Portable sound data, arranged so when loaded, it is one read to load the headers first, then the raw vag data (which is continuous), which is streamed into RAM. This is the fastest way to load sound data from UMD.

Memory managment.
    If so desired, the user can limit fmod's RAM usage to a single block of pre-allocated memory.
    If you want to limit FMOD's memory usage in this way, simply call FSOUND_SetMemorySystem.

    ie.
    FSOUND_SetMemorySystem(NULL, 128*1024, NULL, NULL, NULL);

    This will force FMOD to only use 128kb of IOP memory.
    Note that setting too low a value will cause FMOD to fail in its internal system memory allocations and FSOUND_Init could even fail.

Streaming ATRAC music
    FMOD supports the playback of .at3 files. All the user has to do is play it from disc0, or if they like, they can load the file into memory, then use FSOUND_OPENMEMORY to stream the file from memory.

    Note that the user can use FSOUND_Stream_SetBufferSize to adjust the amount of memory FMOD uses when streaming a file, and if it is from memory, then it will require only a very small stream buffer.
    If streaming from UMD, the buffer size need to be a lot larger. It should be the number of milliseconds between each read, which could be anywhere up to 5000ms.
Battery considerations
    Note, that even though FMOD supports streaming multiple streams from UMD at once, this is not recommended. On the PlayStation Portable seeking should be avoided at all times to preserve movement of the umd read head and therefore battery life.
    This also goes for data streaming. Do not stream data and music at the same time if there is seeking involved. Continuous seeking will degrade battery life because it has to mechanically move the seek head.

    It may be preferable to play 'in memory' music such as sequenced formats like .MOD/.S3M/.XM or .IT. Another idea is to load an AT3 file into memory first, then stream the file from memory as has been mentioned previously in this documentation. As atrac can store a minute of audio per mb at 128kbs stereo, then you would need 3mb of memory for 3 minutes of music.
The "15-20% cpu problem"
    Some users may notice a framerate impact when implementing audio. This is a known issue with Sony, and it is common knowledge among PSP developers that simply playing one sound in 'hardware' will cause up to 15-20% of the PSP's CPU to be used by audio.

    The problem lies in Sony's libwave, and there is nothing that can be done about it from FMOD's side until the issue is resolved with sony. FMOD offers a software mixer that can bypass Sony's VAG routines, but it will still require libwave access which is the problem.


FSOUND API Reference

FSOUND Api. Use this to play sounds, streams, cd's etc

Functions , Structures , Defines , Enums

+ Functions

- Functions

FSOUND_3D_GetAttributes
FSOUND_3D_GetMinMaxDistance
FSOUND_3D_Listener_GetAttributes
FSOUND_3D_Listener_SetAttributes
FSOUND_3D_Listener_SetCurrent
FSOUND_3D_SetAttributes
FSOUND_3D_SetDistanceFactor
FSOUND_3D_SetDopplerFactor
FSOUND_3D_SetMinMaxDistance
FSOUND_3D_SetRolloffFactor
FSOUND_ALLOCCALLBACK
FSOUND_CD_GetNumTracks
FSOUND_CD_GetPaused
FSOUND_CD_GetTrack
FSOUND_CD_GetTrackLength
FSOUND_CD_GetTrackTime
FSOUND_CD_GetVolume
FSOUND_CD_OpenTray
FSOUND_CD_Play
FSOUND_CD_SetPaused
FSOUND_CD_SetPlayMode
FSOUND_CD_SetTrackTime
FSOUND_CD_SetVolume
FSOUND_CD_Stop
FSOUND_Close
FSOUND_CLOSECALLBACK
FSOUND_DSP_ClearMixBuffer
FSOUND_DSP_Create
FSOUND_DSP_Free
FSOUND_DSP_GetActive
FSOUND_DSP_GetBufferLength
FSOUND_DSP_GetBufferLengthTotal
FSOUND_DSP_GetClearUnit
FSOUND_DSP_GetClipAndCopyUnit
FSOUND_DSP_GetFFTUnit
FSOUND_DSP_GetMusicUnit
FSOUND_DSP_GetPriority
FSOUND_DSP_GetSFXUnit
FSOUND_DSP_GetSpectrum
FSOUND_DSP_MixBuffers
FSOUND_DSP_SetActive
FSOUND_DSP_SetPriority
FSOUND_DSPCALLBACK
FSOUND_File_SetCallbacks
FSOUND_FREECALLBACK
FSOUND_FX_Disable
FSOUND_FX_Enable
FSOUND_FX_SetChorus
FSOUND_FX_SetCompressor
FSOUND_FX_SetDistortion
FSOUND_FX_SetEcho
FSOUND_FX_SetFlanger
FSOUND_FX_SetGargle
FSOUND_FX_SetI3DL2Reverb
FSOUND_FX_SetParamEQ
FSOUND_FX_SetWavesReverb
FSOUND_GetAmplitude
FSOUND_GetChannelsPlaying
FSOUND_GetCPUUsage
FSOUND_GetCurrentLevels
FSOUND_GetCurrentPosition
FSOUND_GetCurrentSample
FSOUND_GetDriver
FSOUND_GetDriverCaps
FSOUND_GetDriverName
FSOUND_GetError
FSOUND_GetFreeHWRam
FSOUND_GetFrequency
FSOUND_GetLoopMode
FSOUND_GetMaxChannels
FSOUND_GetMaxSamples
FSOUND_GetMemoryStats
FSOUND_GetMixer
FSOUND_GetMute
FSOUND_GetNumDrivers
FSOUND_GetNumHWChannels
FSOUND_GetNumSubChannels
FSOUND_GetOutput
FSOUND_GetOutputHandle
FSOUND_GetOutputRate
FSOUND_GetPan
FSOUND_GetPaused
FSOUND_GetPriority
FSOUND_GetReserved
FSOUND_GetSFXMasterVolume
FSOUND_GetSpeakerMode
FSOUND_GetSubChannel
FSOUND_GetSurround
FSOUND_GetVersion
FSOUND_GetVolume
FSOUND_Init
FSOUND_IOP_Alloc
FSOUND_IOP_Free
FSOUND_IsPlaying
FSOUND_METADATACALLBACK
FSOUND_OPENCALLBACK
FSOUND_PlaySound
FSOUND_PlaySoundEx
FSOUND_READCALLBACK
FSOUND_REALLOCCALLBACK
FSOUND_Record_GetDriver
FSOUND_Record_GetDriverName
FSOUND_Record_GetNumDrivers
FSOUND_Record_GetPosition
FSOUND_Record_SetDriver
FSOUND_Record_StartSample
FSOUND_Record_Stop
FSOUND_Reverb_GetChannelProperties
FSOUND_Reverb_GetProperties
FSOUND_Reverb_SetChannelProperties
FSOUND_Reverb_SetProperties
FSOUND_Sample_Alloc
FSOUND_Sample_Free
FSOUND_Sample_Get
FSOUND_Sample_GetDefaults
FSOUND_Sample_GetDefaultsEx
FSOUND_Sample_GetLength
FSOUND_Sample_GetLoopPoints
FSOUND_Sample_GetMinMaxDistance
FSOUND_Sample_GetMode
FSOUND_Sample_GetName
FSOUND_Sample_Load
FSOUND_Sample_Lock
FSOUND_Sample_SetDefaults
FSOUND_Sample_SetDefaultsEx
FSOUND_Sample_SetLoopPoints
FSOUND_Sample_SetMaxPlaybacks
FSOUND_Sample_SetMinMaxDistance
FSOUND_Sample_SetMode
FSOUND_Sample_Unlock
FSOUND_Sample_Upload
FSOUND_SEEKCALLBACK
FSOUND_SendData
FSOUND_SetBufferSize
FSOUND_SetCurrentPosition
FSOUND_SetDiskBusy
FSOUND_SetDriver
FSOUND_SetFrequency
FSOUND_SetHWND
FSOUND_SetLevels
FSOUND_SetLoopMode
FSOUND_SetMaxHardwareChannels
FSOUND_SetMemorySystem
FSOUND_SetMinHardwareChannels
FSOUND_SetMixer
FSOUND_SetMute
FSOUND_SetOutput
FSOUND_SetPan
FSOUND_SetPanSeperation
FSOUND_SetPaused
FSOUND_SetPriority
FSOUND_SetReserved
FSOUND_SetSFXMasterVolume
FSOUND_SetSpeakerMode
FSOUND_SetSurround
FSOUND_SetVolume
FSOUND_SetVolumeAbsolute
FSOUND_SPU2_Alloc
FSOUND_SPU2_Free
FSOUND_SPU2_GetRawAddress
FSOUND_StopSound
FSOUND_Stream_AddSyncPoint
FSOUND_Stream_Close
FSOUND_Stream_Create
FSOUND_Stream_CreateDSP
FSOUND_Stream_DeleteSyncPoint
FSOUND_Stream_FindTagField
FSOUND_Stream_GetLength
FSOUND_Stream_GetLengthMs
FSOUND_Stream_GetMode
FSOUND_Stream_GetNumSubStreams
FSOUND_Stream_GetNumSyncPoints
FSOUND_Stream_GetNumTagFields
FSOUND_Stream_GetOpenState
FSOUND_Stream_GetPosition
FSOUND_Stream_GetSample
FSOUND_Stream_GetSyncPoint
FSOUND_Stream_GetSyncPointInfo
FSOUND_Stream_GetTagField
FSOUND_Stream_GetTime
FSOUND_Stream_Net_GetBufferProperties
FSOUND_Stream_Net_GetLastServerStatus
FSOUND_Stream_Net_GetStatus
FSOUND_Stream_Net_SetBufferProperties
FSOUND_Stream_Net_SetMetadataCallback
FSOUND_Stream_Net_SetProxy
FSOUND_Stream_Net_SetTimeout
FSOUND_Stream_Open
FSOUND_Stream_OpenFromHandle
FSOUND_Stream_Play
FSOUND_Stream_PlayEx
FSOUND_Stream_SetBufferSize
FSOUND_Stream_SetEndCallback
FSOUND_Stream_SetLoopCount
FSOUND_Stream_SetLoopPoints
FSOUND_Stream_SetMode
FSOUND_Stream_SetPosition
FSOUND_Stream_SetSubStream
FSOUND_Stream_SetSubStreamSentence
FSOUND_Stream_SetSyncCallback
FSOUND_Stream_SetTime
FSOUND_Stream_Stop
FSOUND_STREAMCALLBACK
FSOUND_TELLCALLBACK
FSOUND_Update
sceSifAddCmdHandler

+ Structures

- Structures

FSOUND_REVERB_CHANNELPROPERTIES
FSOUND_REVERB_PROPERTIES
FSOUND_TOC_TAG

+ Defines

- Defines

FSOUND_CAPS
FSOUND_CDPLAYMODES
FSOUND_DSP_PRIORITIES
FSOUND_INIT_FLAGS
FSOUND_MISC_VALUES
FSOUND_MODES
FSOUND_REVERB_CHANNELFLAGS
FSOUND_REVERB_FLAGS
FSOUND_REVERB_PRESETS
FSOUND_STATUS_FLAGS

+ Enums

- Enums

This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.
Generated Fri Nov 18 00:31:54 2005 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_DSPCALLBACK

Callback definition for DSP units.

void * F_CALLBACKAPI FSOUND_DSPCALLBACK(
void *originalbuffer,
void *newbuffer,
int length,
void *userdata
);

Parameters

originalbuffer | This is the pointer to the original buffer passed into the first DSP unit. This is useful if you want the clean, original data, and you have been returning new modified buffers for the DSP chain to use.
newbuffer | This is a pointer to the previous DSP buffer that *it* returned. This buffer that this DSP returns will be passed into the newbuffer parameter of the NEXT unit in the DSP chain.
length | The length of the buffer provided in SAMPLES, not bytes.
param | A user data value specified in FSOUND_DSP_Create.

Return Value

Pointer to a sample buffer for the next DSP unit to use.

Remarks

You must return the buffer you work on, or it will not be fed through to the next DSP unit, and eventually the the system clip and copy unit, which makes the sound audible.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_DSP_Create , FSOUND_Stream_CreateDSP


[API function]

FSOUND_STREAMCALLBACK

Callback used with user streams.

signed char F_CALLBACKAPI FSOUND_STREAMCALLBACK(
FSOUND_STREAM *stream,
void *buff,
int len,
void *userdata
);

Parameters

stream | Pointer to the stream in question.
buff | from FSOUND_Stream_Create - Pointer to the stream data buffer to write to from FSOUND_Stream_SetEndCallback - NULL from FSOUND_Stream_SetSyncCallback - Pointer to a string
len | from FSOUND_Stream_Create - Length of buffer specified in BYTES. from FSOUND_Stream_SetEndCallback - 0 from FSOUND_Stream_SetSyncCallback - 0
param | A user data value specified from FSOUND_Stream_Create,

Return Value

If created by FSOUND_Stream_Create -
To allow the stream to continue, TRUE is returned.
To stop the stream, FALSE is returned.
The return value is ignored if created by FSOUND_Stream_SetEndCallback or FSOUND_Stream_SetSyncCallback
--------------
PlayStation 2 IMPORTANT! For user created streams only.
The address for 'buff' is an IOP based address, you cannot directly access it.
You have to use FSOUND_SendData to DMA your data from the EE to the IOP.
if FSOUND_SendData is NOT called from this callback the IOP will hang because it is waiting for this command to be executed before it can unlock its buffer and send it to the SPU.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SendData , FSOUND_Stream_Create , FSOUND_Stream_SetEndCallback , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_ALLOCCALLBACK

Callback to allocate a block of memory.

void * F_CALLBACKAPI FSOUND_ALLOCCALLBACK(
unsigned int size
);

Parameters

size Size in bytes of the memory block to be allocated and returned.

Return Value

On success, a pointer to the newly allocated block of memory is returned.
On failure, NULL is returned.

Remarks

Returning an aligned pointer, of 16 byte alignment is recommended for speed purposes.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_FREECALLBACK , FSOUND_GetMemoryStats , FSOUND_REALLOCCALLBACK , FSOUND_SetMemorySystem


[API function]

FSOUND_REALLOCCALLBACK

Callback to re-allocate a block of memory to a different size.

void * F_CALLBACKAPI FSOUND_REALLOCCALLBACK(
void *ptr,
unsigned int size
);

Parameters

ptr | Pointer to a block of memory to be resized. If this is NULL then a new block of memory is simply allocated.
size | Size of the memory to be reallocated. The original memory must be preserved.

Return Value

On success, a pointer to the newly re-allocated block of memory is returned.
On failure, NULL is returned.

Remarks

Returning an aligned pointer, of 16 byte alignment is recommended for speed purposes.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_ALLOCCALLBACK , FSOUND_FREECALLBACK , FSOUND_GetMemoryStats , FSOUND_SetMemorySystem


[API function]

FSOUND_FREECALLBACK

Callback to free a block of memory.

void F_CALLBACKAPI FSOUND_FREECALLBACK(
void *ptr
);

Parameters

ptr Pointer to a pre-existing block of memory to be freed.

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_ALLOCCALLBACK , FSOUND_GetMemoryStats , FSOUND_REALLOCCALLBACK , FSOUND_SetMemorySystem


[API function]

FSOUND_OPENCALLBACK

Callback for opening a file.

void * F_CALLBACKAPI FSOUND_OPENCALLBACK(
const char *name
);

Parameters

name This is the filename. You may treat this as you like.

Return Value

On success, return a non 0 number.
On failure, return 0.

Remarks

You MUST open the file and return a handle for future file function calls. Cast the handle to an unsigned int when returning it, then in other callbacks, cast it back from the unsigned int back to your own handle type.
Return 0 signifies an open error. This is very important.
It is a good idea if you are using memory based file routines, to store the size of the file here, as it is needed to support SEEK_END in the seek function, described below.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_CLOSECALLBACK , FSOUND_File_SetCallbacks , FSOUND_READCALLBACK , FSOUND_SEEKCALLBACK , FSOUND_TELLCALLBACK


[API function]

FSOUND_CLOSECALLBACK

Calback for closing a file.

void F_CALLBACKAPI FSOUND_CLOSECALLBACK(
void *handle
);

Parameters

handle This is the handle you returned from the open callback to use for your own file routines.

Return Value

void

Remarks

Close your file handle and do any cleanup here.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_File_SetCallbacks , FSOUND_OPENCALLBACK , FSOUND_READCALLBACK , FSOUND_SEEKCALLBACK , FSOUND_TELLCALLBACK


[API function]

FSOUND_METADATACALLBACK

Callback to receive a new piece of metadata from an internet stream

signed char F_CALLBACKAPI FSOUND_METADATACALLBACK(
char *name,
char *value,
void *userdata
);

Parameters

name | Pointer to the name of the piece of metadata (null-terminated ASCII string)
value | Pointer to the metadata (null-terminated ASCII string)
userdata | Userdata that was specified in FSOUND_Stream_Net_SetMetadataCallback

Return Value

Currently ignored

Remarks

___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Net_SetMetadataCallback


[API function]

FSOUND_READCALLBACK

Callback for reading from a file.

int F_CALLBACKAPI FSOUND_READCALLBACK(
void *buffer,
int size,
void *handle
);

Parameters

buffer | You must read and copy your file data into this pointer.
length | You must read this many bytes from your file data.
handle | This is the handle you returned from the open callback to use for your own file routines.

Return Value

Return the number of bytes that were *successfully* read here. Normally this is just the same as 'length', but if you are at the end of the file, you will probably only read successfully the number of bytes up to the end of the file (if you tried to read more than that).

Remarks

You must read 'length' number of bytes into the 'buffer' provided, then if you need to, increment your file pointer.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_CLOSECALLBACK , FSOUND_File_SetCallbacks , FSOUND_OPENCALLBACK , FSOUND_SEEKCALLBACK , FSOUND_TELLCALLBACK


[API function]

FSOUND_SEEKCALLBACK

Callback for seeking within a file.

int F_CALLBACKAPI FSOUND_SEEKCALLBACK(
void *handle,
int pos,
signed char mode
);

Parameters

handle | This is the handle you returned from the open callback to use for your own file routines.
pos | This is the position or offset to seek by depending on the mode.
mode | This is the seek command. It uses and is compatible with SEEK_SET, SEEK_CUR and SEEK_END from stdio.h, so use them.

Return Value

If successful, the seek callback returns 0. Otherwise, it returns a nonzero value. On devices incapable of seeking, the return value is undefined.

Remarks

SEEK_END must reposition your file pointer at the END of the file, plus any negative offset. To do this you must know the size of the file, it is suggested you find and store this in the open function. Remember that a SEEK_END position value of -1 is the last byte.
You must reset your file pointer based on the commands given above.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_CLOSECALLBACK , FSOUND_File_SetCallbacks , FSOUND_OPENCALLBACK , FSOUND_READCALLBACK , FSOUND_TELLCALLBACK


[API function]

FSOUND_TELLCALLBACK

Callback for returning the current file pointer position within the file.

int F_CALLBACKAPI FSOUND_TELLCALLBACK(
void *handle
);

Parameters

handle This is the handle you returned from the open callback to use for your own file routines.

Return Value

On success, the offset within the file in bytes is returned.
On failure, -1 is returned.

Remarks

You must return the offset from the base of the file, using this routine.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_CLOSECALLBACK , FSOUND_File_SetCallbacks , FSOUND_OPENCALLBACK , FSOUND_READCALLBACK , FSOUND_SEEKCALLBACK


[API function]

FSOUND_Close

Shuts down the WHOLE FMOD Sound System.

void F_API FSOUND_Close(
);

Return Value

void

Remarks

This also closes down the sample management system, freeing all MANAGED samples loaded (unless they were allocated with the FSOUND_UNMANAGED flag).
Streams are not freed. You must close them yourself.
CD Tracks are stopped.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_CD_GetVolume , FSOUND_CD_SetVolume , FSOUND_Init , FSOUND_Sample_Alloc , FSOUND_Sample_Get , FSOUND_Sample_Load , FSOUND_SetBufferSize , FSOUND_SetDriver , FSOUND_SetHWND , FSOUND_SetMaxHardwareChannels , FSOUND_SetMemorySystem , FSOUND_SetMinHardwareChannels , FSOUND_SetMixer , FSOUND_SetOutput , FSOUND_SetSpeakerMode


[API function]

FSOUND_File_SetCallbacks

Specify user callbacks for FMOD's internal file manipulation functions.
If ANY of these parameters are NULL, then FMOD will switch back to its own file routines.
You can replace this with memory routines (ie name can be cast to a memory address for example, then open sets up
a handle based on this information), or alternate file routines, ie a WAD file reader.

DLL_API void F_API FSOUND_File_SetCallbacks(
FSOUND_OPENCALLBACK useropen,
FSOUND_CLOSECALLBACK userclose,
FSOUND_READCALLBACK userread,
FSOUND_SEEKCALLBACK userseek,
FSOUND_TELLCALLBACK usertell
);

Parameters

OpenCallback | Callback for opening a file.
CloseCallback | Callback for closing a file.
ReadCallback | Callback for reading from a file.
SeekCallback | Callback for seeking within a file..
TellCallback | Callback for returning the offset from the base of the open file in bytes.

Return Value

void

Remarks

Memory loader FMOD functions are not affected, such as FMUSIC_LoadSongMemory etc.
WARNING : This function is dangerous in the wrong hands. You must return the right values, and each command must work properly, or FMOD will not function, or it may even crash if you give it invalid data.
You must support SEEK_SET, SEEK_CUR and SEEK_END properly, or FMOD will not work properly. See standard I/O help files on how these work under fseek().
Read the documentation in REMARKS and do exactly what it says. See the "simple" example for how it is used properly.
The MIDI loader does not support user file callbacks. For WAD type data structures with embedded MIDI files FMUSIC_LoadSongMemory will have to be used.
--------------
PlayStation 2 NOTE! This function takes IOP function pointers, not EE pointers! It is for custom IOP file systems not EE based ones.
This function can only be called after FSOUND_Init on PlayStation 2, not before.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, PlayStation 2, XBox, GameCube

See Also

FMUSIC_LoadSong , FSOUND_CLOSECALLBACK , FSOUND_Init , FSOUND_OPENCALLBACK , FSOUND_READCALLBACK , FSOUND_SEEKCALLBACK , FSOUND_TELLCALLBACK


[API function]

FSOUND_Init

Initializes the FMOD Sound System.

signed char F_API FSOUND_Init(
int mixrate,
int maxsoftwarechannels,
unsigned int flags
);

Parameters

mixrate | Output rate in hz between 4000 and 65535. Any thing outside this will cause the function to fail and return FALSE. PS2 Note. Only rates of 24000 and 48000 are supported. PSP Note. Only rates of 22050 and 44100 are supported. SmartPhone Note. Use 22050 or the operating system may crash outside of the control of fmod.
maxchannels | Maximum number of SOFTWARE channels available. The number of HARDWARE channels is autodetected. The total number of channels available (hardware and software) after initialization can be found with FSOUND_GetMaxChannels. Having a large number of maxchannels does not adversely affect cpu usage, but it means it has the POTENTIAL to mix a large number of channels, which can have an adverse effect on cpu usage. 1024 is the highest number that can be set. Anything higher will return an error.
flags | See FSOUND_INIT_FLAGS. Controls some global or initialization time aspects of playback.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

You do not have control over how many hardware channels are available to you. In a lot of
cases it may be 0 (the sound card does not have the ability to supply hardware channels).
This is why it is usually a good idea to supply FSOUND_Init with a good number of software
channels to fall back onto, for example 32.
Hardware channels are 3D hardware channels only. There is no benefit in supporting hardware
for 2d playback of sound effects. With todays machines and FMOD's superior mixing routines,
FMOD's software engine can sometimes be faster than the driver's hardware support!
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_File_SetCallbacks , FSOUND_GetCurrentLevels , FSOUND_GetDriverCaps , FSOUND_GetFreeHWRam , FSOUND_GetMaxChannels , FSOUND_GetMemoryStats , FSOUND_GetOutputHandle , FSOUND_GetOutputRate , FSOUND_Init , FSOUND_INIT_FLAGS , FSOUND_PlaySound , FSOUND_PlaySoundEx , FSOUND_SetBufferSize , FSOUND_SetDriver , FSOUND_SetHWND , FSOUND_SetMaxHardwareChannels , FSOUND_SetMemorySystem , FSOUND_SetMinHardwareChannels , FSOUND_SetMixer , FSOUND_SetOutput , FSOUND_SetSpeakerMode , FSOUND_SPU2_Alloc , FSOUND_Stream_Play , sceSifAddCmdHandler


[API function]

FSOUND_SetBufferSize

Sets the FMOD internal mixing buffer size.
It is configurable because low buffersizes use less memory, but are more instable.
More importantly, increasing buffer size will increase sound output stability, but
on the other hand increases latency, and to some extent, CPU usage.
* FMOD chooses the most optimal size by default for best stability, depending on the
output type - and if the drivers are emulated or not (NT).
It is not recommended changing this value unless you really need to. You may get worse
performance than the default settings chosen by FMOD.

signed char F_API FSOUND_SetBufferSize(
int len_ms
);

Parameters

len_ms The buffer size in milliseconds.

Return Value

On success, TRUE is returned.
On failure, (ie if FMOD is already active) FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
---------
The buffersize seting defaults to 50ms if it is not called for DSOUND.
It defaults to 200ms for Windows Multimedia wave-out or for emulated DirectSound drivers (such as NT drivers).
When the output is FSOUND_OUTPUT_ASIO the buffersize is ignored. The buffersize should be configured using the ASIO driver which can be done with the supplied asioconfig.exe in the FMOD SDK.
---------
Buffer sizes lower than 50 are clamped at 50.
Buffer sizes are also rounded DOWN to the nearest multiple of 25. This is because FMOD mixes in blocks of 25ms.
Due to this buffersize command latency on software channels will be between 25 and 50ms on average (37.5ms) when the buffersize is set to 50.
---------
Macintosh, PlayStation 2 and GameCube do not support this as they already achieve minimal latency and are forced to 25ms.
___________________
Supported on the following platforms : Win32, WinCE, Linux, XBox

See Also

FSOUND_Close , FSOUND_DSP_GetBufferLengthTotal , FSOUND_Init


[API function]

FSOUND_SetDriver

Selects a soundcard driver.
It is used when an output mode has enumerated more than one output device, and you need to select between them.

signed char F_API FSOUND_SetDriver(
int driver
);

Parameters

driverno Driver number to select.
0 will select the DEFAULT sound driver.
<0 will select an INVALID driver which will case the DEVICE to be set
to a null (nosound) driver.
>0 Selects other valid drivers that can be listed with FSOUND_GetDriverName.

Return Value

On success, TRUE is returned.
On failure, (ie if FMOD is already active) FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_GetDriver , FSOUND_GetDriverName , FSOUND_GetNumDrivers , FSOUND_Init , FSOUND_SetOutput


[API function]

FSOUND_SetHWND

This is an optional function to set the window handle of the application
you are writing, so Directsound can tell if it is in focus or not.

signed char F_API FSOUND_SetHWND(
void *hwnd
);

Parameters

hwnd Pointer to a HWND windows handle of your application.
NULL means it will pick the foreground application window.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
---------
FMOD uses GetForegroundWindow if this function is not called.
___________________
Supported on the following platforms : Win32, WinCE

See Also

FSOUND_Close , FSOUND_Init


[API function]

FSOUND_SetMaxHardwareChannels

This sets the maximum allocatable channels on a hardware card. FMOD automatically detects and allocates the maximum number of 3d hardware channels, so calling this will limit that number if it becomes too much.

DLL_API signed char F_API FSOUND_SetMaxHardwareChannels(
int max
);

Parameters

max The maximum number of hardware channels to allocate, even if the soundcard supports more.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
---------
This function has nothing to do with FSOUND_SetMinHardwareChannels, in that this is not a function that forces FMOD into software mixing if a card has a certain number of channels.
This function only sets a limit on hardware channels, so if your card has 96 hardware channels, and you set FSOUND_SetMaxHardwareChannels(10), then you will only have 10 hardware channels to use.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_Init , FSOUND_SetMaxHardwareChannels , FSOUND_SetMinHardwareChannels


[API function]

FSOUND_SetMemorySystem

Specifies a method for FMOD to allocate memory, either through callbacks or its own internal memory management. You can also supply a pool of memory for FMOD to work with and it will do so with no extra calls to malloc or free.
This is useful for systems that want FMOD to use their own memory management, or fixed memory devices such as PocketPC, XBox, PS2 and GameCube that dont want any allocations occuring out of their control causing fragmentation or unpredictable overflows in a tight memory space.
See remarks for more useful information.

DLL_API signed char F_API FSOUND_SetMemorySystem(
void *poolmem,
int poollen,
FSOUND_ALLOCCALLBACK useralloc,
FSOUND_REALLOCCALLBACK userrealloc,
FSOUND_FREECALLBACK userfree
);

Parameters

pool | If you want a fixed block of memory for FMOD to use, pass it in here. Specify the length in poollen. Specifying NULL doesnt use internal management and it relies on callbacks.
poollen | Length in bytes of the pool of memory for FMOD to use specified in. Specifying 0 turns off internal memory management and relies purely on callbacks. Length must be a multiple of 512.
useralloc | Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to alloc. Compatible with ansi malloc().
userrealloc | Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to realloc. Compatible with ansi realloc().
userfree | Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to free. Compatible with ansi free().

Return Value

void

Remarks

FMOD has been tested to stay in a limit and fail gracefully if the fixed pool size is not large enough with FMOD_ERR_MEMORY errors.
FMOD only does allocation when creating streams, music or samples and the FSOUND_Init stage. It never allocates or deallocates memory during the course of runtime processing.
To find out the required fixed size the user can call FSOUND_GetMemoryStats with a larger than nescessary pool size (or no pool), and find out the maximum ram usage at any one time within FMOD.
-------------------------------------
FMOD behaves differently based on what you pass into this function in 3 different combinations.
Here are the examples.
NULL, 0, NULL, NULL, NULL : Falls back purely to ansi C malloc, realloc and free.
NULL, 0, myalloc, myrealloc, myfree : Calls user supplied callbacks every time fmod does a memory allocation or deallocation.
ptr, len, NULL, NULL, NULL : Uses "ptr" and manages memory internally. NO extra mallocs or frees are performed from this point.
-------------------------------------
Callbacks and memory pools cannot be combined, as if a pool is specified FMOD, manipulates the pool of memory internally with its own allocate and free scheme.
The memory management algorithm to work within a fixed size of ram is extremely efficient and faster than the standard C malloc or free.
-------------------------------------
On XBox you MUST specify a pointer and length. The memory provided must be enough to store all sample data.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_ALLOCCALLBACK , FSOUND_Close , FSOUND_FREECALLBACK , FSOUND_GetFreeHWRam , FSOUND_GetMemoryStats , FSOUND_Init , FSOUND_IOP_Alloc , FSOUND_REALLOCCALLBACK


[API function]

FSOUND_SetMinHardwareChannels

This sets the minimum allowable hardware channels before FMOD drops back to 100 percent software.
This is helpful for minimum spec cards, and not having to guess how many hardware channels
they might have. This way you can guarantee and assume a certain number of channels for
your application and place them all in FSOUND_HW3D without fear of the playsound failing
because it runs out of channels on a low spec card.

DLL_API signed char F_API FSOUND_SetMinHardwareChannels(
int min
);

Parameters

min The minimum number of hardware channels allowable on a card before it uses the software engine 1004562604f the time.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
---------
As an example, if you set your minimum to 16, you can now safely guarantee that 16 sounds can be played at once that are created with FSOUND_HW3D.
This way if you do come across a card that only supports 4 channels, it will just drop back to playing ALL sounds in software mode.
It may sound worse, but at least it doesnt fail on the playsound. (which could sound even worse!)
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_Init , FSOUND_SetMaxHardwareChannels


[API function]

FSOUND_SetMixer

Sets a digital mixer type.

signed char F_API FSOUND_SetMixer(
int mixer
);

Parameters

mixer mixer type, see FSOUND_MIXERTYPES for valid parameters and descriptions.

Return Value

On success, TRUE is returned.
On failure, (ie if FMOD is already active) FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
This function does not nescessarily need to be called, autodetection will select the
fastest mixer for your machine. It is here if you need to test all mixer types for
debugging purposes, or a mixer has a feature that the autodetected one doesnt.
(ie low quality mixers or volume ramping)
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_GetMixer , FSOUND_Init , FSOUND_MIXERTYPES


[API function]

FSOUND_SetOutput

Sets up the soundsystem output mode.

signed char F_API FSOUND_SetOutput(
int outputtype
);

Parameters

outputtype The output system to be used. See FSOUND_OUTPUTTYPES for valid parameters and descriptions. -1 Is autodetect based on operating system.

Return Value

On success, TRUE is returned.
On failure, (ie if FMOD is already active) FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init, or after FSOUND_Close.
-------
Under Windows NT - Waveout is FASTER than DirectSound, achieves LOWER latency, AND
is LESS buggy. DirectSound under NT is achieved by emulating waveout, and therefore is
inferior to waveout. Use WAVEOUT under NT.
Under Windows 9x and W2K - DirectSound is faster than waveout and can achieve lower latency.
Use DIRECTSOUND under Win9x and W2K.
-------
If you dont call FSOUND_SetOutput, FMOD will now autodetect DSOUND or WINMM based on the operating system.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_GetDriverCaps , FSOUND_GetOutput , FSOUND_GetOutputHandle , FSOUND_Init , FSOUND_OUTPUTTYPES , FSOUND_SetDriver , FSOUND_SetOutput


[API function]

FSOUND_SetPanSeperation

Sets the master pan seperation for 2d sound effects.

DLL_API void F_API FSOUND_SetPanSeperation(
F_FLOAT_API pansep
);

Parameters

pansep The pan scalar. 1.0 means full pan seperation, 0 means mono.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This is set to 1.0 by default.
Music is not affected by this. To change pan seperation for music files individually,
see FMUSIC_SetPanSeperation
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetPanSeperation , FSOUND_GetSpeakerMode , FSOUND_SetSpeakerMode


[API function]

FSOUND_SetSFXMasterVolume

Sets the master volume for any sound effects played. Does not affect music or CD output.

DLL_API void F_API FSOUND_SetSFXMasterVolume(
int volume
);

Parameters

volume The volume to set. Valid ranges are from 0 (silent) to 255 (full volume)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetMasterVolume , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute


[API function]

FSOUND_SetSpeakerMode

Sets the mode for the users speaker setup.

void F_API FSOUND_SetSpeakerMode(
unsigned int speakermode
);

Parameters

speakermode This is an enum describing the users speaker setup.

Return Value

void

Remarks

Note - Only reliably works with FSOUND_OUTPUT_DSOUND on windows, or consoles such as PlayStation 2, GameCube and XBox.
For other output types speaker mode only interprets FSOUND_SPEAKERMODE_MONO, everything else is interpreted as stere.
----------------------------------
To get true 5.1 dolby digital or DTS output you will need a soundcard that can encode it, and a receiver that can decode it.
----------------------------------
Calling this will reset the pan separation setting. It sets it to 0 if FSOUND_SPEAKERMODE_MONO is chosen, and 1 otherwise.
You will need to reset the pan separation if required afterwards.
----------------------------------
XBOX
This function must be called before FSOUND_Init to change the default speaker mode. To change on the fly, you must close down FMOD with FSOUND_Close then re-initialize it with FSOUND_Init.
If it is called after FSOUND_Init, only headphone speakermode is interpreted to switch headphone mode on and off.
By default the dashboard setting is used for the speakermode. It is not recommend you change this mode unless you let the user change it in-game.
----------------------------------
PlayStation 2.
Only mono/stereo and prologic 2 modes are interpreted. Dolby digital or DTS are not supported.
This function must be called before playing sounds. Calling this after playing a sound will not make that existing sound work in Prologic 2.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_GetSpeakerMode , FSOUND_Init , FSOUND_SetPanSeperation , FSOUND_SPEAKERMODES


[API function]

FSOUND_Update

This updates the 3d sound engine and DMA engine (only on some platforms), and should be called once a game frame.
This function will also update the software mixer if you have selected FSOUND_OUTPUT_NOSOUND_NONREALTIME as your output mode.

void F_API FSOUND_Update(
);

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetCurrent , FSOUND_3D_SetAttributes , FSOUND_3D_SetDopplerFactor


[API function]

FSOUND_GetCPUUsage

Returns in percent of cpu time the amount of cpu usage that FSOUND/FMUSIC mixing is taking.

F_FLOAT_API F_API FSOUND_GetCPUUsage(
);

Return Value

floating point value between 0.0 and 100.0.

Remarks

This value represents the cpu usage used by streams, the software mixer, and subsequent calls to dsound waveout etc.
MIDI playback is not counted as it is performed by directx.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create


[API function]

FSOUND_GetChannelsPlaying

Returns the number of active channels in FSOUND, or ones that are playing.

int F_API FSOUND_GetChannelsPlaying(
);

Return Value

Number of active channels.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_OptimizeChannels


[API function]

FSOUND_GetDriver

Returns the currently selected driver number. Drivers are enumerated when selecting a driver
with FSOUND_SetDriver or other driver related functions such as FSOUND_GetNumDrivers or
FSOUND_GetDriverName

int F_API FSOUND_GetDriver(
);

Return Value

Currently selected driver id.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2

Remarks

If no driver is manually selected, 0 is returned, or the default driver.

See Also

FSOUND_GetDriver , FSOUND_GetDriverName , FSOUND_GetNumDrivers , FSOUND_SetDriver


[API function]

FSOUND_GetDriverCaps

Returns information on capabilities of the current output mode.

signed char F_API FSOUND_GetDriverCaps(
int id,
unsigned int *caps
);

Parameters

id | Enumerated driver ID. This must be in a valid range delimited by FSOUND_GetNumDrivers,
caps | Pointer to an unsigned int to have the caps bits stored.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function cannot be called after FMOD is already activated with FSOUND_Init.
It must be called before FSOUND_Init.
FSOUND_SetOutput must be called to tell FMOD which output mode you are talking about.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_CAPS , FSOUND_GetNumDrivers , FSOUND_Init , FSOUND_SetOutput


[API function]

FSOUND_GetDriverName

Returns the name of the selected driver. Drivers are enumerated when selecting a driver with
FSOUND_SetDriver or other driver related functions such as FSOUND_GetNumDrivers or
FSOUND_GetDriver

const char * F_API FSOUND_GetDriverName(
int id
);

Parameters

id Enumerated driver ID. This must be in a valid range delimited by FSOUND_GetNumDrivers,

Return Value

On success, a pointer to a NULL terminated string containing the name of the specified device is returned. The number of drivers enumerated can be found with FSOUND_GetNumDrivers.
On failure, NULL is returned.

Remarks

If no driver is selected, the default driver is used.

See Also

FSOUND_GetDriver , FSOUND_GetNumDrivers , FSOUND_SetDriver


[API function]

FSOUND_GetError

Returns an error code set by FMOD.

int F_API FSOUND_GetError(
);

Return Value

error code, see FMOD_ERRORS

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMOD_ERRORS , FSOUND_GetAmplitude , FSOUND_GetFrequency , FSOUND_GetPan , FSOUND_GetPriority , FSOUND_GetVolume


[API function]

FSOUND_GetMaxSamples

Returns the current maximum index for a sample. This figure grows as you allocate more
samples (in blocks)

int F_API FSOUND_GetMaxSamples(
);

Return Value

Maximum sample index

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_GetMaxChannels

Returns the total number of channels allocated.

int F_API FSOUND_GetMaxChannels(
);

Return Value

Number of channels allocated

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Init


[API function]

FSOUND_GetMemoryStats

Returns information on the memory usage of fmod. This is useful for determining a fixed memory size to
make FMOD work within for fixed memory machines such as pocketpc and consoles.

DLL_API void F_API FSOUND_GetMemoryStats(
unsigned int *currentalloced,
unsigned int *maxalloced
);

Parameters

currentalloced | Currently allocated memory at time of call.
maxalloced | Maximum allocated memory since FSOUND_Init or FSOUND_SetMemorySystem

Return Value

void

Remarks

Note that if using FSOUND_SetMemorySystem, the memory usage will be slightly higher than without it, as fmod has to have a small amount of memory overhead to manage the available memory.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_ALLOCCALLBACK , FSOUND_FREECALLBACK , FSOUND_GetFreeHWRam , FSOUND_Init , FSOUND_REALLOCCALLBACK , FSOUND_SetMemorySystem


[API function]

FSOUND_GetNumDrivers

Returns the number of sound cards or devices enumerated for the current output type. (Direct
Sound, WaveOut etc.)

int F_API FSOUND_GetNumDrivers(
);

Return Value

Total number of enumerated sound devices.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetDriver , FSOUND_GetDriverCaps , FSOUND_GetDriverName , FSOUND_SetDriver


[API function]

FSOUND_GetNumHWChannels

Returns the number of available hardware mixed 2d and 3d channels.

signed char F_API FSOUND_GetNumHWChannels(
int *num2d,
int *num3d,
int *total
);

Parameters

num2d | Pointer to integer to store the number of available hardware mixed 2d channels.
num3d | Pointer to integer to store the number of available hardware mixed 3d channels.
total | Usually num2d + num3d, but on some platforms like PS2 and GameCube, this will be the same as num2d and num3d (and not the sum) because 2d and 3d voices share the same pool.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_GetOutput

Returns the current id to the output type.
See FSOUND_OUTPUTTYPES for valid parameters and descriptions.

int F_API FSOUND_GetOutput(
);

Return Value

id to output type

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetOutputHandle , FSOUND_OUTPUTTYPES , FSOUND_SetFrequency , FSOUND_SetOutput


[API function]

FSOUND_GetOutputHandle

Returns a pointer to the system level output device module.
This means a pointer to a DIRECTSOUND, WINMM handle, or with NOSOUND output, NULL

void * F_API FSOUND_GetOutputHandle(
);

Return Value

Pointer to output handle specific to the device.

Remarks

Must be called after FSOUND_Init or else it will fail,
Cast the resulting pointer depending on what output system pointer you are after.
FSOUND_OUTPUT_NOSOUND, NULL is returned.
FSOUND_OUTPUT_WINMM, HWAVEOUT is returned.
FSOUND_OUTPUT_DSOUND, LPDIRECTSOUND is returned.
FSOUND_OUTPUT_OSS, File handle is returned, (cast to int)
FSOUND_OUTPUT_ESD, Handle returned by so_esd_open_sound (cast to int).
FSOUND_OUTPUT_ALSA snd_pcm_t * is returned.
FSOUND_OUTPUT_ASIO AsioDriverList pointer is returned.
FSOUND_OUTPUT_XBOX LPDIRECTSOUND is returned.
FSOUND_OUTPUT_PS2 NULL is returned.
FSOUND_OUTPUT_MAC SndChannelPtr is returned.
FSOUND_OUTPUT_GC NULL is returned.
FSOUND_OUTPUT_PSP NULL is returned.
FSOUND_OUTPUT_NOSOUND_NONREALTIME NULL is returned.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox

See Also

FSOUND_GetOutput , FSOUND_Init , FSOUND_OUTPUTTYPES , FSOUND_SetFrequency , FSOUND_SetOutput


[API function]

FSOUND_GetOutputRate

Returns the current mixing rate

int F_API FSOUND_GetOutputRate(
);

Return Value

Currently set output rate in HZ.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Init


[API function]

FSOUND_GetSFXMasterVolume

Returns the master volume for any sound effects played.
It specifically has SFX in the function name, as it does not affect music or CD volume.
This must also be altered with FMUSIC_SetMasterVolume.

DLL_API int F_API FSOUND_GetSFXMasterVolume(
);

Return Value

On success, the SFX master volume is returned. Valid ranges are from 0 (silent) to 255 (full volume)

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetMasterVolume


[API function]

FSOUND_GetVersion

Returns the FMOD version number.

float F_API FSOUND_GetVersion(
);

Return Value

FMOD version number.

Remarks

Use this to compare the header you are using against the compiled DLL version to make sure your
DLL is up to date.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_Sample_Alloc

Allocates a new empty sample. Used if you want to create a sample from scratch and fill the databuffer with your own data (using FSOUND_Sample_Lock or FSOUND_Sample_Upload), instead of just loading a file with FSOUND_Sample_Load.

FSOUND_SAMPLE * F_API FSOUND_Sample_Alloc(
int index,
int length,
unsigned int mode,
int deffreq,
int defvol,
int defpan,
int defpri
);

Parameters

index | Sample pool index. See remarks for more on the sample pool. 0 or above - The absolute index into fsounds sample pool. The pool will grow as the index gets larger. If a slot is already used it will be replaced. FSOUND_FREE - Let FSOUND select an arbitrary sample slot. FSOUND_UNMANAGED - Dont have fsound free this sample upon FSOUND_Close
length | The length in of the sample buffer in SAMPLES.
mode | Bitfield describing various characteristics of the sample. Valid parameters are described in FSOUND_MODES.
deffreq | Default frequency for this sample.
defvol | Default volume for this sample.
defpan | Default pan for this sample.
defpri | Default priority for this sample.

Return Value

On success, a pointer to an allocated sample is returned.
On failure, NULL is returned.

Remarks

FMOD has a sample management system that holds onto any samples loaded or allocated, and
frees them all when you call FSOUND_Close. It takes the hassle out of having to keep hold
of a lot of sample handles and remember to free them all at the end of your application.
It is basically an expandle array of handles that holds each sample until FMOD closes down where it does
a cleanup. FSOUND_UNMANAGED can be used NOT to use the sample management system.
------------
FSOUND_Sample_Alloc is only nescessary for lower level operations with sample data. Usually
FSOUND_Load does the work for you. lower level operations mean such things as uploading data from memory or
your own compressed data for example.
You can create a new sample from scratch by doing the following operations
1. Allocate a new sample with FSOUND_Sample_Alloc
2. Write data to the sample buffer with FSOUND_Sample_Lock and FSOUND_Sample_Unlock, or
FSOUND_Sample_Upload.
Note FSOUND_Sample_Lock only returns a pointer to the sample data, whereas
FSOUND_Sample_Upload does a copy from data you give it, with format conversion to the
correct format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_MODES , FSOUND_Sample_Alloc , FSOUND_Sample_Free , FSOUND_Sample_Load , FSOUND_Sample_Lock , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetLoopPoints , FSOUND_Sample_Unlock , FSOUND_Sample_Upload


[API function]

FSOUND_Sample_Free

Removes a sample from memory and makes its slot available again.

void F_API FSOUND_Sample_Free(
FSOUND_SAMPLE *sptr
);

Parameters

sptr Pointer to the sample definition to be freed.

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_Load


[API function]

FSOUND_Sample_Get

Returns a pointer to a managed sample based on the index passed.

FSOUND_SAMPLE * F_API FSOUND_Sample_Get(
int sampno
);

Parameters

sampno The index in the sample management pool of the requested sample.

Return Value

Pointer to a sample.

Remarks

Samples that are not created with FSOUND_UNMANAGED are stored in a table inside FMOD.
This way when FMOD can free all samples when FSOUND_Close is called and the user doesnt have to worry about cleaning up memory.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close


[API function]

FSOUND_Sample_GetDefaults

Returns the default volume, frequency, pan and priority values for the specified sample.

signed char F_API FSOUND_Sample_GetDefaults(
FSOUND_SAMPLE *sptr,
int *deffreq,
int *defvol,
int *defpan,
int *defpri
);

Parameters

sptr | Pointer to the sample to get the default information from.
deffreq | Pointer to value to be filled with the sample default frequency. Can be NULL.
defvol | Pointer to value to be filled with the sample default volume. Can be NULL.
defpan | Pointer to value to be filled with the sample default pan. Can be NULL.
defpri | Pointer to value to be filled with the sample default priority. Can be NULL.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Passing NULL in any of these parameters will result in the value being ignored.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_GetDefaultsEx , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx


[API function]

FSOUND_Sample_GetDefaultsEx

Returns the default volume, frequency, pan, priority and random playback variations for the specified sample.

signed char F_API FSOUND_Sample_GetDefaultsEx(
FSOUND_SAMPLE *sptr,
int *deffreq,
int *defvol,
int *defpan,
int *defpri,
int *varfreq,
int *varvol,
int *varpan
);

Parameters

sptr | Pointer to the sample to get the default information from.
deffreq | Pointer to value to be filled with the sample default frequency. Can be NULL.
defvol | Pointer to value to be filled with the sample default volume. Can be NULL.
defpan | Pointer to value to be filled with the sample default pan. Can be NULL.
defpri | Pointer to value to be filled with the sample default priority. Can be NULL.
varfreq | Pointer to value to be filled with the sample random frequency variance. Can be NULL.
varvol | Pointer to value to be filled with the sample random volume variance. Can be NULL.
varpan | Pointer to value to be filled with the sample random pan variance. Can be NULL.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Passing NULL in any of these parameters will result in the value being ignored.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_GetDefaults , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx


[API function]

FSOUND_Sample_GetLength

Returns the length of the sample in SAMPLES

unsigned int F_API FSOUND_Sample_GetLength(
FSOUND_SAMPLE *sptr
);

Parameters

sptr Pointer to the sample to get the length from.

Return Value

On success, the length of sample in SAMPLES is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_Sample_GetLoopPoints

Returns the start and end positions of the specified sample loop
in SAMPLES (not bytes)

DLL_API signed char F_API FSOUND_Sample_GetLoopPoints(
FSOUND_SAMPLE *sptr,
int *loopstart,
int *loopend
);

Parameters

sptr | Pointer to the sample to get the loop point information from.
loopstart | Pointer to value to be filled with the sample loop start point. Can be NULL.
loopend | Pointer to value to be filled with the sample loop end point. Can be NULL.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Passing NULL in any of these parameters will result in the value being ignored.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_Sample_SetLoopPoints , FSOUND_Sample_SetMode


[API function]

FSOUND_Sample_GetMinMaxDistance

Get the minimum and maximum audible distance for a sample.

signed char F_API FSOUND_Sample_GetMinMaxDistance(
FSOUND_SAMPLE *sptr,
F_FLOAT_API *min,
F_FLOAT_API *max
);

Parameters

sptr | The sample to get minimum and maximum audible distance information from.
min | Pointer to value to be filled with the minimum volume distance for the sample. See remarks for more on units.
max | Pointer to value to be filled with the maximum volume distance for the sample. See remarks for more on units.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
The default units for minimum and maximum distances are 1.0 and 1000000000.0f.
Volume drops off at mindistance / distance.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_SetDistanceFactor , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_Sample_GetMode

Returns a bitfield containing information about the specified sample.
The values can be bitwise AND'ed with the values contained in FSOUND_MODES to see if certain criteria are true or not.
Information that can be retrieved from the same in this field are loop type, bitdepth and stereo/mono.

unsigned int F_API FSOUND_Sample_GetMode(
FSOUND_SAMPLE *sptr
);

Parameters

sptr Pointer to the sample to get the mode information on

Return Value

On success, the sample mode is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_Sample_SetMode , FSOUND_SetLoopMode


[API function]

FSOUND_Sample_GetName

Returns a pointer to a NULL terminated string containing the sample's name.

const char * F_API FSOUND_Sample_GetName(
FSOUND_SAMPLE *sptr
);

Parameters

sptr Pointer to the sample to get the name from.

Return Value

On success, the name of the sample is returned.
On failure, NULL is returned.

Remarks

The name may not always make sense. From a MOD file it contains the sample text entered
by the musician. For non descriptive file formats it just contains the filename.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_Sample_Load

Loads and decodes a static soundfile into memory.
This includes such files as .WAV, .MP2, .MP3, .OGG, .RAW and others.

FSOUND_SAMPLE * F_API FSOUND_Sample_Load(
int index,
const char *name_or_data,
unsigned int inputmode,
int offset,
int length
);

Parameters

index | Sample pool index. See remarks for more on the sample pool. 0 or above - The absolute index into the sample pool. The pool will grow as the index gets larger. If a slot is already used it will be replaced. FSOUND_FREE - Let FSOUND select an arbitrary sample slot. FSOUND_UNMANAGED - Dont have this sample managed within fsounds sample management system
name_or_data | Name of sound file or pointer to memory image to load.
mode | Description of the data format, OR in the bits defined in FSOUND_MODES to describe the data being loaded.
offset | Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening. length must also be specified if this value is used.
length | Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading.

Return Value

On success, a sample pointer is returned.
On failure, NULL is returned.

Remarks

FMOD has a sample management system that holds onto any samples loaded or allocated, and frees them all when you call FSOUND_Close.
It takes the hassle out of having to keep hold of a lot of sample handles and remember to free them all at the end of your application.
It is basically an expandle array of handles that holds each sample until FMOD closes down where it does a cleanup.
FSOUND_UNMANAGED can be used so FMOD does NOT use the sample management system. You have to make sure they are freed yourself.
--------
Specify FSOUND_LOADMEMORY to load a file from a memory image.
The pointer you pass to name must be the actual image of the data you want to load.
The length parameter is to be filled out if FSOUND_LOADMEMORY is specified, otherwise if you do not specify memory loading, can be safely ignored and should be set to 0.
--------
Compressed formats are expanded into memory. If the file is quite large, it could take a while to load.
--------
If FSOUND_8BITS is specified and the file decodes to 16bit normally, FMOD will downgrade the sample to 8bit.
--------
On PlayStation 2, the name_or_data pointer and length variables must be 16 byte aligned, for DMA reasons.
--------
Note that FSOUND_NONBLOCKING is NOT supported with this function.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Close , FSOUND_MODES , FSOUND_Sample_Alloc , FSOUND_Sample_Free


[API function]

FSOUND_Sample_Lock

Returns a pointer to the beginning of the sample data for a sample.
Data written to these pointers must be signed.

signed char F_API FSOUND_Sample_Lock(
FSOUND_SAMPLE *sptr,
int offset,
int length,
void **ptr1,
void **ptr2,
unsigned int *len1,
unsigned int *len2
);

Parameters

sptr | Pointer to the sample definition.
offset | Offset in BYTES to the position you want to lock in the sample buffer.
length | Number of BYTES you want to lock in the sample buffer.
ptr1 | Address of a pointer that will point to the first part of the locked data.
ptr2 | Address of a pointer that will point to the second part of the locked data. This will be NULL if the data locked hasnt wrapped at the end of the buffer.
len1 | Length of data in BYTES that was locked for ptr1
len2 | Length of data in BYTES that was locked for ptr2. This will be 0 if the data locked hasnt wrapped at the end of the buffer.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

You must always unlock the data again after you have finished with it, using FSOUND_Sample_Unlock.
For PCM based samples, data must be signed 8 or 16bit. For compressed samples such as those created with FSOUND_IMAADPCM, FSOUND_VAG, FSOUND_GCADPCM, the data must be in its original compressed format.
On PlayStation 2, with FSOUND_HW2D or FSOUND_HW3D based samples, this function does not return a readable or writable buffer, it returns the SPU2 address of the sample. To send data to it you must call FSOUND_SendData.
On GameCube, with FSOUND_HW2D or FSOUND_HW3D based samples, this function will not return the data contained within the sample. It is for upload purposes only.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_Unlock , FSOUND_Sample_Upload , FSOUND_SendData


[API function]

FSOUND_Sample_SetDefaults

Sets a sample's default attributes, so when it is played it uses these values without having to specify them later.

signed char F_API FSOUND_Sample_SetDefaults(
FSOUND_SAMPLE *sptr,
int deffreq,
int defvol,
int defpan,
int defpri
);

Parameters

sptr | Pointer to the sample to have its attributes set.
deffreq | Default sample frequency. The value here is specified in hz. -1 to ignore.
defvol | Default sample volume. This is a value from 0 to 255. -1 to ignore.
defpan | Default sample pan position. This is a value from 0 to 255 or FSOUND_STEREOPAN.
defpri | Default sample priority. This is a value from 0 to 255. -1 to ignore.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_GetDefaults , FSOUND_Sample_GetDefaultsEx , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_GetMode , FSOUND_Sample_SetDefaultsEx , FSOUND_Sample_SetMode , FSOUND_SetFrequency , FSOUND_SetPan , FSOUND_SetPriority , FSOUND_SetVolume


[API function]

FSOUND_Sample_SetDefaultsEx

Sets a sample's default attributes, so when it is played it uses these values without having to specify them later.

signed char F_API FSOUND_Sample_SetDefaultsEx(
FSOUND_SAMPLE *sptr,
int deffreq,
int defvol,
int defpan,
int defpri,
int varfreq,
int varvol,
int varpan
);

Parameters

sptr | Pointer to the sample to have its attributes set.
deffreq | Default sample frequency. The value here is specified in hz. -1 to ignore.
defvol | Default sample volume. This is a value from 0 to 255. -1 to ignore.
defpan | Default sample pan position. This is a value from 0 to 255 or FSOUND_STEREOPAN.
defpri | Default sample priority. This is a value from 0 to 255. -1 to ignore.
varfreq | Frequency variation in hz to apply to deffreq each time this sample is played. -1 to ignore.
varvol | Volume variation to apply to defvol each time this sample is played. -1 to ignore.
varpan | Pan variation to apply to defpan each time this sample is played. -1 to ignore.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Frequency, volume and pan variation values specify a +/- variation to the specified default frequency, volume and pan values i.e. with deffreq=44100, varfreq=2000 the actual frequency value used will be in the range 42100 -> 46100.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_GetDefaults , FSOUND_Sample_GetDefaultsEx , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_GetMode , FSOUND_Sample_SetDefaults , FSOUND_SetFrequency , FSOUND_SetPan , FSOUND_SetPriority , FSOUND_SetVolume


[API function]

FSOUND_Sample_SetMaxPlaybacks

Sets the maximum number of times a sample can play back at once.

signed char F_API FSOUND_Sample_SetMaxPlaybacks(
FSOUND_SAMPLE *sptr,
int max
);

Parameters

sptr Pointer to the sample to have its playback behaviour changed.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_PlaySound


[API function]

FSOUND_Sample_SetMinMaxDistance

Sets the minimum and maximum audible distance for a sample.
MinDistance is the minimum distance that the sound emitter will cease to continue growing
louder at (as it approaches the listener). Within the mindistance it stays at the constant loudest volume possible. Outside of this mindistance it begins to attenuate.
MaxDistance is the distance a sound stops attenuating at. Beyond this point it will stay at the volume it would be at maxdistance units from the listener and will not attenuate any more.
MinDistance is useful to give the impression that the sound is loud or soft in 3d space. An example of this is a small quiet object, such as a bumblebee, which you could set a mindistance of to 0.1 for example, which would cause it to attenuate quickly and dissapear when only a few meters away from the listener.
Another example is a jumbo jet, which you could set to a mindistance of 100.0, which would keep the sound volume at max until the listener was 100 meters away, then it would be hundreds of meters more before it would fade out.
-------
In summary, increase the mindistance of a sound to make it 'louder' in a 3d world, and
decrease it to make it 'quieter' in a 3d world.
maxdistance is effectively obsolete unless you need the sound to stop fading out at a certain point. Do not adjust this from the default if you dont need to.
Some people have the confusion that maxdistance is the point the sound will fade out to, this is not the case.

signed char F_API FSOUND_Sample_SetMinMaxDistance(
FSOUND_SAMPLE *sptr,
F_FLOAT_API min,
F_FLOAT_API max
);

Parameters

sptr | The sample to have its minimum and maximum distance set.
min | The samples minimum volume distance in "units". See remarks for more on units.
max | The samples maximum volume distance in "units". See remarks for more on units.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
The default units for minimum and maximum distances are 1.0 and 1000000000.0f.
Volume drops off at mindistance / distance.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_GetMinMaxDistance , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_3D_SetMinMaxDistance , FSOUND_Sample_GetMinMaxDistance


[API function]

FSOUND_Sample_SetMode

Sets a sample's mode. This can only be FSOUND_LOOP_OFF,FSOUND_LOOP_NORMAL, FSOUND_LOOP_BIDI or FSOUND_2D.
You cannot change the description of the contents of a sample or its location. FSOUND_2D will be ignored on the Win32 platform if FSOUND_HW3D was used to create the sample.

signed char F_API FSOUND_Sample_SetMode(
FSOUND_SAMPLE *sptr,
unsigned int mode
);

Parameters

sptr | Pointer to the sample to have the mode set.
mode | The mode bits to set from FSOUND_MODES.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Only the following modes are accepted, others will be filtered out.
FSOUND_LOOP_BIDI, FSOUND_LOOP_NORMAL, FSOUND_LOOP_OFF, FSOUND_2D.
Normally FSOUND_2D is accepted only if the sound is software mixed. If this is not set, the mode is set for the sample to be 3D processed.
-------------------
On Playstation 2, XBox and GameCube, FSOUND_HW2D and FSOUND_HW3D are supported, so you can change between them at runtime.
-------------------
On Windows, samples created with FSOUND_HW3D or FSOUND_HW2D do not support FSOUND_LOOP_BIDI. This is a limitation of Direct X.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetLoopMode , FSOUND_MODES , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_GetMode , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetLoopPoints


[API function]

FSOUND_Sample_SetLoopPoints

Sets a sample's loop points, specified in SAMPLES, not bytes.

signed char F_API FSOUND_Sample_SetLoopPoints(
FSOUND_SAMPLE *sptr,
int loopstart,
int loopend
);

Parameters

sptr | Pointer to the sample to have its loop points set.
loopstart | The starting position of the sample loop
loopend | The end position of the sample loop

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Samples created with FSOUND_HW3D and FSOUND_HW2D under the FSOUND_OUTPUT_DSOUND output mode do not support this function.
Loop points set on such a sample with be ignored, and the sample will loop in its entirety. This is a limitation of DirectSound.
On XBOX, GameCube and Playstation 2 hardware voices using compressed data (ie XADPCM, VAG or GCADPCM), these values will not be sample accurate, but will be rounded to the nearest compression block size.
On PlayStation 2, the loopend is ignored. The hardware cannot change the end address, so the loopend is always equivalent to length - 1 no matter what you set.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_SetMode


[API function]

FSOUND_Sample_Unlock

Releases previous sample data lock from FSOUND_Sample_Lock

signed char F_API FSOUND_Sample_Unlock(
FSOUND_SAMPLE *sptr,
void *ptr1,
void *ptr2,
unsigned int len1,
unsigned int len2
);

Parameters

sptr | Pointer to the sample definition.
ptr1 | Pointer to the 1st locked portion of sample data, from FSOUND_Sample_Lock.
ptr2 | Pointer to the 2nd locked portion of sample data, from FSOUND_Sample_Lock.
len1 | Length of data in BYTES that was locked for ptr1
len2 | Length of data in BYTES that was locked for ptr2. This will be 0 if the data locked hasnt wrapped at the end of the buffer.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_Lock , FSOUND_Sample_Upload


[API function]

FSOUND_Sample_Upload

This function uploads new sound data from memory to a preallocated/existing sample and does conversion based on the specified source mode.
If sample data already exists at this handle then it is replaced with the new data being uploaded.

signed char F_API FSOUND_Sample_Upload(
FSOUND_SAMPLE *sptr,
void *srcdata,
unsigned int mode_in
);

Parameters

sptr | Pointer to the destination sample
srcdata | Pointer to the source data to be uploaded. On PlayStation 2 this is an IOP address not an EE address.
mode | Description of the source data format. Bitwise OR in these bits to describe the data being passed in. See FSOUND_MODES for valid parameters and descriptions. FSOUND_HW3D, FSOUND_HW2D and FSOUND_LOOP modes are ignored, the mode describes the source format, not the destination format.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Note that on PlayStation 2 the source data address is an IOP address not an EE address.
To get data from EE RAM to the sample you must allocate some IOP memory, dma it to IOP memory then call upload. There are helper functions in fmodps2.h to achieve this.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Sample_Alloc , FSOUND_Sample_Lock , FSOUND_Sample_Unlock


[API function]

FSOUND_PlaySound

Plays a sample in a specified channel, using the sample's default frequency, volume
and pan settings.

int F_API FSOUND_PlaySound(
int channel,
FSOUND_SAMPLE *sptr
);

Parameters

channel | 0+ The absolute channel number in the channel pool. Remember software channels come first, followed by hardware channels. You cannot play a software sample on a hardware channel and vice versa. FSOUND_FREE Chooses a free channel to play in. If all channels are used then it selects a channel with a sample playing that has an EQUAL or LOWER priority than the sample to be played. FSOUND_ALL Passing this will cause ALL channels to play. (note this will make things VERY noisy!) If FSOUND_ALL is used the last channel success flag will be returned.
sptr | Pointer to the sample to be played.

Return Value

On success, the channel handle that was selected is returned.
On failure, -1 is returned.

Remarks

If you play a FSOUND_HW3D declared sample with this function, then the position and velocity
are set to those of the listener. Other attributes such as volume, frequency and pan are taken
from the sample's default volume, frequency, pan etc.
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
Basically it means the only sound you can change the attributes (ie volume/pan/frequency/3d position) for are the one you specifically called playsound for. If another sound steals that channel, and you keep trying to change its attributes (ie volume/pan/frequency/3d position), it will do nothing.
This is great if you have sounds being updated from tasks and you just forget about it.
You can keep updating the sound attributes and if another task steals that channel, your original task wont change the attributes of the new sound!!!
The lower 12 bits contain the channel number. (yes this means a 4096 channel limit for FMOD :)
The upper 19 bits contain the reference count.
The top 1 bit is the sign bit.
ie
S RRRRRRRRRRRRRRRRRRR CCCCCCCCCCCC
----------
Remember if not using FSOUND_FREE, then the channel pool is split up into software and hardware channels.
Software channels occupy the first n indicies specified by the value passed into FSOUND_Init.
Hardware channels occupy the next n indicies after this, and can be a variable amount, depending on the hardware.
Use FSOUND_GetNumHardwareChannels to query how many channels are available in hardware.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_FX_Enable , FSOUND_GetNumHardwareChannels , FSOUND_GetNumSubChannels , FSOUND_GetSubChannel , FSOUND_Init , FSOUND_PlaySoundEx , FSOUND_Sample_SetMaxPlaybacks , FSOUND_StopSound


[API function]

FSOUND_PlaySoundEx

Extended featured version of FSOUND_PlaySound.
New functionality includes the ability to start the sound paused.
This allows attributes of a channel to be set freely before the sound actually starts playing, until FSOUND_SetPaused(FALSE) is used.
Also added is the ability to associate the channel to a specified DSP unit. This allows the user to 'group' channels into seperate DSP units, which allows effects to be inserted between these 'groups', and allow various things like having one group affected by reverb (wet mix) and another group of channels unaffected (dry).
This is useful to seperate things like music from being affected by DSP effects, while other sound effects are.

int F_API FSOUND_PlaySoundEx(
int channel,
FSOUND_SAMPLE *sptr,
FSOUND_DSPUNIT *dspunit,
signed char startpaused
);

Parameters

channel | 0+ The absolute channel number in the channel pool. Remember software channels come first, followed by hardware channels. You cannot play a software sample on a hardware channel and vice versa. FSOUND_FREE Chooses a free channel to play in. If all channels are used then it selects a channel with a sample playing that has an EQUAL or LOWER priority than the sample to be played. FSOUND_ALL Plays the sound on all channels.
sptr | Pointer to the sample to be played.
dspunit | Optional. NULL by default. Pointer to a dsp unit to attach the channel to for channel grouping. Only attach a sound to a user created DSP unit, and not a system DSP unit.
paused | Start the sound paused or not. Pausing the sound allows attributes to be set before the sound starts.

Return Value

On success, the channel handle that was selected is returned.
On failure, -1 is returned.

Remarks

FSOUND_ALL is supported. Passing this will cause ALL channels to play. (note this could make things VERY noisy!)
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
This means the only sound you can change the attributes (ie volume/pan/frequency/3d position) for are the
one you specifically called playsound for. If another sound steals that channel, and you keep trying to
change its attributes (ie volume/pan/frequency/3d position), it will do nothing.
This is great if you have sounds being updated from tasks and you just forget about it.
You can keep updating the sound attributes and if another task steals that channel, your original task
wont change the attributes of the new sound!!!
The lower 12 bits contain the channel number. (yes this means a 4096 channel limit for FMOD :)
The upper 19 bits contain the reference count.
The top 1 bit is the sign bit.
ie
S RRRRRRRRRRRRRRRRRRR CCCCCCCCCCCC
----------
Remember if not using FSOUND_FREE, then the channel pool is split up into software and hardware channels.
Software channels occupy the first n indicies specified by the value passed into FSOUND_Init.
Hardware channels occupy the next n indicies after this, and can be a variable amount, depending on the hardware.
Use FSOUND_GetNumHardwareChannels to query how many channels are available in hardware.
----------
If you attach a sound to a DSP unit (for grouping purposes), the callback for the DSP unit will be overwritten with fmod's internal mixer callback, so the callback the user supplied is rendered obsolete and is not called.
Also, do not attach sounds to system DSP units, the assignment will be ignored if you do.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create , FSOUND_FX_Enable , FSOUND_GetNumSubChannels , FSOUND_GetSubChannel , FSOUND_Init , FSOUND_PlaySound , FSOUND_SetPaused , FSOUND_StopSound


[API function]

FSOUND_StopSound

Stops a specified sound channel from playing, and frees it up for re-use.

signed char F_API FSOUND_StopSound(
int channel
);

Parameters

channel The channel number/handle to stop. FSOUND_ALL can also be used (see remarks)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will cause ALL channels to stop.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_PlaySound , FSOUND_PlaySoundEx


[API function]

FSOUND_SetFrequency

Sets a channels frequency or playback rate, in HZ.

signed char F_API FSOUND_SetFrequency(
int channel,
int freq
);

Parameters

channel | The channel number/handle to change the frequency for. FSOUND_ALL can also be used (see remarks).
freq | The frequency to set. Valid ranges are from 100 to 705600, and -100 to -705600.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported here. Passing this will set ALL channels to specified frequency.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
Negative frequencies make the sound play backwards, so FSOUND_SetCurrentPosition would be needed to set the sound to the right position.
---------
NOTE: FSOUND_HW3D limitations in Direct Sound.
Every hardware device has a minimum and maximum frequency. You can determine these by looking at the DirectSound caps and viewing the members dwMaxSecondarySampleRate and dwMaxSecondarySampleRate.
FMOD clamps frequencies to these values when playing back on hardware, so if you are setting the frequency outside of this range, the frequency will stay at either dwMinSecondarySampleRate or dwMaxSecondarySampleRate.
To find out these two values in fmod (maybe whether to decide to drop back to software mixing or not), you can use the following code.
---------
include <dsound.h>
int minhwfreq, maxhwfreq;
if (FSOUND_GetNumHardwareChannels() && FSOUND_GetOutput() == FSOUND_OUTPUT_DSOUND)
{
HRESULT hr;
DSCAPS dscaps;
memset(&dscaps, 0, sizeof(DSCAPS));
dscaps.dwSize = sizeof(DSCAPS);
hr = IDirectSound_GetCaps((LPDIRECTSOUND)FSOUND_GetOutputHandle(), &dscaps);
minhwfreq = dscaps.dwMinSecondarySampleRate;
maxhwfreq = dscaps.dwMaxSecondarySampleRate;
}
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetFrequency , FSOUND_GetOutput , FSOUND_GetOutputHandle , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_SetCurrentPosition


[API function]

FSOUND_SetLevels

XBox Only - For surround sound systems, this function allows each surround speaker level to be set individually for this channel.

signed char F_API FSOUND_SetLevels(
int channel,
int frontleft,
int center,
int frontright,
int backleft,
int backright,
int lfe
);

Parameters

channel | The channel number/handle to change the output levels for. FSOUND_ALL and FSOUND_SYSTEMCHANNEL can also be used (see remarks)
frontleft | Value from 0 to 255 inclusive, specifying a linear level for the front left speaker.
center | Value from 0 to 255 inclusive, specifying a linear level for the center.
frontright | Value from 0 to 255 inclusive, specifying a linear level for the front right speaker.
backleft | Value from 0 to 255 inclusive, specifying a linear level for the back left speaker.
backright | Value from 0 to 255 inclusive, specifying a linear level for the back right speaker.
lfe | Value from 0 to 255 inclusive, specifying a linear level for the subwoofer speaker.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the pan of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
----------
FSOUND_SYSTEMCHANNEL is supported. You can set the mix levels for the FMOD software engine, and ALL software mixed sounds will be affected.
___________________
Supported on the following platforms : XBox

See Also

FSOUND_GetPan , FSOUND_Reverb_SetChannelProperties


[API function]

FSOUND_SetLoopMode

Sets the loop mode for a particular CHANNEL, not sample.

signed char F_API FSOUND_SetLoopMode(
int channel,
unsigned int loopmode
);

Parameters

channel | The channel number/handle to have its loop mode set.
loopmode | The loopmode to set. This can be FSOUND_LOOP_NORMAL, FSOUND_LOOP_BIDI or FSOUND_LOOP_OFF.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set loop modes for all channels available.
Note, this does not work for hardware sounds played on hardware channels while they are playing. The function has to be called when the channel is paused.
Software based sounds do not have this limitation, and can have their loop mode changed during playback, but for compatibility it is best to use the pause method, else you may get different behaviour if hardware voices do not exist.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_GetMode


[API function]

FSOUND_SetMute

Mutes and un-mutes a channel.

signed char F_API FSOUND_SetMute(
int channel,
signed char mute
);

Parameters

channel | The channel number/handle to mute/unmute. FSOUND_ALL can also be used (see remarks).
mute | Toggle value - TRUE mutes out the channel, FALSE reenables it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will mute/unmute ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetMute


[API function]

FSOUND_SetPan

Sets a channels pan position linearly

signed char F_API FSOUND_SetPan(
int channel,
int pan
);

Parameters

channel | The channel number/handle to change the pan for. FSOUND_ALL can also be used (see remarks)
pan | The panning position for this channel to set. parameters are: - from 0 (full left) to 255 (full right) - FSOUND_STEREOPAN. This is meant for stereo samples, but will work on mono samples as well. It makes both left and right FULL volume instead of 50/50 as middle panning does. See remarks section for more information on this.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the pan of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
----------
Important : If you are playing a STEREO sample, and using normal middle panning, it will only come out at half the volume
they are supposed to. To avoid this use FSOUND_STEREO pan.
Panning works in the following manner:
full left : 100to left, 0to right
full right : 0to left, 100to right
middle : 71to left, 71to right
FMOD Uses 'constant power' panning. The center position is 71 4749664n each channel as it keeps an even RMS output level when
moving the sound from left to right. Placing 50 4749664n each channel for a middle position is incorrect.
The pan graph for constant power panning resembles a curve instead of straight lines.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetPan , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_Stream_Play , FSOUND_Stream_PlayEx


[API function]

FSOUND_SetPaused

Pauses or unpauses a sound channel.

signed char F_API FSOUND_SetPaused(
int channel,
signed char paused
);

Parameters

channel | The channel number/handle to pause or unpause. FSOUND_ALL can also be used (see remarks).
paused | TRUE pauses this channel, FALSE unpauses it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will pause/unpause ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_FX_Enable , FSOUND_GetPaused , FSOUND_PlaySoundEx , FSOUND_Stream_PlayEx


[API function]

FSOUND_SetPriority

Sets a channels priority. Higher priority means it is less likely to get discarded when
FSOUND_FREE is used to select a channel, when all channels are being used, and one has to
be rejected. If a channel has an equal priority then it will be replaced.

signed char F_API FSOUND_SetPriority(
int channel,
int priority
);

Parameters

channel | The channel number/handle to change the priority for. FSOUND_ALL can also be used (see remarks).
priority | The priority to set. Valid ranges are from 0 (lowest) to 255 (highest)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the priority of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetPriority , FSOUND_GetReserved , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_SetReserved


[API function]

FSOUND_SetReserved

This sets the reserved status of a channel. Reserving a channel is related to setting its
priority, but reserving a channel means it can NEVER be stolen by a channel request. It
could be thought of as an extra high priority, but is different in that reserved channels do
not steal from each other, whereas channels with equal priorities do (unless there are
channels with lower priorities that it can steal from). If all channels were reserved and
another request for came in for a channel, it would simply fail and the sound would not be
played.

signed char F_API FSOUND_SetReserved(
int channel,
signed char reserved
);

Parameters

channel | The channel number/handle to change the priority for. FSOUND_ALL can also be used (see remarks). FSOUND_FREE is NOT accepted.
reserved | Reserved flag. Values accepted are TRUE, to reserve a channel, and FALSE to un-reserve a channel.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set ALL channels to be reserved/unreserved.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetPriority , FSOUND_GetReserved , FSOUND_SetPriority


[API function]

FSOUND_SetSurround

Sets a channels surround sound status. This surround sound is a fake dolby trick that
effectively pans the channel to the center, but inverts the waveform in one speaker to
make it sound fuller or spacier, or like it is coming out of space between the 2 speakers.
Panning is ignored while surround is in effect.

signed char F_API FSOUND_SetSurround(
int channel,
signed char surround
);

Parameters

channel | The channel number/handle to change the surround for. FSOUND_ALL can also be used (see remarks).
surround | Toggle value - TRUE enables surround sound on the channel, FALSE disables it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the surround sound mode of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
---------
Note this only works on software channels.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation2, GameCube

See Also

FSOUND_GetSurround


[API function]

FSOUND_SetVolume

Sets a channels volume linearly.
This function IS affected by FSOUND_SetSFXMasterVolume.

signed char F_API FSOUND_SetVolume(
int channel,
int vol
);

Parameters

channel | The channel number/handle to change the volume for. FSOUND_ALL can also be used (see remarks)
vol | The volume to set. Valid ranges are from 0 (silent) to 255 (full volume)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the volume of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetAmplitude , FSOUND_GetSubChannel , FSOUND_GetVolume , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetDefaultsEx , FSOUND_SetSFXMasterVolume , FSOUND_SetVolumeAbsolute , FSOUND_Stream_Play , FSOUND_Stream_PlayEx


[API function]

FSOUND_SetVolumeAbsolute

Sets a channels volume linearly.
This function is NOT affected by master volume.
This function is used when you want to quiet everything down using FSOUND_SetSFXMasterVolume, but make
a channel prominent.

signed char F_API FSOUND_SetVolumeAbsolute(
int channel,
int vol
);

Parameters

channel | The channel number/handle to change the volume for. FSOUND_ALL can also be used (see remarks)
vol | The volume to set. Valid ranges are from 0 (silent) to 255 (full volume)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the absolute volume of ALL channels available.
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
-------------
A good example of this function being used for a game needing a voice over.
If all the background sounds were too loud and drowned out the voice over, there is no way to
feasibly go through all the sfx channels and lower the background noise volumes (some might be allocated by music).
Simply lower the background noise with FSOUND_SetSFXMasterVolume, and use FSOUND_SetVolumeAbsolute to bring
up the volume of the voice over to full, and you will get one channel standing out amongst the rest.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetVolume , FSOUND_SetSFXMasterVolume , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute


[API function]

FSOUND_GetVolume

Returns the linear volume of the specified channel between 0 and 255

int F_API FSOUND_GetVolume(
int channel
);

Parameters

channel The channel number/handle to get the volume from.

Return Value

On success, the following values are returned : 0 = silent to 255 = full volume.
On failure, 0 is returned. To quailfy if this is a real error, call FSOUND_GetError.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetError , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute


[API function]

FSOUND_GetAmplitude

Returns the volume of the channel based on all combinations of set volume, mastervolume and 3d position.
Works on software and hardware voices.

int F_API FSOUND_GetAmplitude(
int channel
);

Parameters

channel The channel number/handle to get the amplitude from.

Return Value

On success, the following values are returned : 0 = silent to 255 = full volume.
On failure, 0 is returned. To quailfy if this is a real error, call FSOUND_GetError.

Remarks

This is not the same as FSOUND_GetCurrentLevels, as that function takes the actual waveform data into account.
This function simply gives a final volume based on 3d position and volume settings.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetCurrentLevels , FSOUND_GetError , FSOUND_SetVolume


[API function]

FSOUND_3D_SetAttributes

This updates the position and velocity of a 3d sound playing on a channel.

signed char F_API FSOUND_3D_SetAttributes(
int channel,
const F_FLOAT_API *pos,
const F_FLOAT_API *vel
);

Parameters

channel | Channel you want to apply 3d positioning to.
pos | Pointer to a position vector (xyz float triplet) of the emitter in world space, measured in distance units. This can be NULL to ignore it.
vel | Pointer to a velocity vector (xyz float triplet), of the emitter measured in distance units PER SECOND. This can be NULL to ignore it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND treats +X as right, +Y as up, and +Z as forwards.
---------
A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
---------
FSOUND vectors expect 3 floats representing x y and z in that order. I.e. a typical definition
of a vector is
typedef struct
{
float x;
float y;
float z;
} VECTOR;
or simply an array of 3 floats.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_GetMinMaxDistance , FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetCurrent , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_3D_SetMinMaxDistance , FSOUND_3D_SetRolloffFactor , FSOUND_Sample_SetMinMaxDistance , FSOUND_Update


[API function]

FSOUND_3D_SetMinMaxDistance

Sets the minimum and maximum audible distance for a channel.
MinDistance is the minimum distance that the sound emitter will cease to continue growing
louder at (as it approaches the listener). Within the mindistance it stays at the constant loudest volume possible. Outside of this mindistance it begins to attenuate.
MaxDistance is the distance a sound stops attenuating at. Beyond this point it will stay at the volume it would be at maxdistance units from the listener and will not attenuate any more.
MinDistance is useful to give the impression that the sound is loud or soft in 3d space. An example of this is a small quiet object, such as a bumblebee, which you could set a mindistance of to 0.1 for example, which would cause it to attenuate quickly and dissapear when only a few meters away from the listener.
Another example is a jumbo jet, which you could set to a mindistance of 100.0, which would keep the sound volume at max until the listener was 100 meters away, then it would be hundreds of meters more before it would fade out.
-------
In summary, increase the mindistance of a sound to make it 'louder' in a 3d world, and
decrease it to make it 'quieter' in a 3d world.
maxdistance is effectively obsolete unless you need the sound to stop fading out at a certain point. Do not adjust this from the default if you dont need to.
Some people have the confusion that maxdistance is the point the sound will fade out to, this is not the case.

signed char F_API FSOUND_3D_SetMinMaxDistance(
int channel,
F_FLOAT_API min,
F_FLOAT_API max
);

Parameters

sptr | The channel to have its minimum and maximum distance set.
min | The channels minimum volume distance in "units". See remarks for more on units.
max | The channels maximum volume distance in "units". See remarks for more on units.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will set the min/max distance on ALL channels available.
A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
The default units for minimum and maximum distances are 1.0 and 1000000000.0f.
Volume drops off at mindistance / distance.
To define the min and max distance per sound and not per channel use FSOUND_Sample_SetMinMaxDistance.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_GetMinMaxDistance , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_SetCurrentPosition

Sets the current position of the sound in SAMPLES not bytes.

signed char F_API FSOUND_SetCurrentPosition(
int channel,
unsigned int pos
);

Parameters

channel | The channel number/handle to have its offset or position set.
offset | The offset in SAMPLES from the start of the sound for the position to be set to.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this set the current position for the sound on ALL channels available.
On XBOX, GameCube and Playstation 2 hardware voices using compressed data (ie XADPCM, VAG or GCADPCM),
this value will not be sample accurate, but will be rounded to the nearest compression block size.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetCurrentPosition , FSOUND_SetFrequency


[API function]

FSOUND_GetCurrentPosition

Returns the current playcursor position of the specified channel.

unsigned int F_API FSOUND_GetCurrentPosition(
int channel
);

Parameters

channel Channel number/handle to get the current position from.

Return Value

On success, the play cursor position in SAMPLES is returned for the specified channel.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Record_StartSample , FSOUND_SetCurrentPosition


[API function]

FSOUND_GetCurrentSample

Returns the current sample being played on the specified channel.

FSOUND_SAMPLE * F_API FSOUND_GetCurrentSample(
int channel
);

Parameters

channel Channel number/handle to get the currently playing sample from.

Return Value

On success, a pointer to a sample handle is returned for the specified channel.
On failure, NULL is returned.

Remarks

Note that current sample does not return to NULL when a sound has ended.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_GetCurrentLevels

Returns a left and right VU/Level reading at the current position of the specified channel.
Levels are are only supported for software channels.

DLL_API signed char F_API FSOUND_GetCurrentLevels(
int channel,
F_FLOAT_API *l,
F_FLOAT_API *r
);

Parameters

channel | Channel number/handle to retrieve left and right level from.
l | Pointer to a floating point value to store left level, between 0 and 1.
r | Pointer to a floating point value to store right level, between 0 and 1.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

By default this function is only point sampled and not latency adjusted (it will appear to trigger ahead of when you hear the sound).
To fix this and get a 'perfect' set of levels in realtime, use FSOUND_INIT_ACCURATEVULEVELS with FSOUND_Init.
-------------------
To get an overall VU reading for all sounds, add all VU values for each channel together, and then clip at 1.0.
Another (harder) way is to write a dsp unit that reads from the mixbuffer being passed into it.
Note: A true 'VU' should be smoothed, but in case people were after more accuracy than a smoothed value, it was decided to return the raw amplitude, and let the user smooth the result in their own way.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetAmplitude , FSOUND_Init


[API function]

FSOUND_GetFrequency

Returns the frequency in HZ of the specified channel.

int F_API FSOUND_GetFrequency(
int channel
);

Parameters

channel The number/handle to get the frequency from.

Return Value

On success, the frequency in HZ of the specified channel is returned.
On failure, 0 is returned. To quailfy if this is a real error, call FSOUND_GetError.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetError , FSOUND_SetFrequency


[API function]

FSOUND_GetLoopMode

Gets the loop mode for a particular channel.

unsigned int F_API FSOUND_GetLoopMode(
int channel
);

Parameters

channel The channel number/handle to get the loop mode from.

Return Value

On success, the loop mode is returned.
On failure, 0 is returned.

Remarks

This works for all channel types, whereas setting it will not work.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Sample_SetMode


[API function]

FSOUND_GetMixer

Returns the currently used mixer type.

int F_API FSOUND_GetMixer(
);

Return Value

FSOUND_GetMixer returns a defenition from FSOUND_MIXERTYPES. See FSOUND_MIXERTYPES for valid
parameters and descriptions.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_MixBuffers , FSOUND_GetMixer , FSOUND_MIXERTYPES , FSOUND_SetMixer


[API function]

FSOUND_GetMute

Returns if the channel specified is muted or not

signed char F_API FSOUND_GetMute(
int channel
);

Parameters

channel The channel number/handle to get the mute status from

Return Value

TRUE - The channel has mute turned ON
FALSE - The channel has mute turned OFF

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetMute


[API function]

FSOUND_GetNumSubChannels

This function returns the number of sub-channels stored in a multi-channel channel handle, which is only possible when playing back a multichannel .FSB file.

int F_API FSOUND_GetNumSubChannels(
int channel
);

Parameters

channel The value returned by FSOUND_Stream_Play, FSOUND_Stream_PlayEx, FSOUND_PlaySound, FSOUND_PlaySoundEx.

Return Value

On success, the number of subchannels is returned
On failure, 0 is returned.

Remarks

A multichannel sound, only possible with the .FSB format, can contain multiple subchannels. When a multichannel sound is played, multiple channels are allocated at the same time.
For example, a 8 sounds/streams can be interleaved into a multichannel FSB. This function would return 8, as 8 real hardware/software voices are used during playback.
FSOUND_GetSubChannel can be used to get access to the secondary channels.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetSubChannel , FSOUND_PlaySound , FSOUND_PlaySoundEx , FSOUND_Stream_Play , FSOUND_Stream_PlayEx


[API function]

FSOUND_GetPan

Returns the linear pan position of the specified channel between 0 and 255

int F_API FSOUND_GetPan(
int channel
);

Parameters

channel The channel number/handle to get the pan from.

Return Value

On success, the following values are returned : 0 = full left to 128 = middle to 255 = full right, FSOUND_STEREOPAN
On failure, 0 is returned. To quailfy if this is a real error, call FSOUND_GetError.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetError , FSOUND_SetLevels , FSOUND_SetPan


[API function]

FSOUND_GetPaused

Gets current pause status of the channel.

signed char F_API FSOUND_GetPaused(
int channel
);

Parameters

channel The channel number/handle to get the paused status from.

Return Value

TRUE - The channel is currently paused.
FALSE - The channel is running.

Remarks

This function is useful for games that have a pause mode, and you dont want the sounds
to continue playing, but you would like them to continue on from where they left off
when you unpause.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetPaused


[API function]

FSOUND_GetPriority

Gets a sound channels priority. Priority is used to determine if soundeffects should
replace other sound effects when the channel limit has been reached. See
FSOUND_SetPriority for more information.

int F_API FSOUND_GetPriority(
int channel
);

Parameters

channel The channel number/handle to get the priority from.

Return Value

On success, the priority of the channel is returned. Ranges between 0 and 255.
On failure, 0 is returned. To quailfy if this is a real error, call FSOUND_GetError.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetError , FSOUND_SetPriority , FSOUND_SetReserved


[API function]

FSOUND_GetReserved

Gets a sound channels reserved status. priority is used to determine if soundeffects should muscle
out other sound effects when the channel limit has been reached.

signed char F_API FSOUND_GetReserved(
int channel
);

Parameters

channel The channel number/handle to get the reserved status from.

Return Value

TRUE Channel is reserved and cannot be selected.
FALSE Channel is reserved and can be selected.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetPriority , FSOUND_SetReserved


[API function]

FSOUND_GetSubChannel

This function returns a channel handle from a subchannel within a multichannel FSB file, so that it can be maniuplated seperately, instead of controlling the whole multichannel array with the parent channel that the user retrieves from FSOUND_PlaySound etc.

int F_API FSOUND_GetSubChannel(
int channel,
int subchannel
);

Parameters

channel | The value returned by FSOUND_Stream_Play, FSOUND_Stream_PlayEx, FSOUND_PlaySound, FSOUND_PlaySoundEx.
subchannel | Offset from the parent channel into the multichannel array.

Return Value

On success, a raw channel handle is returned.
On failure, -1 is returned.

Remarks

A multichannel sound, only possible with the .FSB format, can contain multiple subchannels. When a multichannel sound is played, multiple channels are allocated at the same time.
Normally you can just use the parent handle, and things like FSOUND_SetVolume will affect all subchannels at the same time. With this function, you can get access to the raw subchannels to allow manipulation of each voice seperately within the multichannel array.
For example, a 8 sounds/streams can be interleaved into a multichannel FSB. If you specified a subchannel of 7, it would return a channel handle to the last channel in the multichannel array.
A subchannel index of 0 is the parent channel, and the same as the voice passed in is a parameter.
The number of subchannels within a multichannel voice can be determined with FSOUND_GetNumSubChannels.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetNumSubChannels , FSOUND_PlaySound , FSOUND_PlaySoundEx , FSOUND_SetVolume , FSOUND_Stream_Play , FSOUND_Stream_PlayEx


[API function]

FSOUND_GetSurround

Returns the surround sound status of the specified channel.

signed char F_API FSOUND_GetSurround(
int channel
);

Parameters

channel The channel number/handle to get the surround sound status from.

Return Value

On success, TRUE is returned meaning the channel has surround sound turned ON
On failure, FALSE is returned meaning the channel has surround sound turned OFF

Remarks

Surround sound only works on software channels.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetSurround


[API function]

FSOUND_IsPlaying

Returns if the channel is currently playing or not.

signed char F_API FSOUND_IsPlaying(
int channel
);

Parameters

channel Channel number/handle to get the playing status from.

Return Value

TRUE channel is currently active and playing
FALSE channel is currently idle.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_3D_GetAttributes

signed char F_API FSOUND_3D_GetAttributes(
int channel,
F_FLOAT_API *pos,
F_FLOAT_API *vel
);

Parameters

channel | Channel you want to get 3d information from
pos | Pointer to a position vector (xyz float triplet) of the emitter in world space, measured in distance units. This can be NULL to ignore it.
vel | Pointer to a velocity vector (xyz float triplet), of the emitter measured in distance units PER SECOND. This can be NULL to ignore it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_GetMinMaxDistance

Returns the current min and max distance for a channel.

DLL_API signed char F_API FSOUND_3D_GetMinMaxDistance(
int channel,
F_FLOAT_API *mindistance,
F_FLOAT_API *maxdistance
);

Parameters

channel | Channel number/handle to retrieve min and max distance from.
mindistance | Pointer to a floating point value to store mindistance.
maxdistance | Pointer to a floating point value to store maxdistance.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_SetAttributes , FSOUND_3D_SetMinMaxDistance , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_Listener_GetAttributes

This retrieves the position, velocity and orientation of a 3d sound listener.

void F_API FSOUND_3D_Listener_GetAttributes(
F_FLOAT_API *pos,
F_FLOAT_API *vel,
F_FLOAT_API *fx,
F_FLOAT_API *fy,
F_FLOAT_API *fz,
F_FLOAT_API *tx,
F_FLOAT_API *ty,
F_FLOAT_API *tz
);

Parameters

pos | Pointer to a position vector (xyz float triplet), of the listener in world space, measured in distance units. This can be NULL to ignore it.
vel | Pointer to a velocity vector (xyz float triplet), of the listener measured in distance units PER SECOND. This can be NULL to ignore it.
fx | pointer to x component of a FORWARD unit length orientation vector This can be NULL to ignore it.
fy | pointer to y component of a FORWARD unit length orientation vector This can be NULL to ignore it.
fz | pointer to z component of a FORWARD unit length orientation vector This can be NULL to ignore it.
tx | pointer to x component of a TOP or upwards facing unit length orientation vector This can be NULL to ignore it.
ty | pointer to y component of a TOP or upwards facing unit length orientation vector This can be NULL to ignore it.
tz | pointer to z component of a TOP or upwards facing unit length orientation vector This can be NULL to ignore it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND treats +X as right, +Y as up, and +Z as forwards. (left handed)
To map to your own coordinate system, flip and exchange these values. For example if you wanted to use right handed coordinates, you would negate the Z value of your own direction vector.
Orientation vectors are expected to be of UNIT length. This means the magnitude of the vector should be 1.0f.
---------
A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
---------
Please remember to use units PER SECOND, NOT PER FRAME as this is a common mistake.
Do not just use (pos - lastpos) from the last frame's data for velocity, as this is not correct.
You need to time compensate it so it is given in units per SECOND.
You could alter your pos - lastpos calculation to something like this.
vel = (pos-lastpos) / (time taken since last frame in seconds).
I.e. at 60fps the formula would look like this
vel = (pos-lastpos) / 0.0166667.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_SetCurrent , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_3D_SetDopplerFactor


[API function]

FSOUND_3D_Listener_SetAttributes

This updates the position, velocity and orientation of a 3d sound listener.

void F_API FSOUND_3D_Listener_SetAttributes(
const F_FLOAT_API *pos,
const F_FLOAT_API *vel,
F_FLOAT_API fx,
F_FLOAT_API fy,
F_FLOAT_API fz,
F_FLOAT_API tx,
F_FLOAT_API ty,
F_FLOAT_API tz
);

Parameters

pos | Pointer to a position vector (xyz float triplet), of the listener in world space, measured in distance units. This can be NULL to ignore it.
vel | Pointer to a velocity vector (xyz float triplet), of the listener measured in distance units PER SECOND. This can be NULL to ignore it.
fx | x component of a FORWARD unit length orientation vector
fy | y component of a FORWARD unit length orientation vector
fz | z component of a FORWARD unit length orientation vector
tx | x component of a TOP or upwards facing unit length orientation vector
ty | y component of a TOP or upwards facing unit length orientation vector
tz | z component of a TOP or upwards facing unit length orientation vector

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND treats +X as right, +Y as up, and +Z as forwards. (left handed)
To map to your own coordinate system, flip and exchange these values. For example if you wanted to use
right handed coordinates, you would negate the Z value of your own direction vector.
Orientation vectors are expected to be of UNIT length. This means the magnitude of the vector
should be 1.0f.
---------
A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor. By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
---------
Please remember to use units PER SECOND, NOT PER FRAME as this is a common mistake.
Do not just use (pos - lastpos) from the last frame's data for velocity, as this is not
correct. You need to time compensate it so it is given in units per SECOND.
You could alter your pos - lastpos calculation to something like this.
vel = (pos-lastpos) / (time taken since last frame in seconds). Ie at 60fps the formula
would look like this vel = (pos-lastpos) / 0.0166667.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_SetCurrent , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor , FSOUND_3D_SetDopplerFactor , FSOUND_3D_SetRolloffFactor , FSOUND_Update


[API function]

FSOUND_3D_Listener_SetCurrent

Sets the current listener number and number of listeners, if the user wants to simulate multiple listeners at once.
This is usually for the case in a game where there is a splitscreen and multiple players playing the game at once.

void F_API FSOUND_3D_Listener_SetCurrent(
int current,
int numlisteners
);

Parameters

current | Current listener number. Listener commands following this function call will affect this listener number. (default: 0)
numlisteners | Number of listeners active. (default: 1)

Return Value

void

Remarks

Only affects FSOUND_3D_Listener_SetAttributes and FSOUND_3D_Listener_GetAttributes.
Setting more than 1 listener will turn off doppler and cause all panning to be ignored and 3d sound will come from the center (mono).
-------------
For WIN32 FSOUND_HW3D based sounds, channels must have their attributes set after this function is called, otherwise unexpected audible results may occur.
For example you cannot update your channels with FSOUND_3D_SetAttributes, call FSOUND_3D_Listener_SetCurrent, and then call FSOUND_Update and expect all the voices to update correctly.
The correct order is to call FSOUND_3D_Listener_SetCurrent first, then update all channels with FSOUND_3D_SetAttributes, then call FSOUND_Update.
This is due to DirectSound not supporting multiple listeners, so FMOD has to do inverse transforms on the positions to simulate it with one listener, at the time FSOUND_3D_SetAttributes is called.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetCurrent , FSOUND_3D_SetAttributes , FSOUND_Update


[API function]

FSOUND_3D_SetDistanceFactor

Sets FMOD's 3d engine relative distance factor, compared to 1.0 meters. It equates to
'how many units per meter' does your engine have.

void F_API FSOUND_3D_SetDistanceFactor(
F_FLOAT_API factor
);

Parameters

scale 1.0 = 1 meter units. If you are using feet then scale would equal 3.28.

Return Value

void

Remarks

By default this value is set at 1.0, or meters.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_SetAttributes , FSOUND_3D_SetMinMaxDistance , FSOUND_3D_SetRolloffFactor , FSOUND_Sample_GetMinMaxDistance , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_SetDopplerFactor

Sets the doppler shift scale factor.

void F_API FSOUND_3D_SetDopplerFactor(
F_FLOAT_API scale
);

Parameters

scale Doppler shift scale. Default value for FSOUND is 1.0f

Return Value

void

Remarks

This is a general scaling factor for how much the pitch varies due to doppler shifting.
Increasing the value above 1.0 exaggerates the effect, whereas lowering it reduces the effect.
0 removes the effect all together.
FMOD's speed of sound at a DopplerFactor of 1.0 is 340 m/s.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_Update


[API function]

FSOUND_3D_SetRolloffFactor

Sets the global attenuation rolloff factor.
Normally volume for a sample will scale at 1 / distance. This gives a logarithmic attenuation of volume as the source gets further away (or closer).
Setting this value makes the sound drop off faster or slower. The higher the value, the faster volume will fall off.
The lower the value, the slower it will fall off.
For example a rolloff factor of 1 will simulate the real world, where as a value of 2 will make sounds attenuate 2 times quicker.

void F_API FSOUND_3D_SetRolloffFactor(
F_FLOAT_API factor
);

Parameters

rolloff The rolloff factor to set for this sample. Valid ranges are 0 to 10.

Return Value

void

Remarks

---------
A 'distance unit' is specified by FSOUND_3D_SetDistanceFactor.
By default this is set to meters which is a distance scale of 1.0.
See FSOUND_3D_SetDistanceFactor for more on this.
---------
The default rolloff factor is 1.0.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_SetAttributes , FSOUND_3D_SetDistanceFactor


[API function]

FSOUND_Stream_AddSyncPoint

Adds a user synchronization callback point into a stream.

DLL_API FSOUND_SYNCPOINT * F_API FSOUND_Stream_AddSyncPoint(
FSOUND_STREAM *stream,
unsigned int pcmoffset,
const char *name
);

Parameters

stream | The stream to add a sync point to.
pcmoffset | Offset in SAMPLES (not bytes).
name | The name of the syncpoint, which will be passed into the sync callback when it is triggered.

Return Value

On success, a sync point handle is returned.
On failure, NULL is returned.

Remarks

If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_DeleteSyncPoint , FSOUND_Stream_GetNumSyncPoints , FSOUND_Stream_GetSyncPoint , FSOUND_Stream_GetSyncPointInfo , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_Stream_Close

Shuts down and releases an FSOUND stream.

signed char F_API FSOUND_Stream_Close(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to be closed down.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
The only exception to this rule is for internet streams - this function will successfully close an internet stream that has been opened with FSOUND_NONBLOCKING before that stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_Create , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_PlayEx , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Create

Creates a user definable stream file ready for playing. The stream is serviced through a callback.

DLL_API FSOUND_STREAM * F_API FSOUND_Stream_Create(
FSOUND_STREAMCALLBACK callback,
int lenbytes,
unsigned int mode,
int samplerate,
void *userdata
);

Parameters

callback | A pointer to a user defined stream callback function.
lenbytes | Size of the data in BYTES the callback will require to be written to the buffer.
mode | Description of the raw sample data being opened. see FSOUND_MODES for a description of these modes.
samplerate | Rate of playback. Be careful you dont set the sample rate too high so that the stream servicer (ie the harddisk) may not keep up.
userdata | User data that is passed back into the stream callback when triggered.

Return Value

On success, a pointer to an opened stream is returned.
On failure, NULL is returned.

Remarks

This method only supports SIGNED RAW streams to be written to the buffer supplied by the callback.
They can be 8 or 16 bit, mono or stereo.
'lenbytes' may be rounded down to the nearest sample alignment in bytes. Ie if you specified 1001 bytes for a 16bit stereo sample stream, len would return 1000 in the callback. (250 samples * 4 bytes per sample)
PlayStation 2 IMPORTANT! : if FSOUND_SendData is NOT called from the stream callback the IOP will hang because it is waiting for this command to be executed before it can unlock its buffer.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_SendData , FSOUND_Stream_Close , FSOUND_Stream_Play , FSOUND_Stream_PlayEx , FSOUND_Stream_SetBufferSize , FSOUND_Stream_Stop , FSOUND_STREAMCALLBACK


[API function]

FSOUND_Stream_CreateDSP

Allows the user to add a custom DSP unit to a stream.

FSOUND_DSPUNIT *F_API FSOUND_Stream_CreateDSP(
FSOUND_STREAM *stream,
FSOUND_DSPCALLBACK callback,
int priority,
void *userdata
);

Parameters

stream | The stream pointer to have a DSP attached to.
callback | A standard FSOUND_DSPCALLBACK function callback pointer.
priority | The priority, or position within the streams DSP chain to place the unit.
param | A user parameter that gets passed back into the DSP callback.

Return Value

On success, a handle to the FSOUND_DSPUNIT is returned. All DSP functions are performable on this.
On failure, 0 is returned.

Remarks

The priority for a stream DSP unit is not related to the priorities specified in fmod.h.
The priorities are anything fom 0 onwards, and ALWAYS come after data is read/decoded for the stream.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSPCALLBACK


[API function]

FSOUND_Stream_DeleteSyncPoint

Removes a user synchronization callback point from a stream.

DLL_API signed char F_API FSOUND_Stream_DeleteSyncPoint(
FSOUND_SYNCPOINT *point
);

Parameters

point The sync point to remove

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_AddSyncPoint , FSOUND_Stream_GetNumSyncPoints , FSOUND_Stream_GetSyncPoint , FSOUND_Stream_GetSyncPoints , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_Stream_FindTagField

Find a tag field associated with an open stream by name and type.

signed char F_API FSOUND_Stream_FindTagField(
FSOUND_STREAM *stream,
int type,
const char *name,
void **value,
int *length
);

Parameters

stream | The stream to get the tag field from.
type | The type of the tag field to retrieve. See FSOUND_TAGFIELD_TYPE.
name | The name of the tag field to retrieve.
value | Pointer to a variable that will receive a pointer to the tag field data.
length | Pointer to a variable that will receive the length of the tag field data.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Stream_GetNumTagFields , FSOUND_Stream_GetTagField , FSOUND_TAGFIELD_TYPE


[API function]

FSOUND_Stream_GetLength

Returns the size of the stream in BYTES.

int F_API FSOUND_Stream_GetLength(
FSOUND_STREAM *stream
);

Parameters

stream A pointer to the stream to have its length returned.

Return Value

On success, the size of the stream in BYTES is returned.
On failure, 0 is returned.

Remarks

Position functions for streams work in bytes not samples.
-----
This function is not supported for URL based streams over the internet.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetLengthMs , FSOUND_Stream_GetPosition , FSOUND_Stream_Open , FSOUND_Stream_SetPosition , FSOUND_Stream_SetTime


[API function]

FSOUND_Stream_GetLengthMs

Returns the size of the stream in MILLISECONDS.

int F_API FSOUND_Stream_GetLengthMs(
FSOUND_STREAM *stream
);

Parameters

stream A pointer to the stream to have its total duration returned.

Return Value

On success, the size of the stream in MILLISECONDS is returned.
On failure, 0 is returned.

Remarks

FSOUND_MPEGACCURATE will need to be used with mp3 files that use VBR encoding for more accuracy.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_Open


[API function]

FSOUND_Stream_GetMode

Retrieves the mode of the stream.

unsigned int F_API FSOUND_Stream_GetMode(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to get the mode from.

Return Value

Remarks

If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_SetMode


[API function]

FSOUND_Stream_GetNumSubStreams

Returns the number of substreams inside a multi-stream FSB bank file.

int F_API FSOUND_Stream_GetNumSubStreams(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to query.

Return Value

On success, the number of FSB substreams is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_SetSubStream , FSOUND_Stream_SetSubStreamSentence


[API function]

FSOUND_Stream_GetNumSyncPoints

Returns the number of sync points within a stream.

DLL_API int F_API FSOUND_Stream_GetNumSyncPoints(
FSOUND_STREAM *stream
);

Parameters

stream The stream to request the number of sync points from.

Return Value

On success, The number of sync points in a stream are returned.
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_AddSyncPoint , FSOUND_Stream_DeleteSyncPoint , FSOUND_Stream_GetSyncPointInfo , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_Stream_GetNumTagFields

Get the number of tag fields associated with the specified stream.

signed char F_API FSOUND_Stream_GetNumTagFields(
FSOUND_STREAM *stream,
int *num
);

Parameters

stream | The stream to get the number of tag fields for.
num | Pointer to a variable that will receive the nubmer of tag fields associated with the specified stream.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Stream_FindTagField , FSOUND_Stream_GetTagField


[API function]

FSOUND_Stream_GetOpenState

If a stream is opened with FSOUND_NONBLOCKING, this function returns the state of the opening stream.

int F_API FSOUND_Stream_GetOpenState(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to get the open state from.

Return Value

0 = stream is opened and ready.
-1 = stream handle passed in is invalid.
-2 = stream is still opening or performing a SetSubStream command.
-3 = stream failed to open. (file not found, out of memory or other error).
-4 = connecting to remote host (internet streams only)
-5 = stream is buffering data (internet streams only)

Remarks

A blocking stream will return NULL from FSOUND_Stream_Open so a return value of -3 is redundant in this case.
A blocking stream will always return 0 if it is not NULL.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_Open , FSOUND_Stream_SetSubStream , FSOUND_Stream_SetSubStreamSentence


[API function]

FSOUND_Stream_GetPosition

Returns the current FILE position of the stream of the stream in BYTES.

unsigned int F_API FSOUND_Stream_GetPosition(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to have its position returned.

Return Value

On success, the current stream's position in BYTES is returned.
On failure, 0 is returned.

Remarks

Position functions for streams work in bytes not samples.
Position information is also based on the current file position, not the actual playing
position, so if the stream is only updated every 100ms, then the position will only be
updated every 100ms.
-----
This function is not supported for URL based streams over the internet or CDDA streams
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_SetPosition , FSOUND_Stream_SetTime


[API function]

FSOUND_Stream_GetSample

Returns the FSOUND_SAMPLE definition that the stream uses internally.
You can use this to get a variety of information like the songs name, default speed and more.

FSOUND_SAMPLE * F_API FSOUND_Stream_GetSample(
FSOUND_STREAM *stream
);

Parameters

stream A pointer to the stream to have its internal sample pointer returned.

Return Value

On success, a handle to the FSOUND_SAMPLE definition is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_Stream_GetSyncPoint

Obtains a sync point by index. This is useful when you havent created your own, ie it came from a wav file.

DLL_API FSOUND_SYNCPOINT * F_API FSOUND_Stream_GetSyncPoint(
FSOUND_STREAM *stream,
int index
);

Parameters

stream | The stream to request the sync point from.
index | The sync point offset into the stream.

Return Value

On success, a handle to a sync point is returned.
On failure, NULL is returned.

Remarks

Points are loaded in order of offset, so the index will represent the smallest point to the largest.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_AddSyncPoint , FSOUND_Stream_DeleteSyncPoint , FSOUND_Stream_GetSyncPointInfo , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_Stream_GetSyncPointInfo

Retrieves the name and pcm offset in samples for a specified sync point.

char * F_API FSOUND_Stream_GetSyncPointInfo(
FSOUND_SYNCPOINT *point,
unsigned int *pcmoffset
);

Parameters

point | The handle to the sync point to retrieve information from.
pcmoffset | A pointer to an integer that will receive the sync point offset in pcm SAMPLES. A value of NULL will be ignored.

Return Value

On success, the name of the syncpoint is returned as a string.
On failure, NULL is returned.

Remarks

Convert samples to time by dividing the PCM value by the default samplerate. This would give you the value in seconds. Multiply by 1000 to get milliseconds.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_AddSyncPoint , FSOUND_Stream_GetNumSyncPoints , FSOUND_Stream_GetSyncPoint , FSOUND_Stream_SetSyncCallback


[API function]

FSOUND_Stream_GetTagField

Get a tag field associated with an open stream.

signed char F_API FSOUND_Stream_GetTagField(
FSOUND_STREAM *stream,
int num,
int *type,
char **name,
void **value,
int *length
);

Parameters

stream | The stream to get the tag field from.
num | The number of the tag field to retrieve.
type | Pointer to a variable that will receive the type of the tag field that was retrieved. See FSOUND_TAGFIELD_TYPE.
name | Pointer to a variable that will receive the name of the tag field as a null-terminated ASCII string.
value | Pointer to a variable that will receive a pointer to the tag field data.
length | Pointer to a variable that will receive the length of the tag field data.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Do not attempt to modify or free any pointers returned by this function.
If this function returns successfully, "value" will contain a pointer to a piece of tag-field-specific data - do not assume it will always point to a null-terminated ASCII string.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Stream_FindTagField , FSOUND_Stream_GetNumTagFields , FSOUND_TAGFIELD_TYPE


[API function]

FSOUND_Stream_GetTime

Returns the current time offset in stream in milliseconds.

int F_API FSOUND_Stream_GetTime(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to get the currently playing time offset.

Return Value

On success, the current stream's position in milliseconds is returned.
On failure, 0 is returned.

Remarks

FSOUND_MPEGACCURATE will need to be used with mp3 files that use VBR encoding for more accuracy.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_SetTime


[API function]

FSOUND_Stream_Net_GetBufferProperties

Gets buffer size and thresholds that will be used when opening new internet streams.

signed char F_API FSOUND_Stream_Net_GetBufferProperties(
int *buffersize,
int *prebuffer_percent,
int *rebuffer_percent
);

Parameters

buffersize | Pointer to size in bytes of the streaming buffer.
prebuffer_percent | Pointer to how much to prebuffer when a stream is first opened. Values are expressed as a percentage from 1 to 99.
rebuffer_percent | Pointer to how much to rebuffer after a stream has suffered a buffer underrun. Values are expressed as a percentage from 1 to 99.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function returns the values that will be used for subsequent internet stream opens. Internet streams that already exist may have different values.
Any of the parameters can be NULL, in which case, they will be ignored.
___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Close , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Net_GetLastServerStatus

This function returns a pointer to the last HTTP status line that was received when connecting to an internet stream.

char *F_API FSOUND_Stream_Net_GetLastServerStatus(
);

Return Value

Pointer to the last HTTP status line (null-terminated ASCII string) that was received.

Remarks

The result of this function should be used for informational purposes only. This function provides no facility to discover which internet stream the last HTTP status pertains to when there are multiple internet streams open.
___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Net_GetStatus

Get various status information for an internet stream.

signed char F_API FSOUND_Stream_Net_GetStatus(
FSOUND_STREAM *stream,
int *status,
int *bufferused,
int *bitrate,
unsigned int *flags
);

Parameters

stream | The stream to get status information on.
status | Pointer to a variable that will receive a status value. See FSOUND_STREAM_NET_STATUS.
bufferused | Pointer to a variable that will receive the percentage of the read buffer that is currently in use.
bitrate | Pointer to a variable that will receive the current bitrate of the stream.
flags | Pointer to a variable that will receive a flags field describing protocol and format information. See FSOUND_STATUS_FLAGS.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_STATUS_FLAGS , FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_STREAM_NET_STATUS , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Net_SetBufferProperties

Sets buffer size and thresholds to use when opening new internet streams.

signed char F_API FSOUND_Stream_Net_SetBufferProperties(
int buffersize,
int prebuffer_percent,
int rebuffer_percent
);

Parameters

buffersize | Size in bytes of the streaming buffer. Make it bigger to avoid buffer underruns. (Default = 64000)
prebuffer_percent | How much to prebuffer when a stream is first opened. Values are expressed as a percentage from 1 to 99. (Default = 95)
rebuffer_percent | How much to rebuffer after a stream has suffered a buffer underrun. Values are expressed as a percentage from 1 to 99. (Default = 95)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Call this function before FSOUND_Stream_Open. This function has no effect on internet streams that are already open.
___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Net_SetMetadataCallback

Set a metadata callback for an internet stream.

signed char F_API FSOUND_Stream_Net_SetMetadataCallback(
FSOUND_STREAM *stream,
FSOUND_METADATACALLBACK callback,
void *userdata
);

Parameters

stream | The stream to set the metadata callback for.
callback | Pointer to the metadata callback function to attach to this stream.
userdata | User-defined value that will be passed to the supplied metadata callback function in the userdata parameter.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

The supplied metadata callback function will be called each time the specified internet stream receives a chunk of metadata.
Do not do any time-consuming processing in a metadata callback function or network subsystem performance may degrade.
Do not attempt to modify or free any memory passed to a metadata callback function.
___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_METADATACALLBACK , FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Net_SetProxy

Set a proxy server to use for all subsequent internet connections.

signed char F_API FSOUND_Stream_Net_SetProxy(
const char *proxy
);

Parameters

proxy The name of a proxy server in host:port format e.g. www.fmod.org:8888 (defaults to port 80 if no port is specified).
Basic authentication is supported. To use it, this parameter must be in user:password@host:port format e.g. bob:sekrit123@www.fmod.org:8888
Set this parameter to NULL if no proxy is required.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Open

Opens an audio file/url/cd ready for streaming.
This opens the file in preparation for playback in real-time, without needing to decode the whole file into memory first.

FSOUND_STREAM * F_API FSOUND_Stream_Open(
const char *name_or_data,
unsigned int mode,
int offset,
int length
);

Parameters

name_or_data | Name of the file to open, or pointer to data if FSOUND_LOADMEMORY is used.
mode | Simple description of how to play the file. For all formats except raw PCM, FSOUND_LOOP*, FSOUND_HW3D, FSOUND_HW2D, FSOUND_2D, FSOUND_LOADMEMORY, FSOUND_LOADRAW, FSOUND_MPEGACCURATE, FSOUND_NONBLOCKING flags are the only ones supported.
offset | Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening. length must also be specified if this value is used.
length | Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading.

Return Value

On success, a pointer to an opened stream is returned.
On failure, NULL is returned.

Remarks

WAV support supports windows codec compressed WAV files.
--------------
FSOUND_MPEGACCURATE is to be used cautiously. To open a file with this mode turned on, it has to scan the whole MP3 first. This can take several seconds if the file is big, or the harddisk/cpu is slow.
A way to speed up this process would be to load the compressed mp3 into memory first, and use the FSOUND_LOADMEMORY flag with this function.
--------------
NOTE : Internet stream limitations
- URLs must start with "http://".
- The only supported formats for HTTP streams are MP3 (must have .mp3 extension) and OggVorbis (must have .ogg extension).
--------------
FSB streaming is not supported if the format from FSBank is 'Retain original format'. On PC platforms, only PCM and ADPCM FSB files are allowed.
--------------
Note, on PlayStation 2 you cannot use FSOUND_LOADMEMORY, you may use FSOUND_LOADMEMORYIOP though.
--------------
When opening with the FSOUND_NONBLOCKING flag, this function always succeeds at the point of being called.
It will always return a valid channel handle, even though the file might fail to open. To determine any error in non blocking mode use FSOUND_Stream_GetOpenState.
--------------
NOTE: CDDA Streaming (Win32 only!)
To open a CD for CDDA streaming, specify the drive letter of a CD drive e.g. FSOUND_Stream_Open("d:", 0, 0, 0); FSOUND_Stream_Open will create a stream with multiple substreams, one for each CD track. Use FSOUND_Stream_SetSubStream to select which CD track to play.
A number of options can be passed to FSOUND_Stream_Open along with the drive letter. They are :
*? e.g. FSOUND_Stream_Open("d:*?", 0, 0, 0); This option will cause a tag field called "CD_DEVICE_INFO" to be attached to the stream. This tag field contains information on the specified CD device.
*! e.g. FSOUND_Stream_Open("d:*!", 0, 0, 0); This option will cause the stream to be opened in "quick open" mode. When a stream is opened in this mode, calls to FSOUND_Stream_SetSubStream will return immediately making it quick to select each substream in turn and get the length of each CD track. Note that a stream in quick open mode cannot be played! Use quick open mode to get track lengths and then re-open the stream without quick open mode to actually play it.
*j e.g. FSOUND_Stream_Open("d:*j", 0, 0, 0); This option turns jitter correction OFF.
*a e.g. FSOUND_Stream_Open("d:*a", 0, 0, 0); This option will force FMOD to use ASPI to access the specified CD drive as opposed to NTSCSI. It should generally only be used as a last resort if FMOD is unable to access drives that are known to be working with other programs.
Options can be combined like so: FSOUND_Stream_Open("d:*?!j", 0, 0, 0);
If a nonblocking CDDA stream fails to open, a tag field called "CD_ERROR" will be attached to the stream. This tag field contains a textual description of why the stream failed to open.
NOTE: FMOD will always try to use native NTSCSI support to communicate with CD devices before trying to use ASPI, unless the "*a" option is specified, in which case FMOD will only try to use ASPI. Unlike in pre-3.73 versions, FMOD can now access all CD drives when using ASPI.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_Close , FSOUND_Stream_GetLength , FSOUND_Stream_GetLengthMs , FSOUND_Stream_GetOpenState , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetInfo , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_OpenFromHandle , FSOUND_Stream_Play , FSOUND_Stream_PlayEx , FSOUND_Stream_SetBufferSize , FSOUND_Stream_SetSubStream , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_Play

Starts a pre-opened stream playing.

int F_API FSOUND_Stream_Play(
int channel,
FSOUND_STREAM *stream
);

Parameters

channel | 0+ The channel index in the channel pool. This must not exceed the maximum number of channels allocated with FSOUND_Init FSOUND_FREE Chooses a free channel to play in. If all channels are used then it selects a channel with a sample playing that has a lower priority than the sample to be played.
stream | Pointer to the already opened stream to be played.

Return Value

On success, the channel handle the stream is playing in is returned.
On failure, -1 is returned.

Remarks

When a stream starts to play, it inherits a special high priority (256).
It cannot be rejected by other sound effect channels in the normal fashion as the user can never set a priority above 255 normally.
--------------
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
--------------
FSB streaming is not supported if the format from FSBank is 'Retain original format'. On PC platforms, only PCM and ADPCM FSB files are allowed.
--------------
FSOUND_STEREOPAN is recommended for stereo streams if you call FSOUND_SetPan. This puts the left and right channel to full volume.
Otherwise a normal pan will give half volume for left and right. See FSOUND_SetPan for more information on this.
--------------
You can use normal channel based commands (such as FSOUND_SetVolume etc) on the return handle, as it is a channel handle.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetNumSubChannels , FSOUND_GetSubChannel , FSOUND_Init , FSOUND_SetPan , FSOUND_SetVolume , FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_PlayEx , FSOUND_Stream_SetEndCallback , FSOUND_Stream_SetLoopCount , FSOUND_Stream_SetSubStream , FSOUND_Stream_SetSubStreamSentence , FSOUND_Stream_SetSyncCallback , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_PlayEx

Extended featured version of FSOUND_Stream_Play.
Added functionality includes the ability to start the stream paused. This allows attributes
of a stream channel to be set freely before the stream actually starts playing, until FSOUND_SetPaused(FALSE) is used.
Also added is the ability to associate the stream channel to a specified DSP unit. This allows
the user to 'group' channels into seperate DSP units, which allows effects to be inserted
between these 'groups', and allow various things like having one group affected by reverb (wet mix) and another group of
channels unaffected (dry). This is useful to seperate things like music from being affected
by DSP effects, while other sound effects are.

int F_API FSOUND_Stream_PlayEx(
int channel,
FSOUND_STREAM *stream,
FSOUND_DSPUNIT *dspunit,
signed char paused
);

Parameters

channel | 0+ The absolute channel number in the channel pool. Remember software channels come first, followed by hardware channels. You cannot play a software sample on a hardware channel and vice versa. FSOUND_FREE Chooses a free channel to play in. If all channels are used then it selects a channel with a sample playing that has an EQUAL or LOWER priority than the sample to be played.
stream | Pointer to the already opened stream to be played.
dspunit | Pointer to a dsp unit to attach the channel to.
paused | Start the stream paused or not. Pausing the stream channel allows attributes to be set before it is unpaused.

Return Value

On success, a channel handle the stream is playing in is returned.
On failure, -1 is returned.

Remarks

When a stream starts to play, it inherits a special high priority (256).
It cannot be rejected by other sound effect channels in the normal fashion as the user can never set a priority above 255 normally.
--------
FSOUND_STEREOPAN is recommended for stereo streams if you call FSOUND_SetPan. This puts the left and right channel to full volume.
Otherwise a normal pan will give half volume for left and right. See FSOUND_SetPan for more information on this.
--------
You can use normal channel based commands (such as FSOUND_SetVolume etc) on the return handle, as it is a channel handle.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetNumSubChannels , FSOUND_GetSubChannel , FSOUND_SetPan , FSOUND_SetPaused , FSOUND_SetVolume , FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[API function]

FSOUND_Stream_SetBufferSize

Sets the internal file buffersize for audio streaming of data for the NEXT stream opened with FSOUND_Stream_Open.
Larger values will consume more memory (see remarks), whereas smaller values may be affected by large delays in disk access, especially from CDROM.

signed char F_API FSOUND_Stream_SetBufferSize(
int ms
);

Parameters

ms Time in milliseconds between stream updates. FMOD tries to access the disk and decompress data every period specified. Values less than 50 result in an error.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

The default setting is 400ms.
To calculate memory usage for a stream buffer, it is a simple matter of calculating sizebytes = streambuffersize * sample rate / 1000 * (bitdepth / 8) * numchannels * 2, where numchannels is 1 for mono, or 2 for stereo files.
It is multiplied by 2 because FSOUND stream buffers are double buffers.
Note this function does not affect user created streams, as the buffer size is specified in FSOUND_Stream_Create.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetDiskBusy , FSOUND_Stream_Create , FSOUND_Stream_Open


[API function]

FSOUND_Stream_SetEndCallback

Sets a callback function for when a stream has ended.

signed char F_API FSOUND_Stream_SetEndCallback(
FSOUND_STREAM *stream,
FSOUND_STREAMCALLBACK callback,
void *userdata
);

Parameters

stream | Pointer to the stream to callback on when it is finished.
callback | Function to be called when stream ends.
userdata | data that is passed into the callback at the end of the stream.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Only calls back when a stream stops. (not when a looping stream reaches its end point)
Note it uses a FSOUND_STREAMCALLBACK function callback. This is normally for user streams but for
the sake of re-usability this prototype is used. 'buff' and 'length' are NULL and 0 in this case
when the callback occurs. The return value can be TRUE or FALSE it is ignored.
-----------
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_Play , FSOUND_STREAMCALLBACK


[API function]

FSOUND_Stream_SetLoopCount

Sets the stream to loop the number of times specified by the user. If not called it loops forever.

signed char F_API FSOUND_Stream_SetLoopCount(
FSOUND_STREAM *stream,
int count
);

Parameters

stream | Pointer to the stream to set loop count on.
count | Number of times to loop. 0 would be similar to having FSOUND_LOOP_OFF set. <0 is infinity.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This specifies how many loops, not how many times to play the sound back. Therefore when you specify 0, you will hear the sound once, if you specify 1, you will hear the sound twice, and so on.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_Play


[API function]

FSOUND_Stream_SetLoopPoints

Sets the loop points for a stream.

DLL_API signed char F_API FSOUND_Stream_SetLoopPoints(
FSOUND_STREAM *stream,
unsigned int loopstart,
unsigned int loopend
);

Parameters

stream | The stream to set the loop points on.
loopstart | The start of the loop, specified in PCM SAMPLES.
loopend | The end of the loop, specified in PCM SAMPLES.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

For streams, setting looppoints is reasonably accurate but should not be assumed to be perfectly sample accurate in all cases.
It depends on the compression format in some cases as seek positions need to be rounded to the nearest compression block offset.
FSOUND_MPEGACCURATE will need to be used with mp3 files that use VBR encoding for more accuracy.
You cannot call this function wile the stream is playing, it has to be stopped.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FSOUND_Stream_SetMode

Set a streams mode.

signed char F_API FSOUND_Stream_SetMode(
FSOUND_STREAM *stream,
unsigned int mode
);

Parameters

stream | Pointer to the stream to have the mode set.
mode | The mode bits to set from FSOUND_MODES.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
Only the following modes are accepted, others will be filtered out.
FSOUND_LOOP_BIDI, FSOUND_LOOP_NORMAL, FSOUND_LOOP_OFF, FSOUND_2D. FSOUND_LOOP_BIDI is treated as FSOUND_LOOP_NORMAL. FSOUND_2D is accepted only if the sound is not hardware.
On Playstation 2, XBox and GameCube, FSOUND_HW2D and FSOUND_HW3D are supported, so you can change between them at runtime.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_GetMode


[API function]

FSOUND_Stream_SetPosition

Sets the current stream's FILE position in BYTES.

signed char F_API FSOUND_Stream_SetPosition(
FSOUND_STREAM *stream,
unsigned int position
);

Parameters

stream | Pointer to the stream to have its position set.
position | Offset in bytes from start of actual sound data (not including any header)

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Position functions for streams talk in bytes and NOT samples.
The reason for not taking the header into account is people usually want to know the offset to seek to relative to the start of their data (ie as they see it in soundforge or whatever), not from offset 0 which is almost meaningless if you dont know the format.
--------------
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_GetPosition , FSOUND_Stream_SetTime


[API function]

FSOUND_Stream_SetSubStream

Seeks a stream to the substream inside a multi-stream FSB bank file, specified by its index.

signed char F_API FSOUND_Stream_SetSubStream(
FSOUND_STREAM *stream,
int index
);

Parameters

stream | Handle to the stream to have its position set.
index | The index of the stream within the FSB file.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

A stream will stop if this function is called, as it needs to seek and flush the buffer.
Indicies for this function are generated as user friendly constants when compiling the FSB bank, and are available in the relevant generated header file.
--------------
If the stream has been opened with FSOUND_NONBLOCKING, this function will ALWAYS succeed, but puts the stream back into a non-ready state. You then have to poll after calling this to make sure the stream is ready.
You can either do this by calling FSOUND_Stream_Play repeatedly/once a frame until it is succeeds, or FSOUND_Stream_GetOpenState.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetNumSubStreams , FSOUND_Stream_GetOpenState , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_SetSubStreamSentence


[API function]

FSOUND_Stream_SetSubStreamSentence

This function allows the user to describe the playback order of a list of substreams. The substreams will be played back in order seamlessly.

signed char F_API FSOUND_Stream_SetSubStreamSentence(
FSOUND_STREAM *stream,
const int *sentencelist,
int numitems
);

Parameters

stream | Pointer to the stream to have its position returned.
sentencelist | This is a pointer to an array of 32bit integers, describing a list of substream indicies to play back.
numitems | The number of entries in the sentence list.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This feature only works with FSB files that have multiple streams stored within it.
To remove any sentence, simply call this function with NULL and 0.
FMOD copies the list from the supplied pointer. Once the pointer is used, the caller can discard the original array.
This function will fail if the stream is playing. The stream must be stopped for it to work.
------------
If the stream is opened with FSOUND_NONBLOCKING, and the stream is not ready (it is still opening), then this function will return FALSE.
When it is ready, it will return TRUE, but after this call the stream is put back into a non-ready state, because it is asynchronously seeking again.
You then have to poll after calling this to make sure the stream is ready.
You can either do this by calling FSOUND_Stream_Play repeatedly/once a frame until it is succeeds, or FSOUND_Stream_GetOpenState.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetNumSubStreams , FSOUND_Stream_GetOpenState , FSOUND_Stream_Play , FSOUND_Stream_SetSubStream


[API function]

FSOUND_Stream_SetSyncCallback

Sets a callback function for when a stream passes over a WAV tag/marker. These are markers that
a sound editing program such as Sound Forge can drop into the actual wave data. FMOD will
trigger callbacks with these markers when the stream plays, and pass in the string through the callback that the marker contains.

signed char F_API FSOUND_Stream_SetSyncCallback(
FSOUND_STREAM *stream,
FSOUND_STREAMCALLBACK callback,
void *userdata
);

Parameters

stream | Pointer to the stream to callback when a sync point is reached.
callback | Function to call when sync point is reached.
userdata | user data that is passed into the callback.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Note it uses a FSOUND_STREAMCALLBACK function callback. This is normally for user streams but for
the sake of re-usability this prototype is used. 'buff' is a null terminated string provided by
the marker. 'len' is the offset in samples that the marker was set at.
The return value can be TRUE or FALSE, it is ignored.
-----------
Note you can save a WAV out using an MP3 wav codec (and then just rename the WAV to MP3 if you like) to get
sync marker support for compressed MP3 files. FMOD will pick up on this and read the markers out.
--------------
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_AddSyncPoint , FSOUND_Stream_DeleteSyncPoint , FSOUND_Stream_GetNumSyncPoints , FSOUND_Stream_GetSyncPoint , FSOUND_Stream_GetSyncPointInfo , FSOUND_Stream_Play , FSOUND_STREAMCALLBACK


[API function]

FSOUND_Stream_SetTime

Sets the current stream's FILE position in MILLISECONDS.

signed char F_API FSOUND_Stream_SetTime(
FSOUND_STREAM *stream,
int ms
);

Parameters

stream | Pointer to the stream to have its position set.
ms | Time in milliseconds to seek to.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
FSOUND_MPEGACCURATE will need to be used with mp3 files that use VBR encoding for more accuracy.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_GetPosition , FSOUND_Stream_GetTime , FSOUND_Stream_SetPosition


[API function]

FSOUND_Stream_Stop

Stops a stream from playing.

signed char F_API FSOUND_Stream_Stop(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to a stream to stop.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

The stream is still prepared and sitting in memory ready to go. Use FSOUND_Stream_Close on the stream to completely remove it.
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Net_SetTimeout , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_PlayEx


[API function]

FSOUND_CD_GetNumTracks

Returns the number of tracks on the currently inserted CD.

int F_API FSOUND_CD_GetNumTracks(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

On success, the number of CD tracks on the currently inserted is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux

See Also

FSOUND_CD_GetTrack


[API function]

FSOUND_CD_GetPaused

Gets the pause status of the current CD audio track.

signed char F_API FSOUND_CD_GetPaused(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

If the track is currently paused, TRUE is returned.
If the track is currently not paused, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)


[API function]

FSOUND_CD_GetTrack

Returns the currently playing CD track number.

int F_API FSOUND_CD_GetTrack(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

On success, the CD track number currently playing is returned. (starts from 1)
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_GetNumTracks


[API function]

FSOUND_CD_GetTrackLength

Gets the track length of a CD.

int F_API FSOUND_CD_GetTrackLength(
char drive,
int track
);

Parameters

drive | the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
track | The CD track number to query the length of. (starts from 1)

Return Value

On success, the length of the current track in milliseconds is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_GetTrackTime , FSOUND_CD_SetTrackTime


[API function]

FSOUND_CD_GetTrackTime

Returns the current track time playing on a CD.

int F_API FSOUND_CD_GetTrackTime(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

On success, the position of the current playing track in milliseconds is returned.
On failure, 0 is returned.

Remarks

This is easily one of the slowest functions in the FMOD API. Please use it sparingly.
It seems like it shouldnt take long, but because of windows MCI API it does, and not just a little bit of time, it takes a LOT.
It seems to poll the CD driver and cause a large delay upon completion of the command.
Different algorithms were used to try and emulate this function such as simply using a timer, but this was very inaccurate, especially when pausing/unpausing a lot.
___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_GetTrackLength , FSOUND_CD_SetTrackTime


[API function]

FSOUND_CD_GetVolume

Returns the volume of the playing CD audio.

int F_API FSOUND_CD_GetVolume(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

On success, a value between 0 and 255 is returned, 0 being the lowest volume and 255 being the highest.
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_Play , FSOUND_CD_SetVolume , FSOUND_Close


[API function]

FSOUND_CD_OpenTray

Opens/Closes the CD tray.

signed char F_API FSOUND_CD_OpenTray(
char drive,
signed char open
);

Parameters

drive | The drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
open | If open is set to 1, the CD tray will be opened. If open is set to 0, the CD tray will be closed.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux


[API function]

FSOUND_CD_Play

Plays a CD Audio track.

signed char F_API FSOUND_CD_Play(
char drive,
int track
);

Parameters

drive | the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
track | the CD track number to play. The first track starts at 1.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

See FSOUND_CD_SetPlayMode for information on how to control playback of a CD track.
FSOUND's CD Playback system, is a non intrusive, non polling system.
This may not mean much to a lot of people, but a polling player (take the windows default CD player) will consistantly poll the CD device to update its status, which causes other applications to jerk, or pause consistantly.
This would be inexcusable in a game, to have the game halt or jerk every second to few seconds or so.
FSOUND uses timing and prediction to loop tracks and update the status of the CD, and never touches the CD device during playback, for TRUE 0pu usage.
___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM only)

See Also

FSOUND_CD_GetVolume , FSOUND_CD_SetPlayMode , FSOUND_CD_SetVolume , FSOUND_CD_Stop


[API function]

FSOUND_CD_SetPaused

Sets the pause status of the currently playing CD audio track.

signed char F_API FSOUND_CD_SetPaused(
char drive,
signed char paused
);

Parameters

drive | the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
paused | TRUE to pause track, FALSE to unpause track.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)


[API function]

FSOUND_CD_SetPlayMode

Sets the playback mode of the CD.

void F_API FSOUND_CD_SetPlayMode(
char drive,
signed char mode
);

Parameters

drive | the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
mode | See FSOUND_CDPLAYMODES for a list of valid parameters to send to this function.

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_Play , FSOUND_CDPLAYMODES


[API function]

FSOUND_CD_SetTrackTime

Performs a seek within a track specified by milliseconds.

signed char F_API FSOUND_CD_SetTrackTime(
char drive,
unsigned int ms
);

Parameters

drive | The drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
ms | Time to seek into the current track in milliseconds.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This function will start the track if it is not playing.
___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_GetTrackLength , FSOUND_CD_GetTrackTime


[API function]

FSOUND_CD_SetVolume

Sets the volume of the playing CD audio.

signed char F_API FSOUND_CD_SetVolume(
char drive,
int volume
);

Parameters

drive | the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.
volume | An integer value from 0-255. 0 being the lowest volume, 255 being the highest (full).

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_GetVolume , FSOUND_CD_Play , FSOUND_Close


[API function]

FSOUND_CD_Stop

Stops the currently playing CD audio track.

signed char F_API FSOUND_CD_Stop(
char drive
);

Parameters

drive the drive ID to use. 0 is the default CD drive. Using D or E in single quotes would be D: or E: for example.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Linux, Macintosh (OSX CFM Only)

See Also

FSOUND_CD_Play


[API function]

FSOUND_DSP_ClearMixBuffer

Clears the mixbuffer, especially handy if you are doing a large file operation which
halts the system.
You might try and stop all the sounds, but if you do your file operation straight after
this, it will not have a chance to flush the mixbuffer normally, so this function is called.
It stops the effect of stuttering looping sound while your file operation happens.

void F_API FSOUND_DSP_ClearMixBuffer(
);

Return Value

Remarks

The best way to do it is like this. Turn off the sfx and music DSP units, clear the mix buffer,
then when the operation that halts the machine is done, just re-enable the sfx and music DSP units.
Disabling these units stops the timer trying to get 1 or 2 more mixes in during the file operation,
which will cause more stuttering.
ie.
FSOUND_DSP_SetActive(FSOUND_DSP_GetSFXUnit(), FALSE);
FSOUND_DSP_SetActive(FSOUND_DSP_GetMusicUnit(), FALSE);
FSOUND_DSP_ClearMixBuffer();
//
// maching halting operation here
//
FSOUND_DSP_SetActive(FSOUND_DSP_GetSFXUnit(), TRUE);
FSOUND_DSP_SetActive(FSOUND_DSP_GetMusicUnit(), TRUE);
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_GetMusicUnit , FSOUND_DSP_GetSFXUnit , FSOUND_DSP_SetActive


[API function]

FSOUND_DSP_Create

Creates a DSP unit, and places it in the DSP chain position specified by the priority
parameter. Read the remarks section carefully for issues regarding DSP units.
DSP units are freed with FSOUND_DSP_Free.

FSOUND_DSPUNIT *F_API FSOUND_DSP_Create(
FSOUND_DSPCALLBACK callback,
int priority,
void *userdata
);

Parameters

callback This is a pointer to your DSP Unit callback, of type FSOUND_DSPCALLBACK.
The prototype for a callback is declared in the following fashion.
Callbacks must return a pointer to the buffer you work on, so that
the next dsp unit can work on it.
Here is the simplest case:
void *callback(void *originalbuffer, void *newbuffer, int length, void *userdata)
{
// originalbuffer = fsounds original mixbuffer.
// newbuffer = the buffer passed from the previous DSP unit.
// length = length in samples at this mix time.
// param = user parameter passed through in FSOUND_DSP_Create.
//
// modify the buffer in some fashion
return newbuffer;
}
See the definition of FSOUND_DSPCALLBACK for more.
priority Order in the priority chain. Valid numbers are 0 to 1000, 0 being
highest priority (first), with 1000 being lowest priority (last).
Note that FSOUNDs soundeffects mixers and copy routines are considered
part of this DSP unit chain which you can play with.
param User defined parameter, this gets passed into the callback when it is
called. It is safe to leave this value 0.

Return Value

On success, a pointer to a new valid DSP unit is returned.
On failure, NULL is returned.

Remarks

A dsp unit is NOT ACTIVE by default. You have to activate it with FSOUND_DSP_SetActive
---------------------------------------------------------------------------------------
Priorities and default system units.
---------------------------------------------------------------------------------------
A note on priorities. FSOUND processes DSP units in order of priority. A 0 priority
unit gets processed first, a 1 priority unit gets processed next, and so on.
FSOUND actually uses these DSP units to mix its sound effects and music! Yes, you have
access to them (be careful!). It is possible to totally remove, replace or deactivate
all of FSOUND's system units so that it does nothing at all!
FSOUND has preinstalled default system units at the following priority locations:
FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT (priority 0) - Clear Unit. This unit clears out
the mixbuffer for the next units to mix into. You can disable this unit and replace
it with something other than a clearer, such as a scaler, which fades down the mix
buffer instead of clearing it, to produce a very rough echo effect.
FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT (priority 100) - SFX Unit. This unit mixes sound
effect channels into the mix buffer, which was previously cleared with the Clear
Unit.
FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT (priority 200) - Music Unit. This unit mixes all
music channels into the mix buffer, which was previously mixed into with the SFX
Unit.
FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT (priority 1000) - Clip and Copy Unit. This
unit takes the finally mixed buffer, and clips it to the output stream size (if it
needs to), and then sends it off to the sound device. It is done last. If this is
disabled you will hear no sound.
---------------------------------------------------------------------------------------
Buffer Lengths.
---------------------------------------------------------------------------------------
The 'length' value of the DSP callback is roughly 20ms worth of data.
Use FSOUND_DSP_GetBufferLength to get the exact callback length.
---------------------------------------------------------------------------------------
Buffer Widths
---------------------------------------------------------------------------------------
Remember that FSOUND uses different buffer types depending on what type of mixer it is.
You will have to compensate for this by writing different routines depending on the
mixer type (ie mmx or non mmx), just like FSOUND does.
Currently there are the 3 types of mixers and their buffer sizes.
You can get the type of mixer being used by calling the FSOUND_GetMixer function.
You may want to check on this inside your callback, or set up a function pointer system,
whatever you think is suitable (it costs nothing to do a FSOUND_GetMixer every time).
- FSOUND_MIXER_BLENDMODE : This buffer is a stereo, signed 32bit buffer (8 bytes per
sample). The data is in integer format.
Data written to this buffer is not clipped and passed to the output stream until the
very end of the chain (the clip and copy unit). For this type of mixer, you dont
have to worry about clipping becuase FSOUND does this for you.
- FSOUND_MIXER_QUALITY_FPU / FSOUND_MIXER_QUALITY_FPU_VOLUMERAMP: This buffer is also a
stereo, signed 32bit buffer (8 bytes per sample). This data is in floating point
format.
The same clip and copy rules apply here as for the above mixer.
- Any MMX based mixer : This buffer is a stereo, signed 16bit buffer (4 bytes per sample).
When writing to this buffer, you must make sure the result does not overflow this
signed 16bit range.
If you add data into to this buffer, make sure it is clipped to a signed 16bit range
before writing it back. FSOUND only copies this data to the output stream, it does
not clip it.
---------------------------------------------------------------------------------------
Speed
---------------------------------------------------------------------------------------
DSP Units are processed then and there, inside the mixing routine. Remember to make
your process as FAST as possible, or the output device's play cursor will catch up to
FSOUND's write cursor while your routine takes its time to complete, and make it start
to break up.
So basically, if it isnt fast, then FSOUND will not be able to send the data to the
output device in time for the next mixer update, and the result will be corrupted sound.
FSOUND_DSP_MixBuffers is available now, so if you need to mix some raw data into the output
buffer quickly, you can use FSOUND's own optimized mixer directly to do it!
Finally, you can see how your routine affects cpu usage, by using FSOUND_GetCPUUsage.
The cpu usage returned by this function includes any time spent in DSP units as well.
(this function times everything). If you are really bored, you can see how much FSOUND's
system units take cpu-wise, by turning them on and off and seeing how they affect
performance.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_Free , FSOUND_DSP_GetBufferLength , FSOUND_DSP_GetBufferLengthTotal , FSOUND_DSP_MixBuffers , FSOUND_DSP_PRIORITIES , FSOUND_DSP_SetActive , FSOUND_DSP_SetPriority , FSOUND_DSPCALLBACK , FSOUND_GetCPUUsage , FSOUND_GetMixer , FSOUND_MIXERTYPES , FSOUND_PlaySoundEx , FSOUND_Stream_CreateDSP


[API function]

FSOUND_DSP_Free

Frees and removes a DSP unit from the DSP chain.

void F_API FSOUND_DSP_Free(
FSOUND_DSPUNIT *unit
);

Parameters

unit Pointer to DSP unit to be freed.

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create


[API function]

FSOUND_DSP_SetActive

Allows the user to toggle a DSP unit on or off.

void F_API FSOUND_DSP_SetActive(
FSOUND_DSPUNIT *unit,
signed char active
);

Parameters

unit | Pointer to DSP unit to have its active flag changed.
active | Flag to say whether DSP unit should be rendered active or inactive. valid values are TRUE or FALSE.

Return Value

void

Remarks

It is possible to toggle on and off FSOUNDs internal DSP units, though not recommended.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_Create , FSOUND_DSP_GetActive , FSOUND_DSP_GetSpectrum


[API function]

FSOUND_DSP_GetActive

Returns if a DSP unit is active or not.

signed char F_API FSOUND_DSP_GetActive(
FSOUND_DSPUNIT *unit
);

Parameters

unit Pointer to DSP unit to have its active flag returned.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_SetActive


[API function]

FSOUND_DSP_GetBufferLength

Returns the buffer lenth passed by the DSP system to DSP unit callbacks, so you can allocate memory etc
using this data.

int F_API FSOUND_DSP_GetBufferLength(
);

Return Value

The size of the DSP unit buffer in SAMPLES (not bytes).

Remarks

Remember this is samples not bytes. To convert to bytes you
will have to multiply by 4 for mmx mixers, 8 for other mixers.
(a stereo 16bit sample = 4 bytes, and a stereo 32bit sample (ie fpu) = 8 bytes)
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_GetBufferLengthTotal


[API function]

FSOUND_DSP_GetBufferLengthTotal

This is the total size in samples (not bytes) of the FSOUND mix buffer. This is affected
by FSOUND_SetBufferSize.

int F_API FSOUND_DSP_GetBufferLengthTotal(
);

Return Value

The size of the FSOUND mixing buffer in SAMPLES (not bytes).

Remarks

Remember this is samples not bytes. To convert to bytes you
will have to multiply by 4 for mmx mixers, 8 for other mixers.
(a stereo 16bit sample = 4 bytes, and a stereo 32bit sample (ie fpu) = 8 bytes)
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_GetBufferLength , FSOUND_SetBufferSize


[API function]

FSOUND_DSP_SetPriority

Changes a DSP Unit's priority position in the DSP chain.

void F_API FSOUND_DSP_SetPriority(
FSOUND_DSPUNIT *unit,
int priority
);

Parameters

unit | Pointer to DSP unit to have its priority changed.
priority | Order in the priority chain. Valid numbers are 0 to 1000, 0 being highest priority (first), with 1000 being lowest priority (last).

Return Value

Remarks

DSP units with the same priority as a previous unit already in the chain will be placed
AFTER all like priority units.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_GetPriority


[API function]

FSOUND_DSP_GetPriority

Returns the priority status in the DSP chain, of a specified unit.

int F_API FSOUND_DSP_GetPriority(
FSOUND_DSPUNIT *unit
);

Parameters

unit Pointer to DSP unit to get priority value from.

Return Value

On success, the priority of the unit, from 0 to 1000.
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_SetPriority


[API function]

FSOUND_DSP_GetClearUnit

Returns a pointer to FSOUND's system DSP clear unit.

FSOUND_DSPUNIT *F_API FSOUND_DSP_GetClearUnit(
);

Return Value

Pointer to the DSP unit.

Remarks

The FSOUND clear DSP unit simply sets the mix buffer to 0, silencing it.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetFFTUnit , FSOUND_DSP_GetMusicUnit , FSOUND_DSP_GetSFXUnit


[API function]

FSOUND_DSP_GetClipAndCopyUnit

Returns a pointer to FSOUND's system Clip and Copy DSP unit.

FSOUND_DSPUNIT *F_API FSOUND_DSP_GetClipAndCopyUnit(
);

Return Value

Pointer to the DSP unit.

Remarks

The FSOUND ClipAndCopy DSP unit clips the 32bit buffer down to fit the soundcard's 16bit stereo output, and sends it off to the hardware.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetFFTUnit , FSOUND_DSP_GetMusicUnit , FSOUND_DSP_GetSFXUnit


[API function]

FSOUND_DSP_GetMusicUnit

Returns a pointer to FSOUND's system DSP Music mixer unit.

FSOUND_DSPUNIT *F_API FSOUND_DSP_GetMusicUnit(
);

Return Value

Pointer to the DSP unit.

Remarks

The FSOUND Music DSP executes the FMUSIC engine and mixes the sounds spawned by the music player.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetFFTUnit , FSOUND_DSP_GetSFXUnit


[API function]

FSOUND_DSP_GetSFXUnit

Returns a pointer to FSOUND's system DSP SFX mixer unit.

FSOUND_DSPUNIT *F_API FSOUND_DSP_GetSFXUnit(
);

Return Value

Pointer to the DSP unit.

Remarks

The FSOUND SFX DSP unit mixes sound effects together spawned by the user.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetFFTUnit , FSOUND_DSP_GetMusicUnit


[API function]

FSOUND_DSP_GetFFTUnit

Returns a pointer to FSOUND's system DSP FFT processing unit.

DLL_API FSOUND_DSPUNIT *F_API FSOUND_DSP_GetFFTUnit(
);

Return Value

Pointer to the DSP unit.

Remarks

The FSOUND FFT DSP executes the FFT engine to allow FSOUND_DSP_GetSpectrum to be used.
The FFT unit is off by default, due to the cpu expense incurred in running. Turn it on to use FSOUND_DSP_GetSpectrum.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetMusicUnit , FSOUND_DSP_GetSFXUnit , FSOUND_DSP_GetSpectrum


[API function]

FSOUND_DSP_GetSpectrum

Function to return a pointer to the current spectrum buffer. The buffer contains 512 floating
point values that represent each frequency band's amplitude for the current FMOD SoundSystem
mixing buffer. The range of frequencies covered by the spectrum is 1 to the nyquist frequency
or half of the output rate. So if the output rate is 44100, then frequencies provided are up
to 22050. (entry 511)

F_FLOAT_API * F_API FSOUND_DSP_GetSpectrum(
);

Return Value

A pointer to a buffer containing 512 floats.

Remarks

Note that hardware sounds, MIDI, files do not register on the spectrum graph as they are not run through FMODs DSP system.
Note that to use this you have to turn on the FSOUND FFT DSP unit. This is achieved by calling FSOUND_DSP_GetFFTUnit, then using FSOUND_DSP_SetActive to turn it on.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_DSP_GetFFTUnit , FSOUND_DSP_SetActive


[API function]

FSOUND_DSP_MixBuffers

Allows the user to mix their own data from one buffer to another, using FSOUNDs optimized
mixer routines. This was mainly provided for DSP routines, though it can be used for
anything.

signed char F_API FSOUND_DSP_MixBuffers(
void *destbuffer,
void *srcbuffer,
int len,
int freq,
int vol,
int pan,
unsigned int mode
);

Parameters

destbuffer | Pointer to a buffer to have the data mixed into.
srcbuffer | Pointer to the source buffer to be mixed in.
len | Amount to mix in SAMPLES.
freq | Speed to mix data to output buffer. Remember if you mix at a rate different than the output rate, the buffer lengths will have to be different to compensate. Ie if the output rate is 44100 and you supply a value of 88200 to FSOUND_DSP_MixBuffers, you will only need a destbuffer that is half the size of srcbuffer. If you supply a value of 22050 then you will need a destbuffer that is twice as big as srcbuffer. If they are both the same size then it will only mix half of the data.
vol | volume scalar value of mix. Valid values are 0 (silence) to 255 (full volume). See FSOUND_SetVolume for more information.
pan | pan value for data being mixed. Valid values are 0 (full left), 128 (middle), 255 (full right) and FSOUND_STEREOPAN. See FSOUND_SetPan for more information.
mode | Bit settings to describe the source buffer. Valid values are found in FSOUND_MODES, but only 8/16bit and stereo/mono flags are interpreted, other flags are ignored.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

'destbuffer' should always the format of the mixing output buffer, as it will use the mixer
currently running to do the mixing.
For MMX it is 16bit stereo, so it is 4 bytes per output sample (word left, word right)
For Standard Blend mode it is 32bit stereo, so it is 8 bytes per output sample (left dword, right dword)
For FPU mixer it is 32bit float stereo, so it is 8 bytes per output sample (left float, right float)
FSOUND_GetMixer can be used to determine which mixer is being used.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

See Also

FSOUND_DSP_Create , FSOUND_DSP_MixBuffers , FSOUND_GetMixer , FSOUND_MODES , FSOUND_SetFrequency , FSOUND_SetPan , FSOUND_SetVolume


[API function]

FSOUND_FX_Disable

Disables effect processing for ALL effects on the specified channel.

signed char F_API FSOUND_FX_Disable(
int channel
);

Parameters

channel Channel number/handle to disable all fx for.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported. Passing this will disable fx on ALL channels available.
This command can only be issued while the channel is paused or stopped.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Enable , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_Enable

Enables effect processing for the specified channel. This command continues to add effects to a channel (up to 16) until FSOUND_FX_Disable is called.

int F_API FSOUND_FX_Enable(
int channel,
unsigned int fxtype
);

Parameters

channel | Channel number/handle to enable fx for.
fx | A single fx enum value to enable certain effects.

Return Value

On success, an FX id is returned.
On failure, -1 is returned.

Remarks

FSOUND_ALL is supported. Passing this will enable fx on ALL channels available.
This command can only be issued while the channel is paused.
If an effect is not enabled, then it will not be affected by its corresponding FSOUND_FX_Set functions.
This function must be played after a paused PlaySoundEx (ie FSOUND_PlaySoundEx(FSOUND_FREE, sound, NULL, TRUE)), and before
the FSOUND_SetPaused(FALSE) so that the hardware can get the resource before it starts playing.
A total of 16 FX per channel is allowed, any more will result in an error. FX are reset to 0 after a sound is stopped or played. (but as above, before the unpausing of a play-paused sound).
Warning : This function is expensive to call as it has to set up fx buffers etc. It is best to call it once, reserve the channel then reuse the channel index when calling playsound without calling it again.
Note : Under DirectX 8, channels with FX enabled sounds cannot have their frequency changed. DirectX 9 and above do not have this limitation.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb , FSOUND_PlaySound , FSOUND_PlaySoundEx , FSOUND_SetPaused


[API function]

FSOUND_FX_SetChorus

Sets the parameters for the chorus effect on a particular channel

signed char F_API FSOUND_FX_SetChorus(
int fxid,
float WetDryMix,
float Depth,
float Feedback,
float Frequency,
int Waveform,
float Delay,
int Phase
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set chorus parameters for.
WetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet).
Depth | Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Must be in the range from 0 through 100. The default value is 25.
Feedback | Percentage of output signal to feed back into the effects input, in the range from -99 to 99. The default value is 0.
Frequency | Frequency of the LFO, in the range from 0 to 10. The default value is 0.
Waveform | Waveform of the LFO. Defined values are 0 triangle. 1 sine. By default, the waveform is a sine.
Delay | Number of milliseconds the input is delayed before it is played back, in the range from 0 to 20. The default value is 0 ms.
Phase | Phase differential between left and right LFOs, in the range from 0 through 4. Possible values are defined as follows: 0 -180 degrees 1 - 90 degrees 2 0 degrees 3 90 degrees 4 180 degrees

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_CHORUS before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetCompressor

Sets the parameters for the compressor effect on a particular channel

signed char F_API FSOUND_FX_SetCompressor(
int fxid,
float Gain,
float Attack,
float Release,
float Threshold,
float Ratio,
float Predelay
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set compressor parameters for.
Gain | Output gain of signal after compression, in the range from -60 to 60. The default value is 0 dB.
Attack | Time before compression reaches its full value, in the range from 0.01 to 500. The default value is 0.01 ms.
Release | Speed at which compression is stopped after input drops below fThreshold, in the range from 50 to 3000. The default value is 50 ms.
Threshold | Point at which compression begins, in decibels, in the range from -60 to 0. The default value is -10 dB.
Ratio | Compression ratio, in the range from 1 to 100. The default value is 10, which means 10:1 compression.
Predelay | Time after lThreshold is reached before attack phase is started, in milliseconds, in the range from 0 to 4. The default value is 0 ms.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_COMPRESSOR before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetDistortion

Sets the parameters for the distortion effect on a particular channel

signed char F_API FSOUND_FX_SetDistortion(
int fxid,
float Gain,
float Edge,
float PostEQCenterFrequency,
float PostEQBandwidth,
float PreLowpassCutoff
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set distortion parameters for.
Gain | Amount of signal change after distortion, in the range from -60 through 0. The default value is 0 dB.
Edge | Percentage of distortion intensity, in the range in the range from 0 through 100. The default value is 50 percent.
PostEQCenterFrequency | Center frequency of harmonic content addition, in the range from 100 through 8000. The default value is 4000 Hz.
PostEQBandwidth | Width of frequency band that determines range of harmonic content addition, in the range from 100 through 8000. The default value is 4000 Hz.
PreLowpassCutoff | Filter cutoff for high-frequency harmonics attenuation, in the range from 100 through 8000. The default value is 4000 Hz.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_DISTORTION before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetEcho

Sets the parameters for the echo effect on a particular channel

signed char F_API FSOUND_FX_SetEcho(
int fxid,
float WetDryMix,
float Feedback,
float LeftDelay,
float RightDelay,
int PanDelay
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set echo parameters for.
WetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet).
Feedback | Percentage of output fed back into input, in the range from 0 through 100. The default value is 0.
LeftDelay | Delay for left channel, in milliseconds, in the range from 1 through 2000. The default value is 333 ms.
RightDelay | Delay for right channel, in milliseconds, in the range from 1 through 2000. The default value is 333 ms.
PanDelay | Value that specifies whether to swap left and right delays with each successive echo. The default value is FALSE, meaning no swap. Possible values are defined as TRUE or FALSE.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_Enable and FSOUND_FX_ECHO before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetFlanger

Sets the parameters for the flanger effect on a particular channel

signed char F_API FSOUND_FX_SetFlanger(
int fxid,
float WetDryMix,
float Depth,
float Feedback,
float Frequency,
int Waveform,
float Delay,
int Phase
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set flanger parameters for.
WetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet).
Depth | Percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Must be in the range from 0 through 100. The default value is 25.
Feedback | Percentage of output signal to feed back into the effects input, in the range from -99 to 99. The default value is 0.
Frequency | Frequency of the LFO, in the range from 0 to 10. The default value is 0.
Waveform | Waveform of the LFO. By default, the waveform is a sine. Possible values are defined as follows: 0 - Triangle. 1 - Sine.
Delay | Number of milliseconds the input is delayed before it is played back, in the range from 0 to 4. The default value is 0 ms.
Phase | Phase differential between left and right LFOs, in the range from 0 through 4. Possible values are defined as follows: 0 -180 degrees 1 - 90 degrees 2 0 degrees 3 90 degrees 4 180 degrees

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_Enable and FSOUND_FX_FLANGER before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetGargle

Sets the parameters for the gargle effect on a particular channel

signed char F_API FSOUND_FX_SetGargle(
int fxid,
int RateHz,
int WaveShape
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set gargle parameters for.
RateHz | Rate of modulation, in Hertz. Must be in the range from 1 through 1000.
WaveShape | Shape of the modulation wave. The following values are defined. 0 - Triangular wave. 1 - Square wave.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_Enable and FSOUND_FX_GARGLE before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetI3DL2Reverb

Sets the parameters for the I3DL2 Reverb effect on a particular channel

signed char F_API FSOUND_FX_SetI3DL2Reverb(
int fxid,
int Room,
int RoomHF,
float RoomRolloffFactor,
float DecayTime,
float DecayHFRatio,
int Reflections,
float ReflectionsDelay,
int Reverb,
float ReverbDelay,
float Diffusion,
float Density,
float HFReference
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set I3DL2 Reverb parameters for.
Room | Attenuation of the room effect, in millibels (mB), in the range from -10000 to 0. The default value is -1000 mB.
RoomHF | Attenuation of the room high-frequency effect, in mB, in the range from -10000 to 0. The default value is 0 mB.
RoomRolloffFactor | Rolloff factor for the reflected signals, in the range from 0 to 10. The default value is 0.0. The rolloff factor for the direct path is controlled by the listener.
DecayTime | Decay time, in seconds, in the range from .1 to 20. The default value is 1.49 seconds.
DecayHFRatio | Ratio of the decay time at high frequencies to the decay time at low frequencies, in the range from 0.1 to 2. The default value is 0.83.
Reflections | Attenuation of early reflections relative to lRoom, in mB, in the range from -10000 to 1000. The default value is -2602 mB.
ReflectionsDelay | Delay time of the first reflection relative to the direct path, in seconds, in the range from 0 to 0.3. The default value is 0.007 seconds.
Reverb | Attenuation of late reverberation relative to lRoom, in mB, in the range from -10000 to 2000. The default value is 200 mB.
ReverbDelay | Time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds, in the range from 0 to 0.1. The default value is 0.011 seconds.
Diffusion | Echo density in the late reverberation decay, in percent, in the range from 0 to 100. The default value is 100.0 percent.
Density | Modal density in the late reverberation decay, in percent, in the range from 0 to 100. The default value is 100.0 percent.
HFReference | Reference high frequency, in hertz, in the range from 20 to 20000. The default value is 5000.0 Hz.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_Enable and FSOUND_FX_I3DL2REVERB before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetParamEQ

Sets the parameters for the Param EQ effect on a particular channel

signed char F_API FSOUND_FX_SetParamEQ(
int fxid,
float Center,
float Bandwidth,
float Gain
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, to set ParamEQ parameters for.
Center | Center frequency, in hertz, in the range from 80 to 16000. This value cannot exceed one-third of the frequency of the buffer. Default is 8000.
Bandwidth | Bandwidth, in semitones, in the range from 1 to 36. Default is 12.
Gain | Gain, in the range from -15 to 15. Default is 0.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_Enable and FSOUND_FX_PARAMEQ before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_FX_SetWavesReverb

Sets the parameters for the Waves Reverb effect on a particular channel

signed char F_API FSOUND_FX_SetWavesReverb(
int fxid,
float InGain,
float ReverbMix,
float ReverbTime,
float HighFreqRTRatio
);

Parameters

fxid | fx handle generated by FSOUND_FX_Enable, number/handle to set Waves Reverb parameters for.
InGain | Input gain of signal, in decibels (dB), in the range from -96 through 0. The default value is 0 dB.
ReverbMix | Reverb mix, in dB, in the range from -96 through 0. The default value is 0 dB.
ReverbTime | Reverb time, in milliseconds, in the range from .001 through 3000. The default value is 1000.
HighFreqRTRatio | In the range from .001 through .999. The default value is 0.001.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Make sure you have enabled this effect with FSOUND_FX_WAVES_REVERB before using this function.
___________________
Supported on the following platforms : Win32

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_MODES , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ


[API function]

FSOUND_Record_GetDriver

Returns the currently selected recording driver number. Drivers are enumerated when selecting a driver
with FSOUND_Record_SetDriver or other driver related functions such as FSOUND_Record_GetNumDrivers or
FSOUND_Record_GetDriverName

int F_API FSOUND_Record_GetDriver(
);

Return Value

Currently selected driver id.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_GetDriver , FSOUND_Record_GetDriverName , FSOUND_Record_GetNumDrivers , FSOUND_Record_SetDriver


[API function]

FSOUND_Record_GetDriverName

Returns the name of the selected recording driver. Drivers are enumerated when selecting a driver with
FSOUND_Record_SetDriver or other driver related functions such as FSOUND_Record_GetNumDrivers or FSOUND_Record_GetDriver

const char * F_API FSOUND_Record_GetDriverName(
int id
);

Parameters

id Enumerated driver ID. This must be in a valid range delimited by FSOUND_Record_GetNumDrivers,

Return Value

On success, a pointer to a NULL terminated string containing the name of the specified device is returned. The number of drivers enumerated can be found with FSOUND_Record_GetNumDrivers.
On failure, NULL is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_GetDriver , FSOUND_Record_GetNumDrivers , FSOUND_Record_SetDriver


[API function]

FSOUND_Record_GetNumDrivers

Returns the number of sound cards or devices enumerated for the current input type. (Direct
Sound, WaveOut etc.)

int F_API FSOUND_Record_GetNumDrivers(
);

Return Value

Total number of enumerated sound devices.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_GetDriver , FSOUND_Record_GetDriverName , FSOUND_Record_SetDriver


[API function]

FSOUND_Record_GetPosition

Gets the position in the sample buffer that has been recorded to.

int F_API FSOUND_Record_GetPosition(
);

Return Value

On success, the offset in SAMPLES, for the record buffer that the input device has just written up to is returned.
On failure (recording device hasnt been started), -1 is returned.

Remarks

Note. This is not the 'recording cursor', but rather the latest point that the input has been copied to your sample
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_StartSample


[API function]

FSOUND_Record_SetDriver

Selects a soundcard recording driver.
It is used when an output mode has enumerated more than one recording device and you need to select between them.

signed char F_API FSOUND_Record_SetDriver(
int driver
);

Parameters

driverno Recording driver number to select.
<=0 will select the DEFAULT recording sound driver.
>0 Selects other valid drivers that can be listed with FSOUND_Record_GetDriverName.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_GetDriver , FSOUND_Record_GetDriverName , FSOUND_Record_GetNumDrivers


[API function]

FSOUND_Record_StartSample

Starts recording into a predefined sample using the sample's default playback rate as the recording rate.

signed char F_API FSOUND_Record_StartSample(
FSOUND_SAMPLE *sptr,
signed char loop
);

Parameters

sptr | The sample to record into.
loop | TRUE or FALSE flag whether the recorder should keep recording once it has hit the end, and start from the start again, therefore creating a continuous recording session into that sample buffer. Looping the recording buffer is good for realtime processing of recorded information, as you can record and playback the sample at the same time.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

If you want to play back the sample at the same time is is recording, you will have to play the sound and try and keep it just behind the recording cursor.
Under FSOUND_OUTPUT_OSS mode, it is single duplex, so playback will stop when recording is in progress! Try FSOUND_OUTPUT_ALSA for full duplex as they have better drivers in this respect.
-------------
The recording/playback rates are slightly innacurate and are not identical (ie 44100.0 for playback, 44100.1 for recording), so one could possibly be faster or slower than the other. In this case the recording and the playback cursor could overlap, and the output will sound corrupted.
To counter this you might adjust the playback frequency of the channel you are playing the record sample on while it plays, using FSOUND_GetCurrentPosition and FSOUND_Record_GetPosition as calibration points.
In the recording sample there is an example of trying to play back sound as it records, and the mechanism to try and keep the 2 cursors a safe distance from each other is employed.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_GetCurrentPosition , FSOUND_Record_GetPosition , FSOUND_Record_Stop


[API function]

FSOUND_Record_Stop

Halts recording to the specified sample.

signed char F_API FSOUND_Record_Stop(
);

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh

See Also

FSOUND_Record_StartSample


[API function]

FSOUND_Reverb_SetProperties

Sets hardware reverb parameters for advanced tuning.
The best way to modify these is to set everything to use pre-defined presets given in the header, and then start modifying values.

signed char F_API FSOUND_Reverb_SetProperties(
const FSOUND_REVERB_PROPERTIES *props
);

Parameters

prop A pointer to a FSOUND_REVERB_PROPERTIES struct. The definition for this structure is given in the link below.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

You must be using FSOUND_OUTPUT_DSOUND as the output mode for this to work.
In dsound, the reverb will only work if you have an EAX compatible soundcard such as the SBLive, and your sample/stream was created with the FSOUND_HW3D flag.
For GameCube, use FSOUND_AUXFX_xxx api.
___________________
Supported on the following platforms : Win32, XBox, PlayStation 2

See Also

FSOUND_Reverb_GetChannelProperties , FSOUND_Reverb_GetProperties , FSOUND_REVERB_PROPERTIES , FSOUND_Reverb_SetChannelProperties


[API function]

FSOUND_Reverb_GetProperties

Returns the current hardware reverb environment.

signed char F_API FSOUND_Reverb_GetProperties(
FSOUND_REVERB_PROPERTIES *props
);

Parameters

props Pointer to a FSOUND_REVERB_PROPERTIES structure definition. The definiotion for this structure is given in the link below.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

These values are only relevant if you are in DSOUND mode with an EAX3 compatible soundcard, or XBOX and PS2.
___________________
Supported on the following platforms : Win32, XBox, PlayStation 2

See Also

FSOUND_Reverb_GetChannelProperties , FSOUND_REVERB_PROPERTIES , FSOUND_Reverb_SetChannelProperties , FSOUND_Reverb_SetProperties


[API function]

FSOUND_Reverb_SetChannelProperties

Sets the channel specific reverb properties for hardware, including wet/dry mix (room size), and things like obstruction and occlusion properties.

signed char F_API FSOUND_Reverb_SetChannelProperties(
int channel,
const FSOUND_REVERB_CHANNELPROPERTIES *prop
);

Parameters

channel | The channel to have its reverb properties changed. FSOUND_ALL can also be used (see remarks)
prop | Pointer to a FSOUND_REVERB_CHANNELPROPERTIES structure definition. The definition for this structure is given in the link below.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

FSOUND_ALL is supported here. Passing this will set ALL channels to specified reverb properties.
If FSOUND_ALL is used the last channel success flag will be returned. This return value not useful in most circumstances.
-----------------
Under Win32, you must be using FSOUND_OUTPUT_DSOUND as the output mode for this to work.
In DSound, the reverb will only work if you have an EAX compatible soundcard such as the SBLive, and your sample/stream was created with the FSOUND_HW3D flag.
-----------------
On PlayStation2, the 'Room' parameter is the only parameter supported. The hardware only allows 'on' or 'off', so the reverb will be off when 'Room' is -10000 and on for every other value.
-----------------
On XBox, it is possible to apply reverb to 2d voices using this function. By default reverb is turned off for 2d voices.
If this 2d voice was being positioned in a 5.1 array with the xbox only function FSOUND_SetLevels, then calling this function will disable that capability in favour of enabling reverb for the 2d voice.
It is a limitation of the xbox hardware that only one of the other of these features can be executed at one time.
___________________
Supported on the following platforms : Win32, XBox, PlayStation 2.

See Also

FSOUND_REVERB_CHANNELPROPERTIES , FSOUND_Reverb_GetChannelProperties , FSOUND_Reverb_GetProperties , FSOUND_Reverb_SetProperties , FSOUND_SetLevels


[API function]

FSOUND_Reverb_GetChannelProperties

This function gets the current reverb properties for this channel.

signed char F_API FSOUND_Reverb_GetChannelProperties(
int channel,
FSOUND_REVERB_CHANNELPROPERTIES *prop
);

Parameters

channel | The channel to have its reverb mix returned.
prop | Pointer to a FSOUND_REVERB_CHANNELPROPERTIES structure definition. The definition for this structure is given in the link below.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, XBox

See Also

FSOUND_REVERB_CHANNELPROPERTIES , FSOUND_Reverb_GetProperties , FSOUND_Reverb_SetChannelProperties , FSOUND_Reverb_SetProperties


[Define]

FSOUND_CAPS

Driver description bitfields. Use FSOUND_Driver_GetCaps to determine if a driver enumerated
has the settings you are after. The enumerated driver depends on the output mode, see
FSOUND_OUTPUTTYPES

FSOUND_CAPS_HARDWARE | 0x1 /* This driver supports hardware accelerated 3d sound. */
FSOUND_CAPS_EAX2 | 0x2 /* This driver supports EAX 2 reverb */
FSOUND_CAPS_EAX3 | 0x10 /* This driver supports EAX 3 reverb */

See Also

FSOUND_GetDriverCaps , FSOUND_OUTPUTTYPES


[Define]

FSOUND_CDPLAYMODES

Playback method for a CD Audio track, with FSOUND_CD_SetPlayMode

FSOUND_CD_PLAYCONTINUOUS | 0 /* Starts from the current track and plays to end of CD. */
FSOUND_CD_PLAYONCE | 1 /* Plays the specified track then stops. */
FSOUND_CD_PLAYLOOPED | 2 /* Plays the specified track looped, forever until stopped manually. */
FSOUND_CD_PLAYRANDOM | 3 /* Plays tracks in random order */

See Also

FSOUND_CD_Play , FSOUND_CD_SetPlayMode


[Define]

FSOUND_DSP_PRIORITIES

These default priorities are used by FMOD internal system DSP units. They describe the
position of the DSP chain, and the order of how audio processing is executed.
You can actually through the use of FSOUND_DSP_GetxxxUnit (where xxx is the name of the DSP
unit), disable or even change the priority of a DSP unit.

FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT | 0 /* DSP CLEAR unit - done first */
FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT | 100 /* DSP SFX unit - done second */
FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT | 200 /* DSP MUSIC unit - done third */
FSOUND_DSP_DEFAULTPRIORITY_USER | 300 /* User priority, use this as reference for your own DSP units */
FSOUND_DSP_DEFAULTPRIORITY_FFTUNIT | 900 /* This reads data for FSOUND_DSP_GetSpectrum, so it comes after user units */
FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT | 1000 /* DSP CLIP AND COPY unit - last */

See Also

FSOUND_DSP_Create , FSOUND_DSP_GetSpectrum , FSOUND_DSP_SetPriority


[Define]

FSOUND_MODES

Sample description bitfields, OR them together for loading and describing samples.
NOTE. If the file format being loaded already has a defined format, such as WAV or MP3, then
trying to override the pre-defined format with a new set of format flags will not work. For
example, an 8 bit WAV file will not load as 16bit if you specify FSOUND_16BITS. It will just
ignore the flag and go ahead loading it as 8bits. For these type of formats the only flags
you can specify that will really alter the behaviour of how it is loaded, are the following.
---------
Looping behaviour - FSOUND_LOOP_OFF, FSOUND_LOOP_NORMAL, FSOUND_LOOP_BIDI
Load destination - FSOUND_HW3D, FSOUND_HW2D, FSOUND_2D
Loading behaviour - FSOUND_NONBLOCKING, FSOUND_LOADMEMORY, FSOUND_LOADRAW, FSOUND_MPEGACCURATE, FSOUND_MPEGHALFRATE, FSOUND_FORCEMONO
Playback behaviour - FSOUND_STREAMABLE, FSOUND_ENABLEFX
PlayStation 2 only - FSOUND_USECORE0, FSOUND_USECORE1, FSOUND_LOADMEMORYIOP
---------
See flag descriptions for what these do.

FSOUND_LOOP_OFF | 0x00000001 /* For non looping samples. */
FSOUND_LOOP_NORMAL | 0x00000002 /* For forward looping samples. */
FSOUND_LOOP_BIDI | 0x00000004 /* For bidirectional looping samples. (no effect if in hardware). */
FSOUND_8BITS | 0x00000008 /* For 8 bit samples. */
FSOUND_16BITS | 0x00000010 /* For 16 bit samples. */
FSOUND_MONO | 0x00000020 /* For mono samples. */
FSOUND_STEREO | 0x00000040 /* For stereo samples. */
FSOUND_UNSIGNED | 0x00000080 /* For user created source data containing unsigned samples. */
FSOUND_SIGNED | 0x00000100 /* For user created source data containing signed data. */
FSOUND_DELTA | 0x00000200 /* For user created source data stored as delta values. */
FSOUND_IT214 | 0x00000400 /* For user created source data stored using IT214 compression. */
FSOUND_IT215 | 0x00000800 /* For user created source data stored using IT215 compression. */
FSOUND_HW3D | 0x00001000 /* Attempts to make samples use 3d hardware acceleration. (if the card supports it) */
FSOUND_2D | 0x00002000 /* Tells software (not hardware) based sample not to be included in 3d processing. */
FSOUND_STREAMABLE | 0x00004000 /* For a streamimg sound where you feed the data to it. */
FSOUND_LOADMEMORY | 0x00008000 /* "name" will be interpreted as a pointer to data for streaming and samples. */
FSOUND_LOADRAW | 0x00010000 /* Will ignore file format and treat as raw pcm. */
FSOUND_MPEGACCURATE | 0x00020000 /* For FSOUND_Stream_Open - for accurate FSOUND_Stream_GetLengthMs/FSOUND_Stream_SetTime. WARNING, see FSOUND_Stream_Open for inital opening time performance issues. */
FSOUND_FORCEMONO | 0x00040000 /* For forcing stereo streams and samples to be mono - needed if using FSOUND_HW3D and stereo data - incurs a small speed hit for streams */
FSOUND_HW2D | 0x00080000 /* 2D hardware sounds. allows hardware specific effects */
FSOUND_ENABLEFX | 0x00100000 /* Allows DX8 FX to be played back on a sound. Requires DirectX 8 - Note these sounds cannot be played more than once, be 8 bit, be less than a certain size, or have a changing frequency */
FSOUND_MPEGHALFRATE | 0x00200000 /* For FMODCE only - decodes mpeg streams using a lower quality decode, but faster execution */
FSOUND_IMAADPCM | 0x00400000 /* Contents are stored compressed as IMA ADPCM */
FSOUND_VAG | 0x00800000 /* For PS2 only - Contents are compressed as Sony VAG format */
FSOUND_NONBLOCKING | 0x01000000 /* For FSOUND_Stream_Open/FMUSIC_LoadSong - Causes stream or music to open in the background and not block the foreground app. See FSOUND_Stream_GetOpenState or FMUSIC_GetOpenState to determine when it IS ready. */
FSOUND_GCADPCM | 0x02000000 /* For Gamecube only - Contents are compressed as Gamecube DSP-ADPCM format */
FSOUND_MULTICHANNEL | 0x04000000 /* For PS2 and Gamecube only - Contents are interleaved into a multi-channel (more than stereo) format */
FSOUND_USECORE0 | 0x08000000 /* For PS2 only - Sample/Stream is forced to use hardware voices 00-23 */
FSOUND_USECORE1 | 0x10000000 /* For PS2 only - Sample/Stream is forced to use hardware voices 24-47 */
FSOUND_LOADMEMORYIOP | 0x20000000 /* For PS2 only - "name" will be interpreted as a pointer to data for streaming and samples. The address provided will be an IOP address */
FSOUND_IGNORETAGS | 0x40000000 /* Skips id3v2 etc tag checks when opening a stream, to reduce seek/read overhead when opening files (helps with CD performance) */
FSOUND_STREAM_NET | 0x80000000 /* Specifies an internet stream */
FSOUND_NORMAL | (FSOUND_16BITS | FSOUND_SIGNED | FSOUND_MONO)

See Also

FMUSIC_GetOpenState , FMUSIC_LoadSong , FSOUND_Stream_GetLength , FSOUND_Stream_GetLengthMs , FSOUND_Stream_GetOpenState , FSOUND_Stream_Open , FSOUND_Stream_SetTime


[Define]

FSOUND_REVERB_PRESETS

A set of predefined environment PARAMETERS, created by Creative Labs
These are used to initialize an FSOUND_REVERB_PROPERTIES structure statically.
ie
FSOUND_REVERB_PROPERTIES prop = FSOUND_PRESET_GENERIC;

FSOUND_PRESET_OFF | {0, 7.5f, 1.00f, -10000, -10000, 0, 1.00f, 1.00f, 1.0f, -2602, 0.007f, { 0.0f,0.0f,0.0f }, 200, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 0.0f, 0.0f, 0x33f }
FSOUND_PRESET_GENERIC | {0, 7.5f, 1.00f, -1000, -100, 0, 1.49f, 0.83f, 1.0f, -2602, 0.007f, { 0.0f,0.0f,0.0f }, 200, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_PADDEDCELL | {1, 1.4f, 1.00f, -1000, -6000, 0, 0.17f, 0.10f, 1.0f, -1204, 0.001f, { 0.0f,0.0f,0.0f }, 207, 0.002f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_ROOM | {2, 1.9f, 1.00f, -1000, -454, 0, 0.40f, 0.83f, 1.0f, -1646, 0.002f, { 0.0f,0.0f,0.0f }, 53, 0.003f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_BATHROOM | {3, 1.4f, 1.00f, -1000, -1200, 0, 1.49f, 0.54f, 1.0f, -370, 0.007f, { 0.0f,0.0f,0.0f }, 1030, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 60.0f, 0x3f }
FSOUND_PRESET_LIVINGROOM | {4, 2.5f, 1.00f, -1000, -6000, 0, 0.50f, 0.10f, 1.0f, -1376, 0.003f, { 0.0f,0.0f,0.0f }, -1104, 0.004f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_STONEROOM | {5, 11.6f, 1.00f, -1000, -300, 0, 2.31f, 0.64f, 1.0f, -711, 0.012f, { 0.0f,0.0f,0.0f }, 83, 0.017f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_AUDITORIUM | {6, 21.6f, 1.00f, -1000, -476, 0, 4.32f, 0.59f, 1.0f, -789, 0.020f, { 0.0f,0.0f,0.0f }, -289, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_CONCERTHALL | {7, 19.6f, 1.00f, -1000, -500, 0, 3.92f, 0.70f, 1.0f, -1230, 0.020f, { 0.0f,0.0f,0.0f }, -2, 0.029f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_CAVE | {8, 14.6f, 1.00f, -1000, 0, 0, 2.91f, 1.30f, 1.0f, -602, 0.015f, { 0.0f,0.0f,0.0f }, -302, 0.022f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x1f }
FSOUND_PRESET_ARENA | {9, 36.2f, 1.00f, -1000, -698, 0, 7.24f, 0.33f, 1.0f, -1166, 0.020f, { 0.0f,0.0f,0.0f }, 16, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_HANGAR | {10, 50.3f, 1.00f, -1000, -1000, 0, 10.05f, 0.23f, 1.0f, -602, 0.020f, { 0.0f,0.0f,0.0f }, 198, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_CARPETTEDHALLWAY | {11, 1.9f, 1.00f, -1000, -4000, 0, 0.30f, 0.10f, 1.0f, -1831, 0.002f, { 0.0f,0.0f,0.0f }, -1630, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_HALLWAY | {12, 1.8f, 1.00f, -1000, -300, 0, 1.49f, 0.59f, 1.0f, -1219, 0.007f, { 0.0f,0.0f,0.0f }, 441, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_STONECORRIDOR | {13, 13.5f, 1.00f, -1000, -237, 0, 2.70f, 0.79f, 1.0f, -1214, 0.013f, { 0.0f,0.0f,0.0f }, 395, 0.020f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_ALLEY | {14, 7.5f, 0.30f, -1000, -270, 0, 1.49f, 0.86f, 1.0f, -1204, 0.007f, { 0.0f,0.0f,0.0f }, -4, 0.011f, { 0.0f,0.0f,0.0f }, 0.125f, 0.95f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_FOREST | {15, 38.0f, 0.30f, -1000, -3300, 0, 1.49f, 0.54f, 1.0f, -2560, 0.162f, { 0.0f,0.0f,0.0f }, -229, 0.088f, { 0.0f,0.0f,0.0f }, 0.125f, 1.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 79.0f, 100.0f, 0x3f }
FSOUND_PRESET_CITY | {16, 7.5f, 0.50f, -1000, -800, 0, 1.49f, 0.67f, 1.0f, -2273, 0.007f, { 0.0f,0.0f,0.0f }, -1691, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 50.0f, 100.0f, 0x3f }
FSOUND_PRESET_MOUNTAINS | {17, 100.0f, 0.27f, -1000, -2500, 0, 1.49f, 0.21f, 1.0f, -2780, 0.300f, { 0.0f,0.0f,0.0f }, -1434, 0.100f, { 0.0f,0.0f,0.0f }, 0.250f, 1.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 27.0f, 100.0f, 0x1f }
FSOUND_PRESET_QUARRY | {18, 17.5f, 1.00f, -1000, -1000, 0, 1.49f, 0.83f, 1.0f, -10000, 0.061f, { 0.0f,0.0f,0.0f }, 500, 0.025f, { 0.0f,0.0f,0.0f }, 0.125f, 0.70f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_PLAIN | {19, 42.5f, 0.21f, -1000, -2000, 0, 1.49f, 0.50f, 1.0f, -2466, 0.179f, { 0.0f,0.0f,0.0f }, -1926, 0.100f, { 0.0f,0.0f,0.0f }, 0.250f, 1.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 21.0f, 100.0f, 0x3f }
FSOUND_PRESET_PARKINGLOT | {20, 8.3f, 1.00f, -1000, 0, 0, 1.65f, 1.50f, 1.0f, -1363, 0.008f, { 0.0f,0.0f,0.0f }, -1153, 0.012f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x1f }
FSOUND_PRESET_SEWERPIPE | {21, 1.7f, 0.80f, -1000, -1000, 0, 2.81f, 0.14f, 1.0f, 429, 0.014f, { 0.0f,0.0f,0.0f }, 1023, 0.021f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 0.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 80.0f, 60.0f, 0x3f }
FSOUND_PRESET_UNDERWATER | {22, 1.8f, 1.00f, -1000, -4000, 0, 1.49f, 0.10f, 1.0f, -449, 0.007f, { 0.0f,0.0f,0.0f }, 1700, 0.011f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 1.18f, 0.348f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x3f }
FSOUND_PRESET_DRUGGED | {23, 1.9f, 0.50f, -1000, 0, 0, 8.39f, 1.39f, 1.0f, -115, 0.002f, { 0.0f,0.0f,0.0f }, 985, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 0.25f, 1.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x1f }
FSOUND_PRESET_DIZZY | {24, 1.8f, 0.60f, -1000, -400, 0, 17.23f, 0.56f, 1.0f, -1713, 0.020f, { 0.0f,0.0f,0.0f }, -613, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 1.00f, 0.81f, 0.310f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x1f }
FSOUND_PRESET_PSYCHOTIC | {25, 1.0f, 0.50f, -1000, -151, 0, 7.56f, 0.91f, 1.0f, -626, 0.020f, { 0.0f,0.0f,0.0f }, 774, 0.030f, { 0.0f,0.0f,0.0f }, 0.250f, 0.00f, 4.00f, 1.000f, -5.0f, 5000.0f, 250.0f, 0.0f, 100.0f, 100.0f, 0x1f }
FSOUND_PRESET_PS2_ROOM | {1, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_STUDIO_A | {2, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_STUDIO_B | {3, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_STUDIO_C | {4, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_HALL | {5, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_SPACE | {6, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_ECHO | {7, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_DELAY | {8, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }
FSOUND_PRESET_PS2_PIPE | {9, 0, 0, 0, 0, 0, 0.0f, 0.0f, 0.0f, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0, 0.000f, { 0.0f,0.0f,0.0f }, 0.000f, 0.00f, 0.00f, 0.000f, 0.0f, 0000.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0x31f }

See Also

FSOUND_REVERB_PROPERTIES , FSOUND_Reverb_SetProperties


[Define]

FSOUND_MISC_VALUES

Miscellaneous values for FMOD functions.

FSOUND_FREE | -1 /* value to play on any free channel, or to allocate a sample in a free sample slot. */
FSOUND_UNMANAGED | -2 /* value to allocate a sample that is NOT managed by FSOUND or placed in a sample slot. */
FSOUND_ALL | -3 /* for a channel index , this flag will affect ALL channels available! Not supported by every function. */
FSOUND_STEREOPAN | -1 /* value for FSOUND_SetPan so that stereo sounds are not played at half volume. See FSOUND_SetPan for more on this. */
FSOUND_SYSTEMCHANNEL | -1000 /* special 'channel' ID for all channel based functions that want to alter the global FSOUND software mixing output channel */
FSOUND_SYSTEMSAMPLE | -1000 /* special 'sample' ID for all sample based functions that want to alter the global FSOUND software mixing output sample */

See Also

FSOUND_PlaySound , FSOUND_PlaySoundEx , FSOUND_Sample_Alloc , FSOUND_Sample_Load , FSOUND_SetPan


[Enum]

FMOD_ERRORS

On failure of commands in FMOD, use FSOUND_GetError to attain what happened.

Enumerators

FMOD_ERR_NONE | /* No errors */
FMOD_ERR_BUSY | /* Cannot call this command after FSOUND_Init. Call FSOUND_Close first. */
FMOD_ERR_UNINITIALIZED | /* This command failed because FSOUND_Init or FSOUND_SetOutput was not called */
FMOD_ERR_INIT | /* Error initializing output device. */
FMOD_ERR_ALLOCATED | /* Error initializing output device, but more specifically, the output device is already in use and cannot be reused. */
FMOD_ERR_PLAY | /* Playing the sound failed. */
FMOD_ERR_OUTPUT_FORMAT | /* Soundcard does not support the features needed for this soundsystem (16bit stereo output) */
FMOD_ERR_COOPERATIVELEVEL | /* Error setting cooperative level for hardware. */
FMOD_ERR_CREATEBUFFER | /* Error creating hardware sound buffer. */
FMOD_ERR_FILE_NOTFOUND | /* File not found */
FMOD_ERR_FILE_FORMAT | /* Unknown file format */
FMOD_ERR_FILE_BAD | /* Error loading file */
FMOD_ERR_MEMORY | /* Not enough memory or resources */
FMOD_ERR_VERSION | /* The version number of this file format is not supported */
FMOD_ERR_INVALID_PARAM | /* An invalid parameter was passed to this function */
FMOD_ERR_NO_EAX | /* Tried to use an EAX command on a non EAX enabled channel or output. */
FMOD_ERR_CHANNEL_ALLOC | /* Failed to allocate a new channel */
FMOD_ERR_RECORD | /* Recording is not supported on this machine */
FMOD_ERR_MEDIAPLAYER | /* Windows Media Player not installed so cannot play wma or use internet streaming. */
FMOD_ERR_CDDEVICE | /* An error occured trying to open the specified CD device */

See Also

FSOUND_Close , FSOUND_GetError , FSOUND_Init , FSOUND_SetOutput


[Enum]

FSOUND_MIXERTYPES

These mixer types are used with FSOUND_SetMixer, to choose which mixer to use, or to act
upon for other reasons using FSOUND_GetMixer.
It is not nescessary to set the mixer. FMOD will autodetect the best mixer for you.

Enumerators

FSOUND_MIXER_AUTODETECT | /* CE/PS2/GC Only - Non interpolating/low quality mixer. */
FSOUND_MIXER_BLENDMODE | /* Removed / obsolete. */
FSOUND_MIXER_MMXP5 | /* Removed / obsolete. */
FSOUND_MIXER_MMXP6 | /* Removed / obsolete. */
FSOUND_MIXER_QUALITY_AUTODETECT,/* |
FSOUND_MIXER_QUALITY_FPU | /* Win32/Linux only - Interpolating/volume ramping FPU mixer. */
FSOUND_MIXER_QUALITY_MMXP5 | /* Win32/Linux only - Interpolating/volume ramping P5 MMX mixer. */
FSOUND_MIXER_QUALITY_MMXP6 | /* Win32/Linux only - Interpolating/volume ramping ppro+ MMX mixer. */
FSOUND_MIXER_MONO | /* CE/PS2/GC only - MONO non interpolating/low quality mixer. For speed*/
FSOUND_MIXER_QUALITY_MONO | /* CE/PS2/GC only - MONO Interpolating mixer. For speed */
FSOUND_MIXER_MAX |

See Also

FSOUND_GetMixer , FSOUND_SetMixer


[Enum]

FSOUND_OUTPUTTYPES

These output types are used with FSOUND_SetOutput, to choose which output driver to use.
FSOUND_OUTPUT_DSOUND will not support hardware 3d acceleration if the sound card driver
does not support DirectX 6 Voice Manager Extensions.
FSOUND_OUTPUT_WINMM is recommended for NT and CE.

Enumerators

FSOUND_OUTPUT_NOSOUND | /* NoSound driver, all calls to this succeed but do nothing. */
FSOUND_OUTPUT_WINMM | /* Windows Multimedia driver. */
FSOUND_OUTPUT_DSOUND | /* DirectSound driver. You need this to get EAX2 or EAX3 support, or FX api support. */
FSOUND_OUTPUT_A3D | /* A3D driver. */
FSOUND_OUTPUT_OSS | /* Linux/Unix OSS (Open Sound System) driver, i.e. the kernel sound drivers. */
FSOUND_OUTPUT_ESD | /* Linux/Unix ESD (Enlightment Sound Daemon) driver. */
FSOUND_OUTPUT_ALSA | /* Linux Alsa driver. */
FSOUND_OUTPUT_ASIO | /* Low latency ASIO driver */
FSOUND_OUTPUT_XBOX | /* Xbox driver */
FSOUND_OUTPUT_PS2 | /* PlayStation 2 driver */
FSOUND_OUTPUT_MAC | /* Mac SoundManager driver */
FSOUND_OUTPUT_GC | /* Gamecube driver */
FSOUND_OUTPUT_PSP | /* PlayStation Portable driver */
FSOUND_OUTPUT_NOSOUND_NONREALTIME | /* This is the same as nosound, but the sound generation is driven by FSOUND_Update */

See Also

FSOUND_GetOutput , FSOUND_SetOutput , FSOUND_Update


[Structure]

FSOUND_REVERB_PROPERTIES

Structure defining a reverb environment.
For more indepth descriptions of the reverb properties under win32, please see the EAX2 and EAX3
documentation at http://developer.creative.com/ under the 'downloads' section.
If they do not have the EAX3 documentation, then most information can be attained from
the EAX2 documentation, as EAX3 only adds some more parameters and functionality on top of EAX2.
Note the default reverb properties are the same as the FSOUND_PRESET_GENERIC preset.
Note that integer values that typically range from -10,000 to 1000 are represented in decibels, and are of a logarithmic scale, not linear, wheras float values are typically linear.
PORTABILITY: Each member has the platform it supports in braces ie (win32/xbox).
Some reverb parameters are only supported in win32 and some only on xbox. If all parameters are set then the reverb should product a similar effect on either platform.
The numerical values listed below are the maximum, minimum and default values for each variable respectively.

Members

unsigned int | Environment | /* 0 , 25 , 0 , sets all listener properties (WIN32/PS2 only) */
float | EnvSize | /* 1.0 , 100.0 , 7.5 , environment size in meters (WIN32 only) */
float | EnvDiffusion | /* 0.0 , 1.0 , 1.0 , environment diffusion (WIN32/XBOX) */
int | Room | /* -10000, 0 , -1000 , room effect level (at mid frequencies) (WIN32/XBOX/PS2) */
int | RoomHF | /* -10000, 0 , -100 , relative room effect level at high frequencies (WIN32/XBOX) */
int | RoomLF | /* -10000, 0 , 0 , relative room effect level at low frequencies (WIN32 only) */
float | DecayTime | /* 0.1 , 20.0 , 1.49 , reverberation decay time at mid frequencies (WIN32/XBOX) */
float | DecayHFRatio | /* 0.1 , 2.0 , 0.83 , high-frequency to mid-frequency decay time ratio (WIN32/XBOX) */
float | DecayLFRatio | /* 0.1 , 2.0 , 1.0 , low-frequency to mid-frequency decay time ratio (WIN32 only) */
int | Reflections | /* -10000, 1000 , -2602 , early reflections level relative to room effect (WIN32/XBOX) */
float | ReflectionsDelay | /* 0.0 , 0.3 , 0.007 , initial reflection delay time (WIN32/XBOX) */
float | ReflectionsPan[3] | /* , , [0,0,0], early reflections panning vector (WIN32 only) */
int | Reverb | /* -10000, 2000 , 200 , late reverberation level relative to room effect (WIN32/XBOX) */
float | ReverbDelay | /* 0.0 , 0.1 , 0.011 , late reverberation delay time relative to initial reflection (WIN32/XBOX) */
float | ReverbPan[3] | /* , , [0,0,0], late reverberation panning vector (WIN32 only) */
float | EchoTime | /* .075 , 0.25 , 0.25 , echo time (WIN32/PS2 only. PS2 = Delay time for ECHO/DELAY modes only) */
float | EchoDepth | /* 0.0 , 1.0 , 0.0 , echo depth (WIN32/PS2 only. PS2 = Feedback level for ECHO mode only) */
float | ModulationTime | /* 0.04 , 4.0 , 0.25 , modulation time (WIN32 only) */
float | ModulationDepth | /* 0.0 , 1.0 , 0.0 , modulation depth (WIN32 only) */
float | AirAbsorptionHF | /* -100 , 0.0 , -5.0 , change in level per meter at high frequencies (WIN32 only) */
float | HFReference | /* 1000.0, 20000 , 5000.0 , reference high frequency (hz) (WIN32/XBOX) */
float | LFReference | /* 20.0 , 1000.0, 250.0 , reference low frequency (hz) (WIN32 only) */
float | RoomRolloffFactor | /* 0.0 , 10.0 , 0.0 , like FSOUND_3D_SetRolloffFactor but for room effect (WIN32/XBOX) */
float | Diffusion | /* 0.0 , 100.0 , 100.0 , Value that controls the echo density in the late reverberation decay. (XBOX only) */
float | Density | /* 0.0 , 100.0 , 100.0 , Value that controls the modal density in the late reverberation decay (XBOX only) */
unsigned int | Flags | /* FSOUND_REVERB_FLAGS - modifies the behavior of above properties (WIN32/PS2 only) */

See Also

FSOUND_3D_SetRolloffFactor , FSOUND_REVERB_FLAGS , FSOUND_Reverb_GetProperties , FSOUND_REVERB_PRESETS , FSOUND_Reverb_SetProperties


[Structure]

FSOUND_REVERB_CHANNELPROPERTIES

Structure defining the properties for a reverb source, related to a FSOUND channel.
For more indepth descriptions of the reverb properties under win32, please see the EAX3
documentation at http://developer.creative.com/ under the 'downloads' section.
If they do not have the EAX3 documentation, then most information can be attained from
the EAX2 documentation, as EAX3 only adds some more parameters and functionality on top of
EAX2.
Note the default reverb properties are the same as the FSOUND_PRESET_GENERIC preset.
Note that integer values that typically range from -10,000 to 1000 are represented in
decibels, and are of a logarithmic scale, not linear, wheras float values are typically linear.
PORTABILITY: Each member has the platform it supports in braces ie (win32/xbox).
Some reverb parameters are only supported in win32 and some only on xbox. If all parameters are set then
the reverb should product a similar effect on either platform.
Linux and FMODCE do not support the reverb api.
The numerical values listed below are the maximum, minimum and default values for each variable respectively.

Members

int | Direct | /* -10000, 1000, 0, direct path level (at low and mid frequencies) (WIN32/XBOX) */
int | DirectHF | /* -10000, 0, 0, relative direct path level at high frequencies (WIN32/XBOX) */
int | Room | /* -10000, 1000, 0, room effect level (at low and mid frequencies) (WIN32/XBOX/PS2) */
int | RoomHF | /* -10000, 0, 0, relative room effect level at high frequencies (WIN32/XBOX) */
int | Obstruction | /* -10000, 0, 0, main obstruction control (attenuation at high frequencies) (WIN32/XBOX) */
float | ObstructionLFRatio | /* 0.0, 1.0, 0.0, obstruction low-frequency level re. main control (WIN32/XBOX) */
int | Occlusion | /* -10000, 0, 0, main occlusion control (attenuation at high frequencies) (WIN32/XBOX) */
float | OcclusionLFRatio | /* 0.0, 1.0, 0.25, occlusion low-frequency level re. main control (WIN32/XBOX) */
float | OcclusionRoomRatio | /* 0.0, 10.0, 1.5, relative occlusion control for room effect (WIN32) */
float | OcclusionDirectRatio | /* 0.0, 10.0, 1.0, relative occlusion control for direct path (WIN32) */
int | Exclusion | /* -10000, 0, 0, main exlusion control (attenuation at high frequencies) (WIN32) */
float | ExclusionLFRatio | /* 0.0, 1.0, 1.0, exclusion low-frequency level re. main control (WIN32) */
int | OutsideVolumeHF | /* -10000, 0, 0, outside sound cone level at high frequencies (WIN32) */
float | DopplerFactor | /* 0.0, 10.0, 0.0, like DS3D flDopplerFactor but per source (WIN32) */
float | RolloffFactor | /* 0.0, 10.0, 0.0, like DS3D flRolloffFactor but per source (WIN32) */
float | RoomRolloffFactor | /* 0.0, 10.0, 0.0, like DS3D flRolloffFactor but for room effect (WIN32/XBOX) */
float | AirAbsorptionFactor | /* 0.0, 10.0, 1.0, multiplies AirAbsorptionHF member of FSOUND_REVERB_PROPERTIES (WIN32) */
int | Flags | /* FSOUND_REVERB_CHANNELFLAGS - modifies the behavior of properties (WIN32) */

See Also

FSOUND_REVERB_CHANNELFLAGS , FSOUND_Reverb_GetChannelProperties , FSOUND_REVERB_PROPERTIES , FSOUND_Reverb_SetChannelProperties


[Structure]

FSOUND_TOC_TAG

Structure defining a CD table of contents. This structure is returned as a tag from FSOUND_Stream_FindTagField when the tag name "CD_TOC" is specified.
Note: All tracks on the CD - including data tracks- will be represented in this structure so it's use for anything other than generating disc id information is not recommended.
See the cdda example program for info on retrieving and using this structure.

Members

char | name[4] | /* The string "TOC", just in case this structure is accidentally treated as a string */
int | numtracks | /* The number of tracks on the CD */
int | min[100] | /* The start offset of each track in minutes */
int | sec[100] | /* The start offset of each track in seconds */
int | frame[100] | /* The start offset of each track in frames */

See Also

FSOUND_Stream_FindTagField , FSOUND_Stream_Open


FMUSIC API Reference

FMOD Api. Use this to module files etc

Functions , Structures , Defines , Enums

+ Functions

- Functions

FMUSIC_CALLBACK
FMUSIC_FreeSong
FMUSIC_GetBPM
FMUSIC_GetGlobalVolume
FMUSIC_GetMasterVolume
FMUSIC_GetName
FMUSIC_GetNumChannels
FMUSIC_GetNumInstruments
FMUSIC_GetNumOrders
FMUSIC_GetNumPatterns
FMUSIC_GetNumSamples
FMUSIC_GetOpenState
FMUSIC_GetOrder
FMUSIC_GetPattern
FMUSIC_GetPatternLength
FMUSIC_GetPaused
FMUSIC_GetRealChannel
FMUSIC_GetRow
FMUSIC_GetSample
FMUSIC_GetSpeed
FMUSIC_GetTime
FMUSIC_GetType
FMUSIC_GetUserData
FMUSIC_IsFinished
FMUSIC_IsPlaying
FMUSIC_LoadSong
FMUSIC_LoadSongEx
FMUSIC_OptimizeChannels
FMUSIC_PlaySong
FMUSIC_SetInstCallback
FMUSIC_SetLooping
FMUSIC_SetMasterSpeed
FMUSIC_SetMasterVolume
FMUSIC_SetOrder
FMUSIC_SetOrderCallback
FMUSIC_SetPanSeperation
FMUSIC_SetPaused
FMUSIC_SetReverb
FMUSIC_SetRowCallback
FMUSIC_SetSample
FMUSIC_SetUserData
FMUSIC_SetZxxCallback
FMUSIC_StopAllSongs
FMUSIC_StopSong

+ Structures

- Structures

FSOUND_REVERB_CHANNELPROPERTIES
FSOUND_REVERB_PROPERTIES
FSOUND_TOC_TAG

+ Defines

- Defines

FSOUND_CAPS
FSOUND_CDPLAYMODES
FSOUND_DSP_PRIORITIES
FSOUND_INIT_FLAGS
FSOUND_MISC_VALUES
FSOUND_MODES
FSOUND_REVERB_CHANNELFLAGS
FSOUND_REVERB_FLAGS
FSOUND_REVERB_PRESETS
FSOUND_STATUS_FLAGS

+ Enums

- Enums

This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.
Generated Fri Nov 18 00:31:54 2005 by SourceDoc v0.10, the automated source code documenter.


[API function]

FMUSIC_CALLBACK

Callback definition for FMUSIC callbacks (mod/s3m/xm/it).

void F_CALLBACKAPI FMUSIC_CALLBACK(
FMUSIC_MODULE *mod,
unsigned char param
);

Parameters

mod | The music file to have callbacks performed on.
param | The argument relating specifically to the callback made, whether it is a row/order or Zxx callback. For example on the row callback, the row number would be returned.

Return Value

void

Remarks

The callbacks are made from within the mixer system, so it is best to keep the code to an absolute minimum to prevent sound breakup.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetInstCallback , FMUSIC_SetOrderCallback , FMUSIC_SetRowCallback , FMUSIC_SetZxxCallback


[API function]

FMUSIC_FreeSong

Frees memory allocated for a song and removes it from the FMUSIC system.

signed char F_API FMUSIC_FreeSong(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to be freed.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

See Also

FMUSIC_LoadSong , FMUSIC_LoadSongEx


[API function]

FMUSIC_LoadSong

To load a module or bank with a given filename. FMUSIC Supports loading of
- .MOD (protracker/fasttracker modules)
- .S3M (screamtracker 3 modules)
- .XM (fasttracker 2 modules)
- .IT (impulse tracker modules)
- .MID (MIDI files)
- .RMI (MIDI files)
- .SGT (DirectMusic segment files)
- .FSB (FMOD Sample Bank files)

FMUSIC_MODULE * F_API FMUSIC_LoadSong(
const char *name
);

Parameters

name Filename of module to load.

Return Value

On success, a pointer to a FMUSIC_MODULE handle is returned.
On failure, NULL is returned.

Remarks

This function autodetects the format type, regardless of filename.
The MIDI loader does not support user file callbacks. For WAD type data structures with embedded MIDI files FMUSIC_LoadSongEx will have to be used with memory loading.
Various other functionality is not provided in MIDI. See relevant FMUSIC functions to see if a feature
is supported or not.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_FreeSong , FMUSIC_LoadSong , FMUSIC_LoadSongEx , FSOUND_File_SetCallbacks


[API function]

FMUSIC_LoadSongEx

To load a module or bank with a given filename. FMUSIC Supports loading of
- .MOD (protracker/fasttracker modules)
- .S3M (screamtracker 3 modules)
- .XM (fasttracker 2 modules)
- .IT (impulse tracker modules)
- .MID (MIDI files)
- .RMI (MIDI files)
- .SGT (DirectMusic segment files)
- .FSB (FMOD Sample Bank files)

FMUSIC_MODULE * F_API FMUSIC_LoadSongEx(
const char *name_or_data,
int offset,
int length,
unsigned int mode,
const int *samplelist,
int samplelistnum
);

Parameters

name_or_data | Name of song or pointer to data containing song to load (if loading from memory and not file). On PlayStation 2 data must be 16 byte aligned if loading from memory.
offset | Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening.
length | Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading.
mode | Mode for opening song. With module files, only FSOUND_LOADMEMORY, FSOUND_NONBLOCKING, FSOUND_LOOP_NORMAL, or FSOUND_LOOP_OFF are supported. For FSB files, FSOUND_2D, FSOUND_HW3D, FSOUND_FORCEMONO also work.
samplelist | Optional. Pointer to array of sample indicies to load. Leave as NULL if you want all samples to be loaded (default behaviour). See Remarks for more on this.
samplelistnum | Optional. Number of entries in the samplelist array.

Return Value

On success, a FMUSIC_MODULE handle is returned.
On failure, NULL is returned.

Remarks

Loading a song from a memory handle is dangerous in one respect, if the data is corrupted or truncated, then FMUSIC could crash internally trying to load it.
On PlayStation 2 the data and length pointer must be 16 byte aligned for DMA purposes.
The samplelist and samplelistnum parameters are useful for limiting the amount of data fmod loads. This feature is for the FSB format only. It is especially useful if you have a bank of sounds and want to randomize the loading a bit by telling which sounds to load with random values, and consequently which not to load.
On PlayStation 2, samplelistnum has a limit of 1536 entries.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation2, GameCube

See Also

FMUSIC_FreeSong , FMUSIC_LoadSong


[API function]

FMUSIC_OptimizeChannels

This function helps with channel usage. If you are desperate for channels, and you are prepared to
let the music routines drop a few channels, then calling this function can help.
It basically doesnt try to play any new sounds if a certain channel limit is being played (including sound effects),
and the new sound is below a certain specified volume.
ie.
You set it to maxchannels = 16, and minvolume = 0x10.
In this case, the mod will play normally as long as the total number of channels being played inclusing sound effefcts is below 16
(see FSOUND_GetChannelsPlaying).
If the number of channels playing exceeds 16 (through a change in the music, or extra sound effects
are spawned, then sounds with a musician specified volume of less than 0x10 will be ignored.
The volume is based on volume column/default volume/volume set commands in the mod. master volume,
envelope volumes etc are not taken into account (this gives more control over how it will work from the
tracker).

DLL_API signed char F_API FMUSIC_OptimizeChannels(
FMUSIC_MODULE *mod,
int maxchannels,
int minvolume
);

Parameters

mod | Pointer to the song to set channel/volume optimization settings.
maxchannels | Channel count to be mixed before fmusic starts to drop channels from the song.
minvolume | If maxchannels is exceeded, then music channels with volumes below this value will not be played. Range is 0-64. This is the value the tracker displays. All trackers use 0-64.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

maxchannels will default to the number of channels allocated by FSOUND, so this will never happen
by default.
minvolume will default to 0, so it will always succeed by default.
To see how many channels are currently being MIXED, use FSOUND_GetChannelsPlaying.
As a musician mentioned to me once, most of his default volumes are set fairly high, and any low end
volumes are usually echoes etc, and can afford to be dropped.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_GetChannelsPlaying


[API function]

FMUSIC_PlaySong

Starts a song playing.

signed char F_API FMUSIC_PlaySong(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to be played.

Return Value

TRUE song succeeded playing
FALSE song failed playing

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_IsPlaying , FMUSIC_SetLooping , FMUSIC_StopAllSongs , FMUSIC_StopSong


[API function]

FMUSIC_SetInstCallback

Sets a user callback to occur every time a instrument is played, triggered from a MOD, S3M, XM or IT file.

signed char F_API FMUSIC_SetInstCallback(
FMUSIC_MODULE *mod,
FMUSIC_CALLBACK callback,
int instrument
);

Parameters

mod | The module or song to set the callback for.
callback | The callback function you supply to get called.
instrument | Call the callback when this instrument number is triggered.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

It is important to note that this callback will be called from directly WITHIN the
mixer / music update thread, therefore it is imperative that whatever you do from this
callback be extremely efficient. If the routine takes too long then breakups in the sound
will occur, or it will basically stop mixing until you return from the function.
This sort of function is usually best for just setting a flag, or do some simple variable
manipulation, and then exiting, letting your main thread do what it needs to based on these
flags or variables.
------------
This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization.
Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_CALLBACK , FMUSIC_SetOrderCallback , FMUSIC_SetRowCallback , FMUSIC_SetZxxCallback


[API function]

FMUSIC_SetLooping

Sets looping mode for midi and mod files.

signed char F_API FMUSIC_SetLooping(
FMUSIC_MODULE *mod,
signed char looping
);

Parameters

mod | Pointer to the song.
looping | Set to TRUE to make it loop forever, or FALSE to only have it play once.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Defaults to TRUE. To disable looping you must call this function using FALSE as the parameter.
For midi files this only takes effect before FMUSIC_PlaySong is called. For mod files this
can be called at any time including during playback.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_PlaySong


[API function]

FMUSIC_SetMasterSpeed

Sets a songs master speed scale, so that the song can be sped up or slowed down.

signed char F_API FMUSIC_SetMasterSpeed(
FMUSIC_MODULE *mod,
F_FLOAT_API speed
);

Parameters

mod | Pointer to the song to have its speed scale set.
speed | Speed scale for song. 1.0 is default. Minimum is 0 (stopped), maximum is 10.0.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_SetMasterVolume

Sets a songs master volume.

signed char F_API FMUSIC_SetMasterVolume(
FMUSIC_MODULE *mod,
int volume
);

Parameters

mod | Pointer to the song to have its master volume set.
volume | value from 0-256. 0 = silence, 256 = full volume.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Note if the hardware midi synth is selected, you cannot set the master volume.
This command will only work reliably if FSOUND_INIT_USEDEFAULTMIDISYNTH is selected.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetGlobalVolume , FMUSIC_GetMasterVolume , FSOUND_GetSFXMasterVolume , FSOUND_SetSFXMasterVolume


[API function]

FMUSIC_SetOrder

Sets a songs order position / current playing position.

signed char F_API FMUSIC_SetOrder(
FMUSIC_MODULE *mod,
int order
);

Parameters

mod | Pointer to the song to have its order changed.
order | Order number to jump to.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetOrder


[API function]

FMUSIC_SetOrderCallback

Sets a user callback to occur on every order divisible by the orderstep parameter, played from a MOD, S3M, XM or IT file.

signed char F_API FMUSIC_SetOrderCallback(
FMUSIC_MODULE *mod,
FMUSIC_CALLBACK callback,
int orderstep
);

Parameters

mod | The module or song to set the callback for.
callback | The callback function you supply to get called.
orderstep | Call the callback every multiple of this number of orders.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

It is important to note that this callback will be called from directly WITHIN the
mixer / music update thread, therefore it is imperative that whatever you do from this
callback be extremely efficient. If the routine takes too long then breakups in the sound
will occur, or it will basically stop mixing until you return from the function.
This sort of function is usually best for just setting a flag, or do some simple variable
manipulation, and then exiting, letting your main thread do what it needs to based on these
flags or variables.
------------
This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization.
Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_CALLBACK , FMUSIC_SetInstCallback , FMUSIC_SetRowCallback , FMUSIC_SetZxxCallback


[API function]

FMUSIC_SetPanSeperation

Sets the master pan seperation for a module.

signed char F_API FMUSIC_SetPanSeperation(
FMUSIC_MODULE *mod,
F_FLOAT_API pansep
);

Parameters

pansep The pan scale. 1.0 means full pan seperation, 0 means mono.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This is set to 1.0 by default.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetPanSeperation


[API function]

FMUSIC_SetPaused

Pauses a song

signed char F_API FMUSIC_SetPaused(
FMUSIC_MODULE *mod,
signed char pause
);

Parameters

mod | Pointer to the song to be paused/unpaused.
pause | TRUE - song should be PAUSED, FALSE - song should be UNPAUSED

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetPaused


[API function]

FMUSIC_SetReverb

Turns on reverb for MIDI/RMI files.

signed char F_API FMUSIC_SetReverb(
signed char reverb
);

Parameters

reverb Set to TRUE to turn MIDI reverb on, FALSE to turn MIDI reverb off.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Reverb may be enabled through software emulation in the future for MOD based formats.
___________________
Supported on the following platforms : Win32


[API function]

FMUSIC_SetRowCallback

Sets a user callback to occur on every row divisible by the rowstep parameter, played from a MOD, S3M, XM or IT file.

signed char F_API FMUSIC_SetRowCallback(
FMUSIC_MODULE *mod,
FMUSIC_CALLBACK callback,
int rowstep
);

Parameters

mod | The module or song to set the callback for.
callback | The callback function you supply to get called.
rowstep | Call the callback every multiple of this number of rows.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

It is important to note that this callback will be called from directly WITHIN the
mixer / music update thread, therefore it is imperative that whatever you do from this
callback be extremely efficient. If the routine takes too long then breakups in the sound
will occur, or it will basically stop mixing until you return from the function.
This sort of function is usually best for just setting a flag, or do some simple variable
manipulation, and then exiting, letting your main thread do what it needs to based on these
flags or variables.
------------
This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization.
Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_CALLBACK , FMUSIC_SetInstCallback , FMUSIC_SetOrderCallback , FMUSIC_SetZxxCallback


[API function]

FMUSIC_SetSample

Replaces a mod's sample with a sample definition specified.

signed char F_API FMUSIC_SetSample(
FMUSIC_MODULE *mod,
int sampno,
FSOUND_SAMPLE *sptr
);

Parameters

mod | Pointer to the song to set the sample for.
sampno | index to sample inside module.
sptr | Pointer to the sample definition to replace mod sample

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Because of the instrument nature of some formats like XM, this function lists all the samples in order of instruments and their subsamples.
ie if instrument 1 has 2 samples and instrument 2 contains 3 samples, then sampno in this case would be 0 and 1 for instrument 1's samples, and 2,3 & 4 for instrument 2's samples.
------------
FMOD does not free the existing mod sample that you may be overwriting. If you do overwrite an existing handle, it may be lost, and you may incur a memory leak. It is a good idea to free the existing sample first before overwriting it.
------------
Important: For PlayStation 2, this function has to do a blocking query to the IOP, and can take significantly more time than a standard non blocking fmod function. This means it is best to cache the pointers for samples while loading, and not call this function in realtime.
------------
This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetSample


[API function]

FMUSIC_SetUserData

Sets a user defined value to store with the music file to be retrieved later.

signed char F_API FMUSIC_SetUserData(
FMUSIC_MODULE *mod,
void *userdata
);

Parameters

mod | Pointer to the song.
userdata | Value to store with music object.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetUserData


[API function]

FMUSIC_SetZxxCallback

Sets a user callback for any Zxx commands encountered in an S3M, XM or IT file.

signed char F_API FMUSIC_SetZxxCallback(
FMUSIC_MODULE *mod,
FMUSIC_CALLBACK callback
);

Parameters

mod | The module or song to set the callback for.
callback | The callback function you supply to get called upon execution of a Zxx command.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

The value passed into the param parameter of the callback is the xx value specified in the Zxx
command by the musician.
------------
It is important to note that this callback will be called from directly WITHIN the
mixer / music update thread, therefore it is imperative that whatever you do from this
callback be extremely efficient. If the routine takes too long then breakups in the sound
will occur, or it will basically stop mixing until you return from the function.
This sort of function is usually best for just setting a flag, or do some simple variable
manipulation, and then exiting, letting your main thread do what it needs to based on these
flags or variables.
------------
This callback is LATENCY adjusted by default, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization.
Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively.
------------
Note : This function is not supported with the MIDI format.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_CALLBACK , FMUSIC_SetInstCallback , FMUSIC_SetOrderCallback , FMUSIC_SetRowCallback


[API function]

FMUSIC_StopAllSongs

Stops all songs from playing. This is useful if you have multiple songs playing at once and
want a quick way to stop them

void F_API FMUSIC_StopAllSongs(
);

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_PlaySong , FMUSIC_StopSong


[API function]

FMUSIC_StopSong

Stops a song from playing.

signed char F_API FMUSIC_StopSong(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to be stopped.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_PlaySong , FMUSIC_StopAllSongs


[API function]

FMUSIC_GetBPM

Returns the song's current BPM.

int F_API FMUSIC_GetBPM(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve current song BPM from.

Return Value

On success, song's current BPM is returned.
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetSpeed


[API function]

FMUSIC_GetGlobalVolume

Returns the song's current global volume

int F_API FMUSIC_GetGlobalVolume(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve song global volume from.

Return Value

Songs current global volume, from 0 (silence) to the maximum value
determined by the music format. Global volume maximums are different in
respect to each format, they range from 64 to 256.
On failure, -1 is returned.

Remarks

GLOBAL volume is not the same as MASTER volume. GLOBAL volume is an internal
overall volume which can be altered by the song itself (ie there might be commands
to fade in a particular part of the song by scaling all the volumes in the song
up slowly from nothing).
GLOBAL volume is different to MASTER volume in that the song can modify without
your permission, whereas MASTER volume is an overall scalar that you can control.
For general use, MASTER volume is more useful, but you may want to reset a song's
GLOBAL volume at certain times in the song. (for example the song might have faded
out by using GLOBAL volume and you want to reset it)
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetMasterVolume , FMUSIC_SetMasterVolume


[API function]

FMUSIC_GetMasterVolume

Returns the song's current master volume

int F_API FMUSIC_GetMasterVolume(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve song master volume from.

Return Value

On success, the song's current master volume, from 0 (silence) to 256 (full volume) is returned
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetGlobalVolume , FMUSIC_SetMasterVolume


[API function]

FMUSIC_GetName

Returns the name of the song set by the composer. With MIDI format, the filename is returned.

const char * F_API FMUSIC_GetName(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve name from.

Return Value

On success, the name of the song as a NULL terminated string is returned.
On failure, NULL is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetNumChannels

Returns the number of channels within this songs pattern data

int F_API FMUSIC_GetNumChannels(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve number of channels from.

Return Value

Number of channels within this songs pattern data
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetNumInstruments

Returns the number of instruments contained in this song.

int F_API FMUSIC_GetNumInstruments(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve number of instruments from.

Return Value

On success, the number of instruments contained in this song is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetNumOrders

Returns the number of orders in this song.

int F_API FMUSIC_GetNumOrders(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve number of orders from.

Return Value

On success, the number of orders in this song is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetNumPatterns

Returns the number of patterns contained in this song.

int F_API FMUSIC_GetNumPatterns(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve number of patterns.

Return Value

On success, the number of patterns contained in this song is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetNumSamples

Returns the number of samples contained in this song.

int F_API FMUSIC_GetNumSamples(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve number of samples.

Return Value

Number of samples contained in this song.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetOpenState

If a mod is opened with FSOUND_NONBLOCKING, this function returns the state of the opening mod.

int F_API FMUSIC_GetOpenState(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the mod to get the open state from.

Return Value

0 = mod is opened and ready.
-1 = mod handle passed in is invalid.
-2 = mod is still opening
-3 = mod failed to open. (file not found, out of memory or other error).

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetOrder

Returns the song's current order number

int F_API FMUSIC_GetOrder(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve current order number from.

Return Value

On success, the song's current order number is returned.
On failure, -1 is returned.

Remarks

This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value.
Use FSOUND_INIT_DONTLATENCYADJUST if you want the value at mix time, which is useful if you want to control the music interactively, or from a DSP callback.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetPattern , FMUSIC_GetPatternLength , FMUSIC_SetOrder


[API function]

FMUSIC_GetPattern

Returns the song's current pattern number

int F_API FMUSIC_GetPattern(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve current pattern number from.

Return Value

On success, The song's current pattern number is returned.
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetOrder


[API function]

FMUSIC_GetPatternLength

Returns the the length in rows of the pattern for the specified order number.

int F_API FMUSIC_GetPatternLength(
FMUSIC_MODULE *mod,
int orderno
);

Parameters

mod Pointer to the song to .

Return Value

On success, the songs pattern length at the specified order is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetOrder


[API function]

FMUSIC_GetPaused

Returns whether song is currently paused or not.

signed char F_API FMUSIC_GetPaused(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to get paused flag from.

Return Value

On success, TRUE is returned to say the song is currently paused
On failure, FALSE is returned to say the song is NOT currently paused

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetPaused


[API function]

FMUSIC_GetRealChannel

Returns the real FSOUND channel playing based on the mod's FMUSIC channel.

int F_API FMUSIC_GetRealChannel(
FMUSIC_MODULE *mod,
int modchannel
);

Parameters

mod | Pointer to the song.
modchannel | The mod channel index, to query the real channel from.

Return Value

On success, the channel index for the respective mod channel is returned.
On failure, -1 is returned.

Remarks

Note FMUSIC mod playback only allocates a real channel on a mod channel the first time an instrument is played.
NNA's will not register. This function only returns the primary real channel for the mod channel.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetRow

Returns the song's current row number.

int F_API FMUSIC_GetRow(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve current row from.

Return Value

On success, the song's current row number is returned.
On failure, -1 is returned.

Remarks

This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value.
Use FSOUND_INIT_DONTLATENCYADJUST if you want the value at mix time, which is useful if you want to control the music interactively, or from a DSP callback.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetSample

Returns a pointer to a sample inside a module.
Once you have access to the module's sample, you can do a lot of things
to it, including locking and modifying the data within; using the
FSOUND_Sample_ functionality.

FSOUND_SAMPLE * F_API FMUSIC_GetSample(
FMUSIC_MODULE *mod,
int sampno
);

Parameters

mod | Pointer to the song to retrieve a sample handle from
sampno | index to sample inside module.

Return Value

On success, a valid sample handle is returned.
On failure, NULL is returned.

Remarks

Because of the instrument nature of some formats like XM, this
function lists all the samples in order of instruments and their subsamples.
ie if instrument 1 has 2 samples and instrument 2 contains 3 samples, then
sampno in this case would be 0 and 1 for instrument 1's samples, and 2,3 & 4
for instrument 2's samples.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetSample


[API function]

FMUSIC_GetSpeed

Returns the song's current speed.

int F_API FMUSIC_GetSpeed(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve current song speed from.

Return Value

On success, The song's current speed is returned
On failure, -1 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_GetBPM


[API function]

FMUSIC_GetTime

Returns the time in milliseconds since the song was started. This is useful for
synchronizing purposes becuase it will be exactly the same every time, and it is
reliably retriggered upon starting the song. Trying to synchronize using other
windows timers can lead to varying results, and inexact performance. This fixes that
problem by actually using the number of samples sent to the soundcard as a reference.

int F_API FMUSIC_GetTime(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to get time from.

Return Value

On success, the time played in milliseconds is returned.
On failure, -1 is returned.

Remarks

This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value.
Use FSOUND_INIT_DONTLATENCYADJUST if you want the value at mix time, which is useful if you want to control the music interactively, or from a DSP callback.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_GetType

Returns the format type a song.

int F_API FMUSIC_GetType(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve name from.

Return Value

On success, the following values are returned:
FMUSIC_TYPE_NONE
FMUSIC_TYPE_MOD
FMUSIC_TYPE_S3M
FMUSIC_TYPE_XM
FMUSIC_TYPE_IT
FMUSIC_TYPE_MIDI
On failure, FMUSIC_TYPE_NONE is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_TYPES


[API function]

FMUSIC_GetUserData

Retrieves the data set by FMUSIC_SetUserData

void * F_API FMUSIC_GetUserData(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song.

Return Value

On success, userdata set by FMUSIC_SetUserData is returned.
On failure, 0 is returned.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_SetUserData


[API function]

FMUSIC_IsFinished

Returns whether the song has completed playing, or when the last order has finished playing.
This stays set even if the song loops.

signed char F_API FMUSIC_IsFinished(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song that you want check if finished or not.

Return Value

TRUE Song has finished playing.
FALSE Song has not finished playing.

Remarks

Some songs may use a pattern break or pattern jump and never reach the last pattern.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube


[API function]

FMUSIC_IsPlaying

Returns whether the song is currently playing or not.

signed char F_API FMUSIC_IsPlaying(
FMUSIC_MODULE *mod
);

Parameters

mod Pointer to the song to retrieve name from.

Return Value

TRUE Song is playing.
FALSE Song is stopped.

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FMUSIC_PlaySong


[Enum]

FMUSIC_TYPES

These definitions describe the type of song being played.

Enumerators

FMUSIC_TYPE_NONE |
FMUSIC_TYPE_MOD | /* Protracker / Fasttracker */
FMUSIC_TYPE_S3M | /* ScreamTracker 3 */
FMUSIC_TYPE_XM | /* FastTracker 2 */
FMUSIC_TYPE_IT | /* Impulse Tracker. */
FMUSIC_TYPE_MIDI | /* MIDI file */
FMUSIC_TYPE_FSB | /* FMOD Sample Bank file */

See Also

FMUSIC_GetType


[Enum]

FSOUND_FX_MODES

These values are used with FSOUND_FX_Enable to enable DirectX 8 FX for a channel.

Enumerators

FSOUND_FX_CHORUS
FSOUND_FX_COMPRESSOR
FSOUND_FX_DISTORTION
FSOUND_FX_ECHO
FSOUND_FX_FLANGER
FSOUND_FX_GARGLE
FSOUND_FX_I3DL2REVERB
FSOUND_FX_PARAMEQ
FSOUND_FX_WAVES_REVERB
FSOUND_FX_MAX

See Also

FSOUND_FX_Disable , FSOUND_FX_Enable , FSOUND_FX_SetChorus , FSOUND_FX_SetCompressor , FSOUND_FX_SetDistortion , FSOUND_FX_SetEcho , FSOUND_FX_SetFlanger , FSOUND_FX_SetGargle , FSOUND_FX_SetI3DL2Reverb , FSOUND_FX_SetParamEQ , FSOUND_FX_SetWavesReverb


[API function]

FSOUND_GetFreeHWRam

Return free SRAM and IOP ram after or before FMOD is initialized.

signed char F_API FSOUND_GetFreeHWRam(
int *spu2ram,
int *iopram
);

Parameters

spu2ram | Pointer to variable to contain free SPU2 ram.
iopram | Pointer to variable to contain free IOP ram.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

Free IOP ram means IOP memory free before initializing FMOD, or after FMOD memory pool size is specified with
FSOUND_SetMemorySystem and FSOUND_Init. For example on a 2mb IOP system, before FSOUND_Init it might return
2mb, and after, if you call FSOUND_Init with a memory pool size of 1.5mb, this function would return .5mb.
This is different to the values returned by FSOUND_GetMemoryStats, which is the memory information within that
1.5mb pool.
------------------
Note using FSOUND_INIT_DISABLE_CORE0_REVERB or/and FSOUND_INIT_DISABLE_CORE1_REVERB will regain SPU2 ram,
but disables hardware reverb. Use this if you want to fit more sounds in and are not worried about reverb.
------------------
This function can be called before or after FSOUND_Init.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_GetMemoryStats , FSOUND_Init , FSOUND_SetMemorySystem


[API function]

FSOUND_GetSpeakerMode

Gets the mode for currently set speakermode.

unsigned int F_API FSOUND_GetSpeakerMode(
);

Return Value

void

Remarks

___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_SetPanSeperation , FSOUND_SetSpeakerMode , FSOUND_SPEAKERMODES


[Define]

FSOUND_INIT_FLAGS

Initialization flags. Use them with FSOUND_Init in the flags parameter to change various behaviour.
FSOUND_INIT_ENABLESYSTEMCHANNELFX Is an init mode which enables the FSOUND mixer buffer to be affected by DirectX 8 effects.
Note that due to limitations of DirectSound, FSOUND_Init may fail if this is enabled because the buffersize is too small.
This can be fixed with FSOUND_SetBufferSize. Increase the BufferSize until it works.
When it is enabled you can use the FSOUND_FX api, and use FSOUND_SYSTEMCHANNEL as the channel id when setting parameters.

FSOUND_INIT_USEDEFAULTMIDISYNTH | 0x0001 /* Win32 only - Causes MIDI playback to force software decoding. */
FSOUND_INIT_GLOBALFOCUS | 0x0002 /* Win32 only - For DirectSound output - sound is not muted when window is out of focus. */
FSOUND_INIT_ENABLESYSTEMCHANNELFX | 0x0004 /* Win32 only - For DirectSound output - Allows FSOUND_FX api to be used on global software mixer output! (use FSOUND_SYSTEMCHANNEL as channel id) */
FSOUND_INIT_ACCURATEVULEVELS | 0x0008 /* This latency adjusts FSOUND_GetCurrentLevels, but incurs a small cpu and memory hit */
FSOUND_INIT_PS2_DISABLECORE0REVERB | 0x0010 /* PS2 only - Disable reverb on CORE 0 (SPU2 voices 00-23) to regain SRAM */
FSOUND_INIT_PS2_DISABLECORE1REVERB | 0x0020 /* PS2 only - Disable reverb on CORE 1 (SPU2 voices 24-47) to regain SRAM */
FSOUND_INIT_PS2_SWAPDMACORES | 0x0040 /* PS2 only - By default FMOD uses DMA CH0 for mixing, CH1 for uploads, this flag swaps them around */
FSOUND_INIT_DONTLATENCYADJUST | 0x0080 /* Callbacks are not latency adjusted, and are called at mix time. Also information functions are immediate */
FSOUND_INIT_GC_INITLIBS | 0x0100 /* GC only - Initializes GC audio libraries */
FSOUND_INIT_STREAM_FROM_MAIN_THREAD | 0x0200 /* Turns off fmod streamer thread, and makes streaming update from FSOUND_Update called by the user */
FSOUND_INIT_PS2_USEVOLUMERAMPING | 0x0400 /* PS2 only - Turns on volume ramping system to remove hardware clicks. */
FSOUND_INIT_DSOUND_DEFERRED | 0x0800 /* Win32 only - For DirectSound output. 3D commands are batched together and executed at FSOUND_Update. */
FSOUND_INIT_DSOUND_HRTF_LIGHT | 0x1000 /* Win32 only - For DirectSound output. FSOUND_HW3D buffers use a slightly higher quality algorithm when 3d hardware acceleration is not present. */
FSOUND_INIT_DSOUND_HRTF_FULL | 0x2000 /* Win32 only - For DirectSound output. FSOUND_HW3D buffers use full quality 3d playback when 3d hardware acceleration is not present. */
FSOUND_INIT_XBOX_REMOVEHEADROOM | 0x4000 /* XBox only - By default directsound attenuates all sound by 6db to avoid clipping/distortion. CAUTION. If you use this flag you are responsible for the final mix to make sure clipping / distortion doesn't happen. */
FSOUND_INIT_PSP_SILENCEONUNDERRUN | 0x8000 /* PSP only - If streams skip / stutter when device is powered on, either increase stream buffersize, or use this flag instead to play silence while the UMD is recovering. */

See Also

FSOUND_GetCurrentLevels , FSOUND_Init , FSOUND_SetBufferSize , FSOUND_Update


[API function]

FSOUND_IOP_Alloc

Allocates IOP Ram

void * F_API FSOUND_IOP_Alloc(
int length
);

Parameters

length Length in bytes of IOP RAM to be allocated.

Return Value

The IOP address of the data allocated. This is not directly addressable. The only way to get data to this value is to DMA it.
FSOUND_SendData will DMA data from the EE to the IOP.

Remarks

The memory allocated is taken from FMOD's memory pool using FMOD's internal memory manager.
The pool of memory this is taken from is specified with FSOUND_SetMemorySystem.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_IOP_Free , FSOUND_SendData , FSOUND_SetMemorySystem


[API function]

FSOUND_IOP_Free

Frees a block of IOP ram.

void F_API FSOUND_IOP_Free(
void *iopptr
);

Parameters

data IOP pointer to be freed. Must have been allocated with FSOUND_IOP_Alloc

Return Value

void

Remarks

___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_IOP_Alloc


[Define]

FSOUND_REVERB_CHANNELFLAGS

Values for the Flags member of the FSOUND_REVERB_CHANNELPROPERTIES structure.

FSOUND_REVERB_CHANNELFLAGS_DIRECTHFAUTO | 0x00000001 /* Automatic setting of 'Direct' due to distance from listener */
FSOUND_REVERB_CHANNELFLAGS_ROOMAUTO | 0x00000002 /* Automatic setting of 'Room' due to distance from listener */
FSOUND_REVERB_CHANNELFLAGS_ROOMHFAUTO | 0x00000004 /* Automatic setting of 'RoomHF' due to distance from listener */
FSOUND_REVERB_CHANNELFLAGS_DEFAULT | (FSOUND_REVERB_CHANNELFLAGS_DIRECTHFAUTO |
 | FSOUND_REVERB_CHANNELFLAGS_ROOMAUTO|
 | FSOUND_REVERB_CHANNELFLAGS_ROOMHFAUTO)

See Also

FSOUND_REVERB_CHANNELFLAGS , FSOUND_REVERB_CHANNELPROPERTIES


[Define]

FSOUND_REVERB_FLAGS

Values for the Flags member of the FSOUND_REVERB_PROPERTIES structure.

FSOUND_REVERB_FLAGS_DECAYTIMESCALE | 0x00000001 /* 'EnvSize' affects reverberation decay time */
FSOUND_REVERB_FLAGS_REFLECTIONSSCALE | 0x00000002 /* 'EnvSize' affects reflection level */
FSOUND_REVERB_FLAGS_REFLECTIONSDELAYSCALE | 0x00000004 /* 'EnvSize' affects initial reflection delay time */
FSOUND_REVERB_FLAGS_REVERBSCALE | 0x00000008 /* 'EnvSize' affects reflections level */
FSOUND_REVERB_FLAGS_REVERBDELAYSCALE | 0x00000010 /* 'EnvSize' affects late reverberation delay time */
FSOUND_REVERB_FLAGS_DECAYHFLIMIT | 0x00000020 /* AirAbsorptionHF affects DecayHFRatio */
FSOUND_REVERB_FLAGS_ECHOTIMESCALE | 0x00000040 /* 'EnvSize' affects echo time */
FSOUND_REVERB_FLAGS_MODULATIONTIMESCALE | 0x00000080 /* 'EnvSize' affects modulation time */
FSOUND_REVERB_FLAGS_CORE0 | 0x00000100 /* PS2 Only - Reverb is applied to CORE0 (hw voices 0-23) */
FSOUND_REVERB_FLAGS_CORE1 | 0x00000200 /* PS2 Only - Reverb is applied to CORE1 (hw voices 24-47) */
FSOUND_REVERB_FLAGS_DEFAULT | (FSOUND_REVERB_FLAGS_DECAYTIMESCALE |
 | FSOUND_REVERB_FLAGS_REFLECTIONSSCALE |
 | FSOUND_REVERB_FLAGS_REFLECTIONSDELAYSCALE |
 | FSOUND_REVERB_FLAGS_REVERBSCALE |
 | FSOUND_REVERB_FLAGS_REVERBDELAYSCALE |
 | FSOUND_REVERB_FLAGS_DECAYHFLIMIT |
 | FSOUND_REVERB_FLAGS_CORE0 |
 | FSOUND_REVERB_FLAGS_CORE1 )

See Also

FSOUND_REVERB_FLAGS , FSOUND_REVERB_PROPERTIES


[API function]

FSOUND_SendData

DMA's data from EE to IOP.
For DSP and stream callbacks use this function to get data to the IOP.

signed char F_API FSOUND_SendData(
void *iopaddr,
void *eeaddr,
int lenbytes,
signed char wait,
void (*callback)(void *param),
void *param
);

Parameters

iopaddr | destination IOP Address.
eeaddr | source EE Address.
lenbytes | Length of data block in bytes.
wait | TRUE or FALSE value to determine wether to wait on the completion of DMA or not. Set to 0 from callbacks.
callback | Callback for completion of DMA.
param | User data that will get passed back to the end of DMA callback.

Return Value

src and lenbytes must be 16 byte aligned.

Remarks

Usually only used with a user stream callback, to get your user data to the IOP address that FMOD provided.
You can also allocate some IOP memory with FSOUND_IOP_Alloc if so desired.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_IOP_Alloc , FSOUND_Sample_Lock , FSOUND_Stream_Create , FSOUND_STREAMCALLBACK


[API function]

FSOUND_SetDiskBusy

Tells FMOD that the user is accessing the disk, so that FMOD will wait until it is finished with it.
This is essential for optimal game file access in cooperation with FMOD.

void F_API FSOUND_SetDiskBusy(
signed char diskbusy
);

Parameters

diskbusy TRUE to tell FMOD the caller is about to access the disk. FALSE to tell FMOD it has finished with the disk.

Return Value

Remarks

It is recommended to wrap FSOUND_SetDiskBusy(TRUE) and FSOUND_SetDiskBusy(FALSE) around all game file
access functions.
--------------------
Note if the user halts the disk access for longer than the buffersize set by FSOUND_Stream_SetBufferSize.
Even less than this can cause skipping or corrupted sound, due to seeking and the actual time it takes to
do the audio stream read in the stream subsystem.
To avoid this it is recommended to split game reads up into chunks, to allow FMOD access to the disk periodically.
--------------------
This function will block until FMOD is not using the disk any more.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_IsDiskBusy , FSOUND_SetDiskBusy , FSOUND_Stream_SetBufferSize


[Enum]

FSOUND_SPEAKERMODES

These are speaker types defined for use with the FSOUND_SetSpeakerMode command.
Note - Only reliably works with FSOUND_OUTPUT_DSOUND or FSOUND_OUTPUT_XBOX output modes. Other output modes will only
interpret FSOUND_SPEAKERMODE_MONO and set everything else to be stereo.
Using either DolbyDigital or DTS will use whatever 5.1 digital mode is available if destination hardware is unsure.

Enumerators

FSOUND_SPEAKERMODE_DOLBYDIGITAL | /* Dolby Digital Output (XBOX or PC only). */
FSOUND_SPEAKERMODE_HEADPHONES | /* The speakers are headphones. */
FSOUND_SPEAKERMODE_MONO | /* The speakers are monaural. */
FSOUND_SPEAKERMODE_QUAD | /* The speakers are quadraphonic. */
FSOUND_SPEAKERMODE_STEREO | /* The speakers are stereo (default value). */
FSOUND_SPEAKERMODE_SURROUND | /* The speakers are surround sound. */
FSOUND_SPEAKERMODE_DTS | /* DTS output (XBOX only). */
FSOUND_SPEAKERMODE_PROLOGIC2 | /* Dolby Prologic 2. Playstation 2 and Gamecube only. PlayStation 2 doesnt support interior panning, but supports 48 voices simultaneously. */
FSOUND_SPEAKERMODE_PROLOGIC2_INTERIOR | /* Dolby Prologic 2. Playstation 2 and Gamecube only. PlayStation 2 does support interior panning, but only supports 24 voices simultaneously. */

See Also

FSOUND_SetSpeakerMode


[API function]

FSOUND_SPU2_Alloc

Allocates SPU2 Ram

void * F_API FSOUND_SPU2_Alloc(
int length
);

Parameters

length Length in bytes of SPU2 sound RAM to be allocated.

Return Value

An IOP based handle for the SPU2 ram block.

Remarks

This function is mainly used to reserve memory for purposes such as 3rd party libraries needing memory for their own spu2 use.
DO NOT use this as the offset into spu2 ram! Use FSOUND_SPU2_GetRawAddress to get the spu2 offset into sound ram from this handle.
-----------
The SPU2 has 2mb of ram available, unless reverb is activated on both cores, then it is less. You can disable reverb using
FSOUND_INIT_PS2_DISABLECORE0REVERB and FSOUND_INIT_PS2_DISABLECORE1REVERB with FSOUND_Init.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_Init , FSOUND_SPU2_Free , FSOUND_SPU2_GetRawAddress


[API function]

FSOUND_SPU2_Free

Frees SPU2 Ram

void F_API FSOUND_SPU2_Free(
void *iopptr
);

Parameters

iopptr Handle to free generated by FSOUND_SPU2_Alloc.

Return Value

void

Remarks

Pass the value from FSOUND_SPU2_Alloc, NOT the value from FSOUND_SPU2_GetRawAddress.
___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_SPU2_Alloc , FSOUND_SPU2_GetRawAddress


[API function]

FSOUND_SPU2_GetRawAddress

Gets the raw SPU2 offset inside the SPU2 memory space from the handle returned from FSOUND_SPU2_Alloc

unsigned int F_API FSOUND_SPU2_GetRawAddress(
void *iopptr
);

Parameters

iopptr Pointer to the IOP based sound ram handle.

Return Value

The SPU2 address of the data allocated. This is not directly addressable.
The only way to get data to this address is to DMA it from the EE to the IOP first, then from the IOP to SRAM.

Remarks

___________________
Supported on the following platforms : PlayStation 2

See Also

FSOUND_SPU2_Alloc , FSOUND_SPU2_Free


[Define]

FSOUND_STATUS_FLAGS

These values describe the protocol and format of an internet stream. Use FSOUND_Stream_Net_GetStatus to retrieve this information for an open internet stream.

FSOUND_PROTOCOL_SHOUTCAST | 0x00000001
FSOUND_PROTOCOL_ICECAST | 0x00000002
FSOUND_PROTOCOL_HTTP | 0x00000004
FSOUND_FORMAT_MPEG | 0x00010000
FSOUND_FORMAT_OGGVORBIS | 0x00020000

See Also

FSOUND_Stream_Net_GetStatus


[API function]

FSOUND_Stream_Net_SetTimeout

Sets the timeout for internet streams.

signed char F_API FSOUND_Stream_Net_SetTimeout(
int timeout
);

Parameters

timeout The timeout value in ms

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

___________________
Supported on the following platforms : Win32, Macintosh, Linux

See Also

FSOUND_Stream_Close , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_Stop


[Enum]

FSOUND_STREAM_NET_STATUS

Status values for internet streams. Use FSOUND_Stream_Net_GetStatus to get the current status of an internet stream.

Enumerators

FSOUND_STREAM_NET_NOTCONNECTED | /* Stream hasn't connected yet */
FSOUND_STREAM_NET_CONNECTING | /* Stream is connecting to remote host */
FSOUND_STREAM_NET_BUFFERING | /* Stream is buffering data */
FSOUND_STREAM_NET_READY | /* Stream is ready to play */
FSOUND_STREAM_NET_ERROR | /* Stream has suffered a fatal error */

See Also

FSOUND_Stream_Net_GetStatus


[API function]

FSOUND_Stream_OpenFromHandle

FSOUND_STREAM * F_API FSOUND_Stream_OpenFromHandle(
HANDLE handle,
unsigned int mode
);

Parameters

handle A pointer to a file HANDLE type that was retrieved from XOpenSoundtrackSong.

Return Value

On success, a valid stream handle is returned.
On failure, NULL is returned.

Remarks

Use the XDK functions XFindFirstSoundtrack, XFindNextSoundtrack, XGetSoundtrackSongInfo and XOpenSoundtrackSong
to enumerate and open WMA files saved onto the dashboard by users.
___________________
Supported on the following platforms : XBox

See Also

FSOUND_Stream_Close. , FSOUND_Stream_Open


[Enum]

FSOUND_TAGFIELD_TYPE

Describes the type of a particular tag field.

Enumerators

FSOUND_TAGFIELD_VORBISCOMMENT | /* A vorbis comment */
FSOUND_TAGFIELD_ID3V1 | /* Part of an ID3v1 tag */
FSOUND_TAGFIELD_ID3V2 | /* An ID3v2 frame */
FSOUND_TAGFIELD_SHOUTCAST | /* A SHOUTcast header line */
FSOUND_TAGFIELD_ICECAST | /* An Icecast header line */
FSOUND_TAGFIELD_ASF | /* An Advanced Streaming Format header line */

See Also

FSOUND_Stream_FindTagField , FSOUND_Stream_GetNumTagFields , FSOUND_Stream_GetTagField


[API function]

sceSifAddCmdHandler

For advanced users only.
Only used if users are getting conflicts with FMOD's command handler when writing IOP modules of their own or using other middleware that uses SIFCMD.
This function tells FMOD about the user's SIFCMD buffer that has been set with sceSifSetCmdBuffer, and the indicies into that sceSifCmdData array that FMOD can use.
The user may have specified a SIF command handler of their own before calling FSOUND_Init and loading FMOD.IRX when setting up their own IOP<->EE communication.
It simply enables FMOD to know the size, and what indicies into the sceSifCmdData array the user has set that FMOD can use.
It allows the user's app and FMOD to share the buffer that the user has created.
FMOD uses 2 sif handlers. A main one and secondary one.

sceSifAddCmdHandler(
YOURHANDLERINDEX ,
yourhandler ,
NULL
);

Parameters

buffersize | The size of the sceSifCmdData array that the user has set.
bufferindexmain | The index into the user created sceSifCmdData array for the primary FMOD sifcmd handler.
bufferindexsecondary | The index into the user created sceSifCmdData array for the secondary FMOD sifcmd handler.

Return Value

void

Remarks

FMOD will automatically use the previously set command buffer, as sceSifSetCmdBuffer returns the previously set buffer which FMOD uses.
This is why you dont have to pass in the actual buffer itself.
-----------
IMPORTANT! FMOD.IRX must also be notified when it is initialized!
The IOP side of the command handler, which is initialized when FMOD.IRX is loaded, must also be notified of the user's IOP side buffer size and indicies.
By passing it as command line parameter with sceSifLoadModule, you can do this. If this is not done, unexpected results may occur.
The FMOD.IRX takes 3 parameters. They are simply 3 integers seperated by a space.
Parameter 1 is equal to 'buffersize'
Parameter 2 is equal to 'bufferindexmain'
Parameter 3 is equal to 'bufferindexsecondary'
------------
Here is an example of using sceSifLoadModule to notify FMOD.IRX of your IOP side sifCmd buffer size and command handler index.
sprintf(s, "4989472 1238404 205", CMDBUFSIZE, FMODINDEXMAIN, FMODINDEXSECONDARY); // NOTE : must be formatted as 3 integers seperated by a space.
sceSifLoadModule("host0:api/fmod.irx", strlen(s), s);
Then later on the EE side, before calling FSOUND_Init, you will call this function, ie
FSOUND_SetSifCommandInfo(CMDBUFSIZE, FMODINDEXMAIN, FMODINDEXSECONDARY);
And before any of this, you would have set up your own command handler with something like this.
sceSifInitCmd();
sceSifSetCmdBuffer(&yourcommandbuffer

See Also

FSOUND_Init