FMOD Ex Audio Classes 0.6b

FMOD is a cross platform audio library that supports a wide range of audio formats and playback options, including a physically correct 3D audio engine. The FMOD Ex Audio Classes leverage FMOD to create a simple but powerful audio interface for REALbasic. Note however, that these classes do not expose all of FMOD Exs functionality, nor are they wrappers to access the FMOD Ex API directly.
First, a little background... The FMOD Ex API supports multiple concurrent "system" objects which may map to multiple audio devices installed on the same machine. Consequentially, all audio samples, channels, and effects are owned by a single system object and can not be shared. If a system object is destroyed, all sounds, channels, groups, and effects created under that system become invalidated and accessing them will generate errors (or worse).
To simplify this situation within the REALbasic environment, these classes do not allow for more than one system object to be active at any given time. Under normal circumstances this should not cause any grief - you call FMEx.StartUp when your application is launched, load your audio samples, create player objects, etc., then call FMEx.ShutDown when your application quits and all will be fine. If you have a need to restart FMOD Ex however, all existing FMExAudio, FMExStream, and FMExSubMixer instances will point to invalid audio handles. There is error checking in place to avoid crashes if this situation should arise, but it can still be annoying. In order to properly restart FMOD Ex you should follow the steps below...
Call the Stop method on all existing FMExAudioPlayer and FMExAudioPlayer3D instances. You do not have to dispose of these objects, but calling Stop ensures the internal channel reference is reset.
Dispose of all FMExAudio, FMExStream, and FMExSubMixer instances (i.e. set them to Nil). Be sure to also dispose of any FMExAudio instances that have been assigned to FMExAudioPlayer.DefaultAudio properties.
Call FMEx.ShutDown, followed by FMEx.StartUp, then reload/recreate all required FMExAudio, FMExStream, and FMExSubMixer objects and re-route any submixers.
ByRef methods are provided to allow you to reuse existing FMExAudio, FMExStream, and FMExSubMixer instances by replacing the required data/handles. This can be much easier than recreating them from scratch.
These classes couldve been simplified further by automatically reference counting audio objects and starting/stopping FMOD Ex behind your back, but that would preclude the ability to restart the audio engine at any time, and greatly impair the start up options interface.
- Virtual Channels
One of FMOD Exs most touted features is automatic channel virtualization. This allows you to play sounds on more channels than are physically available and let FMOD Ex decide which are more important based on priority settings and 3D positioning. One caveat with virtualization is that you must call FMEx.Update as frequently as possible for this to actually work (e.g. in games youd typically call FMEx.Update every frame). NOTE: If youre already calling FMEx.Update for 3D audio you do not need to call it twice.
- MIDI
MIDI playback currently only works on Windows, and only if the default system sound font is installed (/windows/system32/drivers/gm.dls). Broader MIDI support is on the would-like list but primary tests point to a broken implementation on Mac OS X (i.e. some FMOD Ex bugs need to be fixed before this can work).
- Other bugs...
Stereo sounds routed to submixers may "pollute" the wave data of other submixers. Everything else works as expected however and the audio output is correct, but submixers may return incorrect values when calling their Level methods. This appears to be a bug within FMOD Ex itself but more testing is required.