FMOD Documentation, Firelight Multimedia

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


3D Sound Tutorial - Firelight Multimedia

3D SOUND AND GAME CODING

Introduction
    3D Sound in FMOD is accomplished through a number different API's which are handled transparently to you through one unified interface. These are:
  • DirectSound 3D with EAX 1.0 and 2.0
  • A3D 3.0
  • 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, char *filename, unsigned int mode, int memlength); 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);

    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);

    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);

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_3D_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 cant 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 dont 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.
    Similairly, 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, A3D, and OpenGL

    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 rediculous 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 doesnt 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 Multimedia

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_GetTime. You can check your record your time offsets in a wav editing program like SoundForge, and use these to poll against while FMOD plays the song back.
    Note that this method may have some very slight accuracy problems, usually to do with framerate, or innacurate sound drivers. An example is that if your framerate is only 10fps, you are only checking in 100ms increments, which is innacruate. If you have a decent framerate it shouldnt be noticable, not to mention the fact if you are executing a graphical effect, you wont be able to see it until the next frame anyway.
    A nice way to poll events would look something like this..

    #define MAX_TIMES 4
    int times[MAX_TIMES] = { 1000, 2500, 10000, 20000 };
    int current = 0;

    do
    {
      if (FSOUND_Stream_GetTime(stream) >= times[current] && current < MAX_TIMES)
      {
        TriggerEvent();
        current++;
      }
    } while (running);

    And there you have it! You have a list of time offsets you want to synchronize against, and it cycles through, triggering each event as it occurs!
MODs
    To synchronize graphics with mod music, try these functions.
  • FMUSIC_SetZxxCallback
  • FMUSIC_SetRowCallback
  • FMUSIC_SetOrderCallback
    This allows you to set callbacks on row, order or Zxx mod effect events.
    There is also a time based function FMUSIC_GetTime. This function is not latency adjusted like all the other synchronization functions mentioned on this page, but is still accurate enough if you have a small enough buffersize. (See FSOUND_SetBufferSize). Under directsound this is usually a 20ms latency by default so it is probably not noticable.


Custom Samples and Streams Tutorial - Firelight Multimedia

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.


TroubleShooting - Firelight Multimedia

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
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)
  • 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).
  • Buffersize is set too small! See following notes.

    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 dont set this value to huge numbers like 2000 or 10000. It wont help increase stability and will consume larger amounts of CPU time.

    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.
Clicking noises
    If you think FMOD is clicking too much when you pan a sound or play a song, you havent enabled the volume ramping mixer.

    Call FSOUND_SetMixer(FSOUND_MIXER_QUALITY_FPU_VOLUMERAMP) to avoid this problem.

    This function must be called before calling FSOUND_Init, it will fail otherwise.


FSOUND API Reference

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

Functions , Defines , Enums

+ Functions

- Functions

FSOUND_3D_GetAttributes
FSOUND_3D_Listener_GetAttributes
FSOUND_3D_Listener_SetAttributes
FSOUND_3D_Listener_SetDistanceFactor
FSOUND_3D_Listener_SetDopplerFactor
FSOUND_3D_Listener_SetRolloffFactor
FSOUND_3D_SetAttributes
FSOUND_3D_Update
FSOUND_CD_Eject
FSOUND_CD_GetNumTracks
FSOUND_CD_GetPaused
FSOUND_CD_GetTrack
FSOUND_CD_GetTrackLength
FSOUND_CD_GetTrackTime
FSOUND_CD_GetVolume
FSOUND_CD_Play
FSOUND_CD_SetPaused
FSOUND_CD_SetPlayMode
FSOUND_CD_SetVolume
FSOUND_CD_Stop
FSOUND_Close
FSOUND_DSP_ClearMixBuffer
FSOUND_DSP_Create
FSOUND_DSP_Free
FSOUND_DSP_GetActive
FSOUND_DSP_GetBufferLength
FSOUND_DSP_GetClearUnit
FSOUND_DSP_GetClipAndCopyUnit
FSOUND_DSP_GetMusicUnit
FSOUND_DSP_GetPriority
FSOUND_DSP_GetSFXUnit
FSOUND_DSP_MixBuffers
FSOUND_DSP_SetActive
FSOUND_DSP_SetPriority
FSOUND_DSPCALLBACK
FSOUND_File_SetCallbacks
FSOUND_Geometry_AddList
FSOUND_Geometry_AddPolygon
FSOUND_Geometry_List_Begin
FSOUND_Geometry_List_Create
FSOUND_Geometry_List_End
FSOUND_Geometry_List_Free
FSOUND_Geometry_Material_Create
FSOUND_Geometry_Material_Free
FSOUND_Geometry_Material_GetAttributes
FSOUND_Geometry_Material_Set
FSOUND_Geometry_Material_SetAttributes
FSOUND_GetChannelsPlaying
FSOUND_GetCPUUsage
FSOUND_GetCurrentPosition
FSOUND_GetCurrentSample
FSOUND_GetCurrentVU
FSOUND_GetDriver
FSOUND_GetDriverCaps
FSOUND_GetDriverName
FSOUND_GetError
FSOUND_GetFrequency
FSOUND_GetMaxChannels
FSOUND_GetMaxSamples
FSOUND_GetMixer
FSOUND_GetMute
FSOUND_GetNumDrivers
FSOUND_GetNumHardwareChannels
FSOUND_GetOutput
FSOUND_GetOutputRate
FSOUND_GetPan
FSOUND_GetPaused
FSOUND_GetPriority
FSOUND_GetReserved
FSOUND_GetSFXMasterVolume
FSOUND_GetSurround
FSOUND_GetVersion
FSOUND_GetVolume
FSOUND_Init
FSOUND_IsPlaying
FSOUND_PlaySound
FSOUND_PlaySound3DAttrib
FSOUND_Record_GetDriver
FSOUND_Record_GetDriverName
FSOUND_Record_GetNumDrivers
FSOUND_Record_GetPosition
FSOUND_Record_SetDriver
FSOUND_Record_StartSample
FSOUND_Record_Stop
FSOUND_Reverb_GetEnvironment
FSOUND_Reverb_GetEnvironmentAdvanced
FSOUND_Reverb_GetMix
FSOUND_Reverb_SetEnvironment
FSOUND_Reverb_SetEnvironmentAdvanced
FSOUND_Reverb_SetMix
FSOUND_Sample_Alloc
FSOUND_Sample_Free
FSOUND_Sample_Get
FSOUND_Sample_GetDefaults
FSOUND_Sample_GetLength
FSOUND_Sample_GetLoopPoints
FSOUND_Sample_GetMode
FSOUND_Sample_GetName
FSOUND_Sample_Load
FSOUND_Sample_Lock
FSOUND_Sample_SetDefaults
FSOUND_Sample_SetLoopMode
FSOUND_Sample_SetLoopPoints
FSOUND_Sample_SetMinMaxDistance
FSOUND_Sample_Unlock
FSOUND_Sample_Upload
FSOUND_SetBufferSize
FSOUND_SetDriver
FSOUND_SetFrequency
FSOUND_SetHWND
FSOUND_SetLoopMode
FSOUND_SetMaxHardwareChannels
FSOUND_SetMinHardwareChannels
FSOUND_SetMixer
FSOUND_SetMute
FSOUND_SetOutput
FSOUND_SetPan
FSOUND_SetPanSeperation
FSOUND_SetPaused
FSOUND_SetPriority
FSOUND_SetReserved
FSOUND_SetSFXMasterVolume
FSOUND_SetSurround
FSOUND_SetVolume
FSOUND_SetVolumeAbsolute
FSOUND_StopSound
FSOUND_Stream_Close
FSOUND_Stream_Create
FSOUND_Stream_CreateDSP
FSOUND_Stream_GetLength
FSOUND_Stream_GetLengthMs
FSOUND_Stream_GetPaused
FSOUND_Stream_GetPosition
FSOUND_Stream_GetSample
FSOUND_Stream_GetTime
FSOUND_Stream_OpenFile
FSOUND_Stream_Play
FSOUND_Stream_Play3DAttrib
FSOUND_Stream_SetEndCallback
FSOUND_Stream_SetPaused
FSOUND_Stream_SetPosition
FSOUND_Stream_SetTime
FSOUND_Stream_Stop
FSOUND_STREAMCALLBACK

+ Defines

- Defines

FSOUND_CAPS
FSOUND_CDPLAYMODES
FSOUND_CHANNELSAMPLEMODE
FSOUND_DSP_PRIORITIES
FSOUND_GEOMETRY_MODES
FSOUND_INIT_FLAGS
FSOUND_MODES
FSOUND_REVERB_IGNOREPARAM
FSOUND_REVERB_PRESETS
FSOUND_REVERBMIX_USEDISTANCE

+ Enums

- Enums

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_DSPCALLBACK

Callback definition for DSP units.

void *FSOUND_DSPCALLBACK(
void *originalbuffer,
void *newbuffer,
int length,
int param
);

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.

See Also

FSOUND_DSP_Create , FSOUND_Stream_CreateDSP

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:38 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_STREAMCALLBACK

Callback used with user streams.

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

Parameters

stream | Pointer to the stream in question.
buff | Pointer to the stream data buffer to write to.
len | Length of buffer specified in BYTES.
param | A user data value specified from FSOUND_Stream_Create

Return Value

To allow the stream to continue, TRUE is returned.
To stop the stream, FALSE is returned.

Remarks

WMA/ASF/Internet streaming does not support user streams.

See Also

FSOUND_Stream_Create , FSOUND_Stream_SetEndCallback

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.
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.
flags | This is reserved for future expansion. Set it to 0.

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 be and usually is faster than hardware support! As for quality,
newer cards have spline interpolation, but I dont think there is a huge difference between
spline and linear interpolation (as FMOD uses) that the normal gamer would pick up on in the
heat of a game.

See Also

FSOUND_CD_Eject , FSOUND_CD_GetPaused , FSOUND_CD_Play , FSOUND_CD_SetPaused , FSOUND_CD_SetPlayMode , FSOUND_CD_Stop , FSOUND_Close , FSOUND_GetDriverCaps , FSOUND_GetMaxChannels , FSOUND_GetOutputRate , FSOUND_Init , FSOUND_PlaySound , FSOUND_PlaySound3DAttrib , FSOUND_SetBufferSize , FSOUND_SetDriver , FSOUND_SetHWND , FSOUND_SetMaxHardwareChannels , FSOUND_SetMinHardwareChannels , FSOUND_SetMixer , FSOUND_SetOutput , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib


[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).
All songs (mods) are stopped (but does not free them).
All streams are stopped and freed.
CD Tracks are stopped.

