forked from KolibriOS/kolibrios
254 lines
9.1 KiB
HTML
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
|