File: howto.txt

package info (click to toggle)
libdumb 1:0.9.3-6
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, jessie, jessie-kfreebsd, sid, stretch
  • size: 1,056 kB
  • ctags: 1,270
  • sloc: ansic: 9,403; makefile: 290; sh: 23
file content (864 lines) | stat: -rw-r--r-- 39,150 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
/*  _______         ____    __         ___    ___
 * \    _  \       \    /  \  /       \   \  /   /       '   '  '
 *  |  | \  \       |  |    ||         |   \/   |         .      .
 *  |  |  |  |      |  |    ||         ||\  /|  |
 *  |  |  |  |      |  |    ||         || \/ |  |         '  '  '
 *  |  |  |  |      |  |    ||         ||    |  |         .      .
 *  |  |_/  /        \  \__//          ||    |  |
 * /_______/ynamic    \____/niversal  /__\  /____\usic   /|  .  . ibliotheque
 *                                                      /  \
 *                                                     / .  \
 * howto.txt - How To Use DUMB.                       / / \  \
 *                                                   | <  /   \_
 * See readme.txt for general information on         |  \/ /\   /
 * DUMB and how to set it up.                         \_  /  > /
 *                                                      | \ / /
 *                                                      |  ' /
 *                                                       \__/
 */


********************
*** Introduction ***
********************


Welcome to the DUMB How-To! It is assumed here that you have already set DUMB
up on your system, with or without Allegro. If not, please see readme.txt.


*********************************
*** Adding music to your game ***
*********************************


These instructions will help you add a piece of music to your game, assuming
your music is stored in a stand-alone IT, XM, S3M or MOD file. If you wish to
use a different method (such as putting the music file in an Allegro
datafile), please follow these instructions first, test your program, and
then follow the instructions further down for adapting your code.


1. You need to include DUMB's header file. If you have Allegro, add the
   following line to the top of your source file (or at the top of each file
   where you wish to use DUMB):

      #include <aldumb.h>

   If you do not have Allegro or do not wish to use it, use dumb.h instead.


2. You need to link with DUMB's library file or files. If you are compiling
   with GCC from a command line on any platform, you need to add the
   following to the command line:

      If you are using Allegro: -laldmd -ldumbd
      If you are not using Allegro: -ldumbd

   If you are using MSVC from the command line:

      If you are using Allegro: /link aldmd.lib dumbd.lib
      If you are not using Allegro: /link dumbd.lib

   With MSVC, you must also add /MD to the command line when compiling (not
   when linking).

   Note that -laldmd or aldmd.lib must PRECEDE alleg.lib, -lalleg_s,
   `allegro-config --libs`, or whatever you are already using to link with
   Allegro. For MSVC users, the /MD flag selects the multithreaded DLL
   implementation of the standard libraries; since DUMB is statically linked,
   you have to use the same library DUMB uses. You would also need this flag
   to link statically with Allegro; if you already have it, there's no need
   to put it twice.

   (If anyone would like to contribute instructions for doing the above using
   MSVC's IDE, please contact me. Contact details are at the end of this
   file.)

   If you are using RHIDE, go to Options -> Libraries. You will need to type
   'aldmd' and 'dumbd' in two boxes, making sure 'aldmd' comes above whatever
   you are using to link with Allegro (or just put 'dumbd' if you are not
   using Allegro). Make sure the box next to each of these libraries is
   checked.

   The above are the debugging libraries. It is VERY HIGHLY RECOMMENDED that
   you use the debugging libraries at first. The reason is as follows.
   Although DUMB is supposedly robust against corrupt music files and things
   like lack of memory, it will NOT tolerate programmer error. If you write
   faulty code, DUMB will probably crash rather than returning an error code
   for you. However, the debugging libraries will abort in many cases,
   enabling you to find out what the cause is.

   Once your program is up and running reliably, you can replace 'aldmd' with
   'aldmb' and 'dumbd' with 'dumb'. Don't forget to do this, or DUMB will be
   a lot slower than it should be!


