ufmod.oalufmod
μFMOD (OpenAL)

uFMOD is a tiny XM player library. It is currently available for Win32 and Linux. File and direct memory playback supported in both operating systems. Win32 library allows resource playback as well.

Win32 library supports the following drivers: WINMM, DirectX DirectSound and OpenAL. Avoid calling functions from different drivers in the same application. So, for example, if you desided to use the WINMM version, don't call DirectX DirectSound and/or OpenAL uFMOD functions in the same application.

It is recommended to read the documentation (available in the \Readme subfolder) for more information on using uFMOD and the included tools, recompiling the library from source code, optimization tips and so on.

In order to use OpenAL you need to first install the OpenAL redistributable package, available from the following locations: OpenAL official website, Mirror.

API Reference

Function uFMOD_OALPlayFile(filename:String,dwReserved,dwFlags,source)
DescriptionLoads the given XM song and starts playing it immediately, unless XM_SUSPENDED is specified. It will stop any currently playing song before loading the new one.
Parameters filename
A string that specifies the name of the file.
 
dwReserved
Reserved for possible future use; should be zero.
 
dwFlags
Additional flags, controlling the playback. The following values are defined:
XM_NOLOOP     An XM track plays repeatedly by default. Specify
              this flag to play it only once.
XM_SUSPENDED  The XM track is loaded in a suspended state,
              and will not play until the uFMOD_OALResume function
              is called. This is useful for preloading a song
              or testing an XM track for validity.
Set to zero, if not using any special flags.
 
source
An integer value identifying an OpenAL source.
ReturnsReturns 0 on error.
RemarksIf no valid song is specified and there is one currently being played, uFMOD_OALPlayFile just stops playback. So, you can call uFMOD_OALPlayFile(0, 0, 0, 0) instead of uFMOD_OALStop.

Once playback has started, it's not necessary to check for "buffer starvation", since uFMOD performs buffer recovering automatically.

Function uFMOD_OALPlayMem(pXM:Byte Ptr,length,dwFlags,source)
DescriptionLoads the XM song contained in the pXM memory buffer and starts playing it immediately, unless XM_SUSPENDED is specified. It will stop any currently playing song before loading the new one.
Parameters pXM
Points to an image of a song in memory.
 
length
Size of the image in bytes.
 
dwFlags
Additional flags, controlling the playback. The following values are defined:
XM_NOLOOP    An XM track plays repeatedly by default. Specify
             this flag to play it only once.
XM_SUSPENDED The XM track is loaded in a suspended state,
             and will not play until the uFMOD_OALResume function
             is called. This is useful for preloading a song
             or testing an XM track for validity.
Set to zero, if not using any special flags.
 
source
An integer value identifying an OpenAL source.
ReturnsReturns 0 on error.
RemarksIf no valid song is specified and there is one currently being played, uFMOD_OALPlayMem just stops playback. So, you can call uFMOD_OALPlayMem(0, 0, 0, 0) instead of uFMOD_OALStop.

Once playback has started, it's not necessary to check for "buffer starvation", since uFMOD performs buffer recovering automatically.

Function uFMOD_OALPlayRes(dwName,hModule,dwFlags,source)
DescriptionWin32 only!

Loads the given XM resource and starts playing it immediately, unless XM_SUSPENDED is specified. It will stop any currently playing song before loading the new one.
Parameters dwName
Specifies the ID of the XM resource. You can change this function's prototype to accept an ASCII null-terminated string, specifying the name of the resource.
 
hModule
Identifies the module whose executable file contains the resource. Could be 0 if the given resource is located in the current module.
 
dwFlags
Additional flags, controlling the playback. The following values are defined:
XM_NOLOOP    An XM track plays repeatedly by default. Specify
             this flag to play it only once.
XM_SUSPENDED The XM track is loaded in a suspended state,
             and will not play until the uFMOD_OALResume function
             is called. This is useful for preloading a song
             or testing an XM track for validity.
Set to zero, if not using any special flags.
 
source
An integer value identifying an OpenAL source.
ReturnsReturns 0 on error.
RemarksThe resource type must be RCDATA.

If no valid song is specified and there is one currently being played, uFMOD_OALPlayRes just stops playback. So, you can call uFMOD_OALPlayRes(0, 0, 0, 0) instead of uFMOD_OALStop.

Once playback has started, it's not necessary to check for "buffer starvation", since uFMOD performs buffer recovering automatically.

Function uFMOD_OALStop()
DescriptionStops the currently playing song, if any.

Function uFMOD_OALPause()
DescriptionPauses the currently playing song, if any.
RemarksWhile paused you can still control the volume (uFMOD_OALSetVolume) and the pattern order (uFMOD_OALJump2Pattern). The RMS volume coefficients (uFMOD_OALGetStats) will go down to 0 and the progress tracker (uFMOD_OALGetTime) will "freeze" while the song is paused.

