/* _______ ____ __ ___ ___
* \ _ \ \ / \ / \ \ / / ' ' '
* | | \ \ | | || | \/ | . .
* | | | | | | || ||\ /| |
* | | | | | | || || \/ | | ' ' '
* | | | | | | || || | | . .
* | |_/ / \ \__// || | |
* /_______/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".
This was broken in DUMB v0.9 and earlier.
#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.
This was broken in DUMB v0.9 and earlier, since it depends on
DUMB_VERSION_STR.
#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, and the STR4 and STR1 constants were broken in v0.9 and earlier.
#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 personal preference. 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, and this was broken anyway in v0.9 and earlier.
*************************
*** 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!)
const char *duh_get_tag(DUH *duh, const char *key);
DUH structs can contain a number of 'tags'. You can retrieve a tag by
giving its key. At present, module files are set up with a single tag,
which you can retrieve by setting key to "TITLE" (case matters). The value
returned is the title of the module.
You can retrieve other author information from the module by calling
duh_get_it_sigdata() and then using the dumb_it_sd_*() functions. See the
descriptions of the relevant functions for the maximum length of the title
for each format and some comments on non-ASCII characters.
***********************************
*** 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);
Module files contain a set of patterns, numbered from zero, but they are
not necessarily played in order. Some patterns may be repeated, and some
may be left out altogether. When a module is played, the player runs
through a sequence of pattern numbers stored in the file, playing the
corresponding pattern for each number. Each entry in the sequence is
called an 'order', and the orders are numbered from from zero.
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 to seek
to a specific time in the music, as if you have recorded it and are
starting playback in the middle, then use 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);
DUH *dumb_load_xm(const char *filename);
DUH *dumb_load_s3m(const char *filename);
DUH *dumb_load_mod(const char *filename);
These load the specified Impulse Tracker, Fast Tracker II, Scream Tracker
3 or 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.
These functions call dumb_it_do_initial_runthrough(), which takes time and
memory but means the playback time is known and fast seeking is possible.
See dumb_it_do_initial_runthrough() for more information. If you do not
need this functionality, consider calling the *_quick() equivalents of
these functions instead.
DUH *dumb_read_it(DUMBFILE *f);
DUH *dumb_read_xm(DUMBFILE *f);
DUH *dumb_read_s3m(DUMBFILE *f);
DUH *dumb_read_mod(DUMBFILE *f);
These read an Impulse Tracker, Fast Tracker II, Scream Tracker 3 or Amiga
module file from an already open DUMBFILE. They leave the DUMBFILE open,
but the DUMBFILE may not be positioned at the end of the data. If you are
embedding a module in another file, you are advised to store the size of
the module file and make up for it at the end using dumbfile_pos().
Otherwise, these functions are identical to dumb_load_*(), and have
*_quick() equivalents.
WARNING: The behaviour of these functions are undefined if you pass a
DUMBFILE from which data have already been read; they are likely
not to work. This oversight will be fixed in future releases.
DUH *dumb_load_it_quick(const char *filename);
DUH *dumb_load_xm_quick(const char *filename);
DUH *dumb_load_s3m_quick(const char *filename);
DUH *dumb_load_mod_quick(const char *filename);
DUH *dumb_read_it_quick(DUMBFILE *f);
DUH *dumb_read_xm_quick(DUMBFILE *f);
DUH *dumb_read_s3m_quick(DUMBFILE *f);
DUH *dumb_read_mod_quick(DUMBFILE *f);
These functions are identical to the versions without the _quick suffix,
except they omit the initial run-through. They execute faster and the
resultant DUH structs use less memory. However, seeking by time is slower
(seeking with dumb_it_start_at_order() is unaffected), and the length is
unknown and returned as -1.
void dumb_it_do_initial_runthrough(DUH *duh);
This runs through the module represented by the DUH and stores a copy of
the playback state at 30-second intervals. It stops when it first
encounters a jump to an earlier pattern or a MOD/XM speed zero effect, at
which point it adds to the DUH struct the length of time for which the
module plays. The playback state images enable DUMB to seek more quickly
when you pass a nonzero time to al_start_duh() or duh_start_sigrenderer().
Note that dumb_it_start_at_order() is unaffected and always executes fast.
This is called automatically by some of the loading functions, so you will
not normally need to call it. If you do decide to call it yourself, be
aware that it cannot execute concurrently with playback. This will be
addressed in the future.
This function does nothing if the parameter is NULL or does not represent
a module.
long dumb_it_build_checkpoints(DUMB_IT_SIGDATA *sigdata);
This is the functionality of dumb_it_do_initial_runthrough() detached from
the DUH struct. It does the same thing, but the length is returned. The
function does nothing if sigdata is NULL.
const unsigned char *dumb_it_sd_get_song_message(DUMB_IT_SIGDATA *sd);
This function retrieves the song message from an IT file, if it was
present and there was sufficient memory to load it. Otherwise it returns
NULL. XM, S3M and MOD files never contain song messages as such, although
there is often a message embedded in the sample and instrument names.
According to Impulse Tracker's documentation, the message uses CR
characters ('\r', ASCII code 13) for line breaks and is null-terminated.
DUMB adds a NUL to the end just in case. You can therefore use strlen()
and otherwise treat the return value as a normal C string.
When interpreting the message, bear in mind that Impulse Tracker is a DOS
program, and extended ASCII from the DOS days does not match the usual
character encodings on modern systems. If you find characters outside the
range 32 to 126 (and not '\r'), you may need to convert in some way for
display.
If anyone knows how to map DOS extended ASCII to Unicode, please feel free
to write an explanation for me to include here. Credit will be given!
Impulse Tracker's message editor generally restricts lines to 74
characters plus the CR, although it is possible to create a 75-character-
long line with no spaces. The documentation says the message may be up to
8000 bytes long. Other IT-compatible trackers may not impose these
restrictions.
int dumb_it_sd_get_n_orders(DUMB_IT_SIGDATA *sd);
This function returns the number of orders in the module. See
dumb_it_start_at_order() for an explanation of orders.
int dumb_it_sd_get_n_samples(DUMB_IT_SIGDATA *sd);
int dumb_it_sd_get_n_instruments(DUMB_IT_SIGDATA *sd);
These functions respectively return the number of samples and the number
of instruments in the module. Note that MOD and S3M files don't support
instruments, and instruments are optional in IT files.
dumb_it_sd_get_n_instruments() will return 0 for modules that only use
samples.
const unsigned char *dumb_it_sd_get_sample_name(DUMB_IT_SIGDATA *sd, int i);
const unsigned char *dumb_it_sd_get_sample_filename
(DUMB_IT_SIGDATA *sd, int i);
const unsigned char *dumb_it_sd_get_instrument_name
(DUMB_IT_SIGDATA *sd, int i);
const unsigned char *dumb_it_sd_get_instrument_filename
(DUMB_IT_SIGDATA *sd, int i);
The trackers allow the author to set a name and sometimes also a file name
for each sample and each instrument. These functions allow you to retrieve
the names. The samples and instruments are numbered from 0 for the
purposes of these functions, and you can determine how many are available
using dumb_it_sd_get_n_samples() and dumb_it_sd_get_n_instruments().
Very often, displaying the names in order will produce a message from the
author. These functions will always return something, but if the field
does not exist, the result will be an empty string. The return value is
null-terminated.
The comments under dumb_it_sd_get_song_message() about code pages applies,
except not all modules were created in DOS; the original MOD files were
born on the Amiga, and many files were transferred from there. If anyone
knows about the characters available on the Amiga, please get in touch so
I can add the information here. Credit will be given!
The table to the right Field | MOD | S3M | XM | IT
specifies the maximum ----------------------+-----+-----+-----+-----
length of each field for Song title | 20 | 28 | 20 | 26
each format, or '-' if Sample name | 22 | 28 | 22 | 26
the field does not exist. Sample file name | - | 13 | - | 13
Instrument name | - | - | 22 | 26
Instrument file name | - | - | - | 13
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.
int dumb_it_sr_get_channel_muted(DUMB_IT_SIGRENDERER *sr, int channel);
void dumb_it_sr_set_channel_muted(DUMB_IT_SIGRENDERER *sr, int channel,
int muted);
These functions obtain or set the flag indicating whether each channel is
muted. Modules cannot override this during playback, although some formats
can make some channels muted initially.
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_generate_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_generate_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_generate_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_sample_analyser_callback(
DUH_SIGRENDERER *sigrenderer,
DUH_SIGRENDERER_SAMPLE_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_SAMPLE_ANALYSER_CALLBACK is defined as follows:
typedef void (*DUH_SIGRENDERER_SAMPLE_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 buffer'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_generate_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_generate_samples() on a buffer that isn't all silence,
this callback function will be passed the existing buffer after mixing,
and thus it will include the original data. This will not be an issue if
you stick to duh_render(), which always starts with a buffer filled with
silence.
The samples array is two-dimensional. It consists of zero or more
interleaved stereo sample buffers, possibly followed by one monaural
buffer. You can access the samples as follows:
n_channels == 1: samples[0][sample_position]
n_channels == 2: samples[0][sample_position*2+channel_number]
n_channels > 2:
channel_number < n_channels & ~1:
samples[channel_number>>1][sample_position*2+(channel_number&1)]
channel_number == n_channels & ~1:
samples[channel_number>>1][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_sample_analyser_callback(), and this pointer will be
relayed to your callback function each time.
To remove the callback function, pass NULL to
duh_sigrenderer_set_sample_analyser_callback().
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_generate_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 allocate_sample_buffer(); see
duh_sigrenderer_set_sample_analyser_callback() for details.
duh_sigrenderer_generate_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_generate_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.
void duh_sigrenderer_get_current_sample(DUH_SIGRENDERER *sigrenderer,
float volume, sample_t *samples);
This generates one sample (or two for a stereo DUH_SIGRENDERER) and stores
them in the array passed in. It does not update the state (with the
exception of potentially having to initialise playback). It is used for
click removal.
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_generate_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_generate_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, where n_channels distinguishes between
mono and stereo and was passed in when the DUH_SIGRENDERER was
constructed.
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_generate_samples(), you
must specify a sample buffer for the output. (If you don't need any
output, call duh_sigrenderer_generate_samples() instead.)
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);
void dumb_register_dat_it_quick(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) or
dumb_register_dat_it_quick(DUMB_DAT_IT) in your program, before you load
the datafile. If 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.
The *_quick() version will cause the initial run-through to be skipped,
speeding up loading. See dumb_load_it() for an explanation.
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);
void dumb_register_dat_xm_quick(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
functions are dumb_register_dat_xm() and dumb_register_dat_xm_quick(), 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);
void dumb_register_dat_s3m_quick(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
functions are dumb_register_dat_s3m() and dumb_register_dat_s3m_quick(),
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);
void dumb_register_dat_mod_quick(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
functions are dumb_register_dat_mod() and dumb_register_dat_mod_quick(),
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;
This is effectively a two-dimensional array. It consists of zero or more
interleaved stereo sample buffers, possibly followed by one monaural
buffer. You can access the samples as follows:
n_channels == 1: samples[0][sample_position]
n_channels == 2: samples[0][sample_position*2+channel_number]
n_channels > 2:
channel_number < n_channels & ~1:
samples[channel_number>>1][sample_position*2+(channel_number&1)]
channel_number == n_channels & ~1:
samples[channel_number>>1][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 **allocate_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 buffers will be stored consecutively in memory, so
the following technique will work and 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
allocate_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.
float al_duh_get_volume(AL_DUH_PLAYER *dp);
void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume);
These functions get and set the volume of an AL_DUH_PLAYER. See
al_start_duh() for details on the volume parameter. DUMB will always leave
the audio stream volume at maximum and use its own volume control, since
it is more accurate and the click remover will handle changes to the
volume.
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_SIGRENDERERs (or separate AL_DUH_PLAYERS).
- You may not load two IT files concurrently (the sample decompression
algorithm has some static state).
******************
*** 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. If you are in Canada, the Blank Media Levy is
non-refundable, although this is irrelevant since the rate is zero for
computer storage devices. I shall not be held accountable for inaccuracies in
the preceding text.)
Ben Davis
entheh@users.sf.net