3. As you use DUMB, it may claim system resources (memory in particular). You
   will need to arrange for these resources to be freed at the end. Doing so
   is very easy. Simply write the following line at the top of your main
   function, but below allegro_init() if you are using Allegro:

      atexit(&dumb_exit);

   This arranges for the function dumb_exit() to be called when your program
   exits; you do not need to call dumb_exit() yourself. This method is
   preferable to calling dumb_exit() manually, as it will free resources even
   if your program aborts unexpectedly.

   If you are happy with this, please skip ahead to Step 4. If you are
   interested in alternative methods, read on, but read on carefully.

   In fact it mostly doesn't matter where you put the above atexit() line,
   provided it gets called only once, and before you do anything with DUMB.
   If you are using DUMB with Allegro, it is recommended that you write the
   functions in this order:

      allegro_init();
      atexit(&dumb_exit);

   And then you must NOT call allegro_exit() yourself (because it has to be
   called after dumb_exit()). Alternatively, if you prefer not to use
   atexit() (or you cannot), you will have to do the following before
   exiting:

      dumb_exit();
      allegro_exit();


4. DUMB does not automatically know how to open files. If you are loading
   stand-alone files, you have to tell it how to open them. Don't worry, it's
   easy. Simply call the following function near the beginning of your
   program, after your atexit() call:

      dumb_register_stdfiles();

   Once you've done this, a stdio FILE will be opened each time DUMB wants to
   open a file (specifically, when dumbfile_open() is called). If you are
   using Allegro and would rather DUMB used PACKFILEs, call the following
   function instead:

      dumb_register_packfiles();

   In the latter case, DUMB will be affected by any password you set with
   packfile_password() in the same way that other PACKFILEs are.

   Note that the procedure for loading datafiles with embedded music is
   independent of these two functions; even if you will be loading datafiles,
   you can use either of these functions. dumb_register_stdfiles() will
   probably be faster. If you are only ever going to load datafiles and never
   stand-alone files, you can actually leave this step out; but I would
   recommend you put this in, test your code with a stand-alone file, then
   follow the instructions in the next section in order to adapt your code to
   use the datafile (the instructions will remind you that you can remove the
   function call).


5. If you are using Allegro, you will have to initialise Allegro's sound
   system. In most cases the following line will do the job:

      install_sound(DIGI_AUTODETECT, MIDI_NONE, NULL);

   Put this line after allegro_init(). See Allegro's documentation if you
   want to initialise a MIDI driver too.


6. All pieces of music are stored in memory in DUH structs. To handle these,
   you must define pointers to them. Such pointers look like this:

      DUH *myduh;

   You can of course replace 'myduh' with anything you like. If you are
   unfamiliar with pointers, please see ptr.txt. It is very important that
   you understand these if you wish to use DUMB correctly.

   You do not have direct access to the contents of a DUH struct, because
   they are liable to change. It is hoped that DUMB's functions will provide
   everything you need; if you need something else, please let me know and I
   shall see what I can do. Contact details are at the end of this file.

   Given the above definition, you can load a piece of music using one of the
   following lines, depending on what file format you want to load:

      myduh = dumb_load_it_quick("a_one.it");
      myduh = dumb_load_xm_quick("a_two.xm");
      myduh = dumb_load_s3m_quick("a_one_two.s3m");
      myduh = dumb_load_mod_quick("three_four.mod");

   You can use relative or absolute paths as normal. You should always use
   forward slash (/), not backslash (\), when coding in C and similar
   languages.

   There are non-"quick" versions of the functions too; for information on
   what this means, please see dumb.txt.

   Every piece of music you load must be unloaded when you've finished with
   it. When you type the above line in, it is good practice to type the
   following line in at the same time, but put it at the end of the program:

      unload_duh(myduh);

   You will now be able to use the DUH struct anywhere in between the two
   lines you just added. There is no need to check the return value; if the
   DUH failed to load for one reason or another (this could be due to lack of
   memory as well as the file not being there), then DUMB will do nothing -
   safely.


