diff options
author | Michiel Van Der Kolk <not.valid@email.address> | 2005-03-17 20:50:03 +0000 |
---|---|---|
committer | Michiel Van Der Kolk <not.valid@email.address> | 2005-03-17 20:50:03 +0000 |
commit | 27be5bc72855a0fbbdae230bc144624c9eb85f5e (patch) | |
tree | b553f1321df924c4b744ffcab48dce5f4f081f7d /apps/codecs/dumb/docs/dumb.txt | |
parent | 7e7662bb716917ca431204f0113d400c1014f2e8 (diff) | |
download | rockbox-27be5bc72855a0fbbdae230bc144624c9eb85f5e.tar.gz rockbox-27be5bc72855a0fbbdae230bc144624c9eb85f5e.zip |
Initial check in dumb 0.9.2 - has a few usages of floating point that should
be rewritten to fixed point. seems to compile cleanly for iriver.
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@6197 a1c6a512-1295-4272-9138-f99709370657
Diffstat (limited to 'apps/codecs/dumb/docs/dumb.txt')
-rw-r--r-- | apps/codecs/dumb/docs/dumb.txt | 1699 |
1 files changed, 1699 insertions, 0 deletions
diff --git a/apps/codecs/dumb/docs/dumb.txt b/apps/codecs/dumb/docs/dumb.txt new file mode 100644 index 0000000000..86b2cc3374 --- /dev/null +++ b/apps/codecs/dumb/docs/dumb.txt | |||
@@ -0,0 +1,1699 @@ | |||
1 | /* _______ ____ __ ___ ___ | ||
2 | * \ _ \ \ / \ / \ \ / / ' ' ' | ||
3 | * | | \ \ | | || | \/ | . . | ||
4 | * | | | | | | || ||\ /| | | ||
5 | * | | | | | | || || \/ | | ' ' ' | ||
6 | * | | | | | | || || | | . . | ||
7 | * | |_/ / \ \__// || | | | ||
8 | * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque | ||
9 | * / \ | ||
10 | * / . \ | ||
11 | * dumb.txt - DUMB library reference. / / \ \ | ||
12 | * | < / \_ | ||
13 | * See readme.txt for general information on | \/ /\ / | ||
14 | * DUMB and how to set it up. \_ / > / | ||
15 | * | \ / / | ||
16 | * If you are new to DUMB, see howto.txt. | ' / | ||
17 | * \__/ | ||
18 | */ | ||
19 | |||
20 | |||
21 | *********************************** | ||
22 | *** Include Files and Libraries *** | ||
23 | *********************************** | ||
24 | |||
25 | |||
26 | dumb.h | ||
27 | |||
28 | Include this if you only want the core DUMB library functions. You will | ||
29 | be able to load music files and render them into memory buffers at your | ||
30 | own pace. The core library is completely portable, and as such does not | ||
31 | access hardware; you must relay the sound data to the sound card yourself. | ||
32 | A stdio file input module is available, but you must actively register it | ||
33 | if you wish to use it (see dumb_register_stdfiles()); if you do not | ||
34 | register it, it will not be linked into your executable. You must register | ||
35 | it, or a DUMBFILE module of your own, in order to load stand-alone music | ||
36 | files. | ||
37 | |||
38 | Optimised: -ldumb or /link dumb.lib | ||
39 | Debugging: -ldumbd or /link dumbd.lib | ||
40 | |||
41 | |||
42 | aldumb.h | ||
43 | |||
44 | Include this if you wish to use DUMB with Allegro. This will provide you | ||
45 | with functions to play DUHs back through Allegro's audio streams and embed | ||
46 | music files in Allegro datafiles. A file input module using Allegro's | ||
47 | packfiles is provided; you have a choice between this and the stdio | ||
48 | module (or provide one of your own). You will be able to load datafiles | ||
49 | containing music files no matter which file input module you register, or | ||
50 | even if you register no file input module. However, you must register a | ||
51 | file input module in order to load stand-alone files. | ||
52 | |||
53 | Optimised: -laldmb -ldumb -lalleg or /link aldmb.lib alleg.lib dumb.lib | ||
54 | Debugging: -laldmd -ldumbd -lalld or /link aldmd.lib alld.lib dumbd.lib | ||
55 | |||
56 | aldmb or aldmd must be linked in first, so the symbols can be resolved | ||
57 | when linking in the other two libraries. | ||
58 | |||
59 | |||
60 | *************************** | ||
61 | *** Version Information *** | ||
62 | *************************** | ||
63 | |||
64 | |||
65 | #define DUMB_MAJOR_VERSION | ||
66 | #define DUMB_MINOR_VERSION | ||
67 | #define DUMB_REVISION_VERSION | ||
68 | |||
69 | Numeric constants representing this version of DUMB. If this were version | ||
70 | 1.0, DUMB_MAJOR_VERSION would be 1 and DUMB_MINOR_VERSION would be 0. | ||
71 | DUMB_REVISION_VERSION will be 0 on any significant releases, and will be | ||
72 | incremented as releases with bugfixes and minor features are made. | ||
73 | |||
74 | Typical usage: | ||
75 | |||
76 | #if DUMB_MAJOR_VERSION < 1 | ||
77 | #error This add-on requires DUMB v1.0 or higher. Please upgrade. | ||
78 | #endif | ||
79 | |||
80 | |||
81 | #define DUMB_VERSION | ||
82 | |||
83 | A numeric constant which appears in the format MMmmrr when displayed in | ||
84 | decimal (M for major, m for minor, r for revision). This is most useful | ||
85 | for comparing version numbers; it has little other practical use. | ||
86 | |||
87 | Typical usage: | ||
88 | |||
89 | #if DUMB_VERSION < 801 | ||
90 | #error This game requires DUMB v0.8.1 or higher. Please upgrade. | ||
91 | #endif | ||
92 | |||
93 | #if DUMB_VERSION < 10002 | ||
94 | #error This game requires DUMB v1.0.2 or higher. Please upgrade. | ||
95 | #endif | ||
96 | |||
97 | |||
98 | #define DUMB_VERSION_STR | ||
99 | |||
100 | String constant representing this version of DUMB. If this were Version | ||
101 | 1.0, DUMB_VERSION_STR would be "1.0". DUMB_REVISION_VERSION will only | ||
102 | appear on the end if it is nonzero; then DUMB_VERSION_STR might be | ||
103 | "1.0.1". | ||
104 | |||
105 | |||
106 | #define DUMB_NAME | ||
107 | |||
108 | A string identifying DUMB and its version. If this were Version 1.0, | ||
109 | DUMB_NAME might be "DUMB v1.0". This constant is suitable for use in your | ||
110 | Credits screen if you wish to acknowledge the use of DUMB there. | ||
111 | |||
112 | |||
113 | #define DUMB_YEAR | ||
114 | #define DUMB_MONTH | ||
115 | #define DUMB_DAY | ||
116 | |||
117 | Numeric constants representing the year, month and day of this release of | ||
118 | DUMB. All four digits are included in the year. Please note that | ||
119 | DUMB_MONTH and DUMB_DAY were inadvertently swapped in the v0.8 release. | ||
120 | |||
121 | |||
122 | #define DUMB_YEAR_STR4 | ||
123 | #define DUMB_YEAR_STR2 | ||
124 | #define DUMB_MONTH_STR2 | ||
125 | #define DUMB_MONTH_STR1 | ||
126 | #define DUMB_DAY_STR2 | ||
127 | #define DUMB_DAY_STR1 | ||
128 | |||
129 | String constants representing the year, month and day of this release of | ||
130 | DUMB. DUMB_MONTH_STR2 and DUMB_DAY_STR2 include a leading zero if the | ||
131 | month or day respectively are less than ten; the STR1 variations do not. | ||
132 | DUMB_YEAR_STR2 contains only the two rightmost digits of the year, while | ||
133 | DUMB_YEAR_STR4 contains all four. I recommend using DUMB_YEAR_STR4, | ||
134 | especially so soon after the turn of the century (indeed the millennium). | ||
135 | However, it is a matter of personal preference which you use. | ||
136 | |||
137 | Please note that the month and day were inadvertently swapped in the v0.8 | ||
138 | release. | ||
139 | |||
140 | |||
141 | #define DUMB_DATE | ||
142 | |||
143 | A numeric constant that appears in the form yyyymmdd when displayed in | ||
144 | decimal. This is most useful for comparing release dates; it has little | ||
145 | other practical use. | ||
146 | |||
147 | WARNING: The month and day were inadvertently swapped in the v0.8 release. | ||
148 | Please do not compare this constant against any date in 2002. In | ||
149 | any case, DUMB_VERSION is probably more useful for this purpose. | ||
150 | |||
151 | |||
152 | #define DUMB_DATE_STR | ||
153 | |||
154 | The date as a string. The format is "d.m.yyyy", with dots used as | ||
155 | separators, the day written first, four digits for the year, and no | ||
156 | leading zeros on the day or month. This is my preferred format. If you | ||
157 | don't like it, you can construct your own format using the other | ||
158 | constants. For example, "mm/dd/yy" could be constructed as follows: | ||
159 | |||
160 | DUMB_MONTH_STR2 "/" DUMB_DAY_STR2 "/" DUMB_YEAR_STR2 | ||
161 | |||
162 | Please note that the month and day were inadvertently swapped in the v0.8 | ||
163 | release. | ||
164 | |||
165 | |||
166 | ************************* | ||
167 | *** Basic Sample Type *** | ||
168 | ************************* | ||
169 | |||
170 | |||
171 | typedef int sample_t; | ||
172 | |||
173 | DUMB works internally with 32-bit integer samples, with a 'normal range' | ||
174 | from -0x800000 to 0x7FFFFF (as of DUMB v0.9.2; previously they ranged from | ||
175 | -0x8000 to 0x7FFF). Any samples that exceed this range will eventually be | ||
176 | clipped, and could cause integer overflow in extreme cases. | ||
177 | |||
178 | |||
179 | *********************************** | ||
180 | *** Library Clean-up Management *** | ||
181 | *********************************** | ||
182 | |||
183 | |||
184 | int dumb_atexit(void (*proc)(void)); | ||
185 | |||
186 | Registers a function to be called at the end of your program. You can | ||
187 | register multiple functions to be called, and the one you register last | ||
188 | will be called first. If you try to register the same function twice, the | ||
189 | second attempt will have no effect. | ||
190 | |||
191 | See fnptr.txt for help with function pointers. | ||
192 | |||
193 | You must call dumb_exit() before exiting your program for this to work | ||
194 | properly. The library itself registers functions with dumb_atexit(), so it | ||
195 | is important to call dumb_exit() even if you do not use dumb_atexit() | ||
196 | yourself. | ||
197 | |||
198 | This function will return zero on success. It will return zero when | ||
199 | trying to install the same function twice. If it fails through lack of | ||
200 | memory, it will return nonzero. Generally you can ignore the return code; | ||
201 | in the worst case some memory will not be freed at the end. If it is | ||
202 | crucial that your function be called (e.g. to shut down some hardware or | ||
203 | save critical data), then you should call your function manually at the | ||
204 | end of the program instead of registering it here - or use the stdlib | ||
205 | function atexit(), guaranteed under ANSI C to succeed for at least 32 | ||
206 | functions. | ||
207 | |||
208 | |||
209 | void dumb_exit(void); | ||
210 | |||
211 | You should call this before exiting your program if you have used any part | ||
212 | of DUMB in the program. Some parts of DUMB will allocate memory, and this | ||
213 | function will free it all up. | ||
214 | |||
215 | More specifically, this function will call any functions that have been | ||
216 | registered with dumb_atexit(). If a part of DUMB needs shutting down, the | ||
217 | shutdown procedure will have been registered in this way. | ||
218 | |||
219 | dumb_exit() will, of course, also call any functions you registered with | ||
220 | dumb_atexit() yourself. | ||
221 | |||
222 | After a call to dumb_exit(), the list of functions is erased. If you are | ||
223 | not ready to exit your program, you can start using DUMB anew as if your | ||
224 | program had just started. (Note that not everything will be reset in | ||
225 | practice - dumb_resampling_quality will retain whatever you set it to, for | ||
226 | example, though you should not assume it will.) | ||
227 | |||
228 | If you only need to call dumb_exit() once at the end of the program, you | ||
229 | can use the following to register dumb_exit() with stdlib.h atexit(): | ||
230 | |||
231 | #include <stdlib.h> | ||
232 | |||
233 | atexit(&dumb_exit); | ||
234 | |||
235 | Then dumb_exit() will be called for you when your program exits. This is | ||
236 | the recommended method, since it will ensure clean-up even if your program | ||
237 | aborts. You should only call dumb_exit() manually if you need to shut DUMB | ||
238 | down prematurely, or if atexit() is unavailable for one reason or another. | ||
239 | |||
240 | |||
241 | ***************************** | ||
242 | *** Sequential File Input *** | ||
243 | ***************************** | ||
244 | |||
245 | |||
246 | DUMB provides a strictly sequential file input system which uses the | ||
247 | DUMBFILE struct. "Strictly sequential" means you cannot seek backwards. | ||
248 | However, the system will keep track of how many bytes you have read, | ||
249 | enabling you to seek forwards. DUMBFILEs provide a convenient error | ||
250 | detection system, so you do not have to check the return value from every | ||
251 | function call in the way you do with the ANSI C functions. | ||
252 | |||
253 | Note that DUMBFILEs cannot be used for output, nor can they be used | ||
254 | portably for text files. | ||
255 | |||
256 | If an error occurs when reading data from a DUMBFILE, the DUMBFILE will | ||
257 | become inoperative. All subsequent activities on the DUMBFILE will return | ||
258 | error codes without attempting to read from the file. The position in the | ||
259 | file will also be forgotten. You can find out if this has happened at any | ||
260 | stage with the dumbfile_error() function. You are still required to close | ||
261 | the DUMBFILE, and the return value from dumbfile_close() will tell you if | ||
262 | an error has occurred. | ||
263 | |||
264 | This system allows you to input large chunks of your file, neither | ||
265 | checking every return value nor wasting time accessing a file that has | ||
266 | already experienced an error. However, before you allocate an amount of | ||
267 | memory or read in a quantity of data depending on previous input from the | ||
268 | file, you should always check that such input was valid. In particular you | ||
269 | should avoid passing zero or negative numbers to malloc(), and avoid | ||
270 | passing negative numbers to dumbfile_skip() and dumbfile_getnc(). | ||
271 | |||
272 | DUMBFILEs can be hooked. In other words, you can specify your own | ||
273 | functions to do the work of reading from a file. While DUMB contains two | ||
274 | modules for this purpose, it does not set them up for you automatically. | ||
275 | In most cases you must register one of these modules yourself, or provide | ||
276 | your own module. See register_dumbfile_system(), dumb_register_stdfiles() | ||
277 | and dumb_register_packfiles(). | ||
278 | |||
279 | |||
280 | void register_dumbfile_system(DUMBFILE_SYSTEM *dfs); | ||
281 | |||
282 | Use this function to register a set of functions for use by the DUMBFILEs | ||
283 | (a DUMBFILE system). The DUMBFILE_SYSTEM struct contains the following | ||
284 | fields: | ||
285 | |||
286 | void *(*open)(const char *filename); | ||
287 | int (*skip)(void *f, long n); | ||
288 | int (*getc)(void *f); | ||
289 | long (*getnc)(char *ptr, long n, void *f); | ||
290 | void (*close)(void *f); | ||
291 | |||
292 | See fnptr.txt for help with function pointers such as these. | ||
293 | |||
294 | Your 'open' function should open the file specified and return a pointer | ||
295 | to a struct representing the open file. This pointer will be passed to | ||
296 | your other functions as 'f'. Your 'close' function should close the file | ||
297 | and free all memory pointed to by 'f'. Note that the 'close' operation | ||
298 | should never be able to fail; if you are calling a function with a return | ||
299 | value, you can generally ignore it. | ||
300 | |||
301 | Your 'getc' function should read one byte from the file and return its | ||
302 | value in the range 0 to 255. If an error occurs, you should return -1. Do | ||
303 | not worry about remembering that an error has occurred; DUMB will do that | ||
304 | for you. | ||
305 | |||
306 | 'skip' is for skipping parts of the file, and should skip n bytes, | ||
307 | returning 0 on success or any other number on failure. 'getnc' should read | ||
308 | n bytes from the file, store them at 'ptr', and return the number of bytes | ||
309 | read (n on success, fewer on failure). However, these two functions are | ||
310 | optional, and you should only provide them if the operations can be done | ||
311 | more efficiently than with repeated calls to your 'getc' function. If this | ||
312 | is not the case, specify NULL for 'skip', 'getnc' or both, and DUMB will | ||
313 | use your 'getc' function to do the work. | ||
314 | |||
315 | Once you have written all your functions, you need to create a | ||
316 | DUMBFILE_SYSTEM struct to hold them, and pass its pointer to | ||
317 | register_dumbfile_system(). | ||
318 | |||
319 | The DUMBFILE_SYSTEM struct must be permanent. In other words, it must be | ||
320 | either global or static, and you should not modify it later. DUMB will not | ||
321 | make its own copy. | ||
322 | |||
323 | You will most likely create your own struct to represent the open file, | ||
324 | but do not be tempted to specify that struct in the function prototypes | ||
325 | and pacify the compiler warnings by casting your function pointers. There | ||
326 | exist computer systems where a (void *) pointer and a (MY_STRUCT *) | ||
327 | pointer are represented differently in memory, and a cast of such a | ||
328 | pointer causes a tangible conversion to take place. If you cast the | ||
329 | function pointers, the computer cannot know when such a conversion is | ||
330 | necessary. Instead, use the following structure: | ||
331 | |||
332 | int myskip(void *f, long n) | ||
333 | { | ||
334 | FILE *file = f; | ||
335 | /* Do some stuff with 'file' */ | ||
336 | return something; | ||
337 | } | ||
338 | |||
339 | If you need examples, have a look at the two existing DUMBFILE systems in | ||
340 | dumb/src/core/stdfile.c and dumb/src/allegro/packfile.c. | ||
341 | |||
342 | |||
343 | DUMBFILE *dumbfile_open(const char *filename); | ||
344 | |||
345 | Open the specified file for input. You must pass the DUMBFILE pointer | ||
346 | whenever you wish to operate on this file. When you have finished with the | ||
347 | file, you must pass it to dumbfile_close(). | ||
348 | |||
349 | Before you use this function, make sure you have registered a DUMBFILE | ||
350 | system. See register_dumbfile_system(), dumb_register_stdfiles() and | ||
351 | dumb_register_packfiles(). | ||
352 | |||
353 | You must check the return value from this function. If it is NULL, the | ||
354 | file could not be opened, and you must not pass the DUMBFILE to any other | ||
355 | function. The debugging library will abort if you get this wrong; the | ||
356 | optimised library will act weird. | ||
357 | |||
358 | |||
359 | DUMBFILE *dumbfile_open_ex(void *file, DUMBFILE_SYSTEM *dfs); | ||
360 | |||
361 | This function is provided for more specialised use. You should create a | ||
362 | DUMBFILE_SYSTEM specially for the purpose. Its 'open' field is irrelevant; | ||
363 | for neatness, set it to NULL, unless you are using this DUMBFILE_SYSTEM | ||
364 | with register_dumbfile_system() as well. | ||
365 | |||
366 | When you have called this function, the DUMBFILE struct it returned can be | ||
367 | used as normal. The specified DUMBFILE_SYSTEM will be used for all input, | ||
368 | with 'file' passed to your 'skip', 'getc' and 'getnc' functions as 'f'. | ||
369 | This can be used, for example, to read from an already open file. | ||
370 | |||
371 | Note that the position will always be initialised to 0 for this DUMBFILE. | ||
372 | This means for example that offsets in the file do not need adjusting when | ||
373 | embedding data in a larger file. | ||
374 | |||
375 | There are two ways to use this function. If you want 'file' to persist | ||
376 | after using a DUMBFILE returned by this function, you should make sure the | ||
377 | 'close' field in the DUMBFILE is set to NULL. When the DUMBFILE is closed, | ||
378 | 'file' will be left alone, and you can and should deal with it yourself | ||
379 | when the DUMBFILE has been closed. | ||
380 | |||
381 | Alternatively, you can provide a 'close' function to get rid of 'file' for | ||
382 | you when the DUMBFILE is closed. If you do this, you should not otherwise | ||
383 | use 'file' after a call to this function. | ||
384 | |||
385 | If dumbfile_open_ex() has to return NULL, owing to lack of memory, then | ||
386 | your 'close' function will be called if provided. In other words, if you | ||
387 | have provided a 'close' function, then you no longer need to worry about | ||
388 | 'file' whether this function succeeds or not. | ||
389 | |||
390 | See dumb/src/helpers/stdfile.c and dumb/src/allegro/packfile.c for | ||
391 | examples of how to use this function. Neither provides a 'close' function, | ||
392 | so I hope my explanation here will suffice. If not, please feel free to | ||
393 | contact me so I can make the explanation clearer and help you do what you | ||
394 | want to do. Contact details are at the end of this file. | ||
395 | |||
396 | |||
397 | long dumbfile_pos(DUMBFILE *f); | ||
398 | |||
399 | Returns the number of bytes read from the DUMBFILE (or skipped) since it | ||
400 | was opened, or -1 if an error has occurred while reading. | ||
401 | |||
402 | |||
403 | int dumbfile_skip(DUMBFILE *f, long n); | ||
404 | |||
405 | Skips n bytes of the specified DUMBFILE. Returns zero on success. | ||
406 | |||
407 | |||
408 | int dumbfile_getc(DUMBFILE *f); | ||
409 | |||
410 | Reads one byte from the DUMBFILE and returns it in unsigned format (from 0 | ||
411 | to 255). If an error occurs, or occurred before, this function returns -1. | ||
412 | |||
413 | |||
414 | int dumbfile_igetw(DUMBFILE *f); | ||
415 | |||
416 | Reads two bytes from the DUMBFILE and combines them into a word ranging | ||
417 | from 0 to 65535. The first byte read is the least significant byte, as | ||
418 | with Intel processors. This function returns -1 on error. | ||
419 | |||
420 | |||
421 | int dumbfile_mgetw(DUMBFILE *f); | ||
422 | |||
423 | Reads two bytes from the DUMBFILE and combines them into a word ranging | ||
424 | from 0 to 65535. The first byte read is the most significant byte, as | ||
425 | with the Apple Macintosh. This function returns -1 on error. | ||
426 | |||
427 | |||
428 | long dumbfile_igetl(DUMBFILE *f); | ||
429 | |||
430 | Reads four bytes from the DUMBFILE and combines them into a long integer | ||
431 | ranging from -2147483648 to 2147483647. The first byte read is the least | ||
432 | significant byte, as with Intel processors. This function returns -1 on | ||
433 | error, but -1 is also a valid return value. After a call to this function, | ||
434 | you can use dumbfile_error() to find out if an error occurred. | ||
435 | |||
436 | |||
437 | long dumbfile_mgetl(DUMBFILE *f); | ||
438 | |||
439 | Reads four bytes from the DUMBFILE and combines them into a long integer | ||
440 | ranging from -2147483648 to 2147483647. The first byte read is the most | ||
441 | significant byte, as with the Apple Macintosh. This function returns -1 on | ||
442 | error, but -1 is also a valid return value. After a call to this function, | ||
443 | you can use dumbfile_error() to find out if an error occurred. | ||
444 | |||
445 | |||
446 | unsigned long dumbfile_cgetul(DUMBFILE *f); | ||
447 | |||
448 | Reads an unsigned (nonnegative) integer from the DUMBFILE. The integer is | ||
449 | stored in a condensed format where smaller numbers use less space: | ||
450 | |||
451 | 0 to 127 1 byte | ||
452 | 128 to 16383 2 bytes | ||
453 | 16384 to 2097151 3 bytes | ||
454 | 2097152 to 268435455 4 bytes | ||
455 | 268435456 to 4294967295 5 bytes | ||
456 | |||
457 | This format is the same as that used for the times between notes in MIDI | ||
458 | files. | ||
459 | |||
460 | If an error occurs, this function returns (unsigned long)(-1), but that | ||
461 | may be a valid return value. After a call to this function, you can use | ||
462 | dumbfile_error() to find out if an error occurred. | ||
463 | |||
464 | |||
465 | signed long dumbfile_cgetsl(DUMBFILE *f); | ||
466 | |||
467 | Reads a signed integer from the DUMBFILE. The integer is stored in a | ||
468 | condensed format where numbers closer to zero use less space: | ||
469 | |||
470 | -64 to 63 1 byte | ||
471 | -8192 to 8191 2 bytes | ||
472 | -1048576 to 1048575 3 bytes | ||
473 | -134217728 to 134217727 4 bytes | ||
474 | -2147483648 to 2147483647 5 bytes | ||
475 | |||
476 | If an error occurs, this function returns -1, but -1 is also a valid | ||
477 | return value. After a call to this function, you can use dumbfile_error() | ||
478 | to find out if an error occurred. | ||
479 | |||
480 | |||
481 | long dumbfile_getnc(char *ptr, long n, DUMBFILE *f); | ||
482 | |||
483 | Reads n bytes from the DUMBFILE and stores them at 'ptr'. Note that the | ||
484 | pointer is to a series of chars. You may also use this function to read in | ||
485 | a series of signed chars or unsigned chars (which are both officially | ||
486 | distinct types from char), but do not use this to read ints, structs or | ||
487 | any other data type from the file. Integers must be read one at a time | ||
488 | using dumbfile_igetl(), dumbfile_cgetul(), etc. To load a struct in, you | ||
489 | must read each field separately using an appropriate function for each | ||
490 | one. For complicated data types, you can simplify this process by writing | ||
491 | a function for each struct. | ||
492 | |||
493 | dumbfile_getnc() returns the number of bytes successfully read, which will | ||
494 | be less than n if an error occurs, and may be as low as zero. If | ||
495 | dumbfile_getnc() returns -1, that means an error occurred on this DUMBFILE | ||
496 | earlier, before this function was called. | ||
497 | |||
498 | |||
499 | int dumbfile_error(DUMBFILE *f); | ||
500 | |||
501 | This function returns -1 if an error has occurred with the specified | ||
502 | DUMBFILE, or 0 if all is well. | ||
503 | |||
504 | |||
505 | int dumbfile_close(DUMBFILE *f); | ||
506 | |||
507 | This function closes the DUMBFILE, after which the pointer will be | ||
508 | invalid. dumbfile_close() returns the value that dumbfile_error() would | ||
509 | have returned, which is -1 if an error occurred while reading or 0 | ||
510 | otherwise. Regardless of the return value, the file will always be closed | ||
511 | properly. | ||
512 | |||
513 | |||
514 | ******************************* | ||
515 | *** stdio File Input Module *** | ||
516 | ******************************* | ||
517 | |||
518 | |||
519 | void dumb_register_stdfiles(void); | ||
520 | |||
521 | This function registers the stdio file input module for use by DUMBFILEs. | ||
522 | FILE structs and their corresponding functions, as defined by the ANSI C | ||
523 | header stdio.h, will be used internally for all DUMBFILE input (unless | ||
524 | opened with dumbfile_open_ex()). | ||
525 | |||
526 | This must be called before dumbfile_open() is used, or else an alternative | ||
527 | system must be registered (see register_dumbfile_system() and | ||
528 | dumb_register_packfiles()). | ||
529 | |||
530 | |||
531 | DUMBFILE *dumbfile_open_stdfile(FILE *p); | ||
532 | |||
533 | If you have a stdio FILE struct representing an open file, you can call | ||
534 | this if you wish to read from it using a DUMBFILE. This is useful when you | ||
535 | need to pass a DUMBFILE struct to a library function, to read an embedded | ||
536 | music file for example. When you close the DUMBFILE, you can continue | ||
537 | using the FILE struct to read what follows the embedded data. | ||
538 | |||
539 | |||
540 | ******************************** | ||
541 | *** Memory File Input Module *** | ||
542 | ******************************** | ||
543 | |||
544 | |||
545 | DUMBFILE *dumbfile_open_memory(const char *data, long size); | ||
546 | |||
547 | This function is useful if you have an image of a music file in memory. | ||
548 | You might have such an image if you use dat2s to encode a datafile | ||
549 | directly into the executable. Pass a pointer to the start of the memory, | ||
550 | and the size of the image to make sure DUMB doesn't overrun the buffer. | ||
551 | The resulting DUMBFILE will feed the contents of the image to you. | ||
552 | |||
553 | Note that the pointer is of type 'char *'. Files are series of chars, and | ||
554 | interpreting them directly as anything else isn't portable. | ||
555 | |||
556 | |||
557 | ********************** | ||
558 | *** DUH Management *** | ||
559 | ********************** | ||
560 | |||
561 | |||
562 | void unload_duh(DUH *duh); | ||
563 | |||
564 | Removes a DUH from memory. You must call this for all DUHs you load, | ||
565 | making sure they're not playing at the time. | ||
566 | |||
567 | |||
568 | long duh_get_length(DUH *duh); | ||
569 | |||
570 | Returns the length of a DUH; 65536 represents one second. This value is | ||
571 | calculated when the DUH is created, and this function simply lifts it from | ||
572 | the struct. It may not truly correspond to the time for which the DUH will | ||
573 | generate sound. For module files, it will represent the point at which the | ||
574 | module first loops (or, in the case of some XM and MOD files, freezes). | ||
575 | Any add-ons to DUMB will provide their own code for calculating this. | ||
576 | |||
577 | The algorithm for calculating the length of a module file can be fooled, | ||
578 | but only by very deliberate methods. In the early days, when modules could | ||
579 | only be played by their editors and had to be exported to .wav or similar | ||
580 | in order to be used elsewhere, musicians would sometimes make the player | ||
581 | think it was looping when it wasn't in order to prevent their music from | ||
582 | being exported properly. If the length of a module seems a lot less than | ||
583 | it should be, the module is probably protected in this way. | ||
584 | |||
585 | Getting around this protection reliably would be extremely difficult, but | ||
586 | after considering it for a while I decided it would be better not to. The | ||
587 | musician has a right to protect his or her music in this way, and I have | ||
588 | no interest in actively breaking that protection. | ||
589 | |||
590 | (On the other hand, some musicians were just showing off!) | ||
591 | |||
592 | |||
593 | *********************************** | ||
594 | *** IT, XM, S3M and MOD Support *** | ||
595 | *********************************** | ||
596 | |||
597 | |||
598 | int dumb_it_max_to_mix; | ||
599 | |||
600 | Specifies the maximum number of samples DUMB will mix at any one time. The | ||
601 | default number is 64. Regardless of this value, all samples will continue | ||
602 | to be processed up to an internal maximum of 256 (roughly speaking; in | ||
603 | fact it will process one sample for each channel plus up to 192 extra | ||
604 | samples that are continuing to play owing to Impulse Tracker's New Note | ||
605 | Actions), and samples that have been cut will sound again as soon as the | ||
606 | congestion clears. Samples are given priority according to their final | ||
607 | volume after all factors affecting the volume of a sample have been | ||
608 | considered. | ||
609 | |||
610 | If you play two or more modules at once, this value represents the | ||
611 | maximum number of samples for each one. You will have to reduce it further | ||
612 | if your computer cannot keep up. | ||
613 | |||
614 | Despite the name, this variable controls XM, S3M and MOD files as well as | ||
615 | IT files. | ||
616 | |||
617 | |||
618 | DUMB_IT_SIGDATA *duh_get_it_sigdata(DUH *duh); | ||
619 | |||
620 | This function attempts to retrieve the DUMB_IT_SIGDATA struct from a DUH. | ||
621 | This struct will exist for any IT, XM, S3M or MOD file, and you can use it | ||
622 | to obtain or override module-specific information. If 'duh' is NULL, or if | ||
623 | the DUH you pass contains something other than a music module, then this | ||
624 | function will return NULL (which can safely be passed to any other | ||
625 | function). | ||
626 | |||
627 | |||
628 | DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer); | ||
629 | |||
630 | This function attempts to retrieve the DUMB_IT_SIGRENDERER struct from a | ||
631 | DUH_SIGRENDERER. This struct will exist for any currently playing IT, XM, | ||
632 | S3M or MOD file, and you can use it to obtain or override information | ||
633 | specific to module playback. If 'sigrenderer' is NULL, or if the | ||
634 | DUH_SIGRENDERER you pass is rendering something other than a music module, | ||
635 | then this function will return NULL (which can safely be passed to any | ||
636 | other function). | ||
637 | |||
638 | |||
639 | DUH_SIGRENDERER *dumb_it_start_at_order | ||
640 | (DUH *duh, int n_channels, int startorder); | ||
641 | |||
642 | This function, given a DUH containing an IT, XM, S3M or MOD file, will | ||
643 | start playing it at the specified order. If the DUH does not contain a | ||
644 | module, this function will fail and return NULL. | ||
645 | |||
646 | Note that starting at an arbitrary order may result in missing notes or | ||
647 | other playback oddities. It should be used primarily for modules that | ||
648 | contain multiple songs that start on different orders. If you wish just to | ||
649 | start some music in the middle, consider using duh_start_sigrenderer() or | ||
650 | al_start_duh() with the pos parameter set appropriately. | ||
651 | |||
652 | |||
653 | void dumb_it_set_loop_callback(DUMB_IT_SIGRENDERER *sigrenderer, | ||
654 | int (*callback)(void *data), void *data); | ||
655 | |||
656 | Installs a callback which will be called every time the module loops. You | ||
657 | can pass any data pointer you like, and it will be passed to the callback | ||
658 | for you. DUMB considers a file to loop when it reaches the end, or when a | ||
659 | 'Jump to order' effect (Bxx in both IT/S3M and XM/MOD) jumps to the same | ||
660 | order or a preceding order. This can result in the loop callback being | ||
661 | called when the module isn't really looping, but this only happens if the | ||
662 | module has a very deliberate design. See duh_get_length() for further | ||
663 | musings on this subject. | ||
664 | |||
665 | If your callback returns nonzero, the music will stop abruptly. Samples | ||
666 | will be cut, and the main program will be notified that the | ||
667 | DUH_SIGRENDERER has ended. | ||
668 | |||
669 | Alternatively, if you pass the DUMB_IT_SIGRENDERER for 'data', or | ||
670 | otherwise arrange for it to be available to the callback, then you can | ||
671 | call: | ||
672 | |||
673 | dumb_it_sr_set_speed(sigrenderer, 0); | ||
674 | |||
675 | from inside the callback, and this will cause the music to freeze but | ||
676 | samples will be able to continue playing. The xm_speed_zero callback will | ||
677 | NOT be called in this case (see below for information on this callback). | ||
678 | Note also that setting the speed in this way will work equally for IT and | ||
679 | S3M files, even though a 'speed zero' effect can only exist in XM and MOD | ||
680 | files. Beware when using this method; samples might not fade at all! | ||
681 | |||
682 | A helper callback, dumb_it_callback_terminate(), is provided; installing | ||
683 | this will cause the music to terminate when it tries to loop for the first | ||
684 | time. | ||
685 | |||
686 | Pass NULL to remove the callback function; the module will then loop as | ||
687 | normal. | ||
688 | |||
689 | |||
690 | void dumb_it_set_xm_speed_zero_callback(DUMB_IT_SIGRENDERER *sigrenderer, | ||
691 | int (*callback)(void *data), void *data); | ||
692 | |||
693 | Installs a callback which is in many ways similar to the loop callback | ||
694 | (see dumb_it_set_loop_callback()). This callback will be called whenever | ||
695 | an F00 effect is encountered in a MOD or XM file, setting the speed to | ||
696 | zero. If the callback returns nonzero, the music will terminate. If not, | ||
697 | any currently playing samples will continue to play. You can pass any data | ||
698 | pointer you like to this function, and it will be passed to your callback | ||
699 | for you. | ||
700 | |||
701 | The helper callback, dumb_it_callback_terminate(), will also work here; | ||
702 | installing it will cause the music to terminate as soon as an F00 effect | ||
703 | is encountered. | ||
704 | |||
705 | Pass NULL to remove the callback function. | ||
706 | |||
707 | |||
708 | void dumb_it_set_midi_callback(DUMB_IT_SIGRENDERER *sigrenderer, | ||
709 | int (*callback)(void *data, int channel, unsigned char byte), | ||
710 | void *data); | ||
711 | |||
712 | Installs a callback function which will be called whenever MIDI data are | ||
713 | generated by an IT file. (No other module formats are capable of | ||
714 | generating MIDI data, so your callback will never be called.) | ||
715 | |||
716 | Zxx macros will generate MIDI data. These are most often used to set the | ||
717 | parameters for IT's low-pass resonant filters, and DUMB will handle these | ||
718 | messages by itself by default. See Impulse Tracker's documentation for | ||
719 | the MIDI messages that control filters. However, Zxx macros can be used | ||
720 | to send any kind of MIDI data. | ||
721 | |||
722 | If you wish to interpret MIDI messages yourself, you can use this | ||
723 | callback. Note that the only MIDI messages generated by DUMB at present | ||
724 | are from Zxx macros; there are no messages for note start, stop, or | ||
725 | anything else. | ||
726 | |||
727 | If you return 1 from this callback, DUMB will subsequently ignore the byte | ||
728 | of MIDI data. You can use this to prevent Zxx macros from controlling the | ||
729 | filters, useful if they were intended to do something else. Note that this | ||
730 | is NOT an effective way to disable filters, since instruments can have | ||
731 | filter envelopes and initial filter parameters. DUMB provides no means to | ||
732 | disable filters, as any IT file that uses them will sound wrong without | ||
733 | them. If you want lower processor consumption, use a different piece of | ||
734 | music. | ||
735 | |||
736 | A helper callback, dumb_it_callback_midi_block(), is provided for blocking | ||
737 | all MIDI messages and making Zxx macros do nothing. | ||
738 | |||
739 | Pass NULL to remove the callback. | ||
740 | |||
741 | |||
742 | int dumb_it_callback_terminate(void *data); | ||
743 | |||
744 | This is a helper callback that can be installed with both | ||
745 | dumb_it_set_loop_callback() and dumb_it_set_xm_speed_zero_callback(). In | ||
746 | each case it will cause the music to terminate abruptly. | ||
747 | |||
748 | |||
749 | int dumb_it_callback_midi_block(void *data, int channel, unsigned char byte); | ||
750 | |||
751 | This helper callback, for use with dumb_it_set_midi_callback(), will | ||
752 | absorb all MIDI messages, returning 1 to prevent DUMB from interpreting | ||
753 | them itself. | ||
754 | |||
755 | |||
756 | DUH *dumb_load_it(const char *filename); | ||
757 | |||
758 | Loads the specified Impulse Tracker file, encapsulating it in a DUH | ||
759 | struct. Once the file is loaded, it can be treated exactly the same as any | ||
760 | other DUH in memory. If this fails it will return NULL, but you can safely | ||
761 | pass this NULL value to DUMB's other functions, so you do not need to | ||
762 | check the return value explicitly. | ||
763 | |||
764 | |||
765 | DUH *dumb_read_it(DUMBFILE *f); | ||
766 | |||
767 | Reads an Impulse Tracker file from an already open DUMBFILE. This leaves | ||
768 | the DUMBFILE open, but the DUMBFILE may not be positioned at the end of | ||
769 | the IT data. If you are embedding an IT in another file, you are advised | ||
770 | to store the size of the IT file and make up for it at the end using | ||
771 | dumbfile_pos(). | ||
772 | |||
773 | Otherwise, this function is identical to dumb_load_it(). | ||
774 | |||
775 | WARNING: The behaviour of this function is undefined if you pass a | ||
776 | DUMBFILE from which data have already been read; it is likely not | ||
777 | to work. This oversight will be fixed in future releases. | ||
778 | |||
779 | |||
780 | DUH *dumb_load_xm(const char *filename); | ||
781 | |||
782 | Loads the specified Fast Tracker II file, encapsulating it in a DUH | ||
783 | struct. Once the file is loaded, it can be treated exactly the same as any | ||
784 | other DUH in memory. If this fails it will return NULL, but you can safely | ||
785 | pass this NULL value to DUMB's other functions, so you do not need to | ||
786 | check the return value explicitly. | ||
787 | |||
788 | |||
789 | DUH *dumb_read_xm(DUMBFILE *f); | ||
790 | |||
791 | Reads a Fast Tracker II file from an already open DUMBFILE. This leaves | ||
792 | the DUMBFILE open, but the DUMBFILE may not be positioned at the end of | ||
793 | the XM data. If you are embedding an XM in another file, you are advised | ||
794 | to store the size of the XM file and make up for it at the end using | ||
795 | dumbfile_pos(). | ||
796 | |||
797 | Otherwise, this function is identical to dumb_load_xm(). | ||
798 | |||
799 | WARNING: The behaviour of this function is undefined if you pass a | ||
800 | DUMBFILE from which data have already been read; it is likely not | ||
801 | to work. This oversight will be fixed in future releases. | ||
802 | |||
803 | |||
804 | DUH *dumb_load_s3m(const char *filename); | ||
805 | |||
806 | Loads the specified Scream Tracker 3 file, encapsulating it in a DUH | ||
807 | struct. Once the file is loaded, it can be treated exactly the same as any | ||
808 | other DUH in memory. If this fails it will return NULL, but you can safely | ||
809 | pass this NULL value to DUMB's other functions, so you do not need to | ||
810 | check the return value explicitly. | ||
811 | |||
812 | |||
813 | DUH *dumb_read_s3m(DUMBFILE *f); | ||
814 | |||
815 | Reads a Scream Tracker 3 file from an already open DUMBFILE. This leaves | ||
816 | the DUMBFILE open, but the DUMBFILE may not be positioned at the end of | ||
817 | the S3M data. If you are embedding an S3M in another file, you are advised | ||
818 | to store the size of the S3M file and make up for it at the end using | ||
819 | dumbfile_pos(). | ||
820 | |||
821 | Otherwise, this function is identical to dumb_load_s3m(). | ||
822 | |||
823 | WARNING: The behaviour of this function is undefined if you pass a | ||
824 | DUMBFILE from which data have already been read; it is likely not | ||
825 | to work. This oversight will be fixed in future releases. | ||
826 | |||
827 | |||
828 | DUH *dumb_load_mod(const char *filename); | ||
829 | |||
830 | Loads the specified Amiga module file, encapsulating it in a DUH struct. | ||
831 | Once the file is loaded, it can be treated exactly the same as any other | ||
832 | DUH in memory. If this fails it will return NULL, but you can safely pass | ||
833 | this NULL value to DUMB's other functions, so you do not need to check the | ||
834 | return value explicitly. | ||
835 | |||
836 | |||
837 | DUH *dumb_read_mod(DUMBFILE *f); | ||
838 | |||
839 | Reads an Amiga module file from an already open DUMBFILE. This leaves the | ||
840 | DUMBFILE open, but the DUMBFILE may not be positioned at the end of the | ||
841 | MOD data. If you are embedding a MOD in another file, you are advised to | ||
842 | store the size of the MOD file and make up for it at the end using | ||
843 | dumbfile_pos(). | ||
844 | |||
845 | Otherwise, this function is identical to dumb_load_mod(). | ||
846 | |||
847 | WARNING: The behaviour of this function is undefined if you pass a | ||
848 | DUMBFILE from which data have already been read; it is likely not | ||
849 | to work. This oversight will be fixed in future releases. | ||
850 | |||
851 | |||
852 | int dumb_it_sd_get_n_orders(DUMB_IT_SIGDATA *sd); | ||
853 | |||
854 | This function returns the number of orders in the module. | ||
855 | |||
856 | |||
857 | int dumb_it_sd_get_initial_global_volume(DUMB_IT_SIGDATA *sd); | ||
858 | void dumb_it_sd_set_initial_global_volume(DUMB_IT_SIGDATA *sd, int gv); | ||
859 | |||
860 | These functions obtain and set the initial global volume for the module. | ||
861 | This value ranges from 0 to 128 inclusive. The module can set the global | ||
862 | volume itself during playback, so your change may not last throughout the | ||
863 | playback. | ||
864 | |||
865 | |||
866 | int dumb_it_sd_get_mixing_volume(DUMB_IT_SIGDATA *sd); | ||
867 | void dumb_it_sd_set_mixing_volume(DUMB_IT_SIGDATA *sd, int mv); | ||
868 | |||
869 | These functions obtain and set the mixing volume for the module. This | ||
870 | value ranges from 0 to 128 inclusive, and does not change during playback. | ||
871 | IT files have the mixing volume stored in them; for other formats it is | ||
872 | set to 48 on loading. | ||
873 | |||
874 | |||
875 | int dumb_it_sd_get_initial_speed(DUMB_IT_SIGDATA *sd); | ||
876 | void dumb_it_sd_set_initial_speed(DUMB_IT_SIGDATA *sd, int speed); | ||
877 | int dumb_it_sd_get_initial_tempo(DUMB_IT_SIGDATA *sd); | ||
878 | void dumb_it_sd_set_initial_tempo(DUMB_IT_SIGDATA *sd, int tempo); | ||
879 | |||
880 | These functions obtain and set the initial speed and tempo for the module. | ||
881 | During module playback, everything happens on a tick. If a beat is 24 | ||
882 | ticks, then the tempo is measured in beats per second. The speed is then | ||
883 | the number of ticks per row. With a speed of 6, a beat is then four rows. | ||
884 | |||
885 | Modules can set these values during playback, so your change may not last | ||
886 | throughout the playback. MOD files have to set the speed and tempo on the | ||
887 | first row if they want anything other than the default 6/125, so your | ||
888 | change may not be noticed at all! | ||
889 | |||
890 | |||
891 | int dumb_it_sd_get_initial_channel_volume(DUMB_IT_SIGDATA *sd, int channel); | ||
892 | void dumb_it_sd_set_initial_channel_volume(DUMB_IT_SIGDATA *sd, int channel, | ||
893 | int volume); | ||
894 | |||
895 | These functions obtain and set the initial volume for the specified | ||
896 | channel. The channel parameter is 0-based (contrary to the display in most | ||
897 | trackers so be careful), and can range from 0 to DUMB_IT_N_CHANNELS - 1, | ||
898 | i.e. from 0 to 63. | ||
899 | |||
900 | Modules can set their channel volumes during playback, so your changes may | ||
901 | not last throughout the playback. | ||
902 | |||
903 | |||
904 | int dumb_it_sr_get_current_order(DUMB_IT_SIGRENDERER *sr); | ||
905 | int dumb_it_sr_get_current_row(DUMB_IT_SIGRENDERER *sr); | ||
906 | |||
907 | These functions return the current order and row of playback. Both are | ||
908 | 0-based. If the DUMB_IT_SIGRENDERER is invalid, or has been terminated | ||
909 | by a callback (see dumb_it_set_loop_callback() and | ||
910 | dumb_it_set_xm_speed_zero_callback()), these functions will both return | ||
911 | -1. | ||
912 | |||
913 | |||
914 | int dumb_it_sr_get_global_volume(DUMB_IT_SIGRENDERER *sr); | ||
915 | void dumb_it_sr_set_global_volume(DUMB_IT_SIGRENDERER *sr, int gv); | ||
916 | |||
917 | These functions obtain and set the current global volume for the module. | ||
918 | This value ranges from 0 to 128 inclusive. The module can set the global | ||
919 | volume itself during playback, so your change may not last. | ||
920 | |||
921 | |||
922 | int dumb_it_sr_get_tempo(DUMB_IT_SIGRENDERER *sr); | ||
923 | void dumb_it_sr_set_tempo(DUMB_IT_SIGRENDERER *sr, int tempo); | ||
924 | int dumb_it_sr_get_speed(DUMB_IT_SIGRENDERER *sr); | ||
925 | void dumb_it_sr_set_speed(DUMB_IT_SIGRENDERER *sr, int speed); | ||
926 | |||
927 | These functions obtain and set the current speed and tempo of the module. | ||
928 | See the dumb_it_sd_*() equivalents of these functions for details on what | ||
929 | the speed and tempo mean. | ||
930 | |||
931 | Modules can set these values during playback, so your change may not last. | ||
932 | |||
933 | |||
934 | int dumb_it_sr_get_channel_volume(DUMB_IT_SIGRENDERER *sr, int channel); | ||
935 | void dumb_it_sr_set_channel_volume(DUMB_IT_SIGRENDERER *sr, int channel, | ||
936 | int volume); | ||
937 | |||
938 | These functions obtain and set the current volume for the specified | ||
939 | channel. The channel parameter is 0-based (contrary to the display in most | ||
940 | trackers so be careful), and can range from 0 to DUMB_IT_N_CHANNELS - 1, | ||
941 | i.e. from 0 to 63. | ||
942 | |||
943 | Modules can set their channel volumes during playback, so your changes may | ||
944 | not last. | ||
945 | |||
946 | |||
947 | void dumb_it_sr_get_channel_state(DUMB_IT_SIGRENDERER *sr, int channel, | ||
948 | DUMB_IT_CHANNEL_STATE *state); | ||
949 | |||
950 | Returns the current playback state of the given channel. If you pass a | ||
951 | channel in the range 0 to DUMB_IT_N_CHANNELS-1 (0 to 63), you will get the | ||
952 | state of the most recently played note on that physical channel, if it is | ||
953 | still playing. For MOD, S3M and XM files, that's all there is to it. | ||
954 | |||
955 | IT files can have more than one note playing on a single channel, courtesy | ||
956 | of New Note Actions. This function also lets you query all the notes that | ||
957 | have been forced into the background and are still playing. For this, set | ||
958 | 'channel' to a value from DUMB_IT_N_CHANNELS to DUMB_IT_TOTAL_CHANNELS-1. | ||
959 | DUMB_IT_TOTAL_CHANNELS is defined as follows: | ||
960 | |||
961 | #define DUMB_IT_TOTAL_CHANNELS \ | ||
962 | (DUMB_IT_N_CHANNELS + DUMB_IT_N_NNA_CHANNELS) | ||
963 | |||
964 | Querying these background channels for MOD, S3M and XM files will not do | ||
965 | any harm; the function will report that these channels are inactive. For | ||
966 | all files, be sure not to query any channel numbers greater than or equal | ||
967 | to DUMB_IT_TOTAL_CHANNELS. | ||
968 | |||
969 | You must provide a pointer to a preallocated DUMB_IT_CHANNEL_STATE struct. | ||
970 | The easiest way to do this is as follows: | ||
971 | |||
972 | DUMB_IT_CHANNEL_STATE state; | ||
973 | dumb_it_sr_get_channel_state(sr, channel, &state); | ||
974 | |||
975 | or: | ||
976 | |||
977 | DUMB_IT_CHANNEL_STATE state[IT_TOTAL_CHANNELS]; | ||
978 | dumb_it_sr_get_channel_state(sr, channel, &state[channel]); | ||
979 | |||
980 | This struct contains the following fields: | ||
981 | |||
982 | int channel; | ||
983 | int sample; | ||
984 | int freq; | ||
985 | float volume; | ||
986 | unsigned char pan; | ||
987 | signed char subpan; | ||
988 | unsigned char filter_cutoff; | ||
989 | unsigned char filter_subcutoff; | ||
990 | unsigned char filter_resonance; | ||
991 | |||
992 | The first field to check is 'sample'; if this is 0, then the channel is | ||
993 | inactive and the other fields are undefined. Otherwise, it is the index of | ||
994 | the currently playing sample, and is 1-based. | ||
995 | |||
996 | The channel number is returned, 0-based. This will be the same as the | ||
997 | channel number you passed, unless you are querying a background channel in | ||
998 | which case it will represent the channel the note originated on. | ||
999 | |||
1000 | The freq field is the current playback frequency, taking into account all | ||
1001 | phenomena such as slides, vibrato and arpeggio. | ||
1002 | |||
1003 | The volume field ranges from 0.0f to 1.0f. In practical terms, it will | ||
1004 | rarely reach 1.0f; if it does, the module is probably clipping a lot. This | ||
1005 | takes mixing volume into account, along with all the other volume | ||
1006 | phenomena in the IT file. The only one it doesn't take into account is the | ||
1007 | one you pass to duh_render() or duh_sigrenderer_get_samples(), or the one | ||
1008 | you passed to al_start_duh() (these are in fact the same thing). | ||
1009 | |||
1010 | The pan field ranges from 0 to 64 for a normally panned sample, but will | ||
1011 | be 100 if the sample is playing using IT's surround mode where the right- | ||
1012 | hand channel is inverted. If you want a more accurate pan reading, use one | ||
1013 | of the following to get one: | ||
1014 | |||
1015 | int scaled_pan = ((int)state.pan << 8) + state.subpan; | ||
1016 | float float_pan = state.pan + state.subpan / 256.0f; | ||
1017 | |||
1018 | The first will give a scaled value ranging (strictly) from 0 to 64*256. | ||
1019 | The second will give a floating-point value whose scale corresponds to | ||
1020 | that of the pan field. These results will only be valid if surround mode | ||
1021 | is off, so you should check that pan <= 64 before using the above | ||
1022 | expressions. At the time of writing, pitch-pan separation and panning | ||
1023 | envelopes take advantage of the extra accuracy offered by subpan. | ||
1024 | |||
1025 | Note that subpan is signed. This means applications that only look at the | ||
1026 | pan field will get an unbiased reading. | ||
1027 | |||
1028 | The filter cut-off and resonance both range from 0 to 127. If the cut-off | ||
1029 | is 127 and the resonance is 0, then no filters are applied. These | ||
1030 | parameters only ever change from the default values for IT files. | ||
1031 | |||
1032 | While IT allows you to set 127 different filter cut-off levels in the | ||
1033 | patterns and as a default value per instrument, it also allows you to | ||
1034 | create a filter envelope, which will result in an actual cut-off somewhere | ||
1035 | between 0 and the first-mentioned value. By the time this has been | ||
1036 | calculated, the actual cut-off may lie in between two levels on the | ||
1037 | original scale. If this is the case, filter_subcutoff will be nonzero and | ||
1038 | you can combine it with filter_cutoff. Typically you will want to use one | ||
1039 | of the following: | ||
1040 | |||
1041 | int scaled_cutoff = ((int)state.filter_cutoff << 8) + | ||
1042 | state.filter_subcutoff; | ||
1043 | |||
1044 | float float_cutoff = state.filter_cutoff + | ||
1045 | state.filter_subcutoff / 256.0f; | ||
1046 | |||
1047 | The first will give you a scaled value whose maximum is 127*256. The | ||
1048 | second will give you a floating-point value whose scale corresponds to the | ||
1049 | scale used by filter_cutoff. These match the expressions given further up | ||
1050 | for pan and subpan, but in this case, filter_subcutoff is unsigned. | ||
1051 | |||
1052 | Note that filter_subcutoff will always be zero if filter_cutoff is 127, so | ||
1053 | you need not check it if you simply wish to determine whether filters are | ||
1054 | being applied. | ||
1055 | |||
1056 | |||
1057 | ******************************* | ||
1058 | *** DUH Rendering Functions *** | ||
1059 | ******************************* | ||
1060 | |||
1061 | |||
1062 | Use these functions to generate samples from a DUH. First you call | ||
1063 | duh_start_sigrenderer() with the DUH, the number of channels you want and | ||
1064 | the position at which you want to start. Then you use duh_render() or | ||
1065 | duh_sigrenderer_get_samples() to generate the samples. You can call these | ||
1066 | functions as many times as you like, and they will generate as many or as | ||
1067 | few samples as you require. When you have finished, call | ||
1068 | duh_end_sigrenderer(). | ||
1069 | |||
1070 | |||
1071 | DUH_SIGRENDERER *duh_start_sigrenderer | ||
1072 | (DUH *duh, int sig, int n_channels, long pos); | ||
1073 | |||
1074 | Starts a DUH_SIGRENDERER off. This is the struct you can use to get | ||
1075 | samples from a DUH. This function does not generate any samples; you must | ||
1076 | pass the struct to duh_render() or duh_sigrenderer_get_samples() for that. | ||
1077 | When you have finished with it, you must pass it to duh_end_sigrenderer(). | ||
1078 | You can use as many DUH_SIGRENDERER structs as you like at the same time. | ||
1079 | |||
1080 | Set sig to 0 for now. Currently, n_channels can only be 1 or 2, for | ||
1081 | monaural and stereo sound respectively. The debugging library will cause | ||
1082 | your program to abort if you pass anything else. Future versions will be | ||
1083 | enhanced to support more channels as soon as someone needs them. | ||
1084 | |||
1085 | When specifying the position, 0 represents the start of the DUH, and 65536 | ||
1086 | represents one second. Unlike most other music systems, DUMB will always | ||
1087 | make sure every note is there right from the start (assuming you aren't | ||
1088 | using any broken add-ons). In other words, you can start a DUH at a point | ||
1089 | halfway through a long note, and you will still hear the long note. | ||
1090 | |||
1091 | |||
1092 | void duh_sigrenderer_set_analyser_callback(DUH_SIGRENDERER *sigrenderer, | ||
1093 | DUH_SIGRENDERER_ANALYSER_CALLBACK callback, void *data); | ||
1094 | |||
1095 | Installs a callback function which will be called every time the given | ||
1096 | sigrenderer is used to generate some samples. This can be used to create | ||
1097 | an oscilloscope or spectrum analyser. DUH_SIGRENDERER_ANALYSER_CALLBACK is | ||
1098 | defined as follows: | ||
1099 | |||
1100 | typedef void (*DUH_SIGRENDERER_ANALYSER_CALLBACK)(void *data, | ||
1101 | const sample_t *const *samples, int n_channels, long length); | ||
1102 | |||
1103 | If the above confuses you, see fnptr.txt. As for the 'samples' parameter, | ||
1104 | the first 'const' says that the samples are read-only; the second says | ||
1105 | that each channel's sample pointer is also read-only. If you don't | ||
1106 | understand this, don't worry about it. | ||
1107 | |||
1108 | Beware: your callback function may occasionally be called with | ||
1109 | samples == NULL. This means the main program has decided to skip through | ||
1110 | the music without generating any data (see duh_sigrenderer_get_samples()). | ||
1111 | You should handle this case elegantly, typically by returning immediately, | ||
1112 | but you may wish to make a note of the fact that the music is being | ||
1113 | skipped, for whatever reason. | ||
1114 | |||
1115 | Beware again: if the main program ever calls duh_sigrenderer_get_samples() | ||
1116 | on a buffer that isn't all silence, this callback function will be passed | ||
1117 | the existing buffer after mixing, and thus it will include the original | ||
1118 | data. This will not be an issue if you stick to duh_render(), which always | ||
1119 | starts with a buffer filled with silence. | ||
1120 | |||
1121 | The samples array is two-dimensional. Refer to it as follows: | ||
1122 | |||
1123 | samples[channel_number][sample_position] | ||
1124 | |||
1125 | where 0 <= channel_number < n_channels, | ||
1126 | and 0 <= sample_position < length. | ||
1127 | |||
1128 | In addition you can pass any 'data' pointer you like to | ||
1129 | duh_sigrenderer_set_analyser_callback(), and this pointer will be relayed | ||
1130 | to your callback function each time. | ||
1131 | |||
1132 | To remove the callback function, pass NULL to | ||
1133 | duh_sigrenderer_set_analyser_callback(). | ||
1134 | |||
1135 | |||
1136 | int duh_sigrenderer_get_n_channels(DUH_SIGRENDERER *sigrenderer); | ||
1137 | |||
1138 | Tells you how many channels a DUH_SIGRENDERER is set up to generate, or 0 | ||
1139 | if it is invalid (perhaps owing to lack of memory). This will be 1 for | ||
1140 | monaural sound or 2 for stereo, in this release. | ||
1141 | |||
1142 | |||
1143 | long duh_sigrenderer_get_position(DUH_SIGRENDERER *sigrenderer); | ||
1144 | |||
1145 | Tells you what position a DUH_SIGRENDERER is up to, or -1 if it is invalid | ||
1146 | (perhaps owing to lack of memory). As usual, 65536 is one second. | ||
1147 | |||
1148 | |||
1149 | long duh_sigrenderer_get_samples(DUH_SIGRENDERER *sigrenderer, | ||
1150 | float volume, float delta, | ||
1151 | long size, sample_t **samples); | ||
1152 | |||
1153 | Generates some samples in DUMB's internal 32-bit format (see sample_t; see | ||
1154 | also duh_render()). The samples buffer is a two-dimensional array, and can | ||
1155 | be allocated with create_sample_buffer(); see | ||
1156 | duh_sigrenderer_set_analyser_callback() for details. | ||
1157 | duh_sigrenderer_get_samples() mixes sample data with what's already in the | ||
1158 | buffer, so you have to call dumb_silence() first. | ||
1159 | |||
1160 | The volume is a float. 1.0f is the pseudo-maximum. If you pass 1.0f, any | ||
1161 | properly designed DUH will play nice and loud, but will not clip. You can | ||
1162 | pass a greater volume if you like, but be prepared for the possibility of | ||
1163 | distortion due to integer overflow. Of course you can pass smaller values | ||
1164 | to play the DUH more quietly, and this will also resolve clipping issues | ||
1165 | in badly designed DUHs. | ||
1166 | |||
1167 | Use delta to control the speed of the output signal. If you pass 1.0f, the | ||
1168 | resultant signal will be suitable for a 65536-Hz sampling rate (which | ||
1169 | isn't a commonly used rate). The most common sampling rates are 11025 Hz, | ||
1170 | 22050 Hz, 44100 Hz and 48000 Hz. You can work out the required delta value | ||
1171 | as follows: | ||
1172 | |||
1173 | delta = 65536.0f / sampling_rate; | ||
1174 | |||
1175 | If you then increase this value, the DUH will speed up and increase in | ||
1176 | pitch. If you decrease it, the DUH will slow down and decrease in pitch. | ||
1177 | |||
1178 | This function will attempt to render 'size' samples. In most cases it will | ||
1179 | succeed. However, if the end of the DUH is reached, it may render fewer. | ||
1180 | The number of samples rendered will be returned. Therefore, if the return | ||
1181 | value is less than the value of 'size' passed, you know the DUH has | ||
1182 | finished. It is safe to continue calling duh_sigrenderer_get_samples() if | ||
1183 | you wish, and it will continually return 0. | ||
1184 | |||
1185 | If the DUH_SIGRENDERER is a null pointer, this function will generate | ||
1186 | precisely 0 samples. If you pass NULL for 'samples', the function will | ||
1187 | behave exactly the same as if you provided a sample buffer, except the | ||
1188 | samples won't be stored anywhere and the function will execute very | ||
1189 | quickly. This can be used to skip ahead in the audio. | ||
1190 | |||
1191 | |||
1192 | long duh_render(DUH_SIGRENDERER *sigrenderer, | ||
1193 | int bits, int unsign, | ||
1194 | float volume, float delta, | ||
1195 | long size, void *sptr); | ||
1196 | |||
1197 | Generates some samples and converts them to an 8-bit or 16-bit format (see | ||
1198 | also duh_sigrenderer_get_samples()). Pass the DUH_SIGRENDERER as returned | ||
1199 | by duh_start_sigrenderer(). Pass the number of bits, which should be 8 or | ||
1200 | 16. If unsign is nonzero, the samples will be unsigned (centred on 0x80 or | ||
1201 | 0x8000 for 8 bits and 16 bits respectively). If unsign is zero, the | ||
1202 | samples will be signed. | ||
1203 | |||
1204 | Allegro's audio streams always take unsigned samples. 8-bit .wav files | ||
1205 | always take unsigned samples. 16-bit .wav files always take signed | ||
1206 | samples. | ||
1207 | |||
1208 | The volume and delta parameters work the same as for | ||
1209 | duh_sigrenderer_get_samples(). | ||
1210 | |||
1211 | This function will attempt to render 'size' samples. In most cases it will | ||
1212 | succeed. However, if the end of the DUH is reached, it may render fewer. | ||
1213 | The number of samples rendered will be returned. Therefore, if the return | ||
1214 | value is less than the value of 'size' passed, you know the DUH has | ||
1215 | finished. It is safe to continue calling duh_render() if you wish, and it | ||
1216 | will continually return 0. However, if you wish to do this, you will | ||
1217 | probably have to fill the rest of the buffer with silence, which is 0 for | ||
1218 | signed, 0x80 for 8-bit unsigned or 0x8000 for 16-bit unsigned. | ||
1219 | |||
1220 | The samples will be placed at sptr. Use an array of chars for 8 bits or an | ||
1221 | array of shorts for 16 bits. Stereo samples will be interleaved, left | ||
1222 | first. Your array should contain at least (size * n_channels) elements of | ||
1223 | the appropriate bit resolution. | ||
1224 | |||
1225 | From an aesthetic standpoint if nothing else, it is wise to use the C | ||
1226 | qualifiers 'signed' or 'unsigned' depending on whether the samples are | ||
1227 | signed or unsigned. This is also convenient if you wish to process the | ||
1228 | samples further yourself. | ||
1229 | |||
1230 | If the DUH_SIGRENDERER is a null pointer, this function will generate | ||
1231 | precisely 0 samples. Unlike with duh_sigrenderer_get_samples(), you must | ||
1232 | specify a sample buffer. | ||
1233 | |||
1234 | |||
1235 | void duh_end_sigrenderer(DUH_SIGRENDERER *dr); | ||
1236 | |||
1237 | Terminates a DUH_SIGRENDERER. Be sure to call this when you've finished | ||
1238 | with one. You can safely pass a null pointer. | ||
1239 | |||
1240 | |||
1241 | ******************************** | ||
1242 | *** Allegro Packfile Support *** | ||
1243 | ******************************** | ||
1244 | |||
1245 | |||
1246 | void dumb_register_packfiles(void); | ||
1247 | |||
1248 | This function registers the Allegro PACKFILE input module for use by | ||
1249 | DUMBFILEs. PACKFILE structs and their corresponding functions, as defined | ||
1250 | by Allegro's header file allegro.h, will be used internally for all | ||
1251 | DUMBFILE input (unless opened with dumbfile_open_ex()). | ||
1252 | |||
1253 | This must be called before dumbfile_open() is used, or else an alternative | ||
1254 | system must be registered (see register_dumbfile_system() and | ||
1255 | dumb_register_stdfiles()). Note that you don't have to call this function | ||
1256 | in order to load datafiles that contain music. | ||
1257 | |||
1258 | |||
1259 | DUMBFILE *dumbfile_open_packfile(PACKFILE *p); | ||
1260 | |||
1261 | If you have an Allegro PACKFILE struct representing an open file, you can | ||
1262 | call this if you wish to read from it using a DUMBFILE. This is useful | ||
1263 | when you need to pass a DUMBFILE struct to a library function, to read an | ||
1264 | embedded music file for example. When you close the DUMBFILE, you can | ||
1265 | continue using the PACKFILE struct to read what follows the embedded data. | ||
1266 | |||
1267 | |||
1268 | DUMBFILE *dumbfile_from_packfile(PACKFILE *p); | ||
1269 | |||
1270 | This function is the same as dumbfile_open_packfile(), except it will | ||
1271 | check if p is NULL, and arrange for pack_fclose() to be called on the | ||
1272 | PACKFILE when you close the DUMBFILE. It can be seen as a function for | ||
1273 | converting a PACKFILE to a DUMBFILE, but it will only work for a PACKFILE | ||
1274 | you obtained with pack_fopen(), not pack_fopen_chunk(). If this function | ||
1275 | fails, which may happen if memory is short, then the PACKFILE will be | ||
1276 | closed immediately, so you need not worry about potential memory leaks or | ||
1277 | files being left open when this happens. | ||
1278 | |||
1279 | The following is typical usage, and will open the compressed file foo.bin: | ||
1280 | |||
1281 | DUMBFILE *f = dumbfile_from_packfile(pack_fopen("foo.bin", | ||
1282 | F_READ_PACKED)); | ||
1283 | |||
1284 | This differs from calling dumb_register_packfiles() and dumbfile_open() in | ||
1285 | that the latter will only read uncompressed files (and is thus a method | ||
1286 | suitable for reading music modules). | ||
1287 | |||
1288 | |||
1289 | *********************************************** | ||
1290 | *** Allegro Datafile Registration Functions *** | ||
1291 | *********************************************** | ||
1292 | |||
1293 | |||
1294 | void dumb_register_dat_it(long type); | ||
1295 | |||
1296 | If you wish to embed an IT file in an Allegro datafile, it is recommended | ||
1297 | that you use "IT " for the type. The grabber will have a box for the type | ||
1298 | when you insert a new object. The grabber will treat the IT file as binary | ||
1299 | data, which means the datafile will contain an exact copy of the IT file | ||
1300 | on disk. | ||
1301 | |||
1302 | You must then call dumb_register_dat_it(DUMB_DAT_IT) in your program | ||
1303 | before you load the datafile. Once you've done this, you'll be able to | ||
1304 | access the DUH using the usual datafile[n].dat notation. You do not need | ||
1305 | to call unload_duh() on this DUH; unload_datafile() will do that for you. | ||
1306 | |||
1307 | If you are using a different type for whatever reason, you can use | ||
1308 | Allegro's DAT_ID() macro for encoding it and passing it to this function. | ||
1309 | For example: | ||
1310 | |||
1311 | dumb_register_dat_it(DAT_ID('B','L','A','H')); | ||
1312 | |||
1313 | Assuming you used the recommended type, the following example iterates | ||
1314 | through all the ITs in disan.dat: | ||
1315 | |||
1316 | DATAFILE *dat; | ||
1317 | int n; | ||
1318 | |||
1319 | dumb_register_dat_it(); | ||
1320 | dat = load_datafile("disan.dat"); | ||
1321 | |||
1322 | for (n = 0; dat[n].type != DAT_END; n++) { | ||
1323 | if (dat[n].type == DUMB_DAT_IT) { | ||
1324 | DUH *duh = dat[n].dat; | ||
1325 | /* Insert code here to play 'duh' or whatever you want to do. */ | ||
1326 | } | ||
1327 | } | ||
1328 | |||
1329 | unload_datafile(dat); | ||
1330 | |||
1331 | |||
1332 | void dumb_register_dat_xm(long type); | ||
1333 | |||
1334 | Inserting an XM file in an Allegro datafile is the same as inserting an IT | ||
1335 | file, except that the recommended type is "XM ", the registration | ||
1336 | function is dumb_register_dat_xm(), and the macro DUMB_DAT_XM is provided | ||
1337 | for the type. The intuitive process of substituting XM for IT in the above | ||
1338 | method will work. | ||
1339 | |||
1340 | |||
1341 | void dumb_register_dat_s3m(long type); | ||
1342 | |||
1343 | Inserting an S3M file in an Allegro datafile is the same as inserting an | ||
1344 | IT file, except that the recommended type is "S3M ", the registration | ||
1345 | function is dumb_register_dat_s3m(), and the macro DUMB_DAT_S3M is | ||
1346 | provided for the type. The intuitive process of substituting S3M for IT in | ||
1347 | the above method will work. | ||
1348 | |||
1349 | |||
1350 | void dumb_register_dat_mod(long type); | ||
1351 | |||
1352 | Inserting a MOD file in an Allegro datafile is the same as inserting an IT | ||
1353 | file, except that the recommended type is "MOD ", the registration | ||
1354 | function is dumb_register_dat_mod(), and the macro DUMB_DAT_MOD is | ||
1355 | provided for the type. The intuitive process of substituting MOD for IT in | ||
1356 | the above method will work. | ||
1357 | |||
1358 | |||
1359 | **************************************** | ||
1360 | *** Sample Buffer Allocation Helpers *** | ||
1361 | **************************************** | ||
1362 | |||
1363 | |||
1364 | Many parts of DUMB require sample buffers allocated in a special way. A | ||
1365 | pointer to one looks like this: | ||
1366 | |||
1367 | sample_t **samples; | ||
1368 | |||
1369 | and it can be indexed as follows: | ||
1370 | |||
1371 | samples[channel_number][sample_position] | ||
1372 | |||
1373 | where 0 <= channel_number < n_channels | ||
1374 | and 0 <= sample_position < length. | ||
1375 | |||
1376 | The following helpers will allocate and deallocate such buffers for you. | ||
1377 | They will not initialise them, and DUMB always writes into these buffers | ||
1378 | by adding to what's already there, so you will generally have to call | ||
1379 | dumb_silence() too. | ||
1380 | |||
1381 | |||
1382 | sample_t **create_sample_buffer(int n_channels, long length); | ||
1383 | |||
1384 | This will allocate a sample buffer to hold the specified number of samples | ||
1385 | for the specified number of channels. Don't forget to check the return | ||
1386 | value! | ||
1387 | |||
1388 | You will generally have to initialise the buffer by calling | ||
1389 | dumb_silence(); the channels will be stored consecutively in memory, so | ||
1390 | the following technique is officially supported: | ||
1391 | |||
1392 | dumb_silence(samples[0], n_channels * length); | ||
1393 | |||
1394 | See dumb_silence() for general information on what this function does. | ||
1395 | |||
1396 | |||
1397 | void destroy_sample_buffer(sample_t **samples); | ||
1398 | |||
1399 | This function does the obvious: it frees up a sample buffer when you've | ||
1400 | finished with it. It is safe to pass a null pointer to this function. | ||
1401 | |||
1402 | |||
1403 | ************************ | ||
1404 | *** Silencing Helper *** | ||
1405 | ************************ | ||
1406 | |||
1407 | |||
1408 | void dumb_silence(sample_t *samples, long length); | ||
1409 | |||
1410 | This function simply stores 'length' samples' worth of silence in the | ||
1411 | array. It is typically used straight after allocating a sample buffer with | ||
1412 | create_sample_buffer(). | ||
1413 | |||
1414 | |||
1415 | ************************** | ||
1416 | *** Resampling Helpers *** | ||
1417 | ************************** | ||
1418 | |||
1419 | |||
1420 | Please forgive the odd section name; it has to do with DUMB's internal | ||
1421 | structure and the fact that the resampling algorithm is there not just for | ||
1422 | use in rendering module files but for use anywhere that a waveform needs | ||
1423 | resampling. Unfortunately DUMB's resampling algorithm is not ready to be | ||
1424 | documented and used yet. However, one thing can be documented, and that's | ||
1425 | the global variable controlling the resampling quality. | ||
1426 | |||
1427 | (Ironically, even this variable has changed! See deprec.txt for | ||
1428 | information on what it used to do.) | ||
1429 | |||
1430 | |||
1431 | int dumb_resampling_quality; | ||
1432 | |||
1433 | Allows you to control the quality of all resampling that takes place. This | ||
1434 | may be set to any DUMB_RQ_* constant (except DUMB_RQ_N_LEVELS). Higher | ||
1435 | values will sound better, but lower values will use up less processor | ||
1436 | time. You may compare any two DUMB_RQ_* constants or values using the | ||
1437 | integer inequalities <, <=, > and >=; higher numbers represent higher- | ||
1438 | quality algorithms. | ||
1439 | |||
1440 | #define DUMB_RQ_ALIASING | ||
1441 | |||
1442 | | --___ 'Aliasing' has very noticeable and usually unwanted | ||
1443 | |__--- __ overtones. It will occasionally produce acceptable | ||
1444 | | ___-- results for noisy (impure) samples (or for cheap | ||
1445 | speakers!), but usually you will want to pay for | ||
1446 | the extra processor time, which isn't much, and go for linear | ||
1447 | interpolation. | ||
1448 | |||
1449 | #define DUMB_RQ_LINEAR | ||
1450 | |||
1451 | | __ Linear interpolation is a pretty good algorithm in most | ||
1452 | | / \ /\ cases. When resampling down a few octaves, however, you | ||
1453 | |/ \/ \__ may begin to notice unwanted high frequencies. You can | ||
1454 | reduce these by switching to cubic interpolation, but it | ||
1455 | will cost you some processor time. | ||
1456 | |||
1457 | #define DUMB_RQ_CUBIC | ||
1458 | |||
1459 | Cubic interpolation looks like a smooth curve to the eye, and will | ||
1460 | produce good results in most cases. At present this is the highest | ||
1461 | quality offered by DUMB, and also the default. While this may seem | ||
1462 | extravagant, GCC 3.x and an AthlonXP handle it quite well - and the | ||
1463 | general trend is for processors to get better! | ||
1464 | |||
1465 | #define DUMB_RQ_N_LEVELS | ||
1466 | |||
1467 | This represents the number of resampling quality levels DUMB provides. | ||
1468 | Values of dumb_resampling_quality from 0 to DUMB_RQ_N_LEVELS - 1 are | ||
1469 | valid. You can use this constant if you wish to offer the resampling | ||
1470 | quality as an option for the user. | ||
1471 | |||
1472 | |||
1473 | ************************************* | ||
1474 | *** Allegro DUH Playing Functions *** | ||
1475 | ************************************* | ||
1476 | |||
1477 | |||
1478 | The functions in this section allow you to play back a DUH through | ||
1479 | Allegro's sound system. You must call Allegro's install_sound() function | ||
1480 | before you use them. | ||
1481 | |||
1482 | |||
1483 | AL_DUH_PLAYER *al_start_duh(DUH *duh, int n_channels, long pos, | ||
1484 | float volume, long bufsize, int freq); | ||
1485 | |||
1486 | Starts playing the specified DUH. | ||
1487 | |||
1488 | An AL_DUH_PLAYER represents one instance of the DUH playing. If you wish, | ||
1489 | you can have two or more AL_DUH_PLAYERs going at the same time, for the | ||
1490 | same DUH or for different ones. Each uses one of Allegro's audio streams | ||
1491 | and hence one voice. The voice will be given priority 255 initially, so a | ||
1492 | build-up of sound effects will not cause your music streams to cut off (as | ||
1493 | long as you don't give all your sound effects priority 255!). You can | ||
1494 | change the priority of a stream with al_duh_set_priority(). See Allegro's | ||
1495 | documentation for more information on how voice priorities work. | ||
1496 | |||
1497 | At present, n_channels can either be 1 or 2 for monaural or stereo | ||
1498 | respectively. If you use the debugging library, your program will abort if | ||
1499 | other values are passed; otherwise weird things will happen. | ||
1500 | |||
1501 | The DUH will start playing from position 'pos'. 0 represents the start of | ||
1502 | the DUH, and 65536 represents one second. Unlike other music systems, DUMB | ||
1503 | will always make sure every note is there right from the start. In other | ||
1504 | words, you can start a DUH at a point halfway through a long note, and you | ||
1505 | will still hear the long note. | ||
1506 | |||
1507 | The volume is a float. 1.0f is the pseudo-maximum. If you pass 1.0f, any | ||
1508 | properly designed DUH file will play nice and loud, but will not clip. You | ||
1509 | can pass a greater volume if you like, but be prepared for clipping to | ||
1510 | occur. Of course you can pass smaller values to play the DUH more quietly, | ||
1511 | and this will also resolve clipping issues in badly designed DUH files. | ||
1512 | |||
1513 | You will need to pass the AL_DUH_PLAYER to other functions when you need | ||
1514 | to stop or pause the DUH, change its volume, or otherwise modify the way | ||
1515 | it is playing. You will also need to pass it to al_poll_duh() at regular | ||
1516 | intervals; if the sound is choppy, try calling al_poll_duh() more often. | ||
1517 | |||
1518 | 'bufsize' is the number of samples that will be rendered at once. 1024 is | ||
1519 | a suitable value for most purposes. The greater this is, the less often | ||
1520 | you will have to call al_poll_duh() - but when al_poll_duh() decides to | ||
1521 | fill the buffer, it will take longer doing so. If your game exhibits | ||
1522 | regular brief freezes, try reducing the buffer size. If the sound is | ||
1523 | choppy, however, you may have to increase it. | ||
1524 | |||
1525 | 'freq' specifies the sampling frequency at which the DUH should be | ||
1526 | rendered. At present there is no (official and portable) way of knowing | ||
1527 | the frequency at which Allegro is mixing - but if you do know that | ||
1528 | frequency, passing it here will give the highest quality sound. If you | ||
1529 | reduce it, the DUH will sound less crisp but use less processor time. | ||
1530 | |||
1531 | When you have finished, you must pass the AL_DUH_PLAYER to al_stop_duh() | ||
1532 | to free up memory. Do not destroy the DUH beforehand. | ||
1533 | |||
1534 | There is no real need to check the return value from this function. The | ||
1535 | other functions can be called safely with null pointers, so if there is a | ||
1536 | problem, your music will simply not play. | ||
1537 | |||
1538 | |||
1539 | void al_stop_duh(AL_DUH_PLAYER *dp); | ||
1540 | |||
1541 | This will stop an AL_DUH_PLAYER. You must call this when you have finished | ||
1542 | with it, before destroying the DUH. The pointer will no longer be valid on | ||
1543 | return from this function. | ||
1544 | |||
1545 | |||
1546 | void al_pause_duh(AL_DUH_PLAYER *dp); | ||
1547 | |||
1548 | This will pause an AL_DUH_PLAYER. Use al_resume_duh() when you want it to | ||
1549 | continue. You can safely call al_poll_duh() while the music is paused, and | ||
1550 | it will do nothing. | ||
1551 | |||
1552 | |||
1553 | void al_resume_duh(AL_DUH_PLAYER *dp); | ||
1554 | |||
1555 | Causes a paused AL_DUH_PLAYER to resume playing (see al_pause_duh()). | ||
1556 | |||
1557 | |||
1558 | void al_duh_set_priority(AL_DUH_PLAYER *dp, int priority); | ||
1559 | |||
1560 | This will set the priority of the audio stream underlying an | ||
1561 | AL_DUH_PLAYER. The priority is an integer ranging from 0 to 255. When | ||
1562 | too many samples play at the same time, those with lower priorities will | ||
1563 | be cut. 128 is the usual default with Allegro, but DUMB overrides the | ||
1564 | default for all AL_DUH_PLAYER structs: they will be set up initially with | ||
1565 | priority 255, so your music won't be cut (unless you play too many other | ||
1566 | streams or samples with priority 255). See Allegro's documentation for | ||
1567 | more information on priorities. | ||
1568 | |||
1569 | |||
1570 | void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume); | ||
1571 | |||
1572 | This will set the volume of an AL_DUH_PLAYER. See al_start_duh() for | ||
1573 | details on the volume parameter. | ||
1574 | |||
1575 | |||
1576 | int al_poll_duh(AL_DUH_PLAYER *dp); | ||
1577 | |||
1578 | An AL_DUH_PLAYER is not interrupt-driven. That means it will not play by | ||
1579 | itself. You must keep it alive from your main program. Call this function | ||
1580 | at regular intervals. If the sound crackles, try calling it more often. | ||
1581 | (There is nothing you can do if Windows decides to play with the hard | ||
1582 | disk; that will make your sound crackle no matter what you do.) | ||
1583 | |||
1584 | Normally this function will return zero. However, if it returns nonzero, | ||
1585 | that means the AL_DUH_PLAYER will not generate any more sound. Indeed the | ||
1586 | underlying audio stream and DUH_SIGRENDERER have been destroyed. When this | ||
1587 | happens, you can call al_stop_duh() whenever you wish - but you do not | ||
1588 | have to. Note that this function will wait two buffers' worth of samples | ||
1589 | before taking this action, allowing Allegro to mix the trailing sound | ||
1590 | before the audio stream is destroyed. This is an attempt to make sure your | ||
1591 | music does not get cut off prematurely, and it should work when using | ||
1592 | Allegro's mixer (the only option on DOS, the default on Linux as far as I | ||
1593 | know, but not the default on Windows). That said, if you immediately call | ||
1594 | Allegro's remove_sound() or exit your program, the music may get cut off. | ||
1595 | If you are using another mixer and experience problems, let me know (but I | ||
1596 | don't guarantee to be able to come up with an elegant solution, i.e. it | ||
1597 | might not get fixed). | ||
1598 | |||
1599 | In case you were wondering, it is not safe on all platforms to call | ||
1600 | al_poll_duh() from an interrupt context (that means an Allegro timer | ||
1601 | handler). Not only is no part of DUMB locked in memory, but many parts of | ||
1602 | DUMB allocate and free their memory on a call-by-call basis! Remember that | ||
1603 | any disk access that occurs in interrupt context is likely to crash the | ||
1604 | machine; this is explained more fully in howto.txt. This limitation only | ||
1605 | applies to DOS at present, and is due to the fact that the DOS file access | ||
1606 | functions are not re-entrant. | ||
1607 | |||
1608 | Multitasking systems are generally safe. If you are sure you don't want to | ||
1609 | target DOS, you can call al_poll_duh() from inside a timer handler, but I | ||
1610 | recommend including a construction like the following! | ||
1611 | |||
1612 | #ifdef ALLEGRO_DOS | ||
1613 | #error calling al_poll_duh() from a timer handler will not work in DOS! | ||
1614 | #endif | ||
1615 | |||
1616 | Furthermore, if you call al_poll_duh() from inside a timer handler, you | ||
1617 | must use a semaphore or other threading mechanism to make sure it is not | ||
1618 | executing when you call al_stop_duh(). If you don't know what a semaphore | ||
1619 | is, for Heaven's sake follow my advice and call al_poll_duh() from your | ||
1620 | main loop! | ||
1621 | |||
1622 | |||
1623 | long al_duh_get_position(AL_DUH_PLAYER *dp); | ||
1624 | |||
1625 | Tells you what position an AL_DUH_PLAYER is up to, or -1 if it is invalid | ||
1626 | (perhaps owing to lack of memory). As usual, 65536 is one second. Note | ||
1627 | that this is a whole number, whereas a fractional part is stored | ||
1628 | internally; the sample will not be continuous if you terminate the | ||
1629 | AL_DUH_PLAYER and then reinitiate it with the same position. Furthermore, | ||
1630 | note that Allegro will not have mixed in all the sound up to this point; | ||
1631 | if you wait for this to reach a certain position and then terminate the | ||
1632 | AL_DUH_PLAYER, the sound will cut off too early. Please contact me if you | ||
1633 | need to get around this. | ||
1634 | |||
1635 | |||
1636 | AL_DUH_PLAYER *al_duh_encapsulate_sigrenderer | ||
1637 | (DUH_SIGRENDERER *sigrenderer, float volume, long bufsize, int freq); | ||
1638 | |||
1639 | If you have a DUH_SIGRENDERER, and would like to start playing music from | ||
1640 | it through an Allegro audio stream, use this function. Beware that it may | ||
1641 | return NULL, in which case you will have to call duh_end_sigrenderer() | ||
1642 | yourself instead of relying on the encapsulating AL_DUH_PLAYER to do it | ||
1643 | for you. | ||
1644 | |||
1645 | |||
1646 | DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp); | ||
1647 | |||
1648 | This returns the DUH_SIGRENDERER contained in an AL_DUH_PLAYER, useful for | ||
1649 | controlling playback, installing callbacks, etc. | ||
1650 | |||
1651 | |||
1652 | DUH_SIGRENDERER *al_duh_decompose_to_sigrenderer(AL_DUH_PLAYER *dp); | ||
1653 | |||
1654 | This destroys an AL_DUH_PLAYER, but preserves the DUH_SIGRENDERER it | ||
1655 | contains, and returns it to you. You can then continue rendering samples | ||
1656 | from the DUH_SIGRENDERER and do whatever you like with them. | ||
1657 | |||
1658 | |||
1659 | ********************* | ||
1660 | *** Thread Safety *** | ||
1661 | ********************* | ||
1662 | |||
1663 | |||
1664 | The following points should pretty much sum up the essence of DUMB's thread | ||
1665 | safety. If I haven't covered the one thing you'd like to do, please don't | ||
1666 | hesitate to ask about it. | ||
1667 | |||
1668 | DOs: | ||
1669 | |||
1670 | - You may load and use multiple DUHs in separate threads. | ||
1671 | |||
1672 | - You may change dumb_resampling_quality and dumb_it_max_to_mix while another | ||
1673 | thread is generating samples. | ||
1674 | |||
1675 | DON'Ts: | ||
1676 | |||
1677 | - You may not generate samples from the same DUH in multiple threads, even if | ||
1678 | you are using separate DUH_RENDERERs (separate AL_DUH_PLAYERS). | ||
1679 | |||
1680 | |||
1681 | ****************** | ||
1682 | *** Conclusion *** | ||
1683 | ****************** | ||
1684 | |||
1685 | |||
1686 | "DUMB is the bestest music player in the world because ..." | ||
1687 | |||
1688 | Complete this sentence in fifteen words or fewer and receive a free copy of | ||
1689 | DUMB! (Your Internet Service Provider may issue charges for your connection, | ||
1690 | required for download of the Product. Your electricity supplier may issue | ||
1691 | charges for the electricity consumed in writing the Product to a Permanent | ||
1692 | Storage Device. You may have been charged for a Permanent Storage Device on | ||
1693 | which to store the Product.) | ||
1694 | |||
1695 | |||
1696 | Ben Davis | ||
1697 | entheh@users.sf.net | ||
1698 | IRC EFnet #dumb | ||
1699 | See readme.txt for details on using IRC. | ||