See Also

FSOUND_CD_Eject , FSOUND_CD_GetPaused , FSOUND_CD_GetVolume , FSOUND_CD_Play , FSOUND_CD_SetPaused , FSOUND_CD_SetPlayMode , FSOUND_CD_SetVolume , FSOUND_CD_Stop , FSOUND_GetDriverCaps , FSOUND_Init , FSOUND_Sample_Alloc , FSOUND_Sample_Get , FSOUND_Sample_Load , FSOUND_SetBufferSize , FSOUND_SetDriver , FSOUND_SetHWND , FSOUND_SetMaxHardwareChannels , FSOUND_SetMinHardwareChannels , FSOUND_SetMixer , FSOUND_SetOutput


[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 40ms if it is not called for DSOUND and A3D. It defaults to
200ms for Windows Multimedia wave-out or for emulated DirectSound drivers (such as NT drivers).
---------
Buffer sizes lower than 40 are clamped at 40.
Buffer sizes are also rounded DOWN to the nearest multiple of 40. This is because FMOD mixes in blocks of 20ms.

See Also

FSOUND_Close , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.

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.

See Also

FSOUND_Close , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_SetMaxHardwareChannels

This sets the maximum allocatable channels on a hardware card. It sets a limit so
when playing sounds on dynamic channels, things dont get too noisy.

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 100 Šyoftware if a card has a certain number of channels.
This function only sets a limit on hardware channels, so if you card has 96 hardware channels, and you set
FSOUND_SetMaxHardwareChannels(10), then you will only have 10 hardware channels to use.

See Also

FSOUND_Close , FSOUND_Init , FSOUND_SetMaxHardwareChannels , FSOUND_SetMinHardwareChannels


[API function]

FSOUND_SetMinHardwareChannels

This sets the minimum allowable hardware channels before FMOD drops back to 100 percent software.
This is VERY helpful for minimum spec cards, and 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 10031361774f 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.
---------
If you set your minimum to 16, you can now safely play 16 sounds 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 sounds even worse!)

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)

See Also

FSOUND_Close , FSOUND_GetMixer , FSOUND_Init , FSOUND_MIXERTYPES

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_SetOutput

Sets up the soundsystem output type. This means if it uses DirectSound(tm), or Windows(tm)
Multimedia waveout etc.

signed char F_API FSOUND_SetOutput(
int outputtype
);

Parameters

outputtype The output system to be used:
See FSOUND_OUTPUTTYPES 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.
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.

See Also

FSOUND_Close , FSOUND_GetOutput , FSOUND_Init , FSOUND_OUTPUTTYPES , FSOUND_SetDriver

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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

See Also

FMUSIC_SetMasterVolume , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_SetPanSeperation

Sets the master pan seperation for 2d sound effects.