7. From this step onwards, it will be assumed you're using Allegro. If not,
   please read these steps anyway, and then see the section entitled
   "Rendering music into a buffer". You will have to write your own playback
   code using whatever sound output system is available. Alternatively you
   may like to write data to a file (especially if you have a module that
   consumes a lot of processor time).

   In order to play the DUH you loaded, you need to define a pointer to an
   AL_DUH_PLAYER struct:

      AL_DUH_PLAYER *dp;

   Two of the functions you will need are prototyped as follows:

      AL_DUH_PLAYER *al_start_duh(DUH *duh, int n_channels, long pos,
                                  float volume, long bufsize, int freq);

      void al_stop_duh(AL_DUH_PLAYER *dp);

   As you can see, al_start_duh() returns a pointer to an AL_DUH_PLAYER
   struct when you call it. You then pass this pointer to all the other
   functions. Again, if it is a NULL pointer for whatever reason (usually
   lack of memory), DUMB will safely do nothing. When you call al_stop_duh(),
   the pointer becomes invalid and you should not use it again; if there's
   any risk of the pointer being used again, it is wise to set it to NULL at
   this point. You can reassign the variable with a new call to
   al_start_duh() of course.

   Set 'n_channels' to 1 or 2 for mono or stereo respectively. Note that this
   parameter has nothing to do with the number of samples that can play at
   once in a music module. Set 'pos' to 0 to play from the beginning; each
   time you add 65536, you will have advanced one second into the piece. (If
   you use the non-"quick" loaders, seeking like this will be faster.) As a
   general rule, set the volume to 1.0f and adjust it later if the music is
   too loud or too quiet - but see Allegro's set_volume_per_voice() function
   first.

   'bufsize' can generally be set to 4096. If your music stutters, try
   increasing it; if your game freezes periodically, try reducing it. Find a
   happy medium. Set 'freq' to 48000 for the best quality, though 44100 will
   do in most cases. 22050 will be fine for a lot of music, though 11025 may
   sound muffled. You can choose any other value, higher, lower or in
   between. If your music stutters, and increasing 'bufsize' doesn't fix it,
   try reducing this value.

   Once you have put in a call to al_start_duh(), it is good practice to
   insert the call to al_stop_duh() at the same time. You must call
   al_stop_duh() before the DUH is unloaded (unload_duh(), Step 6 above).

   Don't get impetuous, your program is not ready yet! Proceed to Step 8.


8. DUMB does not play music in the background for you; if you were expecting
   it to do so, please see the explanation at the end of this step. For your
   music to be played, you have to call another function at regular
   intervals. Here is its prototype:

      int al_poll_duh(AL_DUH_PLAYER *dp);

   Do NOT call this function from inside a timer function unless you really
   know what you are doing. The reasons why this is bad are explained
   further down. You should call it from your main program.

   Simply writing the following line will be sufficient in general, if you
   have a variable 'dp' that points to your AL_DUH_PLAYER struct.

      al_poll_duh(dp);

   As a general rule, calling this once for each logic update will do the
   trick. If, however, you are executing time-consuming algorithms such as
   software 3D rendering, you may wish to insert calls to this function in
   the middle of those algorithms. You cannot call this function too often
   (within reason); if it has nothing to do it will return immediately.

   Exactly how often you need to call the function depends on the values for
   'bufsize' and 'freq' that you passed to al_start_duh():

      n = freq / bufsize;

   You have to call al_poll_duh() at least n times a second. Do not hesitate
   to call it more often for safety; if the sound stutters, you may need to
   do just that. (Or you may need to increase the buffer size or reduce the
   quality settings; the only way to find out is to try.)

   For now, don't worry about al_poll_duh()'s return value. As soon as you
   need it, it will be explained.

   If you are happy, please skip to Step 9. If you were expecting DUMB to
   play your music in the background, please read on.

   The natural way to play music in the background on most operating systems
   nowadays is to use threads. DOS was not built with multithreading in mind,
   and its system operations (notably disk access) assume they will only be
   used from a single thread.

   Interrupts are the next best thing to threads. A DOS hardware interrupt
   could be triggered at any moment, and a handler function will be called.
   This is how Allegro's timer functions work. Unfortunately, what you can do
   inside an interrupt handler is very limited. For one thing, all code and
   data used by the handler must be locked in memory; if not, it could get
   written to disk (virtual memory). If the main program was accessing the
   disk when it got interrupted, the system would then die a horrible death.
   This precludes the possibility of allocating extra memory inside the
   handler, and DUMB does a lot of that in al_poll_duh().

   Given DUMB's architecture, which cannot change for reasons which will
   become apparent in future versions, this renders it impossible to come up
   with a portable solution for making DUMB play music in the background.
   Having said that, if you wish to write your own wrapper for al_poll_duh()
   and use it in a thread, there is nothing stopping you. If you do do this,
   you will have to be very careful when stopping the music; see the
   description of al_poll_duh() in dumb.txt for more information.

   So why not remove DOS support from DUMB? It is all too common a practice
   among programmers to quote the phrase, "DOS is as dead as the dodo."
   Despite being a decidedly derisible demonstation of the dreary device of
   alliteration, it shows a distinct lack of experience. Many embedded
   systems still use DOS because it provides hardware access capabilities and
   real-time possibilities unparalleled by any current multitasking operating
   system. For an argument closer to home, I used to use RHIDE for DOS before
   I switched to Linux, and I have not found a single Freeware Windows IDE
   that measures up to RHIDE. I'm sure many people are in the same boat, and
   really appreciate DUMB's DOS port.

   That, and the fact that you don't have to use the DOS support just because
   it is there. Shame on you for not thinking this through. :)

   We will not be removing DOS support from DUMB. Any blind suggestions to do
   so will be met with fiery flames. You have been warned.


