qzdoom/dumb/docs/dumb.txt

/*  _______         ____    __         ___    ___
 * \    _  \       \    /  \  /       \   \  /   /       '   '  '
 *  |  | \  \       |  |    ||         |   \/   |         .      .
 *  |  |  |  |      |  |    ||         ||\  /|  |
 *  |  |  |  |      |  |    ||         || \/ |  |         '  '  '
 *  |  |  |  |      |  |    ||         ||    |  |         .      .
 *  |  |_/  /        \  \__//          ||    |  |
 * /_______/ynamic    \____/niversal  /__\  /____\usic   /|  .  . ibliotheque
 *                                                      /  \
 *                                                     / .  \
 * dumb.txt - DUMB library reference.                 / / \  \
 *                                                   | <  /   \_
 * See readme.txt for general information on         |  \/ /\   /
 * DUMB and how to set it up.                         \_  /  > /
 *                                                      | \ / /
 * If you are new to DUMB, see howto.txt.               |  ' /
 *                                                       \__/
 */


***********************************
*** Include Files and Libraries ***
***********************************


dumb.h

   Include this if you only want the core DUMB library functions. You will
   be able to load music files and render them into memory buffers at your
   own pace. The core library is completely portable, and as such does not
   access hardware; you must relay the sound data to the sound card yourself.
   A stdio file input module is available, but you must actively register it
   if you wish to use it (see dumb_register_stdfiles()); if you do not
   register it, it will not be linked into your executable. You must register
   it, or a DUMBFILE module of your own, in order to load stand-alone music
   files.

   Optimised: -ldumb   or  /link dumb.lib
   Debugging: -ldumbd  or  /link dumbd.lib


aldumb.h

   Include this if you wish to use DUMB with Allegro. This will provide you
   with functions to play DUHs back through Allegro's audio streams and embed
   music files in Allegro datafiles. A file input module using Allegro's
   packfiles is provided; you have a choice between this and the stdio
   module (or provide one of your own). You will be able to load datafiles
   containing music files no matter which file input module you register, or
   even if you register no file input module. However, you must register a
   file input module in order to load stand-alone files.

   Optimised: -laldmb -ldumb -lalleg  or  /link aldmb.lib alleg.lib dumb.lib
   Debugging: -laldmd -ldumbd -lalld  or  /link aldmd.lib alld.lib dumbd.lib

   aldmb or aldmd must be linked in first, so the symbols can be resolved
   when linking in the other two libraries.


***************************
*** Version Information ***
***************************


#define DUMB_MAJOR_VERSION
#define DUMB_MINOR_VERSION
#define DUMB_REVISION_VERSION

   Numeric constants representing this version of DUMB. If this were version
   1.0, DUMB_MAJOR_VERSION would be 1 and DUMB_MINOR_VERSION would be 0.
   DUMB_REVISION_VERSION will be 0 on any significant releases, and will be
   incremented as releases with bugfixes and minor features are made.

   Typical usage:

      #if DUMB_MAJOR_VERSION < 1
      #error This add-on requires DUMB v1.0 or higher. Please upgrade.
      #endif


#define DUMB_VERSION

   A numeric constant which appears in the format MMmmrr when displayed in
   decimal (M for major, m for minor, r for revision). This is most useful
   for comparing version numbers; it has little other practical use.

   Typical usage:

      #if DUMB_VERSION < 801
      #error This game requires DUMB v0.8.1 or higher. Please upgrade.
      #endif

      #if DUMB_VERSION < 10002
      #error This game requires DUMB v1.0.2 or higher. Please upgrade.
      #endif


#define DUMB_VERSION_STR

   String constant representing this version of DUMB. If this were Version
   1.0, DUMB_VERSION_STR would be "1.0". DUMB_REVISION_VERSION will only
   appear on the end if it is nonzero; then DUMB_VERSION_STR might be
   "1.0.1".


#define DUMB_NAME

   A string identifying DUMB and its version. If this were Version 1.0,
   DUMB_NAME might be "DUMB v1.0". This constant is suitable for use in your
   Credits screen if you wish to acknowledge the use of DUMB there.


#define DUMB_YEAR
#define DUMB_MONTH
#define DUMB_DAY

   Numeric constants representing the year, month and day of this release of
   DUMB. All four digits are included in the year. Please note that
   DUMB_MONTH and DUMB_DAY were inadvertently swapped in the v0.8 release.


#define DUMB_YEAR_STR4
#define DUMB_YEAR_STR2
#define DUMB_MONTH_STR2
#define DUMB_MONTH_STR1
#define DUMB_DAY_STR2
#define DUMB_DAY_STR1

   String constants representing the year, month and day of this release of
   DUMB. DUMB_MONTH_STR2 and DUMB_DAY_STR2 include a leading zero if the
   month or day respectively are less than ten; the STR1 variations do not.
   DUMB_YEAR_STR2 contains only the two rightmost digits of the year, while
   DUMB_YEAR_STR4 contains all four. I recommend using DUMB_YEAR_STR4,
   especially so soon after the turn of the century (indeed the millennium).
   However, it is a matter of personal preference which you use.

   Please note that the month and day were inadvertently swapped in the v0.8
   release.


#define DUMB_DATE

   A numeric constant that appears in the form yyyymmdd when displayed in
   decimal. This is most useful for comparing release dates; it has little
   other practical use.

   WARNING: The month and day were inadvertently swapped in the v0.8 release.
            Please do not compare this constant against any date in 2002. In
            any case, DUMB_VERSION is probably more useful for this purpose.


#define DUMB_DATE_STR

   The date as a string. The format is "d.m.yyyy", with dots used as
   separators, the day written first, four digits for the year, and no
   leading zeros on the day or month. This is my preferred format. If you
   don't like it, you can construct your own format using the other
   constants. For example, "mm/dd/yy" could be constructed as follows:

      DUMB_MONTH_STR2 "/" DUMB_DAY_STR2 "/" DUMB_YEAR_STR2

   Please note that the month and day were inadvertently swapped in the v0.8
   release.


*************************
*** Basic Sample Type ***
*************************


typedef int sample_t;

   DUMB works internally with 32-bit integer samples, with a 'normal range'
   from -0x800000 to 0x7FFFFF (as of DUMB v0.9.2; previously they ranged from
   -0x8000 to 0x7FFF). Any samples that exceed this range will eventually be
   clipped, and could cause integer overflow in extreme cases.


***********************************
*** Library Clean-up Management ***
***********************************


int dumb_atexit(void (*proc)(void));

   Registers a function to be called at the end of your program. You can
   register multiple functions to be called, and the one you register last
   will be called first. If you try to register the same function twice, the
   second attempt will have no effect.

   See fnptr.txt for help with function pointers.

   You must call dumb_exit() before exiting your program for this to work
   properly. The library itself registers functions with dumb_atexit(), so it
   is important to call dumb_exit() even if you do not use dumb_atexit()
   yourself.

   This function will return zero on success. It will return zero when
   trying to install the same function twice. If it fails through lack of
   memory, it will return nonzero. Generally you can ignore the return code;
   in the worst case some memory will not be freed at the end. If it is
   crucial that your function be called (e.g. to shut down some hardware or
   save critical data), then you should call your function manually at the
   end of the program instead of registering it here - or use the stdlib
   function atexit(), guaranteed under ANSI C to succeed for at least 32
   functions.


