Version History
Version 0.8b - February 18, 2008
- Important: These classes are qualified to work with the FMOD Ex 4.12.xx releases only, and now require REALbasic 2006r4 or greater.
- API Change: FMEx.Startup no longer accepts optional maxchan, mixrate, bufferlength, and numbuffers options. Instead, you can now pass an optional FMExConfig instance that provides an interface for those, plus many more options.
- API Change: FMEx and FMExSubMixer Levels methods have been replaced with a Level method that returns one level output at a time given a speaker/output index. This change was required for proper metering of surround and multichannel devices. These methods have also been optimized using direct pointer access when possible.
- API Change: FMEx.SampleRate has been removed use the new FMEx.GetActiveSettings method instead.
- API Change: FMEx.TotalCPUUsage has been replaced with FMEx.CPUUsage.
- Note: FMExAudioPlayer and FMExAudioPlayer3D no longer un-mute on consecutive calls to a Play method (they still un-pause however). This is more consistent with common playback standards.
- Nearly all of FMOD Ex's pre-init options are now supported via a new FMExConfig class. E.g. you can now request specific output types such as ASIO on Windows.
- New FMExDriver class and supporting global methods to enumerate and select drivers for each supported output type. These can be used at any time, allowing pre-flight options to be set accordingly.
- Added support for surround and multichannel devices (automatic for 3D sounds on supported platforms). A "raw" mode is also available to treat each output as a separate mono channel. E.g. for professional multichannel audio cards.
- Re-wrote the start-up sequence to be more robust and conform to the "Windows Startup Sequence" recommend in the FMOD Ex documentation.
- New FMExChannel.Level method.
- New ByteLength and Format properties added to FMExAudio and FMExStream classes.
- New methods to read PCM audio data (for waveform plotting etc.) FMExAudio.Lock/Unlock and FMExStream .ReadData/SeekData.
- Shared streams no longer duplicate the data buffer (and become unshared) when FMExStream.Reinitialize is called.
- Fixed FMExStream.Reinitialize spelling.
- Audio players now properly clear the reference to the last audio played when stopped via the StopLooping method.
- Sounds are now loaded using the FMOD_ACCURATETIME flag to ensure proper timing with files that use VBR encoding. This may result in slightly longer load times for VBR files.
- FMOD Ex is now initialized to use right-handed 3D coordinates by default for better compatibility with Rb3D and OpenGL (this setting can be changed via the FMExConfig class).
- Behind-the-listener occlusion filtering for 3D sounds is now enabled by default (this setting can be changed via the FMExConfig class).
- The FMExChannel class has been split in two to clean up the subclass implementations. E.g. FMExAudioPlayer3D no longer has a useless inherited Pan property.
- FMExChannel instances no longer generate "invalid handle" errors if they go out of scope after FMOD has been shut down.
- Many internal cleanups and updates to take advantage of more modern RB features (computed properties, etc.).
- New documentation format with many updates and corrections.
Version 0.7b - September 23, 2007
- Important: These classes now require FMOD Ex 4.08.01 or later.
- Fixed sound-loading crashes with FMOD Ex 4.08 due to new structure sizes.
- FMEx.Startup no longer returns FMOD_ERR_PLUGIN_MISSING errors on Mac OS X & Linux with FMOD Ex 4.08 (caused by an enum change).
- FMExChannel.Pitch getter method properly returns a double now rather than an integer.
- Added support for "shared" streams. These are regular FMExStream objects that share the same audio buffer, allowing you to play the same audio simultaneously from multiple streams with minimal RAM overhead. This functionality is best accessed using the new FMExStream.Clone method, but can also be managed manually using the new FMEx.CreateStreamShared factory methods.
- Fixed FMExStreamSentence crashing when destructing (this crash was rare previously but persistent with FMOD Ex 4.08).
- FMExStreamSentence now makes clones of fragment streams to prevent a myriad of issues that could arise if the original reference was manipulated. This means you can now safely add a stream to a sentence and still use the original stream instance as normal.
- The FMExStreamSentence.Fragment array is now write-only since the internal stream fragments are not useful or usable outside of the sentence.
- It is no longer valid to assign an FMExStreamSentence instance as a fragment for another FMExStreamSentence. This never worked reliably in these classes, or inside FMOD Ex.
- FMExStreamSentence.Reinitialize actually works now, and also preserves the FragmentPlaybackOrder setting.
- The ByRef version of FMEx.CreateStreamSentence now properly reassigns fragments, and no longer returns False even on successful runs.
- Replacing FMExStreamSentence.Fragment(0) after changing FragmentPlaybackOrder now works more reliably (added a workaround for an FMOD Ex bug).
- The Mac OS X Framework Tool has been updated to better accommodate FMOD Ex universal binary releases.
Version 0.6b - June 27, 2007
- Important: These classes now require FMOD Ex 4.06.22 or later.
- Important: The Mac OS X declare path now links to FMODEx.framework to avoid path hacking with debug vs. release builds. A tool is included to bundle FMOD Ex dylibs into a framework, and can also create a Universal Binary from the platform specific FMOD Ex releases. Please see the documentation for more info.
- New FMExStreamSentence class for gapless stitching of multiple streams. A simple stream stitching example project is also included.
- New FMExChannel.StopLooping method to stop looping audio players once the currently playing sound reaches its endpoint.
- Fixed FMExStream.PlayLooping to respect the optional count parameter.
- Requesting a specific frequency in FMEx.StartUp no longer mangles FMOD's speaker mode (e.g. resulting in mono output).
- Added FMExStream.Handle read-only property.
- FMEx.StartUp will now attempt to use another audio driver if the preferred driver fails to initialize. On Mac OS X it will first try Core Audio, then Sound Manager, and on Linux it will first try ALSA, then OSS.
- Optimization: Error checking overhead has been reduced.
- Optimization: Refactored the sub-mixer functionality to be more efficient and provide better error checking.
- Optimization: Many often-used or typically polled methods use "speedy" pragma settings for release builds.
- Many documentation updates and corrections.
Version 0.5b - December 17, 2006
- Important: These classes now require FMOD Ex version 4.06 or later.
- API Change: Replaced the clunky GetError and GetErrorString methods with a FMEx.ErrorLogger property and FMExErrorLogger interface.
- Fixed an issue that arose with FMOD Ex 4.04.41 due to changes to an internal memory structure.
- FMExAudioPlayer3D and FMExListener3D private properties have been changed to protected scope to allow for more robust subclassing.
- Linux: Now defaults to ALSA output on for better compatibility.
- Sample and stream loading is slightly more efficient.
- Updated the documentation with instructions on how to build a universal binary FMOD Ex dylib.
- "Private" framework properties/methods (which are public do to the lack of a friend scope) are no longer prefixed with an underscore to avoid a scolding from REALSoftware. These pseudo-private properties are now prefixed with xFMEx and should not be accessed directly unless you know what yer doing (or want to crash).
Version 0.4b - April 20, 2006
- Important: These classes now require REALBasic 2005r1 or higher.
- API Change: FMExListener3D memory blocks are now private.
- Added support for FMOD Ex's channel groups via the new FMExSubMixer class.
- Added FMExChannel.RouteToSubMixer (for use by the FMExAudioPlayer and FMExAudioPlayer3D sub classes).
- Added the ability to mute the master mix (FMEx.Mute, FMEx.IsMuted).
- Added FMExStream.Reinitialze to recreate a stream internally using its existing sample data. The ByRef stream loaders are also more robust.
- Added FMExListener3D.SetPositionOrientationAndVelocity, a monolithic method for less update overhead.
- Optimization: 3D audio classes use pointer caching for declares and will also directly manipulate memory in release builds built with REALBasic 2006 r2 or higher.
- Optimization: Errors are no longer logged in release builds for speed-critical functions (e.g. system updates and 3D positioning).
- FMEx.ShutDown now issues a Stop override on all channels (FMOD probably does this internally anyway, but just in case...).
- FMEx.Levels no longer returns 0 when paused/muted but instead queries FMOD and reports the averaged wave data peak as usual. This applies to the new submixers as well.
- The 2D example project has been updated with submixer routings and includes a fix for UV/progress meter glitches when running in REALBasic 2006 r2 or higher.
Version 0.3b - February 12, 2006
- FMExAudioPlayer3D constructor contains an optional flag to use linear roll off instead of the default logarithmic roll off.
- FMExAudioPlayer3D.Maximum3DDistance property added to better accommodate linear roll off support.
- Added ByRef audio/stream loaders to facilitate reloading audio into an existing RB class instance (can be useful when restarting FMOD Ex).
- Fixed an issue with newer FMOD Ex releases where loading sounds would fail with an invalid parameter error due to FMOD API changes (new struct size).
- Now requires FMOD Ex 4.03.00 as the minimum version (partly due to the change above).
- FMEx.GetErrorString now returns a generic FMOD error number when errors occur inside FMOD as opposed to within the RB classes. Previously the FMOD error string function was ported to RB code but keeping this updated with the ever-changing enums in the FMOD headers has proven to be futile.
Version 0.2b - November 26, 2005
- Important: Due to FMOD Ex API changes, these classes now require FMOD Ex version 4.02.02 or greater
- Important: FMEx.StartUp has been refactored to work within new limitations in the FMOD Ex API. To re-start FMOD you must now call FMEx.ShutDown followed by FMEx.StartUp (i.e. you can no longer call FMEx.StartUp multiple times to restart/change mixer settings). Restarting FMOD Ex invalidates all internal audio and channel handles and must be done with care. Please see the documentation for more details.
- API Change: Added two new optional parameters to FMEx.StartUp to control the mixer granularity and latency
- API Change: FMEx.StartUp's optional parameters now behave differently: Passing 0 for any parameter will now cause FMOD Ex to use its internal default value (which may differ between systems and hardware). FMOD Ex's defaults are now also used by default if these properties are omitted entirely.
- API Change: FMExChannel.Rate has been renamed to FMExChannel.Pitch to better reflect the actual functionality (it scales the current sample's rate to a relative pitch, it doesn't represent the actual rate which may differ from sample to sample).
- Added FMEx.Pitch to change the playback speed of the entire mix.
- Added FMEx.SampleRate (read-only) property to return the mixer frequency in Hz.
- FMExAudio now has a DefaultAudio property to allow its default sample to be changed/disposed of at any time.
- FMEx.Pause works again (refactored to work within new limitations in the FMOD Ex API).
- FMEx.MemoryStats is now enabled on Mac OS X (early versions of the FMOD Ex dylib did not properly export the required function).
- FMEx.CreateStream now creates a copy of the stream data rather using a reference to prevent corruption if the original memoryblock is modified by the calling function.
- Fixed an OutOfBoundsException that occurred with Rb2005 when calling FMEx.GetLevels.
- The 2D example project now uses canvas based meters instead of progress bars to avoid problems with different/imprecise behaviour across platforms.
- Updated FMEx.GetErrorString to match new cases in fmod_errors C header.
- Added more sanity checks for invalid system/channel handles to avoid crashes and/or nondescript errors in cases where the FMOD Ex system object is trashed prematurely.
- Removed all DisableAutoWaitCursor pragmas for release builds (profiling with Shark suggests this pragma is evil).
- Many other code clean ups, and documentation additions, corrections, and updates.
Version 0.1b - August 1, 2005
- Initial release