9. Test your program!

   If you have trouble, check through the above steps to make sure you didn't
   miss one out. Refer to faq.txt to see if your problem is addressed there.
   If you still have trouble, contact me; details are at the end of this
   file.


**********************************
*** Controlling music playback ***
**********************************


Here I describe some common operations you may wish to perform. The method
for doing so will seem a bit strange sometimes, as will the names of the
structs. However, there is a reason behind everything. If you would like to
do more exotic things, or better understand some of the methods used here,
then see dumb.txt, which covers everything from the ground up.


To control playback quality:

   #define DUMB_RQ_ALIASING
   #define DUMB_RQ_LINEAR
   #define DUMB_RQ_CUBIC
   #define DUMB_RQ_N_LEVELS
   extern int dumb_resampling_quality;
   extern int dumb_it_max_to_mix;

   Please note that dumb_resampling_quality was changed in DUMB v0.9.2. See
   deprec.txt for more details on the change.

   dumb_resampling_quality can be set to any of the DUMB_RQ_* constants
   (except DUMB_RQ_N_LEVELS; see below). Resampling is the term given to the
   process of adjusting a sample's pitch (in this context).
   dumb_resampling_quality defaults to DUMB_RQ_CUBIC, which sounds nice but
   may take too much processor power on slower systems. Try reducing it if
   you have an older computer (less than 300 MHz) or if you are trying to mix
   an insane number of samples (or both!). See dumb.txt for details on what
   the different values actually do.

   If you wish to give this option to your user, you can use
   DUMB_RQ_N_LEVELS. All the values from 0 to DUMB_RQ_N_LEVELS - 1 will be
   valid resampling levels. If a value outside this range is chosen, it is
   not the end of the world; DUMB will behave as if you had chosen the value
   at whichever extreme you went beyond.

   dumb_it_max_to_mix, defaulting to 64, is the maximum number of samples
   DUMB will ever mix together when playing an IT, XM, S3M or MOD file.
   Unlike many other music systems, DUMB will still keep track of all samples
   (up to a fixed maximum of 256 of them, roughly speaking), and then will
   just render as many of them as this variable permits, starting with the
   loudest ones. When samples are cut or come back in, the exact timings will
   not generally be predictable - but it is hoped this will not be important!

   dumb_it_max_to_mix applies to each currently playing module file
   independently. So if you set it to 64, but render two modules
   simultaneously, DUMB could end up mixing up to 128 samples.


To pause and resume playback, set the volume, get the current playback
position, or get the length of time a DUH will play for before either looping
or freezing (effect F00 in XM and MOD files, which means no new notes will be
played but any existing notes will continue):

   void al_pause_duh(AL_DUH_PLAYER *dp);
   void al_resume_duh(AL_DUH_PLAYER *dp);
   void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume);
   long al_duh_get_position(AL_DUH_PLAYER *dp);

   long duh_get_length(DUH *duh);

   These functions are pretty self-explanatory. The volume passed to
   al_duh_set_volume() and the position returned by al_duh_get_position() are
   in the same units as those you passed to al_start_duh(). Be careful with
   al_duh_get_position(); it will return a position slightly ahead of what
   you can hear, because the system has to keep ahead slightly to avoid
   stuttering.

   duh_get_length() returns the playback length, in the same units as the
   aforementioned position, but beware: the length will not be known if you
   have used the "quick" loader functions, and this function will return -1.
   If you want to calculate the length later, use
   dumb_it_do_initial_runthrough(). See dumb.txt for more information.


