kolibrios/programs/develop/libraries/ufmod/ufmod.inc
Yogev Ezra d21a6e85e7 Added libraries/ufmod source code.
git-svn-id: svn://kolibrios.org@1845 a494cfbc-eb01-0410-851d-a64ba20cac60
2011-02-04 20:13:33 +00:00

254 lines
9.1 KiB
HTML

; 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