| Function uFMOD_DSPlayFile(filename:String,dwReserved,dwFlags,pDSBuffer:IDirectSoundBuffer) | |
| Description | Loads 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_DSResume 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.pDSBuffer A pointer to an IDirectSoundBuffer. uFMOD assumes that it has been properly initialized to 16-bit stereo. |
| Returns | Returns a positive value on success or -1 otherwise. The return value can be handled as a COM HRESULT. |
| Remarks | If no valid song is specified and there is one currently being played, uFMOD_DSPlayFile just stops playback. So, you can call uFMOD_DSPlayFile(0, 0, 0, 0) instead of uFMOD_DSStop. Once playback has started, it's not necessary to check for "buffer lost" condition, since uFMOD performs buffer restoring automatically. |
| Function uFMOD_DSPlayMem(pXM:Byte Ptr,length,dwFlags,pDSBuffer:IDirectSoundBuffer) | |
| Description | Loads 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_DSResume 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.pDSBuffer A pointer to an IDirectSoundBuffer. uFMOD assumes that it has been properly initialized to 16-bit stereo. |
| Returns | Returns a positive value on success or -1 otherwise. The return value can be handled as a COM HRESULT. |
| Remarks | If no valid song is specified and there is one currently being played, uFMOD_DSPlayMem just stops playback. So, you can call uFMOD_DSPlayMem(0, 0, 0, 0) instead of uFMOD_DSStop. Once playback has started, it's not necessary to check for "buffer lost" condition, since uFMOD performs buffer restoring automatically. |
| Function uFMOD_DSPlayRes(dwName,hModule,dwFlags,pDSBuffer:IDirectSoundBuffer) | |
| Description | 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_DSResume 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.pDSBuffer A pointer to an IDirectSoundBuffer. uFMOD assumes that it has been properly initialized to 16-bit stereo. |
| Returns | Returns a positive value on success or -1 otherwise. The return value can be handled as a COM HRESULT. |
| Remarks | The resource type must be RCDATA. If no valid song is specified and there is one currently being played, uFMOD_DSPlayRes just stops playback. So, you can call uFMOD_DSPlayRes(0, 0, 0, 0) instead of uFMOD_DSStop. Once playback has started, it's not necessary to check for "buffer lost" condition, since uFMOD performs buffer restoring automatically. |
| Function uFMOD_DSStop() | |
| Description | Stops the currently playing song, if any. |
| Function uFMOD_DSPause() | |
| Description | Pauses the currently playing song, if any. |
| Remarks | While paused you can still control the volume (uFMOD_DSSetVolume) and the pattern order (uFMOD_DSJump2Pattern). The RMS volume coefficients (uFMOD_DSGetStats) will go down to 0 and the progress tracker (uFMOD_DSGetTime) will "freeze" while the song is paused. uFMOD_DSPause 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_DSPause performs asynchronously and returns very fast. It is not cumulative. So, calling uFMOD_DSPause many times in a row has the same effect as calling it once. If you need synchronous pause/resuming, you can use IDirectSoundBuffer::Stop/Play functions. |
| Function uFMOD_DSResume() | |
| Description | Resumes the currently paused song, if any. |
| Remarks | uFMOD_DSResume 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_DSResume causes it to resume faster. uFMOD_DSResume 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 IDirectSoundBuffer::Stop/Play functions. |
| Function uFMOD_DSGetStats() | |
| Description | Returns 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 channelRange from 0 (silence) to $7FFF (maximum) on each channel. |
| Remarks | This 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_DSGetStats() 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_DSGetStats about 16 times a second whould be quite enough to track volume changes very closely. |
| Function uFMOD_DSGetRowOrder() | |
| Description | Returns the currently playing row and order.low-order word: row hi-order word: order |
| Remarks | This function is useful for synchronization. uFMOD updates both row and order values every 20-40ms, depending on the output sampling rate. So, calling uFMOD_DSGetRowOrder about 16 times a second whould be quite enough to track row and order progress very closely. |
| Function uFMOD_DSGetTime() | |
| Description | Returns the time in milliseconds since the song was started. |
| Remarks | This function is useful for synchronizing purposes. In fact, it is more precise than a regular timer in Win32. Multimedia applications can use uFMOD_DSGetTime to synchronize GFX to sound, for example. An XM player can use this function to update a progress meter. |
| Example | A simple way to pack an 'HH:MM:SS' progress meter:Function HHMMSS$() Local iss:Int = uFMOD_DSGetTime() / 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_DSGetTitle$() | |
| Description | Returns the current song's title. |
| Remarks | Not 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_DSGetTitle()) If Len title$ = 0 title$ = "This song has no title" |
| Function uFMOD_DSSetVolume(vol) | |
| Description | Sets 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. |
| Remarks | uFMOD internally converts the given values to a logarithmic scale (dB). Maximum volume is set by default. The volume value is preserved across uFMOD_DSPlay* calls. You can set the desired volume level before actually starting to play a song. You can use DirectSound and KMixer functions directly to control the L and R channels volumes separately. KMixer also has a wider range than uFMOD_DSSetVolume, sometimes allowing to amplify the sound volume as well, as opposed to uFMOD_DSSetVolume only being able to attenuate it. The bad things about KMixer is that it may produce clicks and is hardware dependent. |
| Example | A simple fading effect:
For i = 20 To 0 Step -4
uFMOD_DSSetVolume(i)
Delay 20
Next
|
| Function uFMOD_DSJump2Pattern(pat) | |
| Description | Jumps to the specified pattern index. |
| Parameters |
pat Next zero based pattern index. |
| Remarks | uFMOD 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_DSJump2Pattern 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_DSRewind as a call to uFMOD_DSJump2Pattern(0). |