To prevent the music from looping and/or freezing:

   DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp);
   DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer);

   void dumb_it_set_loop_callback(DUMB_IT_SIGRENDERER *sigrenderer,
      int (*callback)(void *data), void *data);
   void dumb_it_set_xm_speed_zero_callback(DUMB_IT_SIGRENDERER *sigrenderer,
      int (*callback)(void *data), void *data);

   int dumb_it_callback_terminate(void *data);

   If you are unfamiliar with function pointers, please see fnptr.txt.

   Note that these functions apply to IT, XM, S3M and MOD files - not just to
   IT files. This holds true throughout DUMB, for all functions with "it" in
   the name. The xm_speed_zero event can only occur with XM and MOD files.

   The first two functions will return a pointer to a struct contained by the
   struct you pass. This system is necessary to ensure that these operations
   are possible when not using Allegro. Typically you would write the
   following code:

   {
      DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp);
      DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer);
      dumb_it_set_loop_callback(itsr, &dumb_it_callback_terminate, NULL);
      dumb_it_set_xm_speed_zero_callback
                               (itsr, &dumb_it_callback_terminate, NULL);
   }

   Once you have done this, the return value of al_poll_duh() becomes
   significant. It will be 0 as long as the music is playing. When the music
   stops, al_poll_duh() will return nonzero. You can call al_stop_duh() and
   do something else as soon as you wish, but calling al_poll_duh() some more
   will not do any harm.

   al_poll_duh() will also return 1 if the music could not be loaded, or if
   memory was short when trying to play it, or if it was a quirky music file
   with no music in it (technically one with an empty order list). This
   happens regardless of whether or not you execute the above code to disable
   looping. Normally you shouldn't need to worry about this.

   To undo the above and make DUMB loop or freeze again, pass NULL instead of
   &dumb_it_callback_terminate. If you would like to fade on looping, or loop
   a finite number of times, or display a message when looping, or whatever,
   you will have to write your own callback function. In this case, please
   see dumb.txt.

   Note that the above code can safely be applied for a DUH that doesn't
   contain a music module but contains some other kind of music.
   duh_get_it_sigrenderer() will return NULL, and the code will do nothing.


To analyse the audio as it is generated:

   typedef int sample_t;

   typedef void (*DUH_SIGRENDERER_SAMPLE_ANALYSER_CALLBACK)(void *data,
                const sample_t *const *samples, int n_channels, long length);

   void duh_sigrenderer_set_sample_analyser_callback(
              DUH_SIGRENDERER *sigrenderer,
              DUH_SIGRENDERER_SAMPLE_ANALYSER_CALLBACK callback, void *data);

   If the above confuses you, see fnptr.txt. These functions, along with
   al_duh_get_sigrenderer() from the last section, enable you to register a
   callback function. Every time some samples are generated, they will be
   passed to this function. This enables you to display an oscilloscope or
   spectrum analyser, for example.

   Beware: your callback function may occasionally be called with
   samples == NULL. This means the main program has decided to skip through
   the music without generating any data. You should handle this case
   elegantly, typically by returning immediately, but you may wish to make a
   note of the fact that the music is being skipped, for whatever reason.

   Beware again: if the main program ever calls
   duh_sigrenderer_generate_samples() on a buffer that isn't all silence,
   this callback function will be passed the existing buffer after mixing,
   and thus it will include the original data. This will not be an issue if
   you stick to duh_render(), which always starts with a buffer filled with
   silence.

   The samples array is two-dimensional, but the first index will always be 0
   for mono and stereo sound. Refer to it as follows:

      n_channels == 1: samples[0][sample_position]
      n_channels == 2: samples[0][sample_position*2+channel_number]

   where 0 <= channel_number < n_channels,
     and 0 <= sample_position < length.

   There is a more thorough explanation in dumb.txt.

   In addition you can pass any 'data' pointer you like to
   duh_sigrenderer_set_sample_analyser_callback(), and this pointer will be
   relayed to your callback function each time.

   To remove the callback function, pass NULL to
   duh_sigrenderer_set_sample_analyser_callback().


Everything below this point assumes some knowledge of how a music module is
constructed. If you do not have this knowledge, talk to whoever is writing
music for you, or download a tracking program and play with it (see
readme.txt).


