FMEx Module
This module contains factory methods to create FMOD Ex objects plus global methods and properties that affect FMOD Ex as a whole. With a few exceptions*, you must call FMEx.StartUp before using any other classes, global methods, properties, or class extensions. Once FMEx.StartUp returns a successful start up, be sure to call FMEx.ShutDown when you're finished (e.g. prior to quitting) to allow FMOD Ex to clean up any internal resources.
Important: All existing FMExAudio, FMExStream, FMExStreamSentence, and FMExSubMixer instances become invalidated after calling FMEx.ShutDown. Please see the Restarting FMOD Ex section for details on how to properly restart FMOD Ex should the need arise.
Note: *The FMEx.GetDrivers and FMEx.OutputTypeAvailable methods in combination with the FMExDriver and FMExConfig classes can be used prior to calling FMEx.StartUp to determine hardware capabilities and configure start-up options. All other classes and methods will only function properly after FMEx.StartUp returns successfully.
Note: All properties, and methods listed below have public scope and must be prefixed with the FMEx namespace and dot notation.
FolderItem Extensions
-
OpenAsFMExAudio As FMExAudio
Opens an audio file and returns an FMExAudio instance or Nil if unsuccessful. -
OpenAsFMExAudio ( ByRef audio As FMExAudio ) As Boolean
Opens an audio file and replaces the data in an existing FMExAudio instance. Returns False if unsuccessful. -
OpenAsFMExStream( streambuffersize As Integer = 0 ) As FMExStream
Opens an audio file and returns an FMExStream instance or Nil if unsuccessful. The optional streambuffersize parameter can be used to increase the decoding buffer size to achieve smooth playback on problem hardware. The default (recommended) stream buffer size is 16384 bytes. -
OpenAsFMExStream ( ByRef audio As FMExStream, streambuffersize As Integer = 0 ) As Boolean
Opens an audio file and replaces the data in an existing FMExStream instance. Returns False if unsuccessful. The optional streambuffersize parameter can be used to increase the decoding buffer size to achieve smooth playback on problem hardware. The default (recommended) stream buffer size is 16384 bytes.
Properties
-
ChannelsPlaying As Integer
Returns the number of active FMOD Ex channels. This does not refer to the number of output channels - a stereo sound will only count as one channel for example. Note that paused or muted channels are still considered to be playing. -
CPUUsage As Double
Returns FMOD Ex's current CPU usage as a percentage. -
DistanceFactor3D As Double = 1.0
FMOD Ex's 3D engine uses "FMEx.DistanceFactor3D per meter" units when calculating Doppler shifting effects. The default value of 1.0 means 1 unit in 3D space equals 1 meter. To measure in feet set FMEx.DistanceFactor3D to 3.28 - i.e. 3.28 feet equals 1 meter. -
DopplerScale3D As Double = 1.0
Scales the global 3D Doppler effect. The default of 1.0 sets the speed of sound to 340 meters per second. Higher values exaggerate the pitch shifting while lower values diminish the effect. -
ErrorLogger As FMExErrorLogger
Errors and warnings will be forwarded to the FMExErrorLogger instance assigned to this property. If FMEx.ErrorLogger is Nil, no errors will be reported in release builds, and debug builds will dump errors to System.DebugLog. -
Handle As Integer
Mostly for internal use. Returns the FMOD_SYSTEM handle for the current system object or zero if no system is active. This handle can be used in custom declare statements. -
IsActive As Boolean
Returns True if FMOD Ex has been successfully initialized and is currently active. Mostly for internal use. -
IsMuted As Boolean
Returns True if the master mix is muted. -
IsPaused As Boolean
Returns True if the master mix is paused. -
Listener3D As FMExListener3D
This object defines the listener position and orientation for 3D audio playback. Can be left Nil (default) if 3D audio is not required. -
OutputsAvailable As Integer
Returns the number of output channels (or speakers) available for the current output type and driver.
Note: Due to FMOD Ex limitations, raw speaker modes will always return 16 outputs unless the output type is ASIO, in which case the correct number of outputs is returned, but only up to a maximum of 16. -
Pitch As Double = 1.0
Scales the playback rate of the master mix. E.g. 0.5 plays back at half speed, 1.0 is normal, and 2.0 is double speed. This value is capped internally by FMOD Ex to a value between 0.0 and 10.0. -
RolloffScale3D As Double = 1.0
This is the global sound attenuation/falloff factor for 3D sounds that use logarithmic roll off. The higher the value, the faster volume will attenuate, the lower the value, the slower it will attenuate. This has no effect on sounds that use linear roll off. The default of 1.0 simulates real-world distance attenuation. -
Volume As Double = 1.0
Adjusts the volume for the master mix in the range of 0.0 (silence) to 1.0 (full volume).
Methods
-
CreateAudio ( data As MemoryBlock ) As FMExAudio
Returns a new FMExAudio instance given raw data in a supported audio format. Returns Nil if an error is encountered or if the data is not compatible. -
CreateAudio ( ByRef audio As FMExAudio, data As MemoryBlock ) As Boolean
Replaces the audio data in an existing FMExAudio instance given raw data in a supported audio format. Returns True if successful. -
CreateStream ( data As MemoryBlock, streambuffersize As Integer = 0 ) As FMExStream
Returns a new FMExStream instance given raw data in a supported audio format. Returns Nil if an error is encountered or if the data is not compatible. The optional streambuffersize parameter can be used to increase the decoding buffer size to achieve smooth playback on problem hardware. The default (recommended) stream buffer size is 16384 bytes. -
CreateStream ( ByRef stream As FMExStream, data As MemoryBlock, streambuffersize As Integer = 0 ) As Boolean
Replaces the audio data in an existing FMExStream instance given raw data in a supported audio format. Returns True if successful. The optional streambuffersize parameter can be used to increase the decoding buffer size to achieve smooth playback on problem hardware. The default (recommended) stream buffer size is 16384 bytes. -
CreateStreamSentence ( fragments( ) As FMExStream ) As FMExStreamSentence
Returns a new FMExStreamSentence instance given an array of FMExStream objects. Returns Nil if an error is encountered. This function is overloaded to also accept a loose-list (ParamArray) of FMExStream objects.
Important: All the streams in the array must be valid (not Nil) and have the same frequency, bit depth, and number of channels. In other words, if the first stream is 44.1KHz/16bit Mono, the rest must also be 44.1KHz/16bit Mono. -
CreateStreamSentence ( ByRef sentence As FMExStreamSentence, fragments( ) As FMExStream ) As Boolean
Replaces the stream fragments in an existing FMExStreamSentence instance given an array of FMExStream objects. Returns False if an error is encountered. This function is overloaded to also accept a loose-list (ParamArray) of FMExStream objects.
Important: All the streams in the array must be valid (not Nil) and have the same frequency, bit depth, and number of channels. In other words, if the first stream is 44.1KHz/16bit Mono, the rest must also be 44.1KHz/16bit Mono. -
CreateStreamShared ( data As MemoryBlock, streambuffersize As Integer = 0 ) As FMExStream
-
CreateStreamShared ( ByRef stream As FMExStream, data As MemoryBlock, streambuffersize As Integer = 0 ) As Boolean
-
CreateSubMixer ( ignoreMaster As Boolean = False ) As FMExSubMixer
Returns a new FMExSubMixer instance, or Nil if an error is encountered. Normally sub-mixers are placed before the master mixer DSP chain (e.g. they are affected by FMEx.Volume, FMEx.Pitch, FMEx.Pause, and FMEx.Mute states). If the optional ignoreMaster parameter is set to True, the sub-mixer will act as a peer to the master mix, essentially creating a separate master output. -
CreateSubMixer ( ByRef mixer As FMExSubMixer, ignoreMaster As Boolean = False ) As Boolean
Refreshes the internal FMOD Ex handles in an existing FMExSubMixer instance (mostly only useful after restarting FMOD Ex). Returns False if an error is encountered. Normally sub-mixers are placed before the master mixer DSP chain (e.g. they are affected by FMEx.Volume, FMEx.Pitch, FMEx.Pause, and FMEx.Mute states). If the optional ignoreMaster parameter is set to True, the sub-mixer will act as a peer to the master mix, essentially creating a separate master output. -
GetActiveDriver As FMExDriver
Returns the current audio driver, or Nil if FMOD Ex is not currently active. -
GetActiveSettings As FMExConfig
Returns an FMExConfig instance describing the current FMOD Ex settings, or Nil if FMOD Ex is not currently active. -
GetDrivers ( outputtype As Integer = 0 ) As FMExDriver( )
Returns an array of available audio drivers for the system's default output type (default), or for the specified output type. This function can be called at any time, even prior to FMEx.StartUp to enumerate devices and determine hardware capabilities.
Output Type constants:- FMExConfig.kOutputTypeAuto
- FMExConfig.kOutputTypeLinuxALSA
- FMExConfig.kOutputTypeLinuxESD
- FMExConfig.kOutputTypeLinuxOSS
- FMExConfig.kOutputTypeMacCoreAudio
- FMExConfig.kOutputTypeMacSoundManager
- FMExConfig.kOutputTypeNoSound
- FMExConfig.kOutputTypeWindowsASIO
- FMExConfig.kOutputTypeWindowsDirectSound
- FMExConfig.kOutputTypeWindowsOpenAL
- FMExConfig.kOutputTypeWindowsWASAPI
- FMExConfig.kOutputTypeWindowsMultimedia
-
Level ( channeloffset As Integer ) As Double
Returns the volume level of the master mix for the given speaker index. Levels range from 0.0 to 1.0. channeloffset should be one of the constants listed below, or a number ranging from 0 to 15 inclusive when using the raw speaker mode. Note that the number of valid output channels depends on the current speaker mode and driver capabilities.
Channel Offset constants:- FMExConfig.kSpeakerIndexMono
- FMExConfig.kSpeakerIndexFrontLeft
- FMExConfig.kSpeakerIndexFrontRight
- FMExConfig.kSpeakerIndexLowFreqency
- FMExConfig.kSpeakerIndexFrontCenter
- FMExConfig.kSpeakerIndexBackLeft
- FMExConfig.kSpeakerIndexBackRight
- FMExConfig.kSpeakerIndexSideLeft
- FMExConfig.kSpeakerIndexSideRight
-
MemoryStats ( ByRef currentalloc As Integer, ByRef maxalloc As Integer )
Fills in currentalloc with the number of bytes currently allocated by FMOD Ex, and maxalloc with the maximum number of bytes allocated since the last successful FMEx.StartUp. -
Mute
Toggles the muted state of the master mix. -
OutputTypeAvailable ( type As Integer ) As Boolean
Returns True if the specified output type is available on the current system. This function can be called at any time, even prior to FMEx.StartUp to determine hardware capabilities.
Output Type constants:- FMExConfig.kOutputTypeAuto
- FMExConfig.kOutputTypeLinuxALSA
- FMExConfig.kOutputTypeLinuxESD
- FMExConfig.kOutputTypeLinuxOSS
- FMExConfig.kOutputTypeMacCoreAudio
- FMExConfig.kOutputTypeMacSoundManager
- FMExConfig.kOutputTypeNoSound
- FMExConfig.kOutputTypeWindowsASIO
- FMExConfig.kOutputTypeWindowsDirectSound
- FMExConfig.kOutputTypeWindowsOpenAL
- FMExConfig.kOutputTypeWindowsWASAPI
- FMExConfig.kOutputTypeWindowsMultimedia
-
Pause
Toggles the paused state of the master mix. -
ShutDown As Boolean
Shuts down FMOD Ex and returns True if successful. Call this before quitting (e.g. in App.Close) to ensure FMOD Ex cleans up after itself.
Important: All existing FMExAudio, FMExStream, FMExStreamSentence, and FMExSubMixer instances become invalidated after calling this method. Please see the Restarting FMOD Ex section for details on how to properly restart FMOD Ex should the need arise. -
StartUp ( settings As FMExConfig = Nil ) As Boolean
Initializes FMOD Ex and returns True if successful. The optional settings parameter can be used to request specific FMOD Ex start-up options. Please review the FMExConfig class documentation for available options.
Note: This function uses several fallbacks to conform to the recommended start-up procedure as described in the FMOD Ex SDK documentation. Use the FMEx.GetActiveSettings function to compare your requested settings with the actual successful settings. -
Update
This method must be called once every frame when using 3D audio, or if automatic channel virtualization is required. This is typically only required when using FMOD Ex's 3D audio features.