void dumb_exit(void);

   You should call this before exiting your program if you have used any part
   of DUMB in the program. Some parts of DUMB will allocate memory, and this
   function will free it all up.

   More specifically, this function will call any functions that have been
   registered with dumb_atexit(). If a part of DUMB needs shutting down, the
   shutdown procedure will have been registered in this way.

   dumb_exit() will, of course, also call any functions you registered with
   dumb_atexit() yourself.

   After a call to dumb_exit(), the list of functions is erased. If you are
   not ready to exit your program, you can start using DUMB anew as if your
   program had just started. (Note that not everything will be reset in
   practice - dumb_resampling_quality will retain whatever you set it to, for
   example, though you should not assume it will.)

   If you only need to call dumb_exit() once at the end of the program, you
   can use the following to register dumb_exit() with stdlib.h atexit():

      #include <stdlib.h>

      atexit(&dumb_exit);

   Then dumb_exit() will be called for you when your program exits. This is
   the recommended method, since it will ensure clean-up even if your program
   aborts. You should only call dumb_exit() manually if you need to shut DUMB
   down prematurely, or if atexit() is unavailable for one reason or another.


*****************************
*** Sequential File Input ***
*****************************


   DUMB provides a strictly sequential file input system which uses the
   DUMBFILE struct. "Strictly sequential" means you cannot seek backwards.
   However, the system will keep track of how many bytes you have read,
   enabling you to seek forwards. DUMBFILEs provide a convenient error
   detection system, so you do not have to check the return value from every
   function call in the way you do with the ANSI C functions.

   Note that DUMBFILEs cannot be used for output, nor can they be used
   portably for text files.

   If an error occurs when reading data from a DUMBFILE, the DUMBFILE will
   become inoperative. All subsequent activities on the DUMBFILE will return
   error codes without attempting to read from the file. The position in the
   file will also be forgotten. You can find out if this has happened at any
   stage with the dumbfile_error() function. You are still required to close
   the DUMBFILE, and the return value from dumbfile_close() will tell you if
   an error has occurred.

   This system allows you to input large chunks of your file, neither
   checking every return value nor wasting time accessing a file that has
   already experienced an error. However, before you allocate an amount of
   memory or read in a quantity of data depending on previous input from the
   file, you should always check that such input was valid. In particular you
   should avoid passing zero or negative numbers to malloc(), and avoid
   passing negative numbers to dumbfile_skip() and dumbfile_getnc().

   DUMBFILEs can be hooked. In other words, you can specify your own
   functions to do the work of reading from a file. While DUMB contains two
   modules for this purpose, it does not set them up for you automatically.
   In most cases you must register one of these modules yourself, or provide
   your own module. See register_dumbfile_system(), dumb_register_stdfiles()
   and dumb_register_packfiles().


void register_dumbfile_system(DUMBFILE_SYSTEM *dfs);

   Use this function to register a set of functions for use by the DUMBFILEs
   (a DUMBFILE system). The DUMBFILE_SYSTEM struct contains the following
   fields:

      void *(*open)(const char *filename);
      int (*skip)(void *f, long n);
      int (*getc)(void *f);
      long (*getnc)(char *ptr, long n, void *f);
      void (*close)(void *f);

   See fnptr.txt for help with function pointers such as these.

   Your 'open' function should open the file specified and return a pointer
   to a struct representing the open file. This pointer will be passed to
   your other functions as 'f'. Your 'close' function should close the file
   and free all memory pointed to by 'f'. Note that the 'close' operation
   should never be able to fail; if you are calling a function with a return
   value, you can generally ignore it.

   Your 'getc' function should read one byte from the file and return its
   value in the range 0 to 255. If an error occurs, you should return -1. Do
   not worry about remembering that an error has occurred; DUMB will do that
   for you.

   'skip' is for skipping parts of the file, and should skip n bytes,
   returning 0 on success or any other number on failure. 'getnc' should read
   n bytes from the file, store them at 'ptr', and return the number of bytes
   read (n on success, fewer on failure). However, these two functions are
   optional, and you should only provide them if the operations can be done
   more efficiently than with repeated calls to your 'getc' function. If this
   is not the case, specify NULL for 'skip', 'getnc' or both, and DUMB will
   use your 'getc' function to do the work.

   Once you have written all your functions, you need to create a
   DUMBFILE_SYSTEM struct to hold them, and pass its pointer to
   register_dumbfile_system().

   The DUMBFILE_SYSTEM struct must be permanent. In other words, it must be
   either global or static, and you should not modify it later. DUMB will not
   make its own copy.

   You will most likely create your own struct to represent the open file,
   but do not be tempted to specify that struct in the function prototypes
   and pacify the compiler warnings by casting your function pointers. There
   exist computer systems where a (void *) pointer and a (MY_STRUCT *)
   pointer are represented differently in memory, and a cast of such a
   pointer causes a tangible conversion to take place. If you cast the
   function pointers, the computer cannot know when such a conversion is
   necessary. Instead, use the following structure:

      int myskip(void *f, long n)
      {
         FILE *file = f;
         /* Do some stuff with 'file' */
         return something;
      }

   If you need examples, have a look at the two existing DUMBFILE systems in
   dumb/src/core/stdfile.c and dumb/src/allegro/packfile.c.


DUMBFILE *dumbfile_open(const char *filename);

   Open the specified file for input. You must pass the DUMBFILE pointer
   whenever you wish to operate on this file. When you have finished with the
   file, you must pass it to dumbfile_close().

   Before you use this function, make sure you have registered a DUMBFILE
   system. See register_dumbfile_system(), dumb_register_stdfiles() and
   dumb_register_packfiles().

   You must check the return value from this function. If it is NULL, the
   file could not be opened, and you must not pass the DUMBFILE to any other
   function. The debugging library will abort if you get this wrong; the
   optimised library will act weird.


DUMBFILE *dumbfile_open_ex(void *file, DUMBFILE_SYSTEM *dfs);

   This function is provided for more specialised use. You should create a
   DUMBFILE_SYSTEM specially for the purpose. Its 'open' field is irrelevant;
   for neatness, set it to NULL, unless you are using this DUMBFILE_SYSTEM
   with register_dumbfile_system() as well.

   When you have called this function, the DUMBFILE struct it returned can be
   used as normal. The specified DUMBFILE_SYSTEM will be used for all input,
   with 'file' passed to your 'skip', 'getc' and 'getnc' functions as 'f'.
   This can be used, for example, to read from an already open file.

   Note that the position will always be initialised to 0 for this DUMBFILE.
   This means for example that offsets in the file do not need adjusting when
   embedding data in a larger file.

   There are two ways to use this function. If you want 'file' to persist
   after using a DUMBFILE returned by this function, you should make sure the
   'close' field in the DUMBFILE is set to NULL. When the DUMBFILE is closed,
   'file' will be left alone, and you can and should deal with it yourself
   when the DUMBFILE has been closed.

   Alternatively, you can provide a 'close' function to get rid of 'file' for
   you when the DUMBFILE is closed. If you do this, you should not otherwise
   use 'file' after a call to this function.

   If dumbfile_open_ex() has to return NULL, owing to lack of memory, then
   your 'close' function will be called if provided. In other words, if you
   have provided a 'close' function, then you no longer need to worry about
   'file' whether this function succeeds or not.

   See dumb/src/helpers/stdfile.c and dumb/src/allegro/packfile.c for
   examples of how to use this function. Neither provides a 'close' function,
   so I hope my explanation here will suffice. If not, please feel free to
   contact me so I can make the explanation clearer and help you do what you
   want to do. Contact details are at the end of this file.


long dumbfile_pos(DUMBFILE *f);

   Returns the number of bytes read from the DUMBFILE (or skipped) since it
   was opened, or -1 if an error has occurred while reading.


int dumbfile_skip(DUMBFILE *f, long n);

   Skips n bytes of the specified DUMBFILE. Returns zero on success.


int dumbfile_getc(DUMBFILE *f);

   Reads one byte from the DUMBFILE and returns it in unsigned format (from 0
   to 255). If an error occurs, or occurred before, this function returns -1.


int dumbfile_igetw(DUMBFILE *f);

   Reads two bytes from the DUMBFILE and combines them into a word ranging
   from 0 to 65535. The first byte read is the least significant byte, as
   with Intel processors. This function returns -1 on error.