To start playing an IT, XM, S3M or MOD from an arbitrary order number (the
default being 0, the beginning of the song), use the following:

   DUH_SIGRENDERER *dumb_it_start_at_order
                                  (DUH *duh, int n_channels, int startorder);
   AL_DUH_PLAYER *al_duh_encapsulate_sigrenderer
        (DUH_SIGRENDERER *sigrenderer, float volume, long bufsize, int freq);

   The usage of these functions is as follows:

   {
      DUH_SIGRENDERER *sr = dumb_it_start_at_order
                                               (duh, n_channels, startorder);
      dp = al_duh_encapsulate_sigrenderer(sr, volume, bufsize, freq);
      if (!dp) duh_end_sigrenderer(sr);
   }

   Replace 'dp' with whatever your AL_DUH_PLAYER pointer is. You also need
   to insert suitable values for n_channels, startorder, volume, bufsize and
   freq. These have the same meaning as those passed to al_start_duh().

   Whenever you call al_duh_encapsulate_sigrenderer(), be sure to check the
   return value. If an AL_DUH_PLAYER was returned, then the encapsulated
   DUH_SIGRENDERER will be destroyed when you destroy the AL_DUH_PLAYER. If
   not, you will have to destroy the DUH_SIGRENDERER yourself. The above code
   includes this check.

   The above functions will fail (safely) if you try to use them with a DUH
   that contains a different type of music. No music will play.

   Notice that there is no 'pos' parameter. If you would like to skip through
   the music, you can use this function:

   long duh_sigrenderer_generate_samples(
      DUH_SIGRENDERER *sigrenderer,
      float volume, float delta,
      long size, sample_t **samples
   );

   Pass 0 for volume and NULL for samples, and this function will skip
   through the music nice and quickly. So insert the following between the
   two above statements:

      duh_sigrenderer_generate_samples(sr, 0, 65536.0f / freq, pos, NULL);

   Substitute for 'freq' and 'pos'. An explanation of the 'delta' parameter
   can be found further down in this file.

   Finally, note that duh_get_length() is only meaningful when you start
   playing music from order 0.


If an IT file contains Zxx effects, DUMB will generate MIDI messages, which
will control the low-pass resonant filters unless the IT file actively
specifies something else. In rare cases this may not be what the Zxx effects
were intended to do; if this is the case, you can block the MIDI messages as
follows. Note that this does NOT mean filters are disabled; if an instrument
specifies initial cut-off and resonance values, or has a filter envelope,
then filters will be applied. It only makes sense to use this procedure at
the beginning of playback.

   void dumb_it_set_midi_callback(DUMB_IT_SIGRENDERER *sigrenderer,
      int (*callback)(void *data, int channel, unsigned char byte),
      void *data);

   int dumb_it_callback_midi_block(void *data, int channel,
                                   unsigned char byte);

   Using some functions described in the previous section, we arrive at the
   following code:

   {
      DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp);
      DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer);
      dumb_it_set_midi_callback(itsr, &dumb_it_callback_midi_block, NULL);
   }

DUMB offers no way of disabling filters completely. Disabling filters is not
recommended as a means to reduce processor usage, as it will completely
damage any piece of music that uses the filters. If you want lower processor
consumption, use a piece of music that does not use filters.


Finally, DUMB offers a myriad of functions for querying and adjusting
module playback. Those beginning with "dumb_it_sd" operate on the
DUMB_IT_SIGDATA struct, which represents the piece of music before it starts
to play. Those beginning with "dumb_it_sr" operate on the DUMB_IT_SIGRENDERER
struct, which represents a currently playing instance of the music. Note that
duh_get_length(), described above, becomes meaningless after some of these
functions are used, although you can correct this by calling
dumb_it_build_checkpoints() again.

The method for getting a DUMB_IT_SIGRENDERER struct has already been given,
but the function prototypes are repeated here for convenience:

   DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp);
   DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer);

Getting a DUMB_IT_SIGDATA struct is simpler:

   DUMB_IT_SIGDATA *duh_get_it_sigdata(DUH *duh);

For a list of dumb_it_sd_*() and dumb_it_sr_*() functions, please see
dumb.txt. These functions are new, and may not provide exactly what you need;
if not, please let me know.


**************************************************
*** Embedding music files in Allegro datafiles ***
**************************************************


