Subversion Repositories Kolibri OS

;  uFMOD API reference (NORMAL/UNSAFE mode)

;  ====================================================================

; NOTE: All functions follow the cdecl calling convention!

;    _uFMOD_LoadSong

;    _uFMOD_WaveOut

;    _uFMOD_StopSong

;    _uFMOD_Jump2Pattern

;    _uFMOD_Pause

;    _uFMOD_Resume

;    _uFMOD_GetStats

;    _uFMOD_GetRowOrder

;    _uFMOD_GetTime

;    _uFMOD_GetTitle

;    _uFMOD_SetVolume

;  ====================================================================

;  HANDLE _uFMOD_LoadSong(

;     void *lpXM,

;     void *param,

;     int fdwSong

;  )

;  ---

;  Description:

;  ---

;     Loads the given XM song and starts playing it as soon as you

;     call _uFMOD_WaveOut for the first time. Playback won't begin

;     if XM_SUSPENDED flag is specified. It will stop any currently

;     playing song before loading the new one.

;  ---

;  Parameters:

;  ---

;    lpXM

;       Specifies the song to load. If this parameter is 0, any

;       currently playing song is stopped. In such a case, function

;       does not return a meaningful value. fdwSong parameter

;       determines whether this value is interpreted as a filename

;       or as a pointer to an image of the song in memory.

;    param

;       If XM_MEMORY is specified, this parameter should be the size

;       of the image of the song in memory.

;       If XM_FILE is specified, this parameter is ignored.

;    fdwSong

;       Flags for playing the song. The following values are defined:

;       XM_FILE      lpXM points to filename. param is ignored.

;       XM_MEMORY    lpXM points to an image of a song in memory.

;                    param is the image size. Once, _uFMOD_LoadSong

;                    returns, it's safe to free/discard the memory

;                    buffer.

;       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_Resume function

;                    is called. This is useful for preloading a song

;                    or testing an XM track for validity.

;  ---

;  Return Values:

;  ---

;     On success, returns the handle of the Infinity Sound driver.

;     Returns 0 on failure.

;  ====================================================================

;  int _uFMOD_WaveOut(void)

;  ---

;  Description:

;  ---

;     Updates the internal playback buffer.

;  ---

;  Remarks:

;  ---

;     This function should be called from the same thread

;     _uFMOD_LoadSong was previously called. Playback doesn't actually

;     begin when calling _uFMOD_LoadSong, but when calling _uFMOD_WaveOut

;     after a successful _uFMOD_LoadSong call. Afterwards, you should

;     call _uFMOD_WaveOut repeatedly at least once every 250 ms to

;     prevent "buffer underruns".

;     _uFMOD_WaveOut is a non-blocking function. The accuracy of the

;     InfoAPI functions (_uFMOD_GetStats, _uFMOD_GetRowOrder and

;     _uFMOD_GetTime) depends on the periodicity of this function being

;     invoked.

;  ---

;  Return Values:

;  ---

;     Returns non zero on error.

;  ====================================================================

;  void _uFMOD_StopSong(void)

;  ---

;  Description:

;  ---

;     Stops the currently playing song, freeing the associated

;     resources.

;  ---

;  Remarks:

;  ---

;     Does nothing if no song is playing at the time the call is made.

;  ====================================================================

;  void _uFMOD_Jump2Pattern(

;     unsigned int 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_Jump2Pattern

;     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.

;  ====================================================================

;  void _uFMOD_Pause(void)

;  ---

;  Description:

;  ---

;     Pauses the currently playing song, if any.

;  ---

;  Remarks:

;  ---

;     While paused you can still control the volume (_uFMOD_SetVolume) and

;     the pattern order (_uFMOD_Jump2Pattern). The RMS volume coefficients

;     (_uFMOD_GetStats) will go down to 0 and the progress tracker

;     (_uFMOD_GetTime) will "freeze" while the song is paused.

;     _uFMOD_Pause doesn't perform the request immediately. Instead, it

;     signals to pause when playback reaches next chunk of data.

;     This way, _uFMOD_Pause performs asynchronously and returns very fast.

;     It is not cumulative. So, calling _uFMOD_Pause many times in a row

;     has the same effect as calling it once.

;     You shouldn't stop calling _uFMOD_WaveOut while the song is paused!

;  ====================================================================

;  void _uFMOD_Resume(void)

;  ---

;  Description:

;  ---

;     Resumes the currently paused song, if any.

;  ---

;  Remarks:

;  ---

;     _uFMOD_Resume doesn't perform the request immediately. Instead, it

;     signals to resume when _uFMOD_WaveOut is called again. _uFMOD_Resume

;     is not cumulative. So, calling it many times in a row has the same

;     effect as calling it once.

;  ====================================================================

;  unsigned int _uFMOD_GetStats(void)

;  ---

;  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 channel

;     Range 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_GetStats() as often as you like, but take in mind that uFMOD

;     updates both channel RMS volumes at the same rate _uFMOD_WaveOut

;     function is called. In other words, you should call _uFMOD_WaveOut

;     more often to increase the accuracy of _uFMOD_GetStats.

;  ====================================================================

;  unsigned int _uFMOD_GetRowOrder(void)

;  ---

;  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 at the same rate _uFMOD_WaveOut function is

;     called. In other words, you should call _uFMOD_WaveOut more often

;     to increase the accuracy of _uFMOD_GetRowOrder.

;  ====================================================================

;  unsigned int _uFMOD_GetTime(void)

;  ---

;  Description:

;  ---

;     Returns the time in milliseconds since the song was started.

;  ---

;  Remarks:

;  ---

;     This function is useful for synchronizing purposes. Multimedia

;     applications can use _uFMOD_GetTime to synchronize GFX to sound,

;     for example. An XM player can use this function to update a progress

;     meter.

;  ====================================================================

;  unsigned char* _uFMOD_GetTitle(void)

;  ---

;  Description:

;  ---

;     Returns the current song's title.

;  ---

;  Remarks:

;  ---

;     Not every song has a title, so be prepared to get an empty string.

;  ====================================================================

;  void _uFMOD_SetVolume(

;     unsigned int 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_LoadSong calls. You can set the desired volume level before

;     actually starting to play a song.

;     You can use Infinity Sound API to control the L and R channels volumes

;     separately. It also has a wider range than _uFMOD_SetVolume, sometimes

;     allowing to amplify the sound volume as well, as opposed to

;     _uFMOD_SetVolume only being able to attenuate it.

XM_MEMORY         equ 1

XM_FILE           equ 2

XM_NOLOOP         equ 8

XM_SUSPENDED      equ 16

uFMOD_MIN_VOL     equ 0

uFMOD_MAX_VOL     equ 25

uFMOD_DEFAULT_VOL equ 25