int dumbfile_mgetw(DUMBFILE *f);

   Reads two bytes from the DUMBFILE and combines them into a word ranging
   from 0 to 65535. The first byte read is the most significant byte, as
   with the Apple Macintosh. This function returns -1 on error.


long dumbfile_igetl(DUMBFILE *f);

   Reads four bytes from the DUMBFILE and combines them into a long integer
   ranging from -2147483648 to 2147483647. The first byte read is the least
   significant byte, as with Intel processors. This function returns -1 on
   error, but -1 is also a valid return value. After a call to this function,
   you can use dumbfile_error() to find out if an error occurred.


long dumbfile_mgetl(DUMBFILE *f);

   Reads four bytes from the DUMBFILE and combines them into a long integer
   ranging from -2147483648 to 2147483647. The first byte read is the most
   significant byte, as with the Apple Macintosh. This function returns -1 on
   error, but -1 is also a valid return value. After a call to this function,
   you can use dumbfile_error() to find out if an error occurred.


unsigned long dumbfile_cgetul(DUMBFILE *f);

   Reads an unsigned (nonnegative) integer from the DUMBFILE. The integer is
   stored in a condensed format where smaller numbers use less space:

           0 to 127         1 byte
         128 to 16383       2 bytes
       16384 to 2097151     3 bytes
     2097152 to 268435455   4 bytes
   268435456 to 4294967295  5 bytes

   This format is the same as that used for the times between notes in MIDI
   files.

   If an error occurs, this function returns (unsigned long)(-1), but that
   may be a valid return value. After a call to this function, you can use
   dumbfile_error() to find out if an error occurred.


signed long dumbfile_cgetsl(DUMBFILE *f);

   Reads a signed integer from the DUMBFILE. The integer is stored in a
   condensed format where numbers closer to zero use less space:

           -64 to 63          1 byte
         -8192 to 8191        2 bytes
      -1048576 to 1048575     3 bytes
    -134217728 to 134217727   4 bytes
   -2147483648 to 2147483647  5 bytes

   If an error occurs, this function returns -1, but -1 is also a valid
   return value. After a call to this function, you can use dumbfile_error()
   to find out if an error occurred.


long dumbfile_getnc(char *ptr, long n, DUMBFILE *f);

   Reads n bytes from the DUMBFILE and stores them at 'ptr'. Note that the
   pointer is to a series of chars. You may also use this function to read in
   a series of signed chars or unsigned chars (which are both officially
   distinct types from char), but do not use this to read ints, structs or
   any other data type from the file. Integers must be read one at a time
   using dumbfile_igetl(), dumbfile_cgetul(), etc. To load a struct in, you
   must read each field separately using an appropriate function for each
   one. For complicated data types, you can simplify this process by writing
   a function for each struct.

   dumbfile_getnc() returns the number of bytes successfully read, which will
   be less than n if an error occurs, and may be as low as zero. If
   dumbfile_getnc() returns -1, that means an error occurred on this DUMBFILE
   earlier, before this function was called.


int dumbfile_error(DUMBFILE *f);

   This function returns -1 if an error has occurred with the specified
   DUMBFILE, or 0 if all is well.


int dumbfile_close(DUMBFILE *f);

   This function closes the DUMBFILE, after which the pointer will be
   invalid. dumbfile_close() returns the value that dumbfile_error() would
   have returned, which is -1 if an error occurred while reading or 0
   otherwise. Regardless of the return value, the file will always be closed
   properly.


*******************************
*** stdio File Input Module ***
*******************************


void dumb_register_stdfiles(void);

   This function registers the stdio file input module for use by DUMBFILEs.
   FILE structs and their corresponding functions, as defined by the ANSI C
   header stdio.h, will be used internally for all DUMBFILE input (unless
   opened with dumbfile_open_ex()).

   This must be called before dumbfile_open() is used, or else an alternative
   system must be registered (see register_dumbfile_system() and
   dumb_register_packfiles()).


DUMBFILE *dumbfile_open_stdfile(FILE *p);

   If you have a stdio FILE struct representing an open file, you can call
   this if you wish to read from it using a DUMBFILE. This is useful when you
   need to pass a DUMBFILE struct to a library function, to read an embedded
   music file for example. When you close the DUMBFILE, you can continue
   using the FILE struct to read what follows the embedded data.


********************************
*** Memory File Input Module ***
********************************


DUMBFILE *dumbfile_open_memory(const char *data, long size);

   This function is useful if you have an image of a music file in memory.
   You might have such an image if you use dat2s to encode a datafile
   directly into the executable. Pass a pointer to the start of the memory,
   and the size of the image to make sure DUMB doesn't overrun the buffer.
   The resulting DUMBFILE will feed the contents of the image to you.

   Note that the pointer is of type 'char *'. Files are series of chars, and
   interpreting them directly as anything else isn't portable.


**********************
*** DUH Management ***
**********************


void unload_duh(DUH *duh);

   Removes a DUH from memory. You must call this for all DUHs you load,
   making sure they're not playing at the time.


long duh_get_length(DUH *duh);

   Returns the length of a DUH; 65536 represents one second. This value is
   calculated when the DUH is created, and this function simply lifts it from
   the struct. It may not truly correspond to the time for which the DUH will
   generate sound. For module files, it will represent the point at which the
   module first loops (or, in the case of some XM and MOD files, freezes).
   Any add-ons to DUMB will provide their own code for calculating this.

   The algorithm for calculating the length of a module file can be fooled,
   but only by very deliberate methods. In the early days, when modules could
   only be played by their editors and had to be exported to .wav or similar
   in order to be used elsewhere, musicians would sometimes make the player
   think it was looping when it wasn't in order to prevent their music from
   being exported properly. If the length of a module seems a lot less than
   it should be, the module is probably protected in this way.

   Getting around this protection reliably would be extremely difficult, but
   after considering it for a while I decided it would be better not to. The
   musician has a right to protect his or her music in this way, and I have
   no interest in actively breaking that protection.

   (On the other hand, some musicians were just showing off!)


***********************************
*** IT, XM, S3M and MOD Support ***
***********************************


int dumb_it_max_to_mix;

   Specifies the maximum number of samples DUMB will mix at any one time. The
   default number is 64. Regardless of this value, all samples will continue
   to be processed up to an internal maximum of 256 (roughly speaking; in
   fact it will process one sample for each channel plus up to 192 extra
   samples that are continuing to play owing to Impulse Tracker's New Note
   Actions), and samples that have been cut will sound again as soon as the
   congestion clears. Samples are given priority according to their final
   volume after all factors affecting the volume of a sample have been
   considered.

   If you play two or more modules at once, this value represents the
   maximum number of samples for each one. You will have to reduce it further
   if your computer cannot keep up.

   Despite the name, this variable controls XM, S3M and MOD files as well as
   IT files.


DUMB_IT_SIGDATA *duh_get_it_sigdata(DUH *duh);

   This function attempts to retrieve the DUMB_IT_SIGDATA struct from a DUH.
   This struct will exist for any IT, XM, S3M or MOD file, and you can use it
   to obtain or override module-specific information. If 'duh' is NULL, or if
   the DUH you pass contains something other than a music module, then this
   function will return NULL (which can safely be passed to any other
   function).


DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer);

   This function attempts to retrieve the DUMB_IT_SIGRENDERER struct from a
   DUH_SIGRENDERER. This struct will exist for any currently playing IT, XM,
   S3M or MOD file, and you can use it to obtain or override information
   specific to module playback. If 'sigrenderer' is NULL, or if the
   DUH_SIGRENDERER you pass is rendering something other than a music module,
   then this function will return NULL (which can safely be passed to any
   other function).