In this section it is assumed you are already reasonably familiar with how
Allegro datafiles are used. If not, please refer to Allegro's documentation.
At the time of writing, the documentation you need is off the beaten track,
so to speak, in allegro/tools/grabber.txt.

To add a piece of music to a datafile, you need to create an object of type
"IT  ", "XM  ", "S3M " or "MOD " (note the spaces used as padding, although
you do not need to type these into the grabber). Then grab the piece of music
in. The grabber will treat it as a binary object. Save the datafile as usual.


To use a piece of music you added to the datafile, follow these steps:


1. Before loading the datafile, call one or more of these functions,
   depending on which music format or formats you'd like to support:

      dumb_register_dat_it_quick(DUMB_DAT_IT);
      dumb_register_dat_xm_quick(DUMB_DAT_XM);
      dumb_register_dat_s3m_quick(DUMB_DAT_S3M);
      dumb_register_dat_mod_quick(DUMB_DAT_MOD);

   There are non-"quick" versions too.

   Remember, do not call multiple functions unless you want to support
   multiple formats. Calling more functions will add unused code to your
   executable.

   It is important that you call these before loading the datafile, since
   they tell Allegro how to load the respective files straight from datafiles
   in the future. They will not help Allegro interpret any module files that
   have already been loaded as binary objects. If you ever need to interpret
   a module that has been loaded in this fashion, have a look at
   dumbfile_open_memory() in dumb.txt.

   If for whatever reason your music objects are identified by a different
   type in the datafile, you can tell DUMB what that type is by changing the
   parameter to the registration function above. Use Allegro's DAT_ID()
   macro, e.g. DAT_ID('B','L','A','H'). This is not really recommended
   though, since it would prevent a hypothetical grabber plug-in from being
   able to play your music files. Use the above types if possible.


2. Whenever you need a pointer to a DUH struct, simply use the 'dat' field.
   Do this in the same way you would for a pointer to a BITMAP struct or
   anything else. If it makes you feel more comfortable, you can extract the
   pointer in advance:

      DATAFILE *dat = load_datafile("smurf.dat");
      if (!dat) abort(); /* There are much nicer ways of handling failure! */
      DUH *myduh = (DUH *)dat[GAME_MUSIC].dat;

   The explicit (DUH *) cast is only necessary for C++, not for C. However,
   it does no harm.

   Be sure that you do NOT call unload_duh() for anything stored in the
   datafile. These DUHs will be freed when you call unload_datafile(), and
   freeing them twice is practically guaranteed to crash your program. (But
   do call unload_duh() if you have used dumbfile_open_memory().)


3. If you only ever load music as part of a datafile, and you never load any
   stand-alone music files, you do not need to register a file input system
   for DUMB to use. If you followed the instructions for the first section
   you will have one of these two lines in your program:

      dumb_register_stdfiles();
      dumb_register_packfiles();

   You can safely delete this line - but only if you never load any
   stand-alone music files. The debugging library will bale you out if you
   delete it when you shouldn't; the optimised library won't.


*************************************
*** Rendering music into a buffer ***
*************************************


NOTE: much of the API formerly described in this section has been deprecated,
      and you will need to alter your code. See deprec.txt for details. If
      you are reading this section for the first time, you can ignore this
      note.

Rendering to a buffer is similar to playing using an AL_DUH_PLAYER. However,
you must use a DUH_SIGRENDERER struct instead. Here are the functions:

   DUH_SIGRENDERER *duh_start_sigrenderer
                               (DUH *duh, int sig, int n_channels, long pos);

   int duh_sigrenderer_get_n_channels(DUH_SIGRENDERER *sigrenderer);
   long duh_sigrenderer_get_position(DUH_SIGRENDERER *sigrenderer);

   long duh_sigrenderer_generate_samples(DUH_SIGRENDERER *sigrenderer,
                   float volume, float delta, long size, sample_t **samples);

   void duh_sigrenderer_get_current_sample(DUH_SIGRENDERER *sigrenderer,
                                            float volume, sample_t *samples);

   long duh_render(DUH_SIGRENDERER *sigrenderer,
     int bits, int unsign, float volume, float delta, long size, void *sptr);

   void duh_end_sigrenderer(DUH_SIGRENDERER *sigrenderer);

The parameters to duh_start_sigrenderer() have the same meanings as those to
al_start_duh(). However, note that the volume is not set at this stage. You
pass the desired volume each time you want to render a block. The 'sig'
parameter should be set to 0 for now.