uFMOD_OALPause doesn't perform the request immediately. Instead, it signals to pause when playback reaches next chunk of data, which may take up to about 40ms. This way, uFMOD_OALPause performs asynchronously and returns very fast. It is not cumulative. So, calling uFMOD_OALPause many times in a row has the same effect as calling it once.

If you need synchronous pause/resuming, you can use alSourcePause/alSourcePlay functions.

Function uFMOD_OALResume()
DescriptionResumes the currently paused song, if any.
RemarksuFMOD_OALResume doesn't perform the request immediately. Instead, it signals to resume when an internal thread gets a time slice, which may take some milliseconds to happen. Usually, calling delay 0 immediately after uFMOD_OALResume causes it to resume faster. uFMOD_OALResume is not cumulative. So, calling it many times in a row has the same effect as calling it once.

If you need synchronous pause/resuming, you can use alSourcePause/alSourcePlay functions.

Function uFMOD_OALGetStats()
DescriptionReturns the current RMS volume coefficients in (L)eft and (R)ight channels.
low-order word: RMS volume in R channel
hi-order word:  RMS volume in L channel
Range from 0 (silence) to $7FFF (maximum) on each channel.
RemarksThis function is useful for updating a VU meter. It's recommended to rescale the output to log10 (decibels or dB for short), because human ears track volume changes in a dB scale. You may call uFMOD_OALGetStats() as often as you like, but take in mind that uFMOD updates both channel RMS volumes every 20-40ms, depending on the output sampling rate. So, calling uFMOD_OALGetStats about 16 times a second whould be quite enough to track volume changes very closely.

Function uFMOD_OALGetRowOrder()
DescriptionReturns the currently playing row and order.
low-order word: row
hi-order word:  order
RemarksThis function is useful for synchronization. uFMOD updates both row and order values every 20-40ms, depending on the output sampling rate. So, calling uFMOD_OALGetRowOrder about 16 times a second whould be quite enough to track row and order progress very closely.

Function uFMOD_OALGetTime()
DescriptionReturns the time in milliseconds since the song was started.
RemarksThis function is useful for synchronizing purposes. In fact, it is more precise than a regular timer in Win32. Multimedia applications can use uFMOD_OALGetTime to synchronize GFX to sound, for example. An XM player can use this function to update a progress meter.
ExampleA simple way to pack an 'HH:MM:SS' progress meter:
Function HHMMSS$()
   Local iss:Int = uFMOD_OALGetTime() / 1000
   Local mm$ = (iss / 60)  Mod 60
   Local hh$ = (iss / 360) Mod 24
   Local ss$ = iss         Mod 60
   If Len ss$ = 1 ss$ = "0" + ss$
   If Len mm$ = 1 mm$ = "0" + mm$
   If Len hh$ = 1 hh$ = "0" + hh$
   Return hh$ + ":" + mm$ + ":" + ss$
EndFunction

Function uFMOD_OALGetTitle$()
DescriptionReturns the current song's title.
RemarksNot every song has a title, so be prepared to get an empty string. A proper way to handle such a situation is shown in the following example.
Example
   title$ = Trim(uFMOD_OALGetTitle())
   If Len title$ = 0 title$ = "This song has no title"

Function uFMOD_OALSetVolume(vol)
DescriptionSets the global volume. The volume scale is linear.
Parameters vol
New volume. Range: from uFMOD_MIN_VOL (muting) to uFMOD_MAX_VOL (maximum volume). Any value above uFMOD_MAX_VOL maps to maximum volume.
RemarksuFMOD internally converts the given values to a logarithmic scale (dB).

Maximum volume is set by default. The volume value is preserved across uFMOD_OALPlay* calls. You can set the desired volume level before actually starting to play a song.

You can use OpenAL alSourcef(source, AL_GAIN, gain) function to control the volume in a floating point scale.
ExampleA simple fading effect:
   For i = 20 To 0 Step -4
      uFMOD_OALSetVolume(i)
      Delay 20
   Next

Function uFMOD_OALJump2Pattern(pat)
DescriptionJumps to the specified pattern index.
Parameters pat
Next zero based pattern index.
RemarksuFMOD doesn't automatically perform Note Off effects before jumping to the target pattern. In other words, the original pattern will remain in the mixer until it fades out. You can use this feature to your advantage. If you don't like it, just insert leading Note Off commands in all patterns intended to be used as uFMOD_OALJump2Pattern targets.

if the pattern index lays outside of the bounds of the pattern order table, calling this function jumps to pattern 0, effectively rewinding playback.

You can implement uFMOD_OALRewind as a call to uFMOD_OALJump2Pattern(0).

 
© 2005 - 2007 Asterix and Quantum.
All rights reserved.