DUH_SIGRENDERER *dumb_it_start_at_order
                                  (DUH *duh, int n_channels, int startorder);

   This function, given a DUH containing an IT, XM, S3M or MOD file, will
   start playing it at the specified order. If the DUH does not contain a
   module, this function will fail and return NULL.

   Note that starting at an arbitrary order may result in missing notes or
   other playback oddities. It should be used primarily for modules that
   contain multiple songs that start on different orders. If you wish just to
   start some music in the middle, consider using duh_start_sigrenderer() or
   al_start_duh() with the pos parameter set appropriately.


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

   Installs a callback which will be called every time the module loops. You
   can pass any data pointer you like, and it will be passed to the callback
   for you. DUMB considers a file to loop when it reaches the end, or when a
   'Jump to order' effect (Bxx in both IT/S3M and XM/MOD) jumps to the same
   order or a preceding order. This can result in the loop callback being
   called when the module isn't really looping, but this only happens if the
   module has a very deliberate design. See duh_get_length() for further
   musings on this subject.

   If your callback returns nonzero, the music will stop abruptly. Samples
   will be cut, and the main program will be notified that the
   DUH_SIGRENDERER has ended.

   Alternatively, if you pass the DUMB_IT_SIGRENDERER for 'data', or
   otherwise arrange for it to be available to the callback, then you can
   call:

      dumb_it_sr_set_speed(sigrenderer, 0);

   from inside the callback, and this will cause the music to freeze but
   samples will be able to continue playing. The xm_speed_zero callback will
   NOT be called in this case (see below for information on this callback).
   Note also that setting the speed in this way will work equally for IT and
   S3M files, even though a 'speed zero' effect can only exist in XM and MOD
   files. Beware when using this method; samples might not fade at all!

   A helper callback, dumb_it_callback_terminate(), is provided; installing
   this will cause the music to terminate when it tries to loop for the first
   time.

   Pass NULL to remove the callback function; the module will then loop as
   normal.


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

   Installs a callback which is in many ways similar to the loop callback
   (see dumb_it_set_loop_callback()). This callback will be called whenever
   an F00 effect is encountered in a MOD or XM file, setting the speed to
   zero. If the callback returns nonzero, the music will terminate. If not,
   any currently playing samples will continue to play. You can pass any data
   pointer you like to this function, and it will be passed to your callback
   for you.

   The helper callback, dumb_it_callback_terminate(), will also work here;
   installing it will cause the music to terminate as soon as an F00 effect
   is encountered.

   Pass NULL to remove the callback function.


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

   Installs a callback function which will be called whenever MIDI data are
   generated by an IT file. (No other module formats are capable of
   generating MIDI data, so your callback will never be called.)

   Zxx macros will generate MIDI data. These are most often used to set the
   parameters for IT's low-pass resonant filters, and DUMB will handle these
   messages by itself by default. See Impulse Tracker's documentation for
   the MIDI messages that control filters. However, Zxx macros can be used
   to send any kind of MIDI data.

   If you wish to interpret MIDI messages yourself, you can use this
   callback. Note that the only MIDI messages generated by DUMB at present
   are from Zxx macros; there are no messages for note start, stop, or
   anything else.

   If you return 1 from this callback, DUMB will subsequently ignore the byte
   of MIDI data. You can use this to prevent Zxx macros from controlling the
   filters, useful if they were intended to do something else. Note that this
   is NOT an effective way to disable filters, since instruments can have
   filter envelopes and initial filter parameters. DUMB provides no means to
   disable filters, as any IT file that uses them will sound wrong without
   them. If you want lower processor consumption, use a different piece of
   music.

   A helper callback, dumb_it_callback_midi_block(), is provided for blocking
   all MIDI messages and making Zxx macros do nothing.

   Pass NULL to remove the callback.


int dumb_it_callback_terminate(void *data);

   This is a helper callback that can be installed with both
   dumb_it_set_loop_callback() and dumb_it_set_xm_speed_zero_callback(). In
   each case it will cause the music to terminate abruptly.


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

   This helper callback, for use with dumb_it_set_midi_callback(), will
   absorb all MIDI messages, returning 1 to prevent DUMB from interpreting
   them itself.


DUH *dumb_load_it(const char *filename);

   Loads the specified Impulse Tracker file, encapsulating it in a DUH
   struct. Once the file is loaded, it can be treated exactly the same as any
   other DUH in memory. If this fails it will return NULL, but you can safely
   pass this NULL value to DUMB's other functions, so you do not need to
   check the return value explicitly.


DUH *dumb_read_it(DUMBFILE *f);

   Reads an Impulse Tracker file from an already open DUMBFILE. This leaves
   the DUMBFILE open, but the DUMBFILE may not be positioned at the end of
   the IT data. If you are embedding an IT in another file, you are advised
   to store the size of the IT file and make up for it at the end using
   dumbfile_pos().

   Otherwise, this function is identical to dumb_load_it().

   WARNING: The behaviour of this function is undefined if you pass a
            DUMBFILE from which data have already been read; it is likely not
            to work. This oversight will be fixed in future releases.


DUH *dumb_load_xm(const char *filename);

   Loads the specified Fast Tracker II file, encapsulating it in a DUH
   struct. Once the file is loaded, it can be treated exactly the same as any
   other DUH in memory. If this fails it will return NULL, but you can safely
   pass this NULL value to DUMB's other functions, so you do not need to
   check the return value explicitly.


DUH *dumb_read_xm(DUMBFILE *f);

   Reads a Fast Tracker II file from an already open DUMBFILE. This leaves
   the DUMBFILE open, but the DUMBFILE may not be positioned at the end of
   the XM data. If you are embedding an XM in another file, you are advised
   to store the size of the XM file and make up for it at the end using
   dumbfile_pos().

   Otherwise, this function is identical to dumb_load_xm().

   WARNING: The behaviour of this function is undefined if you pass a
            DUMBFILE from which data have already been read; it is likely not
            to work. This oversight will be fixed in future releases.


DUH *dumb_load_s3m(const char *filename);

   Loads the specified Scream Tracker 3 file, encapsulating it in a DUH
   struct. Once the file is loaded, it can be treated exactly the same as any
   other DUH in memory. If this fails it will return NULL, but you can safely
   pass this NULL value to DUMB's other functions, so you do not need to
   check the return value explicitly.


DUH *dumb_read_s3m(DUMBFILE *f);

   Reads a Scream Tracker 3 file from an already open DUMBFILE. This leaves
   the DUMBFILE open, but the DUMBFILE may not be positioned at the end of
   the S3M data. If you are embedding an S3M in another file, you are advised
   to store the size of the S3M file and make up for it at the end using
   dumbfile_pos().

   Otherwise, this function is identical to dumb_load_s3m().

   WARNING: The behaviour of this function is undefined if you pass a
            DUMBFILE from which data have already been read; it is likely not
            to work. This oversight will be fixed in future releases.


DUH *dumb_load_mod(const char *filename);

   Loads the specified Amiga module file, encapsulating it in a DUH struct.
   Once the file is loaded, it can be treated exactly the same as any other
   DUH in memory. If this fails it will return NULL, but you can safely pass
   this NULL value to DUMB's other functions, so you do not need to check the
   return value explicitly.


DUH *dumb_read_mod(DUMBFILE *f);

   Reads an Amiga module file from an already open DUMBFILE. This leaves the
   DUMBFILE open, but the DUMBFILE may not be positioned at the end of the
   MOD data. If you are embedding a MOD in another file, you are advised to
   store the size of the MOD file and make up for it at the end using
   dumbfile_pos().

   Otherwise, this function is identical to dumb_load_mod().

   WARNING: The behaviour of this function is undefined if you pass a
            DUMBFILE from which data have already been read; it is likely not
            to work. This oversight will be fixed in future releases.


int dumb_it_sd_get_n_orders(DUMB_IT_SIGDATA *sd);

   This function returns the number of orders in the module.


int dumb_it_sd_get_initial_global_volume(DUMB_IT_SIGDATA *sd);
void dumb_it_sd_set_initial_global_volume(DUMB_IT_SIGDATA *sd, int gv);

   These functions obtain and set the initial global volume for the module.
   This value ranges from 0 to 128 inclusive. The module can set the global
   volume itself during playback, so your change may not last throughout the
   playback.