Notice that there are two rendering functions.
duh_sigrenderer_generate_samples() will generate samples in the internal
32-bit format, with a normal range from -0x800000 to 0x7FFFFF; duh_render()
will convert to 8 or 16 bits, signed or unsigned. Both functions will
interleave stereo samples, left first.

When you call duh_render(), pass 8 or 16 for 'bits'. If you pass 8, 'sptr' is
expected to be an array of chars. If you pass 16, 'sptr' is expected to be an
array of shorts. Endianness therefore depends on the platform, and you should
not try to interpret 16-bit wave data as an array of chars (unless you're
writing highly system-specific code anyway). Because DUMB renders internally
with 32 bits, there is no significant speed increase in rendering an 8-bit
stream.

If you are rendering in stereo, make sure your 'sptr' array is twice as big!

If you set 'unsign' to a nonzero value, then the samples generated will be
centred on 0x80 or 0x8000, suitably stored in an array of unsigned chars or
unsigned shorts. If 'unsign' is zero, the samples will be centred on 0,
suitably stored in an array of signed chars or signed shorts. Note that 8-bit
WAV files are unsigned while 16-bit WAV files are signed. This convention was
used by the SoundBlaster 16 when receiving samples to be sent to the
speakers. If you wish to write 16-bit sample data to a WAV file, don't use
fwrite(); instead, take the shorts one at a time, split them up into chars as
follows, and write the chars to the file.

   short sptr[n];
   char lsb = (char)sptr[n];
   char msb = (char)(sptr[n] >> 8);

For a 16-bit WAV file, write the LSB (less significant byte) first.

The following applies equally to duh_render() and
duh_sigrenderer_generate_samples(), except where otherwise stated.

If you set 'delta' to 1.0f, the sound generated will be suitable for playback
at 65536 Hz. Increasing 'delta' causes the wave to speed up, given a constant
sampling rate for playback. Supposing you want to vary the playback sampling
rate but keep the pitch constant, here's the equation for 'delta':

   delta = 65536.0f / sampling_rate;

'size' is the number of samples you want rendered. For duh_render(), they
will be rendered into an array which you pass as 'sptr'. Note that stereo
samples count as one; so if you set n_channels to 2, your array must contain
(2 * size) elements.

For duh_sigrenderer_generate_samples() you will have to use the following
functions:

   sample_t **allocate_sample_buffer(int n_channels, long length);
   void destroy_sample_buffer(sample_t **samples);

   void dumb_silence(sample_t *samples, long length);

allocate_sample_buffer() allocates the buffers sequentially in memory in the
hypothetical future case where there are more than two channels, so the
following technique is valid and officially supported:

   sample_t **samples = allocate_sample_buffer(n_channels, length);
   dumb_silence(samples[0], n_channels * length);

It is necessary to fill the buffer with silence like this because
duh_sigrenderer_generate_samples() mixes what it renders with the existing
contents of the buffer.

The return values from duh_render() and duh_sigrenderer_generate_samples()
tell you how many samples were actually generated. In most cases, this will
be the same as the 'size' parameter. However, if you reach the end of the DUH
(which will happen if you disable looping or freezing as described further
up), this function will return less. When that happens, you can assume the
stream has finished. In the case of duh_render(), the remainder of the array
will not have been initialised, so you either have to initialise it yourself
or avoid using it.

If for whatever reason duh_start_sigrenderer() returns NULL, then
duh_render() and duh_sigrenderer_generate_samples() will generate exactly 0
samples, duh_sigrenderer_get_n_channels() will return 0,
duh_sigrenderer_get_position() will return -1, and duh_end_sigrenderer() will
safely do nothing.

duh_sigrenderer_get_current_sample() is used by the click removal algorithm.
It simply returns the current sample without updating the position, so you
can use it to sniff what is coming next.


*********************
*** Miscellaneous ***
*********************


Please see dumb.txt for an API reference and for information on thread safety
with DUMB. The API reference has been stripped down, since some functions and
variables are subject to change. If something does not appear in dumb.txt,
please do not use it.


******************
*** Conclusion ***
******************


If you have any difficulties, or if you use DUMB successfully, please don't
hesitate to contact me (see below).

Enjoy!


Ben Davis
entheh@users.sf.net