Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
1845 | yogev_ezra | 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 |