int dumb_it_sd_get_mixing_volume(DUMB_IT_SIGDATA *sd);
void dumb_it_sd_set_mixing_volume(DUMB_IT_SIGDATA *sd, int mv);

   These functions obtain and set the mixing volume for the module. This
   value ranges from 0 to 128 inclusive, and does not change during playback.
   IT files have the mixing volume stored in them; for other formats it is
   set to 48 on loading.


int dumb_it_sd_get_initial_speed(DUMB_IT_SIGDATA *sd);
void dumb_it_sd_set_initial_speed(DUMB_IT_SIGDATA *sd, int speed);
int dumb_it_sd_get_initial_tempo(DUMB_IT_SIGDATA *sd);
void dumb_it_sd_set_initial_tempo(DUMB_IT_SIGDATA *sd, int tempo);

   These functions obtain and set the initial speed and tempo for the module.
   During module playback, everything happens on a tick. If a beat is 24
   ticks, then the tempo is measured in beats per second. The speed is then
   the number of ticks per row. With a speed of 6, a beat is then four rows.

   Modules can set these values during playback, so your change may not last
   throughout the playback. MOD files have to set the speed and tempo on the
   first row if they want anything other than the default 6/125, so your
   change may not be noticed at all!


int dumb_it_sd_get_initial_channel_volume(DUMB_IT_SIGDATA *sd, int channel);
void dumb_it_sd_set_initial_channel_volume(DUMB_IT_SIGDATA *sd, int channel,
                                                                 int volume);

   These functions obtain and set the initial volume for the specified
   channel. The channel parameter is 0-based (contrary to the display in most
   trackers so be careful), and can range from 0 to DUMB_IT_N_CHANNELS - 1,
   i.e. from 0 to 63.

   Modules can set their channel volumes during playback, so your changes may
   not last throughout the playback.


int dumb_it_sr_get_current_order(DUMB_IT_SIGRENDERER *sr);
int dumb_it_sr_get_current_row(DUMB_IT_SIGRENDERER *sr);

   These functions return the current order and row of playback. Both are
   0-based. If the DUMB_IT_SIGRENDERER is invalid, or has been terminated
   by a callback (see dumb_it_set_loop_callback() and
   dumb_it_set_xm_speed_zero_callback()), these functions will both return
   -1.


int dumb_it_sr_get_global_volume(DUMB_IT_SIGRENDERER *sr);
void dumb_it_sr_set_global_volume(DUMB_IT_SIGRENDERER *sr, int gv);

   These functions obtain and set the current global volume for the module.
   This value ranges from 0 to 128 inclusive. The module can set the global
   volume itself during playback, so your change may not last.


int dumb_it_sr_get_tempo(DUMB_IT_SIGRENDERER *sr);
void dumb_it_sr_set_tempo(DUMB_IT_SIGRENDERER *sr, int tempo);
int dumb_it_sr_get_speed(DUMB_IT_SIGRENDERER *sr);
void dumb_it_sr_set_speed(DUMB_IT_SIGRENDERER *sr, int speed);

   These functions obtain and set the current speed and tempo of the module.
   See the dumb_it_sd_*() equivalents of these functions for details on what
   the speed and tempo mean.

   Modules can set these values during playback, so your change may not last.


int dumb_it_sr_get_channel_volume(DUMB_IT_SIGRENDERER *sr, int channel);
void dumb_it_sr_set_channel_volume(DUMB_IT_SIGRENDERER *sr, int channel,
                                                                 int volume);

   These functions obtain and set the current volume for the specified
   channel. The channel parameter is 0-based (contrary to the display in most
   trackers so be careful), and can range from 0 to DUMB_IT_N_CHANNELS - 1,
   i.e. from 0 to 63.

   Modules can set their channel volumes during playback, so your changes may
   not last.


void dumb_it_sr_get_channel_state(DUMB_IT_SIGRENDERER *sr, int channel,
                                               DUMB_IT_CHANNEL_STATE *state);

   Returns the current playback state of the given channel. If you pass a
   channel in the range 0 to DUMB_IT_N_CHANNELS-1 (0 to 63), you will get the
   state of the most recently played note on that physical channel, if it is
   still playing. For MOD, S3M and XM files, that's all there is to it.

   IT files can have more than one note playing on a single channel, courtesy
   of New Note Actions. This function also lets you query all the notes that
   have been forced into the background and are still playing. For this, set
   'channel' to a value from DUMB_IT_N_CHANNELS to DUMB_IT_TOTAL_CHANNELS-1.
   DUMB_IT_TOTAL_CHANNELS is defined as follows:

      #define DUMB_IT_TOTAL_CHANNELS \
                                (DUMB_IT_N_CHANNELS + DUMB_IT_N_NNA_CHANNELS)

   Querying these background channels for MOD, S3M and XM files will not do
   any harm; the function will report that these channels are inactive. For
   all files, be sure not to query any channel numbers greater than or equal
   to DUMB_IT_TOTAL_CHANNELS.

   You must provide a pointer to a preallocated DUMB_IT_CHANNEL_STATE struct.
   The easiest way to do this is as follows:

      DUMB_IT_CHANNEL_STATE state;
      dumb_it_sr_get_channel_state(sr, channel, &state);

   or:

      DUMB_IT_CHANNEL_STATE state[IT_TOTAL_CHANNELS];
      dumb_it_sr_get_channel_state(sr, channel, &state[channel]);

   This struct contains the following fields:

          int channel;
          int sample;
          int freq;
          float volume;
          unsigned char pan;
          signed char subpan;
          unsigned char filter_cutoff;
          unsigned char filter_subcutoff;
          unsigned char filter_resonance;

   The first field to check is 'sample'; if this is 0, then the channel is
   inactive and the other fields are undefined. Otherwise, it is the index of
   the currently playing sample, and is 1-based.

   The channel number is returned, 0-based. This will be the same as the
   channel number you passed, unless you are querying a background channel in
   which case it will represent the channel the note originated on.

   The freq field is the current playback frequency, taking into account all
   phenomena such as slides, vibrato and arpeggio.

   The volume field ranges from 0.0f to 1.0f. In practical terms, it will
   rarely reach 1.0f; if it does, the module is probably clipping a lot. This
   takes mixing volume into account, along with all the other volume
   phenomena in the IT file. The only one it doesn't take into account is the
   one you pass to duh_render() or duh_sigrenderer_get_samples(), or the one
   you passed to al_start_duh() (these are in fact the same thing).

   The pan field ranges from 0 to 64 for a normally panned sample, but will
   be 100 if the sample is playing using IT's surround mode where the right-
   hand channel is inverted. If you want a more accurate pan reading, use one
   of the following to get one:

      int scaled_pan = ((int)state.pan << 8) + state.subpan;
      float float_pan = state.pan + state.subpan / 256.0f;

   The first will give a scaled value ranging (strictly) from 0 to 64*256.
   The second will give a floating-point value whose scale corresponds to
   that of the pan field. These results will only be valid if surround mode
   is off, so you should check that pan <= 64 before using the above
   expressions. At the time of writing, pitch-pan separation and panning
   envelopes take advantage of the extra accuracy offered by subpan.

   Note that subpan is signed. This means applications that only look at the
   pan field will get an unbiased reading.

   The filter cut-off and resonance both range from 0 to 127. If the cut-off
   is 127 and the resonance is 0, then no filters are applied. These
   parameters only ever change from the default values for IT files.

   While IT allows you to set 127 different filter cut-off levels in the
   patterns and as a default value per instrument, it also allows you to
   create a filter envelope, which will result in an actual cut-off somewhere
   between 0 and the first-mentioned value. By the time this has been
   calculated, the actual cut-off may lie in between two levels on the
   original scale. If this is the case, filter_subcutoff will be nonzero and
   you can combine it with filter_cutoff. Typically you will want to use one
   of the following:

      int scaled_cutoff = ((int)state.filter_cutoff << 8) +
                                state.filter_subcutoff;

      float float_cutoff = state.filter_cutoff +
                           state.filter_subcutoff / 256.0f;

   The first will give you a scaled value whose maximum is 127*256. The
   second will give you a floating-point value whose scale corresponds to the
   scale used by filter_cutoff. These match the expressions given further up
   for pan and subpan, but in this case, filter_subcutoff is unsigned.

   Note that filter_subcutoff will always be zero if filter_cutoff is 127, so
   you need not check it if you simply wish to determine whether filters are
   being applied.


