Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. ;  uFMOD API reference (NORMAL/UNSAFE mode)
  2. ;  ====================================================================
  3.  
  4. ; NOTE: All functions follow the cdecl calling convention!
  5. ;    _uFMOD_LoadSong
  6. ;    _uFMOD_WaveOut
  7. ;    _uFMOD_StopSong
  8. ;    _uFMOD_Jump2Pattern
  9. ;    _uFMOD_Pause
  10. ;    _uFMOD_Resume
  11. ;    _uFMOD_GetStats
  12. ;    _uFMOD_GetRowOrder
  13. ;    _uFMOD_GetTime
  14. ;    _uFMOD_GetTitle
  15. ;    _uFMOD_SetVolume
  16.  
  17. ;  ====================================================================
  18. ;  HANDLE _uFMOD_LoadSong(
  19. ;     void *lpXM,
  20. ;     void *param,
  21. ;     int fdwSong
  22. ;  )
  23. ;  ---
  24. ;  Description:
  25. ;  ---
  26. ;     Loads the given XM song and starts playing it as soon as you
  27. ;     call _uFMOD_WaveOut for the first time. Playback won't begin
  28. ;     if XM_SUSPENDED flag is specified. It will stop any currently
  29. ;     playing song before loading the new one.
  30. ;  ---
  31. ;  Parameters:
  32. ;  ---
  33. ;    lpXM
  34. ;       Specifies the song to load. If this parameter is 0, any
  35. ;       currently playing song is stopped. In such a case, function
  36. ;       does not return a meaningful value. fdwSong parameter
  37. ;       determines whether this value is interpreted as a filename
  38. ;       or as a pointer to an image of the song in memory.
  39. ;    param
  40. ;       If XM_MEMORY is specified, this parameter should be the size
  41. ;       of the image of the song in memory.
  42. ;       If XM_FILE is specified, this parameter is ignored.
  43. ;    fdwSong
  44. ;       Flags for playing the song. The following values are defined:
  45. ;       XM_FILE      lpXM points to filename. param is ignored.
  46. ;       XM_MEMORY    lpXM points to an image of a song in memory.
  47. ;                    param is the image size. Once, _uFMOD_LoadSong
  48. ;                    returns, it's safe to free/discard the memory
  49. ;                    buffer.
  50. ;       XM_NOLOOP    An XM track plays repeatedly by default. Specify
  51. ;                    this flag to play it only once.
  52. ;       XM_SUSPENDED The XM track is loaded in a suspended state,
  53. ;                    and will not play until the _uFMOD_Resume function
  54. ;                    is called. This is useful for preloading a song
  55. ;                    or testing an XM track for validity.
  56. ;  ---
  57. ;  Return Values:
  58. ;  ---
  59. ;     On success, returns the handle of the Infinity Sound driver.
  60. ;     Returns 0 on failure.
  61.  
  62. ;  ====================================================================
  63. ;  int _uFMOD_WaveOut(void)
  64. ;  ---
  65. ;  Description:
  66. ;  ---
  67. ;     Updates the internal playback buffer.
  68. ;  ---
  69. ;  Remarks:
  70. ;  ---
  71. ;     This function should be called from the same thread
  72. ;     _uFMOD_LoadSong was previously called. Playback doesn't actually
  73. ;     begin when calling _uFMOD_LoadSong, but when calling _uFMOD_WaveOut
  74. ;     after a successful _uFMOD_LoadSong call. Afterwards, you should
  75. ;     call _uFMOD_WaveOut repeatedly at least once every 250 ms to
  76. ;     prevent "buffer underruns".
  77. ;     _uFMOD_WaveOut is a non-blocking function. The accuracy of the
  78. ;     InfoAPI functions (_uFMOD_GetStats, _uFMOD_GetRowOrder and
  79. ;     _uFMOD_GetTime) depends on the periodicity of this function being
  80. ;     invoked.
  81. ;  ---
  82. ;  Return Values:
  83. ;  ---
  84. ;     Returns non zero on error.
  85.  
  86. ;  ====================================================================
  87. ;  void _uFMOD_StopSong(void)
  88. ;  ---
  89. ;  Description:
  90. ;  ---
  91. ;     Stops the currently playing song, freeing the associated
  92. ;     resources.
  93. ;  ---
  94. ;  Remarks:
  95. ;  ---
  96. ;     Does nothing if no song is playing at the time the call is made.
  97.  
  98. ;  ====================================================================
  99. ;  void _uFMOD_Jump2Pattern(
  100. ;     unsigned int pat
  101. ;  )
  102. ;  ---
  103. ;  Description:
  104. ;  ---
  105. ;     Jumps to the specified pattern index.
  106. ;  ---
  107. ;  Parameters:
  108. ;  ---
  109. ;     pat
  110. ;        Next zero based pattern index.
  111. ;  ---
  112. ;  Remarks:
  113. ;  ---
  114. ;     uFMOD doesn't automatically perform Note Off effects before jumping
  115. ;     to the target pattern. In other words, the original pattern will
  116. ;     remain in the mixer until it fades out. You can use this feature to
  117. ;     your advantage. If you don't like it, just insert leading Note Off
  118. ;     commands in all patterns intended to be used as _uFMOD_Jump2Pattern
  119. ;     targets.
  120. ;     if the pattern index lays outside of the bounds of the pattern order
  121. ;     table, calling this function jumps to pattern 0, effectively
  122. ;     rewinding playback.
  123.  
  124. ;  ====================================================================
  125. ;  void _uFMOD_Pause(void)
  126. ;  ---
  127. ;  Description:
  128. ;  ---
  129. ;     Pauses the currently playing song, if any.
  130. ;  ---
  131. ;  Remarks:
  132. ;  ---
  133. ;     While paused you can still control the volume (_uFMOD_SetVolume) and
  134. ;     the pattern order (_uFMOD_Jump2Pattern). The RMS volume coefficients
  135. ;     (_uFMOD_GetStats) will go down to 0 and the progress tracker
  136. ;     (_uFMOD_GetTime) will "freeze" while the song is paused.
  137. ;     _uFMOD_Pause doesn't perform the request immediately. Instead, it
  138. ;     signals to pause when playback reaches next chunk of data.
  139. ;     This way, _uFMOD_Pause performs asynchronously and returns very fast.
  140. ;     It is not cumulative. So, calling _uFMOD_Pause many times in a row
  141. ;     has the same effect as calling it once.
  142. ;     You shouldn't stop calling _uFMOD_WaveOut while the song is paused!
  143.  
  144. ;  ====================================================================
  145. ;  void _uFMOD_Resume(void)
  146. ;  ---
  147. ;  Description:
  148. ;  ---
  149. ;     Resumes the currently paused song, if any.
  150. ;  ---
  151. ;  Remarks:
  152. ;  ---
  153. ;     _uFMOD_Resume doesn't perform the request immediately. Instead, it
  154. ;     signals to resume when _uFMOD_WaveOut is called again. _uFMOD_Resume
  155. ;     is not cumulative. So, calling it many times in a row has the same
  156. ;     effect as calling it once.
  157.  
  158. ;  ====================================================================
  159. ;  unsigned int _uFMOD_GetStats(void)
  160. ;  ---
  161. ;  Description:
  162. ;  ---
  163. ;     Returns the current RMS volume coefficients in (L)eft and (R)ight
  164. ;     channels.
  165. ;        low-order word: RMS volume in R channel
  166. ;        hi-order word:  RMS volume in L channel
  167. ;     Range from 0 (silence) to $7FFF (maximum) on each channel.
  168. ;  ---
  169. ;  Remarks:
  170. ;  ---
  171. ;     This function is useful for updating a VU meter. It's recommended
  172. ;     to rescale the output to log10 (decibels or dB for short), because
  173. ;     human ears track volume changes in a dB scale. You may call
  174. ;     _uFMOD_GetStats() as often as you like, but take in mind that uFMOD
  175. ;     updates both channel RMS volumes at the same rate _uFMOD_WaveOut
  176. ;     function is called. In other words, you should call _uFMOD_WaveOut
  177. ;     more often to increase the accuracy of _uFMOD_GetStats.
  178.  
  179. ;  ====================================================================
  180. ;  unsigned int _uFMOD_GetRowOrder(void)
  181. ;  ---
  182. ;  Description:
  183. ;  ---
  184. ;     Returns the currently playing row and order.
  185. ;        low-order word: row
  186. ;        hi-order word:  order
  187. ;  ---
  188. ;  Remarks:
  189. ;  ---
  190. ;     This function is useful for synchronization. uFMOD updates both
  191. ;     row and order values at the same rate _uFMOD_WaveOut function is
  192. ;     called. In other words, you should call _uFMOD_WaveOut more often
  193. ;     to increase the accuracy of _uFMOD_GetRowOrder.
  194.  
  195. ;  ====================================================================
  196. ;  unsigned int _uFMOD_GetTime(void)
  197. ;  ---
  198. ;  Description:
  199. ;  ---
  200. ;     Returns the time in milliseconds since the song was started.
  201. ;  ---
  202. ;  Remarks:
  203. ;  ---
  204. ;     This function is useful for synchronizing purposes. Multimedia
  205. ;     applications can use _uFMOD_GetTime to synchronize GFX to sound,
  206. ;     for example. An XM player can use this function to update a progress
  207. ;     meter.
  208.  
  209. ;  ====================================================================
  210. ;  unsigned char* _uFMOD_GetTitle(void)
  211. ;  ---
  212. ;  Description:
  213. ;  ---
  214. ;     Returns the current song's title.
  215. ;  ---
  216. ;  Remarks:
  217. ;  ---
  218. ;     Not every song has a title, so be prepared to get an empty string.
  219.  
  220. ;  ====================================================================
  221. ;  void _uFMOD_SetVolume(
  222. ;     unsigned int vol
  223. ;  )
  224. ;  ---
  225. ;  Description:
  226. ;  ---
  227. ;     Sets the global volume. The volume scale is linear.
  228. ;  ---
  229. ;  Parameters:
  230. ;  ---
  231. ;     vol
  232. ;        New volume. Range: from uFMOD_MIN_VOL (muting) to uFMOD_MAX_VOL
  233. ;        (maximum volume). Any value above uFMOD_MAX_VOL maps to maximum
  234. ;        volume.
  235. ;  ---
  236. ;  Remarks:
  237. ;  ---
  238. ;     uFMOD internally converts the given values to a logarithmic scale (dB).
  239. ;     Maximum volume is set by default. The volume value is preserved across
  240. ;     _uFMOD_LoadSong calls. You can set the desired volume level before
  241. ;     actually starting to play a song.
  242. ;     You can use Infinity Sound API to control the L and R channels volumes
  243. ;     separately. It also has a wider range than _uFMOD_SetVolume, sometimes
  244. ;     allowing to amplify the sound volume as well, as opposed to
  245. ;     _uFMOD_SetVolume only being able to attenuate it.
  246.  
  247. XM_MEMORY         equ 1
  248. XM_FILE           equ 2
  249. XM_NOLOOP         equ 8
  250. XM_SUSPENDED      equ 16
  251. uFMOD_MIN_VOL     equ 0
  252. uFMOD_MAX_VOL     equ 25
  253. uFMOD_DEFAULT_VOL equ 25
  254.