/*  _______         ____    __         ___    ___
 * \    _  \       \    /  \  /       \   \  /   /     '   '  '
 *  |  | \  \       |  |    ||         |   \/   |       .      .
 *  |  |  |  |      |  |    ||         ||\  /|  |
 *  |  |  |  |      |  |    ||         || \/ |  |       '  '  '
 *  |  |  |  |      |  |    ||         ||    |  |       .      .
 *  |  |_/  /        \  \__//          ||    |  |
 * /_______/edicated  \____/niversal  /__\  /____\usic /|  .  . astardisation
 *                                                    /  \
 *                                                   / .  \
 * 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 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, please 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, please use dumb.h
   instead.


2. You need to link with DUMB's library file or files. If you are compiling
   with gcc from the command line on DOS or Windows, you need to add the
   following to your 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: /MD /link aldmd.lib dumbd.lib
      If you are not using Allegro: /MD /link dumbd.lib

   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, in case 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 do any of its own file input. You have to tell
   it how to read files. Don't worry, it's easy. Simply call the following
   function at the beginning of your program, but after your atexit() call:

      dumb_register_stdfiles();

   This tells DUMB to use ordinary stdio FILE structs for reading and writing
   files. 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. If you are loading datafiles, your
   executable might be slightly smaller if you use dumb_register_packfiles().
   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 (you
   will be reminded that you can remove the function call).


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

      install_sound(DIGI_AUTODETECT, MIDI_NONE, NULL);

   You may like to initialise a MIDI driver though; see Allegro's docs for
   details. Put this line after allegro_init().


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, so do not
   try. DUMB's functions provide everything you need; if you disagree, 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("a_one.it");
      myduh = dumb_load_xm("a_two.xm");
      myduh = dumb_load_s3m("a_one_two.s3m");
      myduh = dumb_load_mod("three_four.mod");

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

   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 file that
   consumes a lot of processor time), but beware that any streaming audio
   format is likely to be substantially larger than the module file you
   generate it from, and formats like MP3 will be lower quality. You might
   not be able to hear the difference between the MP3 and the original, but
   many people can and don't like it, so please consider them. I'm one of
   them. If you really want to use a lossy compression format, I highly
   recommend Ogg Vorbis:

      http://www.vorbis.com/

   But I digress.

   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 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. Set 'pos' to 0
   to play from the beginning; each time you add 65536, you will have
   advanced one second into the piece. 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
   the Allegro function set_volume_per_voice() first.

   'bufsize' can generally be set to 1024. 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.

   Having called 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);

   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.

   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. Note also
   that you will be going against the spirit of Allegro, namely that games
   should compile on all platforms, including DOS.

   So why not kill DOS? 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 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.

   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:

   extern int dumb_resampling_quality;
   extern int dumb_it_max_to_mix;

   dumb_resampling_quality can be anything from 0 to 4, and controls the
   quality at which samples are rendered. Resampling is the term given to the
   process of adjusting a sample's pitch (in this context). This value
   defaults to 4, which sounds nice but takes a lot of processor power. Try
   reducing it if you have an older computer 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.

   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 nor will they be important.


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(). The length
   returned by duh_get_length() is in the same units as the aforementioned
   position; see dumb.txt for more information on this function. 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.


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.

   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
   memory was short when trying to play it, or it was a quirky music file
   with no music in it (technically one with an empty order list). This
   happens regardless of whether 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's generated:

   typedef int sample_t;

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

   void duh_sigrenderer_set_callback(DUH_SIGRENDERER *sigrenderer,
                              DUH_SIGRENDERER_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.

   The samples array is two-dimensional. Refer to it as follows:

      samples[channel_number][sample_position]

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

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

   To remove the callback function, pass NULL to
   duh_sigrenderer_set_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 a DUH 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);
   }

   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().

   WARNING: after passing a pointer to an "encapsulate" function, do not use
            that pointer again. (More specifically, do not use it again if
            the function returns NULL, because the function will have
            destroyed the pointer if this happens, to help prevent memory
            leaks.) There will be a "get" function with which you can obtain
            the original pointer if it is still valid, or NULL otherwise.

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

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

   long duh_render_signal(
      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_render_signal(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.

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.

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(DUMB_DAT_IT);
      dumb_register_dat_xm(DUMB_DAT_XM);
      dumb_register_dat_s3m(DUMB_DAT_S3M);
      dumb_register_dat_mod(DUMB_DAT_MOD);

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

   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;

   Note that 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.


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 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_render_signal(DUH_SIGRENDERER *sigrenderer,
      float volume, float delta,
      long size, 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_render_signal() will
generate samples in the internal 32-bit format, with each channel in a
separate array; duh_render() will convert to 8 or 16 bits, signed or
unsigned, with stereo samples interleaved, 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
shorts. If 'unsign' is zero, the samples will be centred on 0, suitably
stored in an array of signed chars or 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_render_signal(), 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_render_signal() you will have to use the following functions:

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

   void dumb_silence(sample_t *samples, long length);

create_sample_buffer() allocates the channels sequentially in memory, so the
following technique is valid:

   sample_t **samples = create_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_render_signal() mixes what it renders with the existing contents of the
buffer.

The return values from duh_render() and duh_render_signal() 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_render_signal() 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.


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


Please see dumb.txt for an API reference. This 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
IRC EFnet #dumb
See readme.txt for details on using IRC.