DLL_API void F_API FSOUND_SetPanSeperation(
float 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

See Also

FMUSIC_SetPanSeperation

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.

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_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

See Also

FMUSIC_OptimizeChannels

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_GetMaxChannels

Returns the total number of channels allocated.

int F_API FSOUND_GetMaxChannels(
);

Return Value

Number of channels allocated

Remarks

See Also

FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FSOUND_GetDriver , FSOUND_GetDriverCaps , FSOUND_GetDriverName , FSOUND_SetDriver


[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

See Also

FSOUND_OUTPUTTYPES , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced , 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

See Also

FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

signed 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_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.

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

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_Load

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.

See Also

FSOUND_Close

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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
s default frequency. Can be NULL. | defvol
Pointer to value to be filled with the sample | s default volume. Can be NULL.
defpan | Pointer to value to be filled with the sample
s default pan. Can be NULL. | defpri
Pointer to value to be filled with the sample | s 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.

See Also

FSOUND_Sample_SetDefaults

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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
s loop start point. Can be NULL. | loopend
Pointer to value to be filled with the sample | s 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.

See Also

FSOUND_Sample_SetDefaults , FSOUND_Sample_SetLoopMode , FSOUND_Sample_SetLoopPoints


[API function]

FSOUND_Sample_GetMode

Returns a bitfield containing inforemation 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 loop end value is returned.
On failure, 0 is returned.

Remarks

See Also

FSOUND_MODES , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetLoopMode


[API function]

FSOUND_Sample_GetName

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

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.


[API function]

FSOUND_Sample_Load

Loads and decodes a static soundfile into memory.

FSOUND_SAMPLE * F_API FSOUND_Sample_Load(
int index,
const char *name,
unsigned int mode,
int memlength
);

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 | 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.
memlength | If FSOUND_LOADMEMORY is specified as a mode, then this value must contain the length in BYTES of the memory image being passed into the name field of the parameter list. Otherwise this value can be ignored and set to zero (for example if you were loading a file from disk). .

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 NOT to use the sample management system.
-----
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.
memlength is to be filled out if this flag is specified, otherwise it can be 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.

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 that was locked for ptr1
len2 | Length of data 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 unlock the data again after you have finished with it, using FSOUND_Sample_Unlock.
Data written to these pointers must be signed.

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_Unlock , FSOUND_Sample_Upload


[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 vale from 0 to 255. -1 to ignore.
defpri | Default frequency. This is a value from 0 to 255. -1 to ignore.

Return Value

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

Remarks

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_GetDefaults , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_GetMode , FSOUND_Sample_SetLoopMode , FSOUND_SetFrequency , FSOUND_SetPan , FSOUND_SetPriority , FSOUND_SetVolume


[API function]

FSOUND_Sample_SetLoopMode

Sets a sample's loop mode. This can be FSOUND_LOOP_OFF,FSOUND_LOOP_NORMAL or
FSOUND_LOOP_BIDI.

signed char F_API FSOUND_Sample_SetLoopMode(
FSOUND_SAMPLE *sptr,
unsigned int loopmode
);

Parameters

sptr | Pointer to the sample that needs its loop points set.
loopmode | The loop mode to set.

Return Value

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

Remarks

See Also

FSOUND_MODES , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_GetMode , FSOUND_Sample_SetDefaults , FSOUND_Sample_SetLoopPoints , FSOUND_SetLoopMode


[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

See Also

FSOUND_Sample_Alloc , FSOUND_Sample_GetLoopPoints , FSOUND_Sample_SetLoopMode


[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, regardless of how close it is (beyond that point).
This is useful to give the impression that the sound is very loud or soft. An example of
this is taken from the DirectSound3D documentation.
Take a bee and a jet engine, Their original sampledata is recorded to fit into 16bits, and
therefore could have the same volume, but making a jets minimum distance 100 meters would
keep it loud for 100 meters, and then drop off, but if the bees minimum distance was 2cm it
would start to drop off almost immediately, and depending on its maximum distance, fade out
altogether.
-------
MaxDistance is the distance a sound stops getting quieter at. This does not affect how fast
the volume drops off, and should not be changed unless nescessary. It is only available for
completeness, it is really an obsolete value in most situations.
-------
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.

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

Parameters

sptr | The sample to have its minimum and maximum distance set.
min | The sample
s minimum volume distance in | units
. See remarks for more on units. | max
The sample | s 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_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_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.

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_SetAttributes


[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.
offset | Offset in BYTES to the position you want to lock in the sample buffer.
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 that was locked for ptr1
len2 | Length of data 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

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
);

Parameters

sptr | Pointer to the destination sample
srcdata | Pointer to the source data to be uploaded
mode | Description of the source data format. Bitwise OR in these bits to describe the data being passed. See FSOUND_MODES for valid parameters and descriptions. FSOUND_HW3D, 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

See Also

FSOUND_MODES , FSOUND_Sample_Alloc , FSOUND_Sample_Lock , FSOUND_Sample_Unlock


[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 id 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.

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. It is not very useful.

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetFrequency , FSOUND_Record_StartSample , FSOUND_Sample_SetDefaults


[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 playing channel to have its loop mode set.

Return Value

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

Remarks

Note, this does not work for hardware sounds played on hardware channels, this will only on software
mixed channels.
The loop mode will only change after it has been played. This is because the channel inherits the
SAMPLE's loop mode upon playback.

See Also

FSOUND_Sample_SetLoopMode

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 id 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. It is not very useful.

See Also

FSOUND_GetMute

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_SetPan

Sets a channels pan position linearly

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

Parameters

channel | The channel id 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. It is not very useful.
----------
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 (yes you can pan - or more accurately
'fade' stereo samples using the FSOUND_SetPan command).
The way panning works normally is like this:
full left : 100to left, 0to right
full right : 0to left, 100to right
middle : 50to left, 50to right
To get a stereo sample to play at full volume, there is a special pan command
FSOUND_STEREOPAN which you pass to FSOUND_SetPan. This gives 100to left AND 100to right.
This also works for mono samples, they just come out twice as loud as normal middle as well.
If you are wondering about the logic of 50/50 for middle panning, it can be explained simply
by saying that 100/100 panning just does not sound good. The way it is now each channel
ramps linearly as it moves from left to right or right to left. If it was 100 in each
channel at the middle point, you would not hear one of the channels start to fade until you
passed to the other side of the middle point, which is very harsh.

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetPan , FSOUND_Sample_SetDefaults , FSOUND_SetPan , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.

See Also

FSOUND_GetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.

See Also

FSOUND_GetPriority , FSOUND_GetReserved , FSOUND_Sample_SetDefaults , FSOUND_SetReserved

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.

See Also

FSOUND_GetPriority , FSOUND_GetReserved , FSOUND_SetPriority , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.
---------
Note this only works on software channels.

See Also

FSOUND_GetSurround

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.

See Also

FSOUND_DSP_MixBuffers , FSOUND_GetVolume , FSOUND_Sample_SetDefaults , FSOUND_SetSFXMasterVolume , FSOUND_SetVolumeAbsolute , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 id 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. It is not very useful.
-------------
A good example of this function being used was in a game I was making, and we needed a voice over.
All the background sounds were too loud and drowned out the voice over, and there was no way i could
feasibly go through all the sfx channels and lower the background noise volumes. This way you just
lower the background noise with FSOUND_SetSFXMasterVolume, and use FSOUND_SetVolumeAbsolute to bring
up the volume of the voice over to full! And there you have it!

See Also

FSOUND_GetVolume , FSOUND_SetSFXMasterVolume , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 index 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. It is not very useful.

See Also

FSOUND_PlaySound , FSOUND_PlaySound3DAttrib

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.
sptr | Pointer to the sample to be played.

Return Value

On success, the channel id 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.
----------
FSOUND_ALL is supported. 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. This is not very useful.
----------
The channel id :
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.

See Also

FSOUND_GetNumHardwareChannels , FSOUND_Init , FSOUND_PlaySound3DAttrib , FSOUND_StopSound


[API function]

FSOUND_PlaySound3DAttrib

Plays a sample in a specified channel, with a specified frequency, volume, pan, position or velocity,
overriding the sample's default settings.
Members can be ignored if you dont wish to set them (ie passing NULL to position etc).

int F_API FSOUND_PlaySound3DAttrib(
int channel,
FSOUND_SAMPLE *sptr,
int freq,
int vol,
int pan,
float *pos,
float *vel
);

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.
sptr | Pointer to the sample to be played.
freq | frequency in hz to play sound at. -1 will use samples default frequency.
vol | volume to play sound at (0-255). -1 will use samples default volume.
pan | pan position to play sound at (0-255, FSOUND_STEREOPAN). -1 will use samples default pan.
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. (especially if the sound is 2D!)
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. (especially if the sound is 2D!)

Return Value

On success, the channel id 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 will make things
VERY noisy!)
If FSOUND_ALL is used the last channel success flag will be returned. This is not very useful.
----------
The channel id :
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.

See Also

FSOUND_GetNumHardwareChannels , FSOUND_Init , FSOUND_PlaySound , FSOUND_StopSound


[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 to inquire about the volume.

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

See Also

FSOUND_GetError , FSOUND_SetVolume , FSOUND_SetVolumeAbsolute


[API function]

FSOUND_IsPlaying

Returns if the channel is currently playing or not.

signed char F_API FSOUND_IsPlaying(
int channel
);

Parameters

channel Channel id.

Return Value

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

Remarks

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_GetCurrentPosition

Returns the current playcursor position of the specified channel.

unsigned int F_API FSOUND_GetCurrentPosition(
int channel
);

Parameters

channel Channel id.

Return Value

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

Remarks

See Also

FSOUND_Record_StartSample

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 id.

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.


[API function]

FSOUND_GetCurrentVU

Returns a VU reading at the current position of the specified channel.
VU meters are only supported for software channels currently.

float F_API FSOUND_GetCurrentVU(
int channel
);

Parameters

channel Channel id to retrieve VU meter.

Return Value

On success, a value between 0.0 and 1.0 is returned representing the actual amplitude of
the waveform of current channel.
On failure, 0 is returned.

Remarks

To get an overall VU reading, 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, i decided to return the raw amplitude, and let the user smooth the
result if they like.


[API function]

FSOUND_GetFrequency

Returns the frequency in HZ of the specified channel.

int F_API FSOUND_GetFrequency(
int channel
);

Parameters

channel - The channel to inquire about the frequency.

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

See Also

FSOUND_GetError , FSOUND_SetFrequency

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

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 to inquire about the mute status

Return Value

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

Remarks

See Also

FSOUND_SetMute

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 to inquire.

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

See Also

FSOUND_GetError , FSOUND_SetPan

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_GetPaused

Gets current pause status of the channel.

signed char F_API FSOUND_GetPaused(
int channel
);

Parameters

channel The channel 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.

See Also

FSOUND_SetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 to get priority for.

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

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 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

See Also

FSOUND_SetPriority , FSOUND_SetReserved

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 to inquire about the surround sound status

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.

See Also

FSOUND_SetSurround

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_3D_Listener_GetAttributes

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

void F_API FSOUND_3D_Listener_GetAttributes(
float *pos,
float *vel,
float *fx,
float *fy,
float *fz,
float *tx,
float *ty,
float *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_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_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.

See Also

FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_Listener_SetDopplerFactor , FSOUND_3D_SetAttributes


[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(
float *pos,
float *vel,
float fx,
float fy,
float fz,
float tx,
float ty,
float 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_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_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.

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_Listener_SetDopplerFactor , FSOUND_3D_Listener_SetRolloffFactor , FSOUND_3D_SetAttributes , FSOUND_3D_Update


[API function]

FSOUND_3D_GetAttributes

signed char F_API FSOUND_3D_GetAttributes(
int channel,
float *pos,
float *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_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_SetDistanceFactor
for more on this.

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_SetAttributes , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_Listener_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_Listener_SetDistanceFactor(
float scale
);

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.

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetRolloffFactor , FSOUND_3D_SetAttributes , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_Listener_SetDopplerFactor

Sets the doppler shift scale factor.

void F_API FSOUND_3D_Listener_SetDopplerFactor(
float 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.

See Also

FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Update


[API function]

FSOUND_3D_Listener_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.

DLL_API void F_API FSOUND_3D_Listener_SetRolloffFactor(
float scale
);

Parameters

sptr | The sample to have its rolloff factor set.
rolloff | The rolloff factor to set for this sample. Valid ranges are 0 to 10.

Return Value

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

Remarks

---------
A 'distance unit' is specified by FSOUND_3D_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_SetDistanceFactor
for more on this.
---------
The default rolloff factor is 1.0.

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_SetAttributes


[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,
float *pos,
float *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_Listener_SetDistanceFactor. By default this is
set to meters which is a distance scale of 1.0. See FSOUND_3D_Listener_SetDistanceFactor
for more on this.
---------
FSOUND vectors expect 3 floats representing x y and z in that order. Ie a typical definition
of a vector is
typedef struct
{
float x;
float y;
float z;
} VECTOR;
or simply an array of 3 floats.

See Also

FSOUND_3D_GetAttributes , FSOUND_3D_Listener_GetAttributes , FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetDistanceFactor , FSOUND_3D_Listener_SetRolloffFactor , FSOUND_3D_Update , FSOUND_Sample_SetMinMaxDistance


[API function]

FSOUND_3D_Update

This updates all buffered 3d sound commands (for api's like dsound and a3d), so it needs to
be called at the end of every game loop. Not all commands are buffered, and it depends on
the output mode being used. With A3D every command is buffered, whereas with DS3D and
software mode only listener and emitter attributes are flushed.
Geometry is buffered and is flushed upon calling this function.

void F_API FSOUND_3D_Update(
);

Return Value

Remarks

See Also

FSOUND_3D_Listener_SetAttributes , FSOUND_3D_Listener_SetDopplerFactor , FSOUND_3D_SetAttributes , FSOUND_Geometry_AddList , FSOUND_Geometry_AddPolygon


[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

See Also

FSOUND_Stream_Create , FSOUND_Stream_OpenFile , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib , FSOUND_Stream_Stop

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 length,
unsigned int mode,
int samplerate,
int userdata
);

Parameters

callback | A pointer to a user defined stream callback function. An example of the callback function would look like this. void streamcallback(FSOUND_STREAM *stream, void *buff, int len, int param) { return TRUE; } len in this callback is specified in BYTES. The return value is whether to end the stream or not. Returning FALSE will terminate the stream.
length | 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 harddisk) cant keep up. A sound that has a default rate of 44.1khz that is played at 132khz will have to read the hard disk 3 times faster than normal.

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.
'length' 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)

See Also

FSOUND_MODES , FSOUND_Stream_Close , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib , FSOUND_Stream_Stop , FSOUND_STREAMCALLBACK

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.

See Also

FSOUND_Stream_GetLengthMs , FSOUND_Stream_GetPosition , FSOUND_Stream_OpenFile , FSOUND_Stream_SetPosition , FSOUND_Stream_SetTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_OpenFile

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_GetPaused

Gets the paused status of a stream.

signed char F_API FSOUND_Stream_GetPaused(
FSOUND_STREAM *stream
);

Parameters

stream Pointer to the stream to enquire on the paused state.

Return Value

On success, the paused state of the stream is returned. TRUE or FALSE.
On failure, FALSE is returned.

Remarks

See Also

FSOUND_Stream_SetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_GetPosition

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

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.
-----
WMA/ASF support for this function is only emulated by calculating the fraction of the filesize based on the time and the current time so it is not 100accurate.
-----
This function is not supported for URL based streams over the internet.

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_SetPosition , FSOUND_Stream_SetTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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

WMA/ASF/Internet streaming does not support this function.

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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

See Also

FSOUND_Stream_SetTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_OpenFile

Opens a RAW/.WAV/.MP2/.MP3/.OGG/.WMA or .ASF streamable file ready for streaming.

FSOUND_STREAM * F_API FSOUND_Stream_OpenFile(
const char *filename,
unsigned int mode,
int memlength
);

Parameters

filename | 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_2D, FSOUND_LOADMEMORY, FSOUND_LOADRAW, FSOUND_MPEGACCURATE flags are the only ones supported.
memlength | Only used if FSOUND_LOADMEMORY is specified in the mode, otherwise leave as 0. This specifies the lengh of the memory block in BYTES being passed if FSOUND_LOADMEMORY is used.

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.
--------------
NOTE : WMA/ASF/Internet streams are a limited implementation because of the way the formats work.. Note the following limitations
- Multiple WMA/ASF/Internet streams streams are not supported.
- Playing WMA/ASF/Internet streams do not run through the software engine, and will not show up in the DSP chain output, and does not use a logical FMOD channel either.
- Streaming WMA/ASF from memory is not supported.
- WMA/ASF/Internet stream playback will always comes from primary sound device.
- Channel attributes such as volume frequency and pan cannot be controlled for WMA/ASF/Internet streams as the FSOUND_Stream_Play function will return a dummy channel handle.
- WMA/ASF/Internet streams cannot loop, the flag will be ignored.
--------------
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.

See Also

FSOUND_MODES , FSOUND_Stream_Close , FSOUND_Stream_GetLength , FSOUND_Stream_GetLengthMs , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib , FSOUND_Stream_Stop

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 number the stream is playing in is returned.
On failure, -1 is returned.

Remarks

When a stream starts to play, it reserves a channel at the highest priority. It cannot
be rejected by other sound effect channels in the normal fashion. If you try to start
a stream when all the allocated channels are playing, it will kick out the lowest priority
channel it can find, but failing that (all channels are at high priority), it will kick out
the first channel it finds.
If you dont want streams to reserve a channel, then use FSOUND_SetReserved(channel, FALSE)
on the stream straight after you play it and get the channel number from FSOUND_Stream_Play.
--------
Important : If you are streaming a STEREO sample, and using normal middle panning, it will
only come out at half the volume they are supposed to, as it gives half the amplitude to each
channel. FSOUND_STEREOPAN is recommended for this which will center the sound and give it normal amplitude.
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. (except for WMA and internet streamed streams)
--------
NOTE : WMA/ASF/Internet streams are a limited implementation because of the way the formats work.. Note the following limitations
- Multiple WMA/ASF/Internet streams streams are not supported.
- Playing WMA/ASF/Internet streams do not run through the software engine, and will not show up in the DSP chain output, and does not use a logical FMOD channel either.
- Streaming WMA/ASF from memory is not supported.
- WMA/ASF/Internet stream playback will always comes from primary sound device.
- Channel attributes such as volume frequency and pan cannot be controlled for WMA/ASF/Internet streams as the FSOUND_Stream_Play function will return a dummy channel handle.
- WMA/ASF/Internet streams cannot loop, the flag will be ignored.

See Also

FSOUND_Init , FSOUND_SetPan , FSOUND_SetReserved , FSOUND_SetVolume , FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_OpenFile , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib , FSOUND_Stream_SetEndCallback , FSOUND_Stream_Stop

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_Play3DAttrib

Starts a pre-opened stream playing.

int F_API FSOUND_Stream_Play3DAttrib(
int channel,
FSOUND_STREAM *stream,
int freq,
int vol,
int pan,
float *pos,
float *vel
);

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.
freq | frequency in hz to play sound at. -1 will use streams default frequency.
vol | volume to play sound at (0-255). -1 will use streams default volume.
pan | pan position to play sound at (0-255, FSOUND_STEREOPAN). -1 will use streams default pan.
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. (especially if the sound is 2D!)
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. (especially if the sound is 2D!)

Return Value

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

Remarks

When a stream starts to play, it reserves a channel at the highest priority. It cannot
be rejected by other sound effect channels in the normal fashion. If you try to start
a stream when all the allocated channels are playing, it will kick out the lowest priority
channel it can find, but failing that (all channels are at high priority), it will kick out
the first channel it finds.
If you dont want streams to reserve a channel, then use FSOUND_SetReserved(channel, FALSE)
on the stream straight after you play it and get the channel number from FSOUND_Stream_Play.
--------
Important : If you are streaming a STEREO sample, and using normal middle panning, it will
only come out at half the volume they are supposed to, as it gives half the amplitude to each
channel. FSOUND_STEREOPAN is recommended for this which will center the sound and give it normal amplitude.
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. (note WMA/ASF/Internet streaming limitations)
--------
NOTE : WMA/ASF/Internet streams are a limited implementation because of the way the formats work.. Note the following limitations
- Multiple WMA/ASF/Internet streams streams are not supported.
- Playing WMA/ASF/Internet streams do not run through the software engine, and will not show up in the DSP chain output, and does not use a logical FMOD channel either.
- Streaming WMA/ASF from memory is not supported.
- WMA/ASF/Internet stream playback will always comes from primary sound device.
- Channel attributes such as volume frequency and pan cannot be controlled for WMA/ASF/Internet streams as the FSOUND_Stream_Play function will return a dummy channel handle.
- WMA/ASF/Internet streams cannot loop, the flag will be ignored.

See Also

FSOUND_Init , FSOUND_SetPan , FSOUND_SetReserved , FSOUND_SetVolume , FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_OpenFile , FSOUND_Stream_Play , FSOUND_Stream_Stop

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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,
int userdata
);

Parameters

stream | Pointer to the stream to callback on when it is finished.
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.
A callback occurs if the stream is forcibly stopped or closed.
-----------
WMA/ASF/Internet streaming does not support this function.

See Also

FSOUND_MODES , FSOUND_Stream_Play , FSOUND_STREAMCALLBACK

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_SetPaused

Pauses and unpauses a stream.

signed char F_API FSOUND_Stream_SetPaused(
FSOUND_STREAM *stream,
signed char paused
);

Parameters

stream | Pointer to the stream to be paused / unpaused.
paused | paused flag. TRUE to pause the stream, FALSE to unpause it.

Return Value

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

Remarks

See Also

FSOUND_Stream_GetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_Stream_SetPosition

Sets the current stream's FILE position in BYTES.

signed char F_API FSOUND_Stream_SetPosition(
FSOUND_STREAM *stream,
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.

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_GetPosition , FSOUND_Stream_SetTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.

Return Value

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

Remarks

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_GetPosition , FSOUND_Stream_GetTime , FSOUND_Stream_SetPosition

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.

See Also

FSOUND_Stream_Close , FSOUND_Stream_Create , FSOUND_Stream_OpenFile , FSOUND_Stream_Play , FSOUND_Stream_Play3DAttrib

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_CD_Eject

Opens/Closes the CD tray.

signed char F_API FSOUND_CD_Eject(
);

Return Value

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

Remarks

Calling this when the CD tray is open will cause it to close.
Calling this when the CD tray is closed will cause it to open.
FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_Close , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_GetNumTracks

Returns the number of tracks on the currently inserted CD.

int F_API FSOUND_CD_GetNumTracks(
);

Return Value

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

Remarks

See Also

FSOUND_CD_GetTrack

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_GetPaused

Gets the pause status of the current CD audio track.

signed char F_API FSOUND_CD_GetPaused(
);

Return Value

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

Remarks

FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_Close , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_GetTrack

Returns the currently playing CD track number.

int F_API FSOUND_CD_GetTrack(
);

Return Value

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

Remarks

See Also

FSOUND_CD_GetNumTracks

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_GetTrackLength

Gets the track length of a CD.

int F_API FSOUND_CD_GetTrackLength(
int track
);

Parameters

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

See Also

FSOUND_CD_GetTrackTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_GetTrackTime

Returns the current track time playing on a CD.

int F_API FSOUND_CD_GetTrackTime(
);

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. Due to time constraints it was
left the way it was.

See Also

FSOUND_CD_GetTrackLength

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_Play

Plays a CD Audio track.

signed char F_API FSOUND_CD_Play(
int track
);

Parameters

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.
FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_CD_GetVolume , FSOUND_CD_SetPlayMode , FSOUND_CD_SetVolume , FSOUND_CD_Stop , FSOUND_Close , FSOUND_Init


[API function]

FSOUND_CD_SetPaused

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

signed char F_API FSOUND_CD_SetPaused(
signed char paused
);

Parameters

paused TRUE to pause track, FALSE to unpause track.

Return Value

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

Remarks

FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_Close , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_SetPlayMode

Sets the playback mode of the CD.

void F_API FSOUND_CD_SetPlayMode(
signed char mode
);

Parameters

mode See FSOUND_CDPLAYMODES for a list of valid parameters to send to this function.

Return Value

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

Remarks

FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_CD_Play , FSOUND_CDPLAYMODES , FSOUND_Close , FSOUND_Init


[API function]

FSOUND_CD_SetVolume

Sets the volume of the playing CD audio.

signed char F_API FSOUND_CD_SetVolume(
int volume
);

Parameters

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

See Also

FSOUND_CD_Play , FSOUND_Close

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_CD_Stop

Stops the currently playing CD audio track.

char F_API FSOUND_CD_Stop(
);

Return Value

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

Remarks

FSOUND_Init or FSOUND_Close are not needed to use these functions.

See Also

FSOUND_CD_Play , FSOUND_Close , FSOUND_Init


[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);

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,
int param
);

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, int param)
{
// 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.

See Also

FSOUND_DSP_Create , FSOUND_DSP_Free , FSOUND_DSP_GetBufferLength , FSOUND_DSP_MixBuffers , FSOUND_DSP_PRIORITIES , FSOUND_DSP_SetActive , FSOUND_DSP_SetPriority , FSOUND_DSPCALLBACK , FSOUND_GetCPUUsage , FSOUND_GetMixer , FSOUND_MIXERTYPES , 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

See Also

FSOUND_DSP_Create

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FSOUND_DSP_SetActive

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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)

See Also

FSOUND_DSP_Create

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FSOUND_DSP_GetClipAndCopyUnit , 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

See Also

FSOUND_DSP_GetClearUnit , 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

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetSFXUnit


[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

See Also

FSOUND_DSP_SetPriority

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_GetClearUnit , FSOUND_DSP_GetClipAndCopyUnit , FSOUND_DSP_GetMusicUnit


[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.

See Also

FSOUND_DSP_Create , FSOUND_DSP_MixBuffers , FSOUND_GetMixer , FSOUND_MODES , FSOUND_SetFrequency , FSOUND_SetPan , FSOUND_SetVolume


[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.

See Also

FSOUND_DSP_ClearMixBuffer , FSOUND_DSP_Create , FSOUND_DSP_GetActive


[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.

See Also

FSOUND_DSP_Create , FSOUND_DSP_GetPriority


[API function]

FSOUND_Geometry_AddList

Adds a geometry list into the current audio scene.
This is a quicker alternative to FSOUND_Geometry_AddPolygon, as you can add a whole audio
scene in one function call, in the soundsystem's native format, instead of building it
every frame polygon by polygon. It also has the benefit of bounding volume rejection.
See FSOUND_Geometry_List_Create for more information on lists.

int F_API FSOUND_Geometry_AddList(
FSOUND_GEOMLIST *geomlist
);

Parameters

geomlist Pointer to a valid geometry list

Return Value

On success, The number of polygons processed in the list is returned.
On failure, -1 is returned.

Remarks

See Also

FSOUND_3D_Update , FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Create


[API function]

FSOUND_Geometry_AddPolygon

Adds a polygon to the geometry database between FSOUND_3D_Update calls.
This function can take a triangle or a quad, based on whether 'p4' is NULL or not.
It is also able to be defined as an 'openning' polygon, which can serve as doorways or
windows.

signed char F_API FSOUND_Geometry_AddPolygon(
float *p1,
float *p2,
float *p3,
float *p4,
float *normal,
unsigned int mode,
float *openingfactor
);

Parameters

p1 | Pointer to the polygons vertex. This must be a pointer to an array of 3 floats. This value cannot be NULL.
p2 | Pointer to the polygons vertex. This must be a pointer to an array of 3 floats. This value cannot be NULL.
p3 | Pointer to the polygons vertex. This must be a pointer to an array of 3 floats. This value cannot be NULL.
p4 | Pointer to the polygons vertex. This must be a pointer to an array of 3 floats. This CAN be NULL, if you are specifying a triangle and not a quad.
normal | Pointer to the polygons vertex. This must be a pointer to an array of 3 floats. This value CAN be NULL. If it is, then a nomral is computed based for you. This is only to save time computing a normal internally, it does not matter which direction it faces. (ie what winding)
mode | This is a setting of bits defined by FSOUND_GEOMETRY_MODES to determine what type of polygon it is, ie reflective or an opening for example.
openingfactor | Pointer to a polygon opening factor. This value is only relevant if FSOUND_GEOMETRY_OPENING or FSOUND_GEOMETRY_OPENING_REFERENCE is supplied, and is ignored otherwise. Valid ranges are and from 0 to 1. 0 is closed, 1 is fully open. Remember that FSOUND_GEOMETRY_OPENING is only relevant to the previous polygon. if this value is NULL, then this polygon is discarded and there is no hole.

Return Value

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

Remarks

This is a buffered command. It only takes effect when FSOUND_3D_Update is called.
At this point all polygons are cleared, and another batch has to be prepared, either through
using FSOUND_Geometry_AddPolygon, or FSOUND_Geometry_AddList.
--------
A more efficient methohd to add geometry is through FSOUND_Geometry_AddList. This is a pre-
stored method of adding polygons as a batch in the geometry renderers native format, instead
of individually which is more time consuming.
--------
What do FSOUND_GEOMETRY_OPENING and FSOUND_GEOMETRY_OPENING_REFERENCE mean??
These 2 methods are useful when wanting to cut a hole in a polygon, for a door or window for
example, and dont want to add the extra polygons it would take to do it in geometry.
If you are calling FSOUND_Geometry_AddPolygon every frame, therefore rebuilding the audio
scene every frame, then it is a good idea to use FSOUND_GEOMETRY_OPENING. The value you
pass in is COPIED, and is not pointed to internally.
If you are building a list, and once the list is built, you want access to the opening factor,
then it would be a good idea to use FSOUND_GEOMETRY_OPENING_REFERENCE. This means when you
are using FSOUND_Geometry_AddList every frame, you still can alter the opening factors you
set previously (when building the list with FSOUND_Geometry_AddPolygon). As always keep the
scope of the pointer relevant to where you call the function from if it is declared on the
stack, otherwise it will cause unpredictable results if the value suddenly goes out of scope
and becomes corrupted.
This is also the case if you had the pointer stored inside a dynamically allocated section
memory, and the memory holding your pointer is freed. If FSOUND_Geometry_AddList processes
this pointer it will lead to unpredictable results.
There is no reason not to use FSOUND_GEOMETRY_OPENING if you are building a list, it is
very reasonable to do so if you want to reduce the polygon count of the audibility database.
You just wont have access to the opening factor once the list is built.
--------
As an efficiency note, an opening polygon is NOT a boolean polygon cut which is considerably
more expensive than just supplying a pre-cut database. It does not add polygons which can be
time consuming.
It is just a transparency which is overlaid onto the previous polygon. Sound tests, upon
contacting the opening, do not process the parent (except to get material information).

See Also

FSOUND_3D_Update , FSOUND_Geometry_AddList , FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Begin , FSOUND_Geometry_List_Create , FSOUND_Geometry_List_End , FSOUND_Geometry_Material_Create , FSOUND_Geometry_Material_Set , FSOUND_GEOMETRY_MODES


[API function]

FSOUND_Geometry_List_Begin

Starts the definition of a geometry list, to be followed by FSOUND_Geometry_AddPolygon and
material based functions.
For more information on geometry lists, see FSOUND_Geometry_List_Create.

signed char F_API FSOUND_Geometry_List_Begin(
FSOUND_GEOMLIST *geomlist
);

Parameters

geomlist Pointer to a valid geometry list

Return Value

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

Remarks

See Also

FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Create , FSOUND_Geometry_List_End


[API function]

FSOUND_Geometry_List_Create

Creates a new empty geometry list. Geometry lists are an optimization. Instead of
rebuilding the audio scene every frame with FSOUND_Geometry_AddPolygon, you can first
pre-build a list, and then use 1 call to FSOUND_Geometry_AddList which is in the
soundsystem's native format. The only downside is that the scene is not totally dynamic.
It is able to have some dynamics in that pointers set up with
FSOUND_GEOMETRY_OPENING_REFERENCE are still able to have their opening factors changed,
so you can open and close doors etc.
You can create multiple lists and add them into the audio scene without reasonable
limitation.

FSOUND_GEOMLIST * F_API FSOUND_Geometry_List_Create(
signed char boundingvolume
);

Parameters

geomlist | Pointer to a valid geometry list
boudingvolume | TRUE or FALSE. This specifies whether a bounding box optimization should be calaculated as the list is created. Using this enables trivial acceptance and rejection of lists, which can increase polygon throughputs dramatically. It is enabled as an option in case the user wants to use their own rejection techniques.

Return Value

On success, a pointer to a newly created Geometry list is returned.
On failure, NULL is returned.

Remarks

See Also

FSOUND_Geometry_AddList , FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Begin , FSOUND_Geometry_List_End , FSOUND_Geometry_List_Free


[API function]

FSOUND_Geometry_List_End

Ends the description of a polygon list, started with FSOUND_Geometry_List_Begin, then built
with FSOUND_Geometry_AddPolygon.

signed char F_API FSOUND_Geometry_List_End(
FSOUND_GEOMLIST *geomlist
);

Parameters

geomlist Pointer to a valid geometry list

Return Value

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

Remarks

See Also

FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Begin , FSOUND_Geometry_List_Create


[API function]

FSOUND_Geometry_List_Free

Frees a geometry list database from memory.

signed char F_API FSOUND_Geometry_List_Free(
FSOUND_GEOMLIST *geomlist
);

Parameters

geomlist Pointer to a valid geometry list

Return Value

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

Remarks

See Also

FSOUND_Geometry_List_Create

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_Geometry_Material_Create

Create a material to later apply to the audio scene for geometry rendering.

FSOUND_MATERIAL * F_API FSOUND_Geometry_Material_Create(
);

Return Value

On success, a pointer to a newly created material is returned.
On failure, NULL is returned.

Remarks

Set the materials attributes with FSOUND_Geometry_Material_SetAttributes
To apply the material when building an audio scene with FSOUND_Geometry_AddPolygon, use
FSOUND_Geometry_Material_Set.

See Also

FSOUND_Geometry_AddPolygon , FSOUND_Geometry_Material_Free , FSOUND_Geometry_Material_GetAttributes , FSOUND_Geometry_Material_Set , FSOUND_Geometry_Material_SetAttributes


[API function]

FSOUND_Geometry_Material_Free

Frees a material allocated with FSOUND_Geometry_Material_Create.

signed char F_API FSOUND_Geometry_Material_Free(
FSOUND_MATERIAL *material
);

Parameters

material Pointer to a valid fsound geometry material type.

Return Value

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

Remarks

See Also

FSOUND_Geometry_Material_Create

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_Geometry_Material_GetAttributes

Gets the reflectiveness and transmittance attributes of a material.

signed char F_API FSOUND_Geometry_Material_GetAttributes(
FSOUND_MATERIAL *material,
float *reflectancegain,
float *reflectancefreq,
float *transmittancegain,
float *transmittancefreq
);

Parameters

material | Pointer to a valid fsound geometry material to have its attributes returned.
reflectancegain | Pointer to a value to receive the reflectance gain. This can be NULL to ignore. See FSOUND_Geometry_Material_SetAttributes for a description of the attribute.
reflectancefreq | Pointer to a value to receive the reflectance high frequency. This can be NULL to ignore. See FSOUND_Geometry_Material_SetAttributes for a description of the attribute.
transmittancegain | Pointer to a value to receive the transmittance gain. This can be NULL to ignore. See FSOUND_Geometry_Material_SetAttributes for a description of the attribute.
transmittancefreq | Pointer to a value to receive the transmittance high frequency. This can be NULL to ignore. See FSOUND_Geometry_Material_SetAttributes for a description of the attribute.

Return Value

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

Remarks

See Also

FSOUND_Geometry_Material_Create , FSOUND_Geometry_Material_Set , FSOUND_Geometry_Material_SetAttributes


[API function]

FSOUND_Geometry_Material_Set

Sets the current material whilst building a polygon audio scene, to the one specified.

signed char F_API FSOUND_Geometry_Material_Set(
FSOUND_MATERIAL *material
);

Parameters

material Pointer to a valid fsound geometry material.

Return Value

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

Remarks

See Also

FSOUND_Geometry_AddPolygon , FSOUND_Geometry_Material_Create , FSOUND_Geometry_Material_GetAttributes , FSOUND_Geometry_Material_SetAttributes


[API function]

FSOUND_Geometry_Material_SetAttributes

Set the relfectiveness and transmittance attributes of a material.

signed char F_API FSOUND_Geometry_Material_SetAttributes(
FSOUND_MATERIAL *material,
float reflectancegain,
float reflectancefreq,
float transmittancegain,
float transmittancefreq
);

Parameters

material | Pointer to a valid fsound geometry material
reflectancegain | A floating point number between 0 and 1. Reflectance gain is how much of the original signal is relfected off this material. 0 means none of the signal is reflected, and 1 means all of it is reflected.
reflectancefreq | A floating point number between 0 and 1. Reflectance high frequency is the level of the signals frequency that is reflected back to the listener. 0 means no frequencies are reflected back whereas 1 means all frequencies are reflected back.
transmittancegain | A floating point number between 0 and 1. Transmittance gain is how much of the original signal passed through this material. 0 means none of the signal is transmitted, or passes through, whereas 1 means all of it passes through, so it is completely transparent.
transmittancefreq | A floating point number between 0 and 1. Transmittance high frequency is the level of the signals frequency that can pass through the material.. 0 means no frequencies are pass through the material, whereas 1 means all frequencies are transmittable through the material.

Return Value

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

Remarks

Attributes set, do not take affect unless FSOUND_Geometry_Material_Set is called within
the rendering of a scene.

See Also

FSOUND_Geometry_Material_Create , FSOUND_Geometry_Material_GetAttributes , FSOUND_Geometry_Material_Set


[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

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

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

signed 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

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, A3D, WaveOut etc.)

int F_API FSOUND_Record_GetNumDrivers(
);

Return Value

Total number of enumerated sound devices.

Remarks

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 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

See Also

FSOUND_Record_StartSample

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

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

Note: 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.
The recording/playback rate are slightly innacurate and are not identical, so one will be faster or slower
than the other. In this case the recording and the playback cursor could overlap, and the output will sound
corrupted. 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 to call GetPosition for each,
and use FSOUND_SetFrequency on the playback, to slow it down if it is getting too close, or speed it up if it
is getting too far behind.

See Also

FSOUND_GetCurrentPosition , FSOUND_Record_GetPosition , FSOUND_Record_Stop , FSOUND_SetFrequency


[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

See Also

FSOUND_Record_StartSample

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_Reverb_GetEnvironment

Returns the current reverb environment.

signed char F_API FSOUND_Reverb_GetEnvironment(
int *env,
float *vol,
float *decay,
float *damp
);

Parameters

env | Pointer to the type of this environment. This can be NULL to ignore it.
vol | Pointer to the volume value for this environment. This can be NULL to ignore it.
decay | Pointer to the decay value for this environment. This can be NULL to ignore it.
damp | Pointer to the damping value for this environment. This can be NULL to ignore it.

Return Value

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

Remarks

You must be using DirectSound output mode for this command to work.
You must have an compatible card such as an SBLive! to hear the effects.

See Also

FSOUND_Reverb_SetEnvironment

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_Reverb_GetEnvironmentAdvanced

Returns the current EAX reverb environment.

signed char F_API FSOUND_Reverb_GetEnvironmentAdvanced(
int *env,
int *Room,
int *RoomHF,
float *RoomRolloffFactor,
float *DecayTime,
float *DecayHFRatio,
int *Reflections,
float *ReflectionsDelay,
int *Reverb,
float *ReverbDelay,
float *EnvironmentSize,
float *EnvironmentDiffusion,
float *AirAbsorptionHF
);

Parameters

env | The environment type. see FSOUND_REVERB_ENVIRONMENTS for types This can be NULL to ignore it.
Room | Room effect level at low frequencies -10000 to 0 default: -10000 mB This can be NULL to ignore it.
RoomHF | Room effect high-frequency level re. low frequency level -10000 to 0 default: 0 mB This can be NULL to ignore it.
RoomRolloffFactor | Like DS3D flRolloffFactor but for room effect 0.0 to 10.0 default: 0.0 This can be NULL to ignore it.
DecayTime | Reverberation decay time at low frequencies 0.1 to 20.0 default: 1.0 s This can be NULL to ignore it.
DecayHFRatio | High-frequency to low-frequency decay time ratio 0.1 to 2.0 default: 0.5 This can be NULL to ignore it.
Reflections | Early reflections level relative to room effect -10000 to 1000 default: -10000 mB This can be NULL to ignore it.
ReflectionsDelay | Initial reflection delay time 0.0 to 0.3 default: 0.02 s This can be NULL to ignore it.
Reverb | Late reverberation level relative to room effect -10000 to 2000 default: -10000 mB This can be NULL to ignore it.
ReverbDelay | Late reverberation delay time relative to initial reflection 0.0 to 0.1 default: 0.04 s This can be NULL to ignore it.
EnvironmentSize | Environment size in meters 0.0 to 100.0 default: 100.0 This can be NULL to ignore it.
EnvironmentDiffusion | Environment diffusion 0.0 to 100.0 default: 100.0 This can be NULL to ignore it.
AirAbsorptionHF | Change in level per meter at 5 kHz 20.0 to 20000.0 default: 5000.0 Hz This can be NULL to ignore it.

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 EAX2 compatible soundcard,
or using A3D3.0.

See Also

FSOUND_REVERB_ENVIRONMENTS , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced


[API function]

FSOUND_Reverb_GetMix

This function gets wet/dry mix, or the amount of reverb being applied to this channel.

signed char F_API FSOUND_Reverb_GetMix(
int channel,
float *mix
);

Parameters

channel | The channel to have its reverb mix returned.
mix | Pointer to a value which will contain the reverb mix for the specified channel. 0.0 to 1.0 are the valid values, as well as -1 or FSOUND_REVERBMIX_USEDISTANCE.

Return Value

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

Remarks

See Also

FSOUND_Reverb_SetMix , FSOUND_REVERBMIX_USEDISTANCE


[API function]

FSOUND_Reverb_SetEnvironment

Allows you to set a global reverb environment using EAX or A3D reverb.

signed char F_API FSOUND_Reverb_SetEnvironment(
int env,
float vol,
float decay,
float damp
);

Parameters

env | Sets an environment type. see FSOUND_REVERB_ENVIRONMENTS for types. Setting this resets all other parameters to default!!! This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
vol | Linear volume of global reverb mix, from 0 to 1 default: varies depending on environment This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
decay | Decay value for reverb , in seconds from 0 to 20 default: varies depending on environment This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
damp | Room effect level at low frequencies from 0 to 2 default: varies depending on environment This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.

Return Value

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

Remarks

You must be using FSOUND_OUTPUT_DSOUND or FSOUND_OUTPUT_A3D 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 was created with the FSOUND_HW3D flag.
----------------
Note that EAX and A3D reverb sound different. If you are fussy you may want to tweak for
both by doing this.
if (FSOUND_GetOutput() == FSOUND_OUTPUT_A3D)
FSOUND_Reverb_SetEnvironment(one set of settings);
else
FSOUND_Reverb_SetEnvironment(another set of settings);
---------------------------
From the EAX 1.0 documentation.
---------------------------
Volume:
The Volume property is the master volume control for the reverb added to all
sound sources; it sets the maximum volume of all reverb added to the sound
mix in the primary buffer (the listener). Sound sources mixed into the primary
buffer may have reverb volumes that vary relative to each other. (The reverb
for each source is set by its wet/dry ratio as described in the Reverb Mix sound-source
property.) As the master reverb volume goes up and down, controlled
by Volume, the reverb for each sound source goes up or down in proportion.
The Reverb Volume property value is a linear amplitude value, not a linear
decibel value. The maximum value of 1.0 turns overall reverb up to its fullest
possible volume. Each time you halve the value, you halve the volume and
therefore drop it by 6 dB. For example, turning the volume down from 1.0 to
0.5 drops the volume by 6 dB. Turning it down from 1.0 to 0.25 drops 12 dB;
from 1.0 to 0.125 18 dB; and so on. Setting the volume to 0.0 turns off all
reverb completely.
----------------------------
Decay:
Reverb decay is caused when a room’s surfaces absorb acoustic energy. Each
time an echo bounces off a surface, it decreases in volume until there is no
echo. If room surfaces are acoustically "live," they absorb very little acoustic
energy, echoes diminish only gradually each time they bounce, and the reverb
(a mixture of all the echoes) takes a long time to decay. If room surfaces are
acoustically "dead", reverb decays very quickly as acoustic energy is absorbed.
The Decay Time property effectively sets the acoustic properties of the virtual
room’s surfaces by setting the time in seconds it takes the reverb to diminish by
60 dB. When set to the maximum value (20 seconds), it simulates very live
surfaces; when set to the minimum value (0.1 seconds), it simulates very dead
surfaces with almost no reverb at all.
----------------------------
Damping:
The acoustic reflectivity of a room surface is not always even across all
frequencies. Some surfaces reflect more low and middle frequencies while
absorbing high frequencies. This high-frequency roll-off is called damping.
The Damping property sets the amount of damping applied to an environment.
Damping affects the decay time of the reverb as set by the property Decay
Time. The damping value 1.0 is neutral: the decay time is equal for high
frequencies and for low and middle frequencies. As the damping value
increases above 1.0, the high-frequency decay time increases so it’s longer than
the decay time of the middle and low frequencies. You hear a more brilliant
reverb. As the damping value decreases below 1.0, high-frequency decay time
decreases so it’s shorter than the decay time of the middle and low frequencies.
You hear a more muffled reverb.
---------------------------
For more advanced control use FSOUND_Reverb_SetEnvironmentAdvanced, but note, this
only works under A3D 3.0 or EAX2 compatible hardware.
-----------------
FSOUND_REVERB_IGNOREPARAM is handy if the parameter list is overwhelming. It allows you to only adjust a certain value in the environment without
having to worry about setting the rest.

See Also

FSOUND_GetOutput , FSOUND_REVERB_ENVIRONMENTS , FSOUND_Reverb_GetEnvironment , FSOUND_Reverb_GetEnvironmentAdvanced , FSOUND_REVERB_IGNOREPARAM , FSOUND_REVERB_PRESETS , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced


[API function]

FSOUND_Reverb_SetEnvironmentAdvanced

A3D 3.0 and EAX 2.0 reverb parameters for advanced tuning.
The best way to play with these is to set everything to its defaults, and then start modifying values.

signed char F_API FSOUND_Reverb_SetEnvironmentAdvanced(
int env,
int Room,
int RoomHF,
float RoomRolloffFactor,
float DecayTime,
float DecayHFRatio,
int Reflections,
float ReflectionsDelay,
int Reverb,
float ReverbDelay,
float EnvironmentSize,
float EnvironmentDiffusion,
float AirAbsorptionHF
);

Parameters

env | Sets an environment type. see FSOUND_REVERB_ENVIRONMENTS for types. Setting this resets all other parameters to default! This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
Room | Room effect level at low frequencies -10000 to 0 default: -10000 mB This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
RoomHF | Room effect high-frequency level re. low frequency level -10000 to 0 default: 0 mB This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
RoomRolloffFactor | Like DS3D flRolloffFactor but for room effect 0.0 to 10.0 default: 0.0 This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
DecayTime | Reverberation decay time at low frequencies 0.1 to 20.0 default: 1.0 s This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
DecayHFRatio | High-frequency to low-frequency decay time ratio 0.1 to 2.0 default: 0.5 This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
Reflections | Early reflections level relative to room effect -10000 to 1000 default: -10000 mB This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
ReflectionsDelay | Initial reflection delay time 0.0 to 0.3 default: 0.02 s This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
Reverb | Late reverberation level relative to room effect -10000 to 2000 default: -10000 mB This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
ReverbDelay | Late reverberation delay time relative to initial reflection 0.0 to 0.1 default: 0.04 s This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
EnvironmentSize | Environment size in meters 0.0 to 100.0 default: 100.0 This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
EnvironmentDiffusion | Environment diffusion 0.0 to 100.0 default: 100.0 This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
AirAbsorptionHF | Change in level per meter at 5 kHz 20.0 to 20000.0 default: 5000.0 Hz This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.

Return Value

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

Remarks

You must be using FSOUND_OUTPUT_DSOUND or FSOUND_OUTPUT_A3D 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 was created with the FSOUND_HW3D flag.
----------------
Note that EAX, EAX2 and A3D reverb may sound different. If you are fussy you may want to tweak for
both by doing this.
if (FSOUND_GetOutput() == FSOUND_OUTPUT_A3D)
FSOUND_Reverb_SetEnvironmentAdvanced(one set of settings);
else
FSOUND_Reverb_SetEnvironmentAdvanced(another set of settings);
-----------------
FSOUND_REVERB_IGNOREPARAM is handy if the parameter list is overwhelming. It allows you to only adjust a certain value in the environment without
having to worry about setting the rest.

See Also

FSOUND_GetOutput , FSOUND_REVERB_ENVIRONMENTS , FSOUND_Reverb_GetEnvironmentAdvanced , FSOUND_REVERB_IGNOREPARAM , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced


[API function]

FSOUND_Reverb_SetMix

Sets a scalar, or the wet/dry mix value for the amount of reverb to be applied to this channel,
or to tell it to automatically calculate the reverb amount based on distance from listener.

signed char F_API FSOUND_Reverb_SetMix(
int channel,
float mix
);

Parameters

channel | The channel to have its reverb mix changed.
mix | 0.0 to 1.0. 0 means no reverb for this channel (dry), whereas 1.0 means full reverb (wet). EAX_REVERBMIX_USEDISTANCE. This will scale the reverb mix automatically based on the distance from the listener. It is recommended to use this value as it is the most natural sounding.

Return Value

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

Remarks

If no mix value is set, EAX_REVERBMIX_USEDISTANCE is the default.
-----------------
You must be using FSOUND_OUTPUT_DSOUND or FSOUND_OUTPUT_A3D 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 was created with the FSOUND_HW3D flag.

See Also

FSOUND_Reverb_GetMix , FSOUND_REVERBMIX_USEDISTANCE


[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

See Also

FMUSIC_SetMasterVolume

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.


[API function]

FSOUND_GetDriverCaps

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, or after FSOUND_Close.

See Also

FSOUND_CAPS , FSOUND_Close , FSOUND_GetNumDrivers , FSOUND_Init


[API function]

FSOUND_GetCPUUsage

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

float 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.
WMA/ASF and MIDI playback is not counted as it is performed by directx.

See Also

FSOUND_DSP_Create

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_File_SetCallbacks

Specify user callbacks for FMOD's internal file manipulation.
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.

void F_API FSOUND_File_SetCallbacks(
unsigned int (*OpenCallback)(const char *name),
void (*CloseCallback)(unsigned int handle),
int (*ReadCallback)(void *buffer,
int size,
unsigned int handle),
int (*SeekCallback)(unsigned int handle,
int pos,
signed char mode),
int (*TellCallback
);

Parameters

OpenCallback | Callback for opening a file. Parameters: ----------- "name" This is the filename. You may treat this how you like. Instructions: ------------- 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 later functions, cast it back to your own handle type. Return 0 signify 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.
CloseCallback | Callback for closing a file. Parameters: ----------- "handle" This is the handle you returned from the open callback to use for your own file routines. Instructions: ------------- Close your file handle and do any cleanup here.
ReadCallback | Callback for opening a file. 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. Instructions: ------------- You must read "length" number of bytes into the "buffer" provided, then if you need to, increment your file pointer. IMPORTANT: you MUST 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).
SeekCallback | Callback for seeking within a file. There are 3 modes of seeking, as described below. 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. Instructions: ------------- You must reset your file pointer based on the commands given above. 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.
TellCallback | Callback for returning the offset from the base of the file in BYTES. Parameters: ----------- "handle" This is the handle you returned from the open callback to use for your own file routines. Instructions: ------------- You must return the offset from the base of the file, using this routine.

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.

See Also

FMUSIC_LoadSong , FMUSIC_LoadSongMemory

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FSOUND_GetError

Returns an error code set by FMOD.

int F_API FSOUND_GetError(
);

Return Value

error code, see FMOD_ERRORS

Remarks

See Also

FMOD_ERRORS , FSOUND_GetFrequency , FSOUND_GetPan , FSOUND_GetPriority , FSOUND_GetVolume


[API function]

FSOUND_GetNumHardwareChannels

Returns the number of available hardware mixed 3d channels.

int F_API FSOUND_GetNumHardwareChannels(
);

Return Value

The number of available hardware mixed 3d channels.

Remarks

See Also

FSOUND_PlaySound , FSOUND_PlaySound3DAttrib


[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_EAX | 0x2 // This driver supports EAX reverb
FSOUND_CAPS_GEOMETRY_OCCLUSIONS | 0x4 // This driver supports (A3D) geometry occlusions
FSOUND_CAPS_GEOMETRY_REFLECTIONS | 0x8 // This driver supports (A3D) geometry reflections
FSOUND_CAPS_EAX2 | 0x10 // This driver supports EAX2/A3D3 reverb

See Also

FSOUND_GetDriverCaps , FSOUND_OUTPUTTYPES

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_CDPLAYMODES

Playback method for a CD Audio track, using FSOUND_CD_Play

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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_DSP_PRIORITIES

These default priorities are

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
FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT | 1000 // DSP CLIP AND COPY unit - last

See Also

FSOUND_DSP_Create , FSOUND_DSP_SetPriority

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_GEOMETRY_MODES

Geometry flags, used as the mode flag in FSOUND_Geometry_AddPolygon

FSOUND_GEOMETRY_NORMAL | 0x0 // Default geometry type. Occluding polygon
FSOUND_GEOMETRY_REFLECTIVE | 0x01 // This polygon is reflective
FSOUND_GEOMETRY_OPENING | 0x02 // Overlays a transparency over the previous polygon. The 'openingfactor' value supplied is copied internally.
FSOUND_GEOMETRY_OPENING_REFERENCE | 0x04 // Overlays a transparency over the previous polygon. The 'openingfactor' supplied is pointed to (for access when building a list)

See Also

FSOUND_Geometry_AddPolygon

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_MODES

Sample description bitfields, OR them together for loading and describing samples.

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 source data containing unsigned samples.
FSOUND_SIGNED | 0x00000100 // For source data containing signed data.
FSOUND_DELTA | 0x00000200 // For source data stored as delta values.
FSOUND_IT214 | 0x00000400 // For source data stored using IT214 compression.
FSOUND_IT215 | 0x00000800 // For 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 // Ignores any 3d processing. overrides FSOUND_HW3D. Located in software.
FSOUND_STREAMABLE | 0x00004000 // For a streamable sound where you feed the data to it. If you dont supply this sound may come out corrupted. (only affects a3d output)
FSOUND_LOADMEMORY | 0x00008000 // 'name' will be interpreted as a pointer to data for streaming and samples.
FSOUND_LOADRAW | 0x00010000 // For will ignore file format and treat as raw pcm.
FSOUND_MPEGACCURATE | 0x00020000 // For FSOUND_Stream_OpenFile - for accurate FSOUND_Stream_GetLengthMs/FSOUND_Stream_SetTime. WARNING, see FSOUNDStream_OpenFile for inital opening time performance issues.
FSOUND_NORMAL | (FSOUND_LOOP_OFF | FSOUND_8BITS | FSOUND_MONO)

See Also

FSOUND_Stream_GetLength , FSOUND_Stream_GetLengthMs , FSOUND_Stream_OpenFile , FSOUND_Stream_SetTime

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_REVERB_IGNOREPARAM

Used with FSOUND_Reverb_SetEnvironment and FSOUND_Reverb_SetEnvironmentAdvanced, this can
be placed in the place of a specific parameter for the reverb setting. It allows you to
not set any parameters except the ones you are interested in .. and example would be this.
FSOUND_Reverb_SetEnvironment(FSOUND_REVERB_IGNOREPARAM,
FSOUND_REVERB_IGNOREPARAM,
FSOUND_REVERB_IGNOREPARAM,
0.0f);
This means env, vol and decay are left alone, but 'damp' is set to 0.

FSOUND_REVERB_IGNOREPARAM -9999999 // used with FSOUND_Reverb_SetEnvironmentAdvanced to ignore certain parameters by choice.

See Also

FSOUND_REVERB_IGNOREPARAM , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_REVERB_PRESETS

A set of predefined environment PARAMETERS, created by Creative Labs
These can be placed directly into the FSOUND_Reverb_SetEnvironment call

FSOUND_PRESET_OFF | FSOUND_ENVIRONMENT_GENERIC,0.0f,0.0f,0.0f
FSOUND_PRESET_GENERIC | FSOUND_ENVIRONMENT_GENERIC,0.5f,1.493f,0.5f
FSOUND_PRESET_PADDEDCELL | FSOUND_ENVIRONMENT_PADDEDCELL,0.25f,0.1f,0.0f
FSOUND_PRESET_ROOM | FSOUND_ENVIRONMENT_ROOM,0.417f,0.4f,0.666f
FSOUND_PRESET_BATHROOM | FSOUND_ENVIRONMENT_BATHROOM,0.653f,1.499f,0.166f
FSOUND_PRESET_LIVINGROOM | FSOUND_ENVIRONMENT_LIVINGROOM,0.208f,0.478f,0.0f
FSOUND_PRESET_STONEROOM | FSOUND_ENVIRONMENT_STONEROOM,0.5f,2.309f,0.888f
FSOUND_PRESET_AUDITORIUM | FSOUND_ENVIRONMENT_AUDITORIUM,0.403f,4.279f,0.5f
FSOUND_PRESET_CONCERTHALL | FSOUND_ENVIRONMENT_CONCERTHALL,0.5f,3.961f,0.5f
FSOUND_PRESET_CAVE | FSOUND_ENVIRONMENT_CAVE,0.5f,2.886f,1.304f
FSOUND_PRESET_ARENA | FSOUND_ENVIRONMENT_ARENA,0.361f,7.284f,0.332f
FSOUND_PRESET_HANGAR | FSOUND_ENVIRONMENT_HANGAR,0.5f,10.0f,0.3f
FSOUND_PRESET_CARPETEDHALLWAY | FSOUND_ENVIRONMENT_CARPETEDHALLWAY,0.153f,0.259f,2.0f
FSOUND_PRESET_HALLWAY | FSOUND_ENVIRONMENT_HALLWAY,0.361f,1.493f,0.0f
FSOUND_PRESET_STONECORRIDOR | FSOUND_ENVIRONMENT_STONECORRIDOR,0.444f,2.697f,0.638f
FSOUND_PRESET_ALLEY | FSOUND_ENVIRONMENT_ALLEY,0.25f,1.752f,0.776f
FSOUND_PRESET_FOREST | FSOUND_ENVIRONMENT_FOREST,0.111f,3.145f,0.472f
FSOUND_PRESET_CITY | FSOUND_ENVIRONMENT_CITY,0.111f,2.767f,0.224f
FSOUND_PRESET_MOUNTAINS | FSOUND_ENVIRONMENT_MOUNTAINS,0.194f,7.841f,0.472f
FSOUND_PRESET_QUARRY | FSOUND_ENVIRONMENT_QUARRY,1.0f,1.499f,0.5f
FSOUND_PRESET_PLAIN | FSOUND_ENVIRONMENT_PLAIN,0.097f,2.767f,0.224f
FSOUND_PRESET_PARKINGLOT | FSOUND_ENVIRONMENT_PARKINGLOT,0.208f,1.652f,1.5f
FSOUND_PRESET_SEWERPIPE | FSOUND_ENVIRONMENT_SEWERPIPE,0.652f,2.886f,0.25f
FSOUND_PRESET_UNDERWATER | FSOUND_ENVIRONMENT_UNDERWATER,1.0f,1.499f,0.0f
FSOUND_PRESET_DRUGGED | FSOUND_ENVIRONMENT_DRUGGED,0.875f, 8.392f,1.388f
FSOUND_PRESET_DIZZY | FSOUND_ENVIRONMENT_DIZZY,0.139f,17.234f,0.666f
FSOUND_PRESET_PSYCHOTIC | FSOUND_ENVIRONMENT_PSYCHOTIC,0.486f,7.563f,0.806f

See Also

FSOUND_Reverb_SetEnvironment

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_REVERBMIX_USEDISTANCE

Used with FSOUND_Reverb_SetMix, this setting allows reverb to attenuate based on distance from the listener.
Instead of hard coding a value with FSOUND_Reverb_SetMix, this value can be used instead, for a more natural
reverb dropoff.

FSOUND_REVERBMIX_USEDISTANCE -1.0f // used with FSOUND_Reverb_SetMix to scale reverb by distance

See Also

FSOUND_Reverb_SetMix

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Define]

FSOUND_CHANNELSAMPLEMODE

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.

See Also

FSOUND_PlaySound , FSOUND_PlaySound3DAttrib , FSOUND_Sample_Alloc , FSOUND_Sample_Load , FSOUND_SetPan

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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 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
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_NO_EAX2 | // Tried to use an advanced EAX2 command on a non EAX2 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 cant play wma or use internet streaming.

See Also

FSOUND_Close , FSOUND_GetError , FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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.

Enumerators

FSOUND_MIXER_AUTODETECT | // Enables autodetection of the fastest mixer based on your cpu.
FSOUND_MIXER_BLENDMODE | // Enables the standard non mmx, blendmode mixer.
FSOUND_MIXER_MMXP5 | // Enables the mmx, pentium optimized blendmode mixer.
FSOUND_MIXER_MMXP6 | // Enables the mmx, ppro/p2/p3 optimized mixer.
FSOUND_MIXER_QUALITY_AUTODETECT,// |
FSOUND_MIXER_QUALITY_FPU | // Enables the interpolating/volume ramping FPU mixer.
FSOUND_MIXER_QUALITY_MMXP5 | // Enables the interpolating/volume ramping p5 MMX mixer.
FSOUND_MIXER_QUALITY_MMXP6 | // Enables the interpolating/volume ramping ppro/p2/p3+ MMX mixer.

See Also

FSOUND_GetMixer , FSOUND_SetMixer

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Enum]

FSOUND_OUTPUTTYPES

These output types are used with FSOUND_SetOutput, to choose which output driver to use.
FSOUND_OUTPUT_A3D will cause FSOUND_Init to FAIL if you have not got a vortex
based A3D card. The suggestion for this is to immediately try and reinitialize FMOD with
FSOUND_OUTPUT_DSOUND, and if this fails, try initializing FMOD with FSOUND_OUTPUT_WAVEOUT.
FSOUND_OUTPUT_DSOUND will not support hardware 3d acceleration if the sound card driver
does not support DirectX 6 Voice Manager Extensions.

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 EAX or EAX2 support.
FSOUND_OUTPUT_A3D | // A3D driver. You need this to get geometry support.
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.

See Also

FSOUND_GetOutput , FSOUND_Init , FSOUND_SetOutput

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[Enum]

FSOUND_REVERB_ENVIRONMENTS

These are environment types defined for use with the FSOUND_Reverb API.

Enumerators

FSOUND_ENVIRONMENT_GENERIC
FSOUND_ENVIRONMENT_PADDEDCELL
FSOUND_ENVIRONMENT_ROOM
FSOUND_ENVIRONMENT_BATHROOM
FSOUND_ENVIRONMENT_LIVINGROOM
FSOUND_ENVIRONMENT_STONEROOM
FSOUND_ENVIRONMENT_AUDITORIUM
FSOUND_ENVIRONMENT_CONCERTHALL
FSOUND_ENVIRONMENT_CAVE
FSOUND_ENVIRONMENT_ARENA
FSOUND_ENVIRONMENT_HANGAR
FSOUND_ENVIRONMENT_CARPETEDHALLWAY
FSOUND_ENVIRONMENT_HALLWAY
FSOUND_ENVIRONMENT_STONECORRIDOR
FSOUND_ENVIRONMENT_ALLEY
FSOUND_ENVIRONMENT_FOREST
FSOUND_ENVIRONMENT_CITY
FSOUND_ENVIRONMENT_MOUNTAINS
FSOUND_ENVIRONMENT_QUARRY
FSOUND_ENVIRONMENT_PLAIN
FSOUND_ENVIRONMENT_PARKINGLOT
FSOUND_ENVIRONMENT_SEWERPIPE
FSOUND_ENVIRONMENT_UNDERWATER
FSOUND_ENVIRONMENT_DRUGGED
FSOUND_ENVIRONMENT_DIZZY
FSOUND_ENVIRONMENT_PSYCHOTIC
FSOUND_ENVIRONMENT_COUNT

See Also

FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


FMUSIC API Reference

FMOD Api. Use this to module files etc

Functions , 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_GetOrder
FMUSIC_GetPattern
FMUSIC_GetPatternLength
FMUSIC_GetPaused
FMUSIC_GetRow
FMUSIC_GetSample
FMUSIC_GetSpeed
FMUSIC_GetTime
FMUSIC_GetType
FMUSIC_IsFinished
FMUSIC_IsPlaying
FMUSIC_LoadSong
FMUSIC_LoadSongMemory
FMUSIC_OptimizeChannels
FMUSIC_PlaySong
FMUSIC_SetMasterVolume
FMUSIC_SetOrder
FMUSIC_SetOrderCallback
FMUSIC_SetPanSeperation
FMUSIC_SetPaused
FMUSIC_SetReverb
FMUSIC_SetRowCallback
FMUSIC_SetSample
FMUSIC_SetZxxCallback
FMUSIC_StopAllSongs
FMUSIC_StopSong

+ Defines

- Defines

FSOUND_CAPS
FSOUND_CDPLAYMODES
FSOUND_CHANNELSAMPLEMODE
FSOUND_DSP_PRIORITIES
FSOUND_GEOMETRY_MODES
FSOUND_INIT_FLAGS
FSOUND_MODES
FSOUND_REVERB_IGNOREPARAM
FSOUND_REVERB_PRESETS
FSOUND_REVERBMIX_USEDISTANCE

+ Enums

- Enums

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FMUSIC_CALLBACK

Callback definition for FMUSIC callbacks (mod/s3m/xm/it).

void 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.

See Also

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

void

Remarks

See Also

FMUSIC_LoadSong , FMUSIC_LoadSongMemory

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FMUSIC_LoadSong

To load a module 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)

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_LoadSongMemory will have to be used.
Various other functionality is not provided in MIDI. See relevant FMUSIC functions to see if a feature
is supported or not.

See Also

FMUSIC_FreeSong , FMUSIC_LoadSong , FMUSIC_LoadSongMemory , FSOUND_File_SetCallbacks


[API function]

FMUSIC_LoadSongMemory

To load a module from a preloaded memory handle. FMUSIC Supports loading of :
- .MOD (protracker/fasttracker modules)
- .S3M (screamtracker 3 modules)
- .XM (fasttracker 2 modules)
- .IT (impulse tracker modules)

FMUSIC_MODULE * F_API FMUSIC_LoadSongMemory(
void *data,
int length
);

Parameters

data Memory handle to data containing song to load.

Return Value

On success, a pointer to 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 will crash internally trying to load it.
One XM I tested had been truncated by around 30k somehow in the past. When
FMUSIC tried to load it, it could not help but try and read that 30k, and so
it tried to read outside of memory bounds and crashed. The same file loaded
from a file handle worked ok, becuase a filereader knows where the end of the
file is, and knows to stop.
The only solution to this particular problem is to make this function accept
a length value as well, so the memory reader never tries to read past this, or
you just pass it non corrupted songs. I prefer the latter, to make it easier
on the programmer, so they do not have to make them worry about extra code to
get filesizes.

See Also

FMUSIC_FreeSong , FMUSIC_LoadSong , FSOUND_File_SetCallbacks


[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.

See Also

FSOUND_GetChannelsPlaying

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_IsPlaying , FMUSIC_StopAllSongs , FMUSIC_StopSong


[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

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.

See Also

FMUSIC_GetOrder

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FMUSIC_SetOrderCallback

Sets a user callback to occur on every order divisible by the orderstep parameter, played from an 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.
------------
Note : This function is not supported with the MIDI format.

See Also

FMUSIC_CALLBACK , 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,
float 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.

See Also

FSOUND_SetPanSeperation

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_GetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.


[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.
------------
Note : This function is not supported with the MIDI format.

See Also

FMUSIC_CALLBACK , 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 frees the sample inside the mod, but only if it was not previously set with SetSample. (previous versions of fmod freed the sample regardless)
------------
Note : This function is not supported with the MIDI format.

See Also

FMUSIC_GetSample

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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, so that the callback happens when you HEAR the sound,
not when it is mixed, for accurate synchronization.
------------
Note : This function is not supported with the MIDI format.

See Also

FMUSIC_CALLBACK , 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

See Also

FMUSIC_PlaySong , FMUSIC_StopSong

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

void

Remarks

See Also

FMUSIC_PlaySong , FMUSIC_StopAllSongs

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_GetSpeed

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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)

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

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.

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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

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

See Also

FMUSIC_GetOrder

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_GetOrder

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_SetPaused

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.

See Also

FMUSIC_SetSample

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_GetBPM

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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 document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[API function]

FMUSIC_GetType

Returns the format type a song.

signed char 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

See Also

FMUSIC_TYPES

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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.


[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

See Also

FMUSIC_PlaySong

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[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

See Also

FMUSIC_GetType

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[API function]

FSOUND_CD_GetVolume

Returns the volume of the playing CD audio.

int F_API FSOUND_CD_GetVolume(
);

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

See Also

FSOUND_CD_Play , FSOUND_Close

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.


[Define]

FSOUND_INIT_FLAGS

Initialization flags. Use them with FSOUND_Init in the flags parameter to change various behaviour.

FSOUND_INIT_USEDEFAULTMIDISYNTH 0x01 // Causes MIDI playback to force software decoding.

See Also

FSOUND_Init

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.


[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,
int param
);

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.

See Also

FSOUND_DSP_Create , FSOUND_DSPCALLBACK

This document copyright ©Firelight Multimedia, 1999-2000. All rights reserved.
Generated Mon Dec 18 02:38:39 2000 by SourceDoc v0.10, the automated source code documenter.