*******************************
*** DUH Rendering Functions ***
*******************************


   Use these functions to generate samples from a DUH. First you call
   duh_start_sigrenderer() with the DUH, the number of channels you want and
   the position at which you want to start. Then you use duh_render() or
   duh_sigrenderer_get_samples() to generate the samples. You can call these
   functions as many times as you like, and they will generate as many or as
   few samples as you require. When you have finished, call
   duh_end_sigrenderer().


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

   Starts a DUH_SIGRENDERER off. This is the struct you can use to get
   samples from a DUH. This function does not generate any samples; you must
   pass the struct to duh_render() or duh_sigrenderer_get_samples() for that.
   When you have finished with it, you must pass it to duh_end_sigrenderer().
   You can use as many DUH_SIGRENDERER structs as you like at the same time.

   Set sig to 0 for now. Currently, n_channels can only be 1 or 2, for
   monaural and stereo sound respectively. The debugging library will cause
   your program to abort if you pass anything else. Future versions will be
   enhanced to support more channels as soon as someone needs them.

   When specifying the position, 0 represents the start of the DUH, and 65536
   represents one second. Unlike most other music systems, DUMB will always
   make sure every note is there right from the start (assuming you aren't
   using any broken add-ons). In other words, you can start a DUH at a point
   halfway through a long note, and you will still hear the long note.


void duh_sigrenderer_set_analyser_callback(DUH_SIGRENDERER *sigrenderer,
                     DUH_SIGRENDERER_ANALYSER_CALLBACK callback, void *data);

   Installs a callback function which will be called every time the given
   sigrenderer is used to generate some samples. This can be used to create
   an oscilloscope or spectrum analyser. DUH_SIGRENDERER_ANALYSER_CALLBACK is
   defined as follows:

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

   If the above confuses you, see fnptr.txt. As for the 'samples' parameter,
   the first 'const' says that the samples are read-only; the second says
   that each channel's sample pointer is also read-only. If you don't
   understand this, don't worry about it.

   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 (see duh_sigrenderer_get_samples()).
   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_get_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. 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_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_analyser_callback().


int duh_sigrenderer_get_n_channels(DUH_SIGRENDERER *sigrenderer);

   Tells you how many channels a DUH_SIGRENDERER is set up to generate, or 0
   if it is invalid (perhaps owing to lack of memory). This will be 1 for
   monaural sound or 2 for stereo, in this release.


long duh_sigrenderer_get_position(DUH_SIGRENDERER *sigrenderer);

   Tells you what position a DUH_SIGRENDERER is up to, or -1 if it is invalid
   (perhaps owing to lack of memory). As usual, 65536 is one second.


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

   Generates some samples in DUMB's internal 32-bit format (see sample_t; see
   also duh_render()). The samples buffer is a two-dimensional array, and can
   be allocated with create_sample_buffer(); see
   duh_sigrenderer_set_analyser_callback() for details.
   duh_sigrenderer_get_samples() mixes sample data with what's already in the
   buffer, so you have to call dumb_silence() first.

   The volume is a float. 1.0f is the pseudo-maximum. If you pass 1.0f, any
   properly designed DUH will play nice and loud, but will not clip. You can
   pass a greater volume if you like, but be prepared for the possibility of
   distortion due to integer overflow. Of course you can pass smaller values
   to play the DUH more quietly, and this will also resolve clipping issues
   in badly designed DUHs.

   Use delta to control the speed of the output signal. If you pass 1.0f, the
   resultant signal will be suitable for a 65536-Hz sampling rate (which
   isn't a commonly used rate). The most common sampling rates are 11025 Hz,
   22050 Hz, 44100 Hz and 48000 Hz. You can work out the required delta value
   as follows:

      delta = 65536.0f / sampling_rate;

   If you then increase this value, the DUH will speed up and increase in
   pitch. If you decrease it, the DUH will slow down and decrease in pitch.

   This function will attempt to render 'size' samples. In most cases it will
   succeed. However, if the end of the DUH is reached, it may render fewer.
   The number of samples rendered will be returned. Therefore, if the return
   value is less than the value of 'size' passed, you know the DUH has
   finished. It is safe to continue calling duh_sigrenderer_get_samples() if
   you wish, and it will continually return 0.

   If the DUH_SIGRENDERER is a null pointer, this function will generate
   precisely 0 samples. If you pass NULL for 'samples', the function will
   behave exactly the same as if you provided a sample buffer, except the
   samples won't be stored anywhere and the function will execute very
   quickly. This can be used to skip ahead in the audio.


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

   Generates some samples and converts them to an 8-bit or 16-bit format (see
   also duh_sigrenderer_get_samples()). Pass the DUH_SIGRENDERER as returned
   by duh_start_sigrenderer(). Pass the number of bits, which should be 8 or
   16. If unsign is nonzero, the samples will be unsigned (centred on 0x80 or
   0x8000 for 8 bits and 16 bits respectively). If unsign is zero, the
   samples will be signed.

   Allegro's audio streams always take unsigned samples. 8-bit .wav files
   always take unsigned samples. 16-bit .wav files always take signed
   samples.

   The volume and delta parameters work the same as for
   duh_sigrenderer_get_samples().

   This function will attempt to render 'size' samples. In most cases it will
   succeed. However, if the end of the DUH is reached, it may render fewer.
   The number of samples rendered will be returned. Therefore, if the return
   value is less than the value of 'size' passed, you know the DUH has
   finished. It is safe to continue calling duh_render() if you wish, and it
   will continually return 0. However, if you wish to do this, you will
   probably have to fill the rest of the buffer with silence, which is 0 for
   signed, 0x80 for 8-bit unsigned or 0x8000 for 16-bit unsigned.

   The samples will be placed at sptr. Use an array of chars for 8 bits or an
   array of shorts for 16 bits. Stereo samples will be interleaved, left
   first. Your array should contain at least (size * n_channels) elements of
   the appropriate bit resolution.

   From an aesthetic standpoint if nothing else, it is wise to use the C
   qualifiers 'signed' or 'unsigned' depending on whether the samples are
   signed or unsigned. This is also convenient if you wish to process the
   samples further yourself.

   If the DUH_SIGRENDERER is a null pointer, this function will generate
   precisely 0 samples. Unlike with duh_sigrenderer_get_samples(), you must
   specify a sample buffer.


void duh_end_sigrenderer(DUH_SIGRENDERER *dr);

   Terminates a DUH_SIGRENDERER. Be sure to call this when you've finished
   with one. You can safely pass a null pointer.


********************************
*** Allegro Packfile Support ***
********************************


void dumb_register_packfiles(void);

   This function registers the Allegro PACKFILE input module for use by
   DUMBFILEs. PACKFILE structs and their corresponding functions, as defined
   by Allegro's header file allegro.h, will be used internally for all
   DUMBFILE input (unless opened with dumbfile_open_ex()).

   This must be called before dumbfile_open() is used, or else an alternative
   system must be registered (see register_dumbfile_system() and
   dumb_register_stdfiles()). Note that you don't have to call this function
   in order to load datafiles that contain music.


DUMBFILE *dumbfile_open_packfile(PACKFILE *p);

   If you have an Allegro PACKFILE struct representing an open file, you can
   call this if you wish to read from it using a DUMBFILE. This is useful
   when you need to pass a DUMBFILE struct to a library function, to read an
   embedded music file for example. When you close the DUMBFILE, you can
   continue using the PACKFILE struct to read what follows the embedded data.


DUMBFILE *dumbfile_from_packfile(PACKFILE *p);

   This function is the same as dumbfile_open_packfile(), except it will
   check if p is NULL, and arrange for pack_fclose() to be called on the
   PACKFILE when you close the DUMBFILE. It can be seen as a function for
   converting a PACKFILE to a DUMBFILE, but it will only work for a PACKFILE
   you obtained with pack_fopen(), not pack_fopen_chunk(). If this function
   fails, which may happen if memory is short, then the PACKFILE will be
   closed immediately, so you need not worry about potential memory leaks or
   files being left open when this happens.

   The following is typical usage, and will open the compressed file foo.bin:

      DUMBFILE *f = dumbfile_from_packfile(pack_fopen("foo.bin",
                                                      F_READ_PACKED));

   This differs from calling dumb_register_packfiles() and dumbfile_open() in
   that the latter will only read uncompressed files (and is thus a method
   suitable for reading music modules).


***********************************************
*** Allegro Datafile Registration Functions ***
***********************************************


void dumb_register_dat_it(long type);

   If you wish to embed an IT file in an Allegro datafile, it is recommended
   that you use "IT  " for the type. The grabber will have a box for the type
   when you insert a new object. The grabber will treat the IT file as binary
   data, which means the datafile will contain an exact copy of the IT file
   on disk.

   You must then call dumb_register_dat_it(DUMB_DAT_IT) in your program
   before you load the datafile. Once you've done this, you'll be able to
   access the DUH using the usual datafile[n].dat notation. You do not need
   to call unload_duh() on this DUH; unload_datafile() will do that for you.

   If you are using a different type for whatever reason, you can use
   Allegro's DAT_ID() macro for encoding it and passing it to this function.
   For example:

      dumb_register_dat_it(DAT_ID('B','L','A','H'));

   Assuming you used the recommended type, the following example iterates
   through all the ITs in disan.dat:

      DATAFILE *dat;
      int n;

      dumb_register_dat_it();
      dat = load_datafile("disan.dat");

      for (n = 0; dat[n].type != DAT_END; n++) {
         if (dat[n].type == DUMB_DAT_IT) {
            DUH *duh = dat[n].dat;
            /* Insert code here to play 'duh' or whatever you want to do. */
         }
      }

      unload_datafile(dat);


void dumb_register_dat_xm(long type);

   Inserting an XM file in an Allegro datafile is the same as inserting an IT
   file, except that the recommended type is "XM  ", the registration
   function is dumb_register_dat_xm(), and the macro DUMB_DAT_XM is provided
   for the type. The intuitive process of substituting XM for IT in the above
   method will work.


void dumb_register_dat_s3m(long type);

   Inserting an S3M file in an Allegro datafile is the same as inserting an
   IT file, except that the recommended type is "S3M ", the registration
   function is dumb_register_dat_s3m(), and the macro DUMB_DAT_S3M is
   provided for the type. The intuitive process of substituting S3M for IT in
   the above method will work.


void dumb_register_dat_mod(long type);

   Inserting a MOD file in an Allegro datafile is the same as inserting an IT
   file, except that the recommended type is "MOD ", the registration
   function is dumb_register_dat_mod(), and the macro DUMB_DAT_MOD is
   provided for the type. The intuitive process of substituting MOD for IT in
   the above method will work.


****************************************
*** Sample Buffer Allocation Helpers ***
****************************************


   Many parts of DUMB require sample buffers allocated in a special way. A
   pointer to one looks like this:

      sample_t **samples;

   and it can be indexed as follows:

      samples[channel_number][sample_position]

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

   The following helpers will allocate and deallocate such buffers for you.
   They will not initialise them, and DUMB always writes into these buffers
   by adding to what's already there, so you will generally have to call
   dumb_silence() too.


sample_t **create_sample_buffer(int n_channels, long length);

   This will allocate a sample buffer to hold the specified number of samples
   for the specified number of channels. Don't forget to check the return
   value!

   You will generally have to initialise the buffer by calling
   dumb_silence(); the channels will be stored consecutively in memory, so
   the following technique is officially supported:

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

   See dumb_silence() for general information on what this function does.


void destroy_sample_buffer(sample_t **samples);

   This function does the obvious: it frees up a sample buffer when you've
   finished with it. It is safe to pass a null pointer to this function.


************************
*** Silencing Helper ***
************************


void dumb_silence(sample_t *samples, long length);

   This function simply stores 'length' samples' worth of silence in the
   array. It is typically used straight after allocating a sample buffer with
   create_sample_buffer().


**************************
*** Resampling Helpers ***
**************************


   Please forgive the odd section name; it has to do with DUMB's internal
   structure and the fact that the resampling algorithm is there not just for
   use in rendering module files but for use anywhere that a waveform needs
   resampling. Unfortunately DUMB's resampling algorithm is not ready to be
   documented and used yet. However, one thing can be documented, and that's
   the global variable controlling the resampling quality.

   (Ironically, even this variable has changed! See deprec.txt for
   information on what it used to do.)


int dumb_resampling_quality;

   Allows you to control the quality of all resampling that takes place. This
   may be set to any DUMB_RQ_* constant (except DUMB_RQ_N_LEVELS). Higher
   values will sound better, but lower values will use up less processor
   time. You may compare any two DUMB_RQ_* constants or values using the
   integer inequalities <, <=, > and >=; higher numbers represent higher-
   quality algorithms.

   #define DUMB_RQ_ALIASING

      |     --___         'Aliasing' has very noticeable and usually unwanted
      |__---     __       overtones. It will occasionally produce acceptable
      |            ___--  results for noisy (impure) samples (or for cheap
                          speakers!), but usually you will want to pay for
      the extra processor time, which isn't much, and go for linear
      interpolation.

   #define DUMB_RQ_LINEAR

      |  __          Linear interpolation is a pretty good algorithm in most
      | /  \  /\     cases. When resampling down a few octaves, however, you
      |/    \/  \__  may begin to notice unwanted high frequencies. You can
                     reduce these by switching to cubic interpolation, but it
      will cost you some processor time.

   #define DUMB_RQ_CUBIC

      Cubic interpolation looks like a smooth curve to the eye, and will
      produce good results in most cases. At present this is the highest
      quality offered by DUMB, and also the default. While this may seem
      extravagant, GCC 3.x and an AthlonXP handle it quite well - and the
      general trend is for processors to get better!

   #define DUMB_RQ_N_LEVELS

      This represents the number of resampling quality levels DUMB provides.
      Values of dumb_resampling_quality from 0 to DUMB_RQ_N_LEVELS - 1 are
      valid. You can use this constant if you wish to offer the resampling
      quality as an option for the user.


*************************************
*** Allegro DUH Playing Functions ***
*************************************


   The functions in this section allow you to play back a DUH through
   Allegro's sound system. You must call Allegro's install_sound() function
   before you use them.


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

   Starts playing the specified DUH.

   An AL_DUH_PLAYER represents one instance of the DUH playing. If you wish,
   you can have two or more AL_DUH_PLAYERs going at the same time, for the
   same DUH or for different ones. Each uses one of Allegro's audio streams
   and hence one voice. The voice will be given priority 255 initially, so a
   build-up of sound effects will not cause your music streams to cut off (as
   long as you don't give all your sound effects priority 255!). You can
   change the priority of a stream with al_duh_set_priority(). See Allegro's
   documentation for more information on how voice priorities work.

   At present, n_channels can either be 1 or 2 for monaural or stereo
   respectively. If you use the debugging library, your program will abort if
   other values are passed; otherwise weird things will happen.

   The DUH will start playing from position 'pos'. 0 represents the start of
   the DUH, and 65536 represents one second. Unlike other music systems, DUMB
   will always make sure every note is there right from the start. In other
   words, you can start a DUH at a point halfway through a long note, and you
   will still hear the long note.

   The volume is a float. 1.0f is the pseudo-maximum. If you pass 1.0f, any
   properly designed DUH file will play nice and loud, but will not clip. You
   can pass a greater volume if you like, but be prepared for clipping to
   occur. Of course you can pass smaller values to play the DUH more quietly,
   and this will also resolve clipping issues in badly designed DUH files.

   You will need to pass the AL_DUH_PLAYER to other functions when you need
   to stop or pause the DUH, change its volume, or otherwise modify the way
   it is playing. You will also need to pass it to al_poll_duh() at regular
   intervals; if the sound is choppy, try calling al_poll_duh() more often.

   'bufsize' is the number of samples that will be rendered at once. 1024 is
   a suitable value for most purposes. The greater this is, the less often
   you will have to call al_poll_duh() - but when al_poll_duh() decides to
   fill the buffer, it will take longer doing so. If your game exhibits
   regular brief freezes, try reducing the buffer size. If the sound is
   choppy, however, you may have to increase it.

   'freq' specifies the sampling frequency at which the DUH should be
   rendered. At present there is no (official and portable) way of knowing
   the frequency at which Allegro is mixing - but if you do know that
   frequency, passing it here will give the highest quality sound. If you
   reduce it, the DUH will sound less crisp but use less processor time.

   When you have finished, you must pass the AL_DUH_PLAYER to al_stop_duh()
   to free up memory. Do not destroy the DUH beforehand.

   There is no real need to check the return value from this function. The
   other functions can be called safely with null pointers, so if there is a
   problem, your music will simply not play.


void al_stop_duh(AL_DUH_PLAYER *dp);

   This will stop an AL_DUH_PLAYER. You must call this when you have finished
   with it, before destroying the DUH. The pointer will no longer be valid on
   return from this function.


void al_pause_duh(AL_DUH_PLAYER *dp);

   This will pause an AL_DUH_PLAYER. Use al_resume_duh() when you want it to
   continue. You can safely call al_poll_duh() while the music is paused, and
   it will do nothing.


void al_resume_duh(AL_DUH_PLAYER *dp);

   Causes a paused AL_DUH_PLAYER to resume playing (see al_pause_duh()).


void al_duh_set_priority(AL_DUH_PLAYER *dp, int priority);

   This will set the priority of the audio stream underlying an
   AL_DUH_PLAYER. The priority is an integer ranging from 0 to 255. When
   too many samples play at the same time, those with lower priorities will
   be cut. 128 is the usual default with Allegro, but DUMB overrides the
   default for all AL_DUH_PLAYER structs: they will be set up initially with
   priority 255, so your music won't be cut (unless you play too many other
   streams or samples with priority 255). See Allegro's documentation for
   more information on priorities.


void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume);

   This will set the volume of an AL_DUH_PLAYER. See al_start_duh() for
   details on the volume parameter.


int al_poll_duh(AL_DUH_PLAYER *dp);

   An AL_DUH_PLAYER is not interrupt-driven. That means it will not play by
   itself. You must keep it alive from your main program. Call this function
   at regular intervals. If the sound crackles, try calling it more often.
   (There is nothing you can do if Windows decides to play with the hard
   disk; that will make your sound crackle no matter what you do.)

   Normally this function will return zero. However, if it returns nonzero,
   that means the AL_DUH_PLAYER will not generate any more sound. Indeed the
   underlying audio stream and DUH_SIGRENDERER have been destroyed. When this
   happens, you can call al_stop_duh() whenever you wish - but you do not
   have to. Note that this function will wait two buffers' worth of samples
   before taking this action, allowing Allegro to mix the trailing sound
   before the audio stream is destroyed. This is an attempt to make sure your
   music does not get cut off prematurely, and it should work when using
   Allegro's mixer (the only option on DOS, the default on Linux as far as I
   know, but not the default on Windows). That said, if you immediately call
   Allegro's remove_sound() or exit your program, the music may get cut off.
   If you are using another mixer and experience problems, let me know (but I
   don't guarantee to be able to come up with an elegant solution, i.e. it
   might not get fixed).

   In case you were wondering, it is not safe on all platforms to call
   al_poll_duh() from an interrupt context (that means an Allegro timer
   handler). Not only is no part of DUMB locked in memory, but many parts of
   DUMB allocate and free their memory on a call-by-call basis! Remember that
   any disk access that occurs in interrupt context is likely to crash the
   machine; this is explained more fully in howto.txt. This limitation only
   applies to DOS at present, and is due to the fact that the DOS file access
   functions are not re-entrant.

   Multitasking systems are generally safe. If you are sure you don't want to
   target DOS, you can call al_poll_duh() from inside a timer handler, but I
   recommend including a construction like the following!

      #ifdef ALLEGRO_DOS
      #error calling al_poll_duh() from a timer handler will not work in DOS!
      #endif

   Furthermore, if you call al_poll_duh() from inside a timer handler, you
   must use a semaphore or other threading mechanism to make sure it is not
   executing when you call al_stop_duh(). If you don't know what a semaphore
   is, for Heaven's sake follow my advice and call al_poll_duh() from your
   main loop!


long al_duh_get_position(AL_DUH_PLAYER *dp);

   Tells you what position an AL_DUH_PLAYER is up to, or -1 if it is invalid
   (perhaps owing to lack of memory). As usual, 65536 is one second. Note
   that this is a whole number, whereas a fractional part is stored
   internally; the sample will not be continuous if you terminate the
   AL_DUH_PLAYER and then reinitiate it with the same position. Furthermore,
   note that Allegro will not have mixed in all the sound up to this point;
   if you wait for this to reach a certain position and then terminate the
   AL_DUH_PLAYER, the sound will cut off too early. Please contact me if you
   need to get around this.


AL_DUH_PLAYER *al_duh_encapsulate_sigrenderer
        (DUH_SIGRENDERER *sigrenderer, float volume, long bufsize, int freq);

   If you have a DUH_SIGRENDERER, and would like to start playing music from
   it through an Allegro audio stream, use this function. Beware that it may
   return NULL, in which case you will have to call duh_end_sigrenderer()
   yourself instead of relying on the encapsulating AL_DUH_PLAYER to do it
   for you.


DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp);

   This returns the DUH_SIGRENDERER contained in an AL_DUH_PLAYER, useful for
   controlling playback, installing callbacks, etc.


DUH_SIGRENDERER *al_duh_decompose_to_sigrenderer(AL_DUH_PLAYER *dp);

   This destroys an AL_DUH_PLAYER, but preserves the DUH_SIGRENDERER it
   contains, and returns it to you. You can then continue rendering samples
   from the DUH_SIGRENDERER and do whatever you like with them.


*********************
*** Thread Safety ***
*********************


The following points should pretty much sum up the essence of DUMB's thread
safety. If I haven't covered the one thing you'd like to do, please don't
hesitate to ask about it.

DOs:

- You may load and use multiple DUHs in separate threads.

- You may change dumb_resampling_quality and dumb_it_max_to_mix while another
  thread is generating samples.

DON'Ts:

- You may not generate samples from the same DUH in multiple threads, even if
  you are using separate DUH_RENDERERs (separate AL_DUH_PLAYERS).


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


"DUMB is the bestest music player in the world because ..."

Complete this sentence in fifteen words or fewer and receive a free copy of
DUMB! (Your Internet Service Provider may issue charges for your connection,
required for download of the Product. Your electricity supplier may issue
charges for the electricity consumed in writing the Product to a Permanent
Storage Device. You may have been charged for a Permanent Storage Device on
which to store the Product.)


Ben Davis
entheh@users.sf.net
IRC EFnet #dumb
See readme.txt for details on using IRC.