mirror of
https://github.com/ZDoom/gzdoom-gles.git
synced 2024-12-15 14:51:13 +00:00
1718 lines
71 KiB
Text
1718 lines
71 KiB
Text
|
/* _______ ____ __ ___ ___
|
||
|
* \ _ \ \ / \ / \ \ / / ' ' '
|
||
|
* | | \ \ | | || | \/ | . .
|
||
|
* | | | | | | || ||\ /| |
|
||
|
* | | | | | | || || \/ | | ' ' '
|
||
|
* | | | | | | || || | | . .
|
||
|
* | |_/ / \ \__// || | |
|
||
|
* /_______/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 in order to load stand-alone music files.
|
||
|
|
||
|
Optimised: libdumb.a (-ldumb)
|
||
|
Debugging: libdumbd.a (-ldumbd)
|
||
|
|
||
|
|
||
|
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. 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 -lalleg -ldumb
|
||
|
Debugging: -laldmd -lalld -ldumbd
|
||
|
|
||
|
libaldmb.a or libaldmd.a must be linked in first, so the symbols can be
|
||
|
resolved when linking in the other two libraries.
|
||
|
|
||
|
|
||
|
***********************************
|
||
|
*** 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 passing zero or negative numbers to malloc() or 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().
|
||
|
|
||
|
|
||
|
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 datatypes, you can simplify this process by writing a
|
||
|
function for each struct.
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
|
||
|
********************************
|
||
|
*** Signal Type Registration ***
|
||
|
********************************
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
NOTE: SINCE THIS IS NOT TO BE THE INTRODUCTION TO DUMB, SHOULD THE
|
||
|
FOLLOWING INFORMATION BE MOVED TO ANOTHER FILE?
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
If you are lazy, then don't bother to read this section. Simply follow
|
||
|
these steps:
|
||
|
|
||
|
1. Call all the dumb_register_sigtype_*() functions. You must do this
|
||
|
after dumb_init(), but before you try to call load_duh(). If you try
|
||
|
to load any DUH files beforehand, the library will fail to load
|
||
|
them.
|
||
|
|
||
|
2. Run your program, and make sure the DUH file was successfully loaded
|
||
|
and played.
|
||
|
|
||
|
3. Comment out the first dumb_register_sigtype_*() function call.
|
||
|
|
||
|
3.1. If the DUH file is still loaded and played, remove this function
|
||
|
call.
|
||
|
3.2. If the DUH file was not loaded and played, uncomment and keep this
|
||
|
function call.
|
||
|
|
||
|
4. Repeat Step 3 for the other function calls.
|
||
|
|
||
|
Alternatively, the musician might have told you which of the functions you
|
||
|
need to call.
|
||
|
|
||
|
If you are the epitome of laziness, stop after Step 1. However, if you do
|
||
|
this, your executable may contain unnecessary code.
|
||
|
|
||
|
If, on the other hand, you are interested in how all this works, then read
|
||
|
on.
|
||
|
|
||
|
A DUH file comprises a number of 'signals'. A signal may be thought of as
|
||
|
a 'black box'; commands go in, sound comes out. A signal may in turn call
|
||
|
upon other signals to generate sound, and then do something with this
|
||
|
sound to generate its own output.
|
||
|
|
||
|
For example, here are the contents of a simple DUH file:
|
||
|
Signal #0 SEQU
|
||
|
Signal #1 SAMP
|
||
|
Signal #2 SAMP
|
||
|
Signal #3 SAMP
|
||
|
|
||
|
'SEQU' and 'SAMP' are the signal types. 'SAMP' designates a sample, so
|
||
|
Signals #1, #2 and #3 are simple recordings. For instance, Signal #1 could
|
||
|
be a bass drum, Signal #2 a snare drum and Signal #3 a high hat. When
|
||
|
invoked, these signals simply output their respective percussion sounds.
|
||
|
|
||
|
'SEQU' designates a sequence. Signal #0 will therefore generate its sound
|
||
|
by taking the output waveforms from the other signals and mixing them in
|
||
|
at appropriate times. For example:
|
||
|
|
||
|
0.00 Signal #1
|
||
|
|
||
|
0.50 Signal #2
|
||
|
|
||
|
1.00 Signal #1
|
||
|
1.25 Signal #3
|
||
|
1.50 Signal #2 Signal #3
|
||
|
1.75 Signal #3
|
||
|
2.00 Signal #1
|
||
|
2.25 Signal #3
|
||
|
2.50 Signal #2 Signal #3
|
||
|
2.75 Signal #3
|
||
|
3.00 Signal #1
|
||
|
|
||
|
3.50 Signal #2 Signal #3
|
||
|
|
||
|
The numbers down the left are times. Those with a good sense of rhythm
|
||
|
will be able to see that this represents a rather lame, highly cheesy pop
|
||
|
beat. Experienced gurus will also realise how painfully slow the beat is,
|
||
|
given that the times are in seconds. But enough of that.
|
||
|
|
||
|
A DUH is played by taking the output from Signal #0 and sending it through
|
||
|
to the sound card via an Allegro audio stream. If you do not know what an
|
||
|
audio stream is, suffice it to say that you must call Allegro's
|
||
|
install_sound() function, and an audio stream uses one voice (hence one
|
||
|
voice per DUH file). If you still don't know what I'm on about, read up on
|
||
|
Allegro's digital sound system and then come back here. Alternatively,
|
||
|
read porting.txt for details on how to use DUMB without Allegro.
|
||
|
|
||
|
In reality, DUH files are likely to be much more complicated than the
|
||
|
above example. Sequences may call upon other 'sub-sequences' to generate
|
||
|
their sound, so the above beat might be used repeatedly by a
|
||
|
'super-sequence' to generate a more complex (but still lame) piece of
|
||
|
music.
|
||
|
|
||
|
The DUH player library is split into two main parts - the core and the
|
||
|
basic signal types. The core is very simple. It does not know what 'SAMP'
|
||
|
or 'SEQU' mean. In fact it is not familiar with any signal type. It only
|
||
|
contains generic code for dealing with signals and generating output. By
|
||
|
itself, it cannot load or play any DUH file.
|
||
|
|
||
|
In addition to the core, the player library comprises a few basic signal
|
||
|
types, including 'SAMP' and 'SEQU'. In order to use a signal type, you
|
||
|
must 'register' this signal type by calling its corresponding
|
||
|
dumb_register_sigtype_*() function. These functions are listed below,
|
||
|
along with descriptions of the signals.
|
||
|
|
||
|
If you do not register a signal type, the code for that signal type will
|
||
|
not be linked into your executable file. That means DUMB will not become
|
||
|
bloated with age; new features will not add to the size of your executable
|
||
|
unless you use them. Dynamically linked libraries will still increase in
|
||
|
size.
|
||
|
|
||
|
If you try to load a DUH file that uses a signal type you haven't
|
||
|
registered, the library will not crash. It will simply fail to load the
|
||
|
DUH file. In fact, an unrecognised or corrupt signal will prevent the
|
||
|
library from reading the rest of the file - but remember, DUH files are
|
||
|
always (intended to be) generated from other formats, so you will never
|
||
|
lose any data this way.
|
||
|
|
||
|
If you are unsure which signal types a DUH uses, get in contact with the
|
||
|
author of the DUH file, or register them all and remove them one by one to
|
||
|
find out which are required (as described in the steps for lazy people at
|
||
|
the start of this section).
|
||
|
|
||
|
The great advantage of DUMB over other music systems is that it enables
|
||
|
you to create your own signals. Filters, synthesisers and compression
|
||
|
algorithms can all be set up this way. Programming and audio experience
|
||
|
are useful, but the editor provides a way to create your own signals even
|
||
|
if you don't know C. More information is available in the on-line help in
|
||
|
the editor.
|
||
|
|
||
|
If you are interested in the gory details of how a signal works, or if you
|
||
|
wish to brave creating your own without the help of the editor, then see
|
||
|
the section entitled Signal Design.
|
||
|
|
||
|
|
||
|
void dumb_register_sigtype_sample(void);
|
||
|
|
||
|
Registers the sample signal type ('SAMP'). This signal deals with samples,
|
||
|
or recordings, in the DUH file. All samples are monaural; a combining
|
||
|
signal can be used to combine two of these into a stereo sample. The DUMB
|
||
|
library will cater for more than two channels to a certain extent, but it
|
||
|
is currently limited by Allegro's audio streams.
|
||
|
|
||
|
|
||
|
void dumb_register_sigtype_combining(void);
|
||
|
|
||
|
Registers the combining signal type ('COMB'). This signal takes a set of
|
||
|
monaural signals and combines them into one signal with multiple channels.
|
||
|
Stereo samples can be set up this way.
|
||
|
|
||
|
|
||
|
void dumb_register_sigtype_stereopan(void);
|
||
|
|
||
|
Registers the stereo pan signal type ('SPAN'). This signal takes a
|
||
|
monaural sample and sources it at the stereo position you specify,
|
||
|
provided the DUH is played in stereo (or, more precisely, provided stereo
|
||
|
output is requested of the signal).
|
||
|
|
||
|
|
||
|
void dumb_register_sigtype_sequence(void);
|
||
|
|
||
|
Registers the sequence signal type ('SEQU'). This signal sequences the
|
||
|
sound from other signals. It is what turns a random collection of
|
||
|
recordings of single notes into a complete piece of music.
|
||
|
|
||
|
|
||
|
**********************
|
||
|
*** DUH Management ***
|
||
|
**********************
|
||
|
|
||
|
|
||
|
DUH *load_duh(const char *filename);
|
||
|
|
||
|
Loads a .duh file. Before you call this, make sure you have registered all
|
||
|
the necessary signal types (see 'Signal Registration'). The DUH is
|
||
|
returned to you; you will need to pass it to various functions. When you
|
||
|
have finished with it, call unload_duh() to remove it from memory.
|
||
|
|
||
|
There is no special need to check that this function succeeds. All other
|
||
|
functions can safely be called with a null pointer, which means your music
|
||
|
will simply not play if it could not be loaded.
|
||
|
|
||
|
|
||
|
DUH *read_duh(DUMBFILE *f);
|
||
|
|
||
|
Reads a DUH from an already open file, and leaves the file open so you can
|
||
|
read subsequent data from the file if you wish. Otherwise this function is
|
||
|
identical to load_duh().
|
||
|
|
||
|
|
||
|
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
|
||
|
simply lifted from the DUH struct, so it may not truly correspond to the
|
||
|
time for which the DUH will generate sound. However, if the musician is
|
||
|
any good - or if the code that calculated this value is written properly -
|
||
|
you can assume it represents the point at which the DUH first loops, or
|
||
|
else it allows time for any final flourish to be appreciated. It is used
|
||
|
by the Winamp plug-in to decide when to stop.
|
||
|
|
||
|
|
||
|
*******************************
|
||
|
*** Impulse Tracker 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 128 (slightly
|
||
|
simplified), and cut samples will sound again as soon as the congestion
|
||
|
clears. Samples are prioritised by final volume, after all factors
|
||
|
affecting the volume of a sample have been considered.
|
||
|
|
||
|
If you play two or more IT files 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.
|
||
|
|
||
|
|
||
|
DUH *dumb_load_it(const char *filename);
|
||
|
|
||
|
Loads the specified Impulse Tracker file, encapsulating it in a DUH
|
||
|
struct. No signal types need be registered for this to work. The length
|
||
|
will be set to the point at which the music first loops (see
|
||
|
duh_get_length()).
|
||
|
|
||
|
Once the file is loaded, it can be treated exactly the same as any other
|
||
|
DUH in memory.
|
||
|
|
||
|
|
||
|
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().
|
||
|
|
||
|
|
||
|
*******************************
|
||
|
*** DUH Rendering Functions ***
|
||
|
*******************************
|
||
|
|
||
|
|
||
|
Use these functions to generate samples from a DUH. First you call
|
||
|
duh_start_renderer() with the DUH, the number of channels you want and the
|
||
|
position at which you want to start. Then you use duh_render() to generate
|
||
|
the samples. You can call duh_render() as many times as you like, and it
|
||
|
will generate as many or as few samples as you require. When you have
|
||
|
finished, call duh_end_renderer().
|
||
|
|
||
|
|
||
|
DUH_RENDERER *duh_start_renderer(DUH *duh, int n_channels, long pos);
|
||
|
|
||
|
Starts a DUH_RENDERER 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() for that. When you have finished with it, you must
|
||
|
pass it to duh_end_renderer(). You can use as many DUH_RENDERER structs as
|
||
|
you like at the same time.
|
||
|
|
||
|
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 (provided any custom
|
||
|
signal types are properly designed). In other words, you can start a DUH
|
||
|
at a point halfway through a long note, and you will still hear the long
|
||
|
note.
|
||
|
|
||
|
|
||
|
long duh_render(
|
||
|
DUH_RENDERER *dr,
|
||
|
int bits, int unsign,
|
||
|
float volume, float delta,
|
||
|
long size, void *sptr
|
||
|
);
|
||
|
|
||
|
Generates some samples. Pass the DUH_RENDERER as returned by
|
||
|
duh_start_renderer(). 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 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 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 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_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.
|
||
|
|
||
|
|
||
|
long duh_renderer_get_position(DUH_RENDERER *dr);
|
||
|
|
||
|
Tells you what position a DUH_RENDERER 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
|
||
|
DUH_RENDERER and then reinitiate it with the same position.
|
||
|
|
||
|
|
||
|
void duh_end_renderer(DUH_RENDERER *dr);
|
||
|
|
||
|
Terminates a DUH_RENDERER. Be sure to call this when you've finished with
|
||
|
one.
|
||
|
|
||
|
|
||
|
***********************************
|
||
|
*** Signal Design Helper Values ***
|
||
|
***********************************
|
||
|
|
||
|
|
||
|
DUMB_SEMITONE_BASE
|
||
|
|
||
|
When a 'delta' value is required, you can use DUMB_SEMITONE_BASE to
|
||
|
control the pitch. Use pow(DUMB_SEMITONE_BASE, n) to transpose up by n
|
||
|
semitones. To transpose down, use negative n.
|
||
|
|
||
|
|
||
|
DUMB_QUARTERTONE_BASE
|
||
|
|
||
|
When a 'delta' value is required, you can use DUMB_QUARTERTONE_BASE to
|
||
|
control the pitch. Use pow(DUMB_QUARTERTONE_BASE, n) to transpose up by n
|
||
|
quartertones. To transpose down, use negative n.
|
||
|
|
||
|
|
||
|
DUMB_PITCH_BASE
|
||
|
|
||
|
When a 'delta' value is required, you can use DUMB_PITCH_BASE to control
|
||
|
the pitch accurately. Use pow(DUMB_PITCH_BASE, n) to transpose up by n
|
||
|
units, where 256 units represent one semitone. This scale is used for the
|
||
|
'pitch' in a sequence (SEQU).
|
||
|
|
||
|
|
||
|
************************************
|
||
|
*** Signal Design Function Types ***
|
||
|
************************************
|
||
|
|
||
|
|
||
|
In order to design your own signal type, you will have to write six
|
||
|
functions to be linked into your program. They are described below.
|
||
|
|
||
|
See fnptr.txt for help with function pointer types such as these.
|
||
|
|
||
|
|
||
|
typedef void *(*DUH_LOAD_SIGNAL)(DUH *duh, DUMBFILE *file);
|
||
|
|
||
|
Write a function conforming to this type which loads or creates all the
|
||
|
data required by your signal. You may use this, for instance, to load a
|
||
|
sample. You will be reading directly from the DUH file, so make sure you
|
||
|
read exactly the quantity of data stored in the file for this signal. You
|
||
|
should allocate memory (multiple blocks if you like), and return a pointer
|
||
|
referencing all these data. Your data will be stored, and provided
|
||
|
whenever this signal is handled. Be careful about using global data, since
|
||
|
your load_signal function will be called more than once for different
|
||
|
signals of the same type (e.g. for signals which are both samples but are
|
||
|
different samples).
|
||
|
|
||
|
On failure you should return NULL. Please take the possibility of failed
|
||
|
memory allocation seriously, especially when loading large quantities of
|
||
|
data. You should make sure all allocated memory is freed before you return
|
||
|
with failure. See the standard signal types for examples of how to do this
|
||
|
elegantly using your unload_signal function. On failure, you need not
|
||
|
worry about reading the right quantity of data from the file.
|
||
|
|
||
|
Do not close the file under any circumstances.
|
||
|
|
||
|
Often you will write this function before you have written any code to
|
||
|
write a DUH file using this signal. If this is the case, don't worry; you
|
||
|
can write this function free-style, and then the function itself will
|
||
|
serve as a file format reference when you come to create the file.
|
||
|
|
||
|
Note that a null return value will always be interpreted as failure. If
|
||
|
this type of signal does not need to load any data, you should not provide
|
||
|
a load_signal function at all. The absence of this function will convey
|
||
|
the intended message to the library.
|
||
|
|
||
|
|
||
|
typedef void *(*DUH_START_SAMPLES)(
|
||
|
DUH *duh,
|
||
|
void *signal,
|
||
|
int n_channels,
|
||
|
long pos
|
||
|
);
|
||
|
|
||
|
Write a function conforming to this type. Every time your signal is
|
||
|
required to produce some output, this will be called first. The 'signal'
|
||
|
parameter is the same one you returned from your load_signal function. The
|
||
|
'n_channels' parameter specifies how many channels you will need to render
|
||
|
sound in. In general you should support one or two, although sometimes
|
||
|
only one is necessary, depending on how your signal is used. If you can
|
||
|
write generic code to support more channels, then do so. Store the number
|
||
|
of channels for use later, unless you're only permitting one value.
|
||
|
|
||
|
If your signal does not support more than two channels, you are
|
||
|
responsible for making sure it is never invoked with more than two;
|
||
|
likewise if your signal only supports one, then make sure it is never
|
||
|
invoked with more than one. In general you only need to make sure the DUH
|
||
|
file is never rendered with too many channels (see duh_start_renderer()
|
||
|
and al_start_duh()). It may be prudent to use Allegro's ASSERT() macro to
|
||
|
catch bugs of this kind.
|
||
|
|
||
|
The 'pos' parameter specifies where to start, 65536 being one second into
|
||
|
the signal. Even if you do not intend to start in the middle of the signal
|
||
|
yourself, you should support this as it will be used when a DUH is not
|
||
|
played from the beginning.
|
||
|
|
||
|
This function should make the necessary preparations in order to render a
|
||
|
string of samples. All your preparations should be stored in allocated
|
||
|
memory, to which you return a pointer; this allows several instances of
|
||
|
the same signal to play at the same time. You will not be given the 'duh'
|
||
|
and 'signal' parameters again, so you must store them if you need them in
|
||
|
the render_samples or free_samples functions.
|
||
|
|
||
|
Once again, on the rare occasions on which you do not need such data (e.g.
|
||
|
a white noise signal), you should not provide a start_samples function. A
|
||
|
null return code is interpreted as failure, and your music will be lacking
|
||
|
notes (which is better than crashing on undetected memory allocation
|
||
|
failure).
|
||
|
|
||
|
|
||
|
typedef void (*DUH_SET_PARAMETER)(
|
||
|
void *sampinfo,
|
||
|
unsigned char id, long value
|
||
|
);
|
||
|
|
||
|
Some signals can take parameters. For example, a stereo pan signal allows
|
||
|
you to specify the position at which to source the sample, and you might
|
||
|
want to choose the cut-off frequency for a low-pass filter. Such
|
||
|
parameters are set on an instance-by-instance basis, not globally.
|
||
|
Therefore, if you have any parameters, you should place default values for
|
||
|
them in the data you initialise in start_samples. Then you should write a
|
||
|
function conforming to this type, and have it change the parameters when
|
||
|
the correct IDs are passed (see below).
|
||
|
|
||
|
Each of your parameters should be identified by a single byte, which will
|
||
|
be passed in the 'id' parameter. When one of your parameters is correctly
|
||
|
identified by id, you should change the parameter's value in the data you
|
||
|
returned from your start_samples function. These data are available via
|
||
|
the 'sampinfo' parameter. If you do not recognise the ID passed, you may
|
||
|
wish to log the situation using Allegro's TRACE() macro (which will
|
||
|
compile away to nothing unless you define DEBUGMODE), since it signifies a
|
||
|
fault in the DUH file.
|
||
|
|
||
|
Take some care in deciding what should be a parameter and what should be
|
||
|
arranged through the use of separate signals (of the same type). For
|
||
|
example, if you are doing a low-pass filter, you will need a source signal
|
||
|
on which to apply the filter; this signal's index should be loaded by the
|
||
|
load_signal function, so you will create separate filter signals for the
|
||
|
separate source signals. However, the cut-off frequency for the filter is
|
||
|
more suitably stored in a parameter. Here are some guidelines:
|
||
|
|
||
|
Continuous values, or discrete quantities, can be stored in parameters.
|
||
|
Examples: filter cut-off, echo time, stereo pan position.
|
||
|
|
||
|
Discrete indices or references should be loaded by load_signal.
|
||
|
Examples: references to other signals.
|
||
|
|
||
|
Another way of looking at it is as follows:
|
||
|
|
||
|
If a value could be changed halfway through playing the signal, then
|
||
|
consider storing it in a parameter.
|
||
|
|
||
|
If a value needs to be known by the start_samples function and cannot
|
||
|
change later, then consider loading it in the load_signal function.
|
||
|
|
||
|
If your signal has no parameters, do not provide a set_parameters
|
||
|
function. Attempts to change parameters for this signal will not cause a
|
||
|
crash, but will cause the operation to be logged using Allegro's TRACE()
|
||
|
macro if the debugging library is used to play the DUH.
|
||
|
|
||
|
|
||
|
typedef long (*DUH_RENDER_SAMPLES)(
|
||
|
void *sampinfo,
|
||
|
float volume, float delta,
|
||
|
long size, sample_t **samples
|
||
|
);
|
||
|
|
||
|
Write a function conforming to this type. It should render a series of
|
||
|
samples into the array of buffers provided (see below). You are passed
|
||
|
'sampinfo' as returned by start_samples. The 'samples' parameter points to
|
||
|
an array of buffers, one for each channel. You can get a pointer to the
|
||
|
buffer for channel #n with:
|
||
|
|
||
|
sample_t *buffer = samples[n];
|
||
|
|
||
|
As you can see, samples are of type sample_t, which is typedeffed as a
|
||
|
signed int (32 bits). Your waveform should be centred on 0 and should peak
|
||
|
at no more than +/- 32768, or +/- 0x8000, given a volume of 1.0f. If your
|
||
|
waveform goes higher, it will be clipped later on (you do not need to test
|
||
|
for this yourself). Please do not read any special meaning into the volume
|
||
|
parameter; it is simply a factor to be multiplied into each sample. If you
|
||
|
wish to adjust the tone, use a parameter (see DUH_SET_PARAMETER).
|
||
|
|
||
|
In this function, you should render 'size' samples into the buffer for
|
||
|
each channel. Return the number of samples actually rendered, which will
|
||
|
be fewer than 'size' if you run out of samples (e.g. if you reach the end
|
||
|
of a non-looping sample). Never stop short unless the signal ends, and do
|
||
|
not overrun under any circumstances. Update the 'sampinfo' data so that
|
||
|
the samples generated by the next call to render_samples will continue
|
||
|
seamlessly from the samples generated this time.
|
||
|
|
||
|
The delta parameter governs the speed at which your signal will play back.
|
||
|
Higher values of delta should cause the speed and pitch to increase, as
|
||
|
with duh_render(). In general, if delta is 1.0f then your waveform should
|
||
|
be suitable for playback at a sampling rate of 65536 Hz. If you wish to
|
||
|
bend this rule, then be careful - usually it is wiser to adjust your
|
||
|
thinking in other parts.
|
||
|
|
||
|
For example, consider a sample recorded at 44100 Hz, stored in a sample
|
||
|
signal. If a delta of 1.0f is passed to this signal's render function, the
|
||
|
output will be exactly the same as the original sample - a signal at
|
||
|
44100 Hz. So it breaks the rule.
|
||
|
|
||
|
Ah, but it doesn't. Instead, it is wiser to consider the sample stored in
|
||
|
the DUH file as being sampled at 65536 Hz. Once we consider this, it is
|
||
|
clear that the output is suitable for playback at 65536 Hz, so we do not
|
||
|
break the rule. Now it is a simple matter of adjusting all the pitches in
|
||
|
the sequence to compensate for this. See duhtech.txt for details on how to
|
||
|
do this when you are writing the DUH file.
|
||
|
|
||
|
Note that the position that was passed to the start_samples function is
|
||
|
65536 for one second into the signal as played with delta 1.0f. So, with a
|
||
|
sample signal, this position is interpreted as the index of the sample on
|
||
|
which to start. If delta is 2.0, only half a second of the resultant
|
||
|
output will have been skipped.
|
||
|
|
||
|
Once again, please do not read any special meaning into the delta
|
||
|
parameter. The effect of doubling delta should be virtually the same as
|
||
|
the effect of not doubling delta but resampling the output. If you wish to
|
||
|
adjust the tone for different pitches, use a parameter.
|
||
|
|
||
|
This function is compulsory. Silent signals only increase processor and
|
||
|
memory usage, and we are not Microsoft-Intel evangelists.
|
||
|
|
||
|
|
||
|
typedef void (*DUH_END_SAMPLES)(void *sampinfo);
|
||
|
|
||
|
Write a function conforming to this type. It will be called when a signal
|
||
|
stops playing. The parameter points to the data you returned from the
|
||
|
start_samples function, and here you should simply free the memory up.
|
||
|
|
||
|
This function should be provided, always if, and only if, start_samples is
|
||
|
present. The debugging library will check you get this right.
|
||
|
|
||
|
|
||
|
typedef void (*DUH_UNLOAD_SIGNAL)(void *signal);
|
||
|
|
||
|
Write a function conforming to this type. It will be called when the DUH
|
||
|
is removed from memory. It should free all memory allocated by your
|
||
|
load_signal function. The parameter is the same pointer that you returned
|
||
|
from load_signal.
|
||
|
|
||
|
If you only ever use this signal type with make_duh(), and not with
|
||
|
dumb_register_sigtype(), then the following does not apply.
|
||
|
|
||
|
If load_signal is present, unload_signal should also be present; if you
|
||
|
did not provide a load_signal function, then you should not provide an
|
||
|
unload_signal function either. The debugging library will check you get
|
||
|
this right.
|
||
|
|
||
|
|
||
|
**********************************
|
||
|
*** Signal Design Registration ***
|
||
|
**********************************
|
||
|
|
||
|
|
||
|
void dumb_register_sigtype(DUH_SIGTYPE_DESC *desc);
|
||
|
|
||
|
When you have written all the functions that represent your signal, you
|
||
|
will need to register them with the library before it will be able to load
|
||
|
your DUH file. Use this function. The DUH_SIGTYPE_DESC struct contains the
|
||
|
following fields:
|
||
|
|
||
|
long type;
|
||
|
DUH_LOAD_SIGNAL load_signal;
|
||
|
DUH_START_SAMPLES start_samples;
|
||
|
DUH_SET_PARAMETER set_parameter;
|
||
|
DUH_RENDER_SAMPLES render_samples;
|
||
|
DUH_END_SAMPLES end_samples;
|
||
|
DUH_UNLOAD_SIGNAL unload_signal;
|
||
|
|
||
|
You need to create a DUH_SIGTYPE_DESC struct and pass its pointer to
|
||
|
dumb_register_sigtype(). The struct must be in permanent memory. In other
|
||
|
words, it must be either global or static, and you should not modify it
|
||
|
later. DUMB will not make its own copy.
|
||
|
|
||
|
'type' should be a four-character string encoded with DUMB_ID(), for
|
||
|
example DUMB_ID('M','E','O','W'). By convention it should be upper case,
|
||
|
and padded with spaces if you do not use all four characters. However, you
|
||
|
do not have to stick to this.
|
||
|
|
||
|
If you are not providing a function, specify NULL for the corresponding
|
||
|
function pointer.
|
||
|
|
||
|
|
||
|
**********************************
|
||
|
*** Signal Rendering Functions ***
|
||
|
**********************************
|
||
|
|
||
|
|
||
|
When you are designing your own signals, you will often want to retrieve
|
||
|
samples from another signal in the DUH. This signal's index ('sig') should
|
||
|
be loaded by your load_samples function. You can use the following
|
||
|
functions to obtain the samples.
|
||
|
|
||
|
|
||
|
DUH_SIGNAL_SAMPINFO *duh_signal_start_samples(
|
||
|
DUH *duh, int sig, int n_channels, long pos
|
||
|
);
|
||
|
|
||
|
Specifies where you want to start rendering. This function returns a
|
||
|
DUH_SIGNAL_SAMPINFO struct, which you need to pass to the other functions.
|
||
|
You can use as many DUH_SIGNAL_SAMPINFOs at once as you like.
|
||
|
|
||
|
Pass the DUH and the index of the signal whose samples you want to obtain
|
||
|
('sig'). Specify how many channels you want, and where you want to start
|
||
|
rendering (65536 represents one second).
|
||
|
|
||
|
There is no special need to check that this function succeeds. The other
|
||
|
functions are safe to call with null pointers. However, checking the
|
||
|
return value can make your code more efficient.
|
||
|
|
||
|
Be sure to call duh_signal_end_samples() when you've finished.
|
||
|
|
||
|
|
||
|
void duh_signal_set_parameter(
|
||
|
DUH_SIGNAL_SAMPINFO *signal_sampinfo,
|
||
|
unsigned char id, long value
|
||
|
);
|
||
|
|
||
|
Sets a parameter for the signal whose samples are being rendered by
|
||
|
signal_sampinfo.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
Calls the set_parameter function for the instance started by
|
||
|
duh_signal_start_samples of the signal whose details you passed to that
|
||
|
function. Exactly what this does depends on the signal in question.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
THIS IS NOT VERY HELPFUL. REFER TO A FILE?
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
long duh_signal_render_samples(
|
||
|
DUH_SIGNAL_SAMPINFO *signal_sampinfo,
|
||
|
float volume, float delta,
|
||
|
long size, sample_t **samples
|
||
|
);
|
||
|
|
||
|
Renders 'size' samples of the signal for which signal_sampinfo was set up.
|
||
|
See duh_render() and DUH_RENDER_SAMPLES for details on the 'volume' and
|
||
|
'delta' parameters. This function will return the number of samples
|
||
|
generated, which will be fewer than 'size' if the signal ends.
|
||
|
|
||
|
Sometimes you can pass the array of sample buffers which was passed to
|
||
|
your function, and process the data in place. Other times you will have to
|
||
|
set up the array of sample buffer pointers yourself, making sure each
|
||
|
buffer can hold 'size' samples. Below is some code to do that. Note that
|
||
|
we prefix some variable names with sub-, so they don't clash with the
|
||
|
parameters to the function that would typically contain this code.
|
||
|
|
||
|
sample_t **subsamples;
|
||
|
int n;
|
||
|
long subsize;
|
||
|
|
||
|
subsamples = malloc(n_channels * sizeof(*subsamples));
|
||
|
|
||
|
if (!subsamples)
|
||
|
return 0;
|
||
|
|
||
|
subsamples[0] = malloc(size * n_channels * sizeof(*subsamples[0]));
|
||
|
|
||
|
if (!subsamples[0]) {
|
||
|
free(subsamples);
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
for (n = 1; n < n_channels; n++)
|
||
|
subsamples[n] = subsamples[n-1] + size;
|
||
|
|
||
|
subsize = signal_render_samples(
|
||
|
subsampinfo,
|
||
|
volume, delta,
|
||
|
size, subsamples
|
||
|
);
|
||
|
|
||
|
/* Process the samples here. */
|
||
|
|
||
|
free(subsamples[0]);
|
||
|
free(subsamples);
|
||
|
|
||
|
return subsize;
|
||
|
|
||
|
|
||
|
void duh_signal_end_samples(DUH_SIGNAL_SAMPINFO *signal_sampinfo);
|
||
|
|
||
|
Call this when you have finished with a DUH_SIGNAL_SAMPINFO struct. It
|
||
|
will free all memory used by the struct.
|
||
|
|
||
|
|
||
|
**************************
|
||
|
*** Resampling Helpers ***
|
||
|
**************************
|
||
|
|
||
|
|
||
|
The DUH player library provides a versatile resampling system. The sample
|
||
|
signal type uses it, and it is available for use in any of your signals.
|
||
|
|
||
|
Be warned that the resampler may overrun the memory you specify by up to
|
||
|
DUMB_EXTRA_SAMPLES samples, so you must allocate these samples and set
|
||
|
them to appropriate values when you load your signal. Generally, if you
|
||
|
are going to loop, set them to reflect the samples at the loop start
|
||
|
point; if you are not going to loop, set them to zero.
|
||
|
|
||
|
DUMB_EXTRA_SAMPLES is defined as follows:
|
||
|
|
||
|
#define DUMB_EXTRA_SAMPLES 3
|
||
|
|
||
|
|
||
|
extern int resampling_quality;
|
||
|
|
||
|
Allows you to control the quality of all resampling that takes place. This
|
||
|
may be set to any value from 0 to 4. Higher values will sound better, but
|
||
|
lower values will use up less processor time.
|
||
|
|
||
|
| --___
|
||
|
0 - Aliasing |__--- __
|
||
|
| ___--
|
||
|
|
||
|
| __
|
||
|
1 - Linear resampling | / \ /\
|
||
|
|/ \/ \__
|
||
|
|
||
|
2 - Linear resampling / linear average
|
||
|
|
||
|
3 - Quadratic / linear average
|
||
|
|
||
|
4 - Cubic / linear average
|
||
|
|
||
|
Level 0 has very noticeable unwanted overtones. It will occasionally
|
||
|
produce satisfactory results for noisy signals, but usually you will
|
||
|
want to pay for the extra processor time (which isn't much) and go
|
||
|
for Level 1.
|
||
|
|
||
|
Levels 1 and 2 are already pretty good. When resampling down a few
|
||
|
octaves, however, you will begin to notice unwanted high frequencies.
|
||
|
These can be eliminated by switching to Levels 3 or 4.
|
||
|
|
||
|
When Level 2 or higher are selected, a linear average function is used for
|
||
|
speeding the wave up. Instead of skipping samples, all samples in the
|
||
|
interval will be averaged. The interval is also smoothed at the edges.
|
||
|
This will be especially beneficial when increasing the pitch by several
|
||
|
octaves.
|
||
|
|
||
|
Levels 3 and 4 are both smooth curves to the eye. They both give
|
||
|
extremely good performance, but you may sometimes notice the difference
|
||
|
when reducing the pitch of a sample by several octaves, where Level 3
|
||
|
may exhibit unwanted high frequencies.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
NOTE: WHAT IS THE DEFAULT? (2 at the moment, but might change. Config?)
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
long dumb_resample(
|
||
|
sample_t *src, long *_src_pos, int *_src_subpos,
|
||
|
long src_start, long src_end,
|
||
|
sample_t *dst, long dst_size,
|
||
|
float delta, int *_dir,
|
||
|
DUMB_RESAMPLE_PICKUP pickup, void *pickup_data
|
||
|
);
|
||
|
|
||
|
This is the resampling function. It takes an array of source samples and
|
||
|
fills as much of the destination array as it can for you. Its operation is
|
||
|
quite complicated, so pay attention.
|
||
|
|
||
|
All the parameters prefixed with an underline (_) are pointers to the
|
||
|
fields they describe. This means the function can modify the variables you
|
||
|
pass, but you have to prefix the variable with an ampersand (&) when
|
||
|
passing it. If you get warnings about ints being converted to pointers
|
||
|
without casts, you have most likely forgotten an ampersand somewhere.
|
||
|
|
||
|
'src' points to the source sample data. It should point to the beginning
|
||
|
of the sample, even if you are starting your resampling from somewhere in
|
||
|
the middle. Do not break this rule unless you know what you're doing.
|
||
|
|
||
|
'_src_pos' and '_src_subpos' together represent the current position in
|
||
|
the sample. When you first call the function, they represent the starting
|
||
|
position. Once the function has done its work, they will represent the
|
||
|
point at which the resampling stopped. '_src_pos' is measured in samples.
|
||
|
'_src_subpos' represents how far between samples we are, and ranges from
|
||
|
0 to 65535 - so if _src_subpos is 65535, we are very nearly on to the next
|
||
|
sample.
|
||
|
|
||
|
Once _src_pos and _src_subpos have been modified by this function, you can
|
||
|
pass them to the function again and the resampling will continue
|
||
|
seamlessly. This is important, as you will hardly ever get to render all
|
||
|
your samples in one go. Typically you will make one call to this function
|
||
|
from within your render_samples function.
|
||
|
|
||
|
This function does not need to know the size of the source buffer as such.
|
||
|
Instead, it knows src_start and src_end, which are start and end points.
|
||
|
The end point actually points to the first sample not to use, following
|
||
|
the usual start-inclusive end-exclusive convention. In general, the
|
||
|
resampling will stop when src_pos tries to pass one of these.
|
||
|
|
||
|
WARNING: dumb_resample() may read up to DUMB_EXTRA_SAMPLES samples beyond
|
||
|
src_end. Make sure the memory belongs to you.
|
||
|
|
||
|
The _dir parameter should be either 1 or -1, and tells this function
|
||
|
whether to go forwards or backwards respectively through the source sample
|
||
|
buffer. If _dir is 0, nothing will happen - resampling has stopped
|
||
|
permanently. Any other values of _dir will have unpredictable results, and
|
||
|
the debugging library will abort if you try to use them.
|
||
|
|
||
|
If _dir is 1, then _src_pos will only be tested against src_end.
|
||
|
If _dir is -1, then _src_pos will only be tested against src_start.
|
||
|
|
||
|
That means you can set src_start and src_end to your loop points, and
|
||
|
start playing from the beginning of the sample. The resampling will
|
||
|
proceed unimpeded while _src_pos is outside the loop section, provided it
|
||
|
is advancing towards the loop section. The sample signal makes extensive
|
||
|
use of this capability.
|
||
|
|
||
|
The output waveform will be rendered into the buffer pointed to by dst.
|
||
|
Up to dst_size samples will be generated. Fewer will be generated if the
|
||
|
resampling stops permanently. The number generated will be returned. You
|
||
|
can find out if resampling ended by testing the value of your direction
|
||
|
variable (pointed to by _dir); if it is 0, then resampling stopped
|
||
|
permanently.
|
||
|
|
||
|
If you pass NULL for dst, no samples will be generated. However, _src_pos,
|
||
|
_src_subpos and _dir will be updated as normal. The pick-up function will
|
||
|
be called as necessary; you should pass the usual 'src' parameter so it
|
||
|
can be passed to your pick-up function. (See below for information on
|
||
|
pick-up functions.) The function returns the number of samples that would
|
||
|
have been generated, had dst pointed somewhere. The operation of
|
||
|
do_resample() when dst is NULL is exactly the same as that when dst points
|
||
|
somewhere. However, do_resample() is much faster in this case; you should
|
||
|
use it when volume is 0, or when you are culling quieter samples to gain
|
||
|
execution speed.
|
||
|
|
||
|
If delta is 1.0f, the destination is the same speed as the source. Greater
|
||
|
values cause the sample to speed up, and lesser values cause the sample to
|
||
|
slow down. delta should always be positive.
|
||
|
|
||
|
We have covered most of the parameters. There are only two left - pickup
|
||
|
and pickup_data. The simplest usage is to set these both to NULL. Then, if
|
||
|
resampling stops, it stops permanently. Use this if your sample will not
|
||
|
loop.
|
||
|
|
||
|
Alternatively, you may wish to write a pick-up function. Your pick-up
|
||
|
function will take control whenever _src_pos tries to pass the start or
|
||
|
end points. You can use it for looping, or for a multitude of other tasks.
|
||
|
The typedef is as follows:
|
||
|
|
||
|
typedef int (*DUMB_RESAMPLE_PICKUP)(
|
||
|
sample_t *src, long *_src_pos, int *_src_subpos,
|
||
|
long *_src_start, long *_src_end,
|
||
|
int dir,
|
||
|
void *data
|
||
|
);
|
||
|
|
||
|
You are passed the source buffer, in case you want to fill it with new
|
||
|
samples. You have the _src_pos, _src_subpos, _src_start and _src_end
|
||
|
pointers, should you need to change the values to which they point. You
|
||
|
also have dir, but note that it is not a pointer. Instead, you should
|
||
|
return the new direction, or 0 to stop the resampling permanently.
|
||
|
|
||
|
The data parameter is a copy of pickup_data as passed to dumb_resample().
|
||
|
This is typically used to give you access to your 'sampinfo' parameter,
|
||
|
passed to your render_samples function.
|
||
|
|
||
|
BEWARE: you must refer to and change src_pos, src_subpos, src_start and
|
||
|
src_end through the parameters passed. Do not mistakenly use their
|
||
|
equivalents in your struct instead. The equivalents in your struct
|
||
|
will eventually be updated, but they will not be accurate during
|
||
|
the pick-up function.
|
||
|
|
||
|
On entry to this function, src_pos and src_subpos will have overrun by a
|
||
|
small amount. When changing them, you should preserve this overrun. The
|
||
|
following examples will do this for you:
|
||
|
|
||
|
If you are executing a simple loop, subtract (or add) the difference
|
||
|
between the loop points from (or to) src_pos. Do not simply set src_pos
|
||
|
to the other loop point.
|
||
|
|
||
|
*_src_pos -= *_src_end - *_src_start;
|
||
|
|
||
|
If you are executing a ping-pong loop, you need to reflect the pointer
|
||
|
off the loop boundary. To reflect off the loop end point:
|
||
|
|
||
|
*_src_pos = (*_src_end << 1) - 1 - *_src_pos;
|
||
|
*_src_subpos ^= 65535;
|
||
|
dir = -1;
|
||
|
|
||
|
To reflect off the loop start point:
|
||
|
|
||
|
*_src_pos = (*_src_start << 1) - 1 - *_src_pos;
|
||
|
*_src_subpos ^= 65535;
|
||
|
dir = 1;
|
||
|
|
||
|
In each case, don't forget to return the new direction correctly!
|
||
|
|
||
|
An ideal example of a pick-up function can be found in src/sample.c.
|
||
|
|
||
|
Of course there is more that can be done with a pick-up function. Enjoy
|
||
|
experimenting!
|
||
|
|
||
|
|
||
|
************************
|
||
|
*** DUH Construction ***
|
||
|
************************
|
||
|
|
||
|
|
||
|
DUH *make_duh(
|
||
|
long length,
|
||
|
int n_signals,
|
||
|
DUH_SIGTYPE_DESC *desc[],
|
||
|
void *signal[]
|
||
|
);
|
||
|
|
||
|
Constructs a DUH from its component parts. Use this function if you are
|
||
|
writing a function to load a music file format other than .duh. Indeed,
|
||
|
this function is used internally to load IT files.
|
||
|
|
||
|
Before you call this function, you must do some preparation. Your DUH will
|
||
|
contain a fixed number of signals; pass this number as n_signals. Each
|
||
|
signal will have a DUH_SIGTYPE_DESC struct, and you pass an array of
|
||
|
pointers to these. The DUH_SIGTYPE_DESC struct contains the following
|
||
|
fields:
|
||
|
|
||
|
long type;
|
||
|
DUH_LOAD_SIGNAL load_signal;
|
||
|
DUH_START_SAMPLES start_samples;
|
||
|
DUH_SET_PARAMETER set_parameter;
|
||
|
DUH_RENDER_SAMPLES render_samples;
|
||
|
DUH_END_SAMPLES end_samples;
|
||
|
DUH_UNLOAD_SIGNAL unload_signal;
|
||
|
|
||
|
The structs must be in permanent memory, i.e. either global or static, and
|
||
|
not modified later; however, the array of pointers can be destroyed as
|
||
|
soon as the function returns.
|
||
|
|
||
|
The values of 'type' and 'load_signal' are irrelevant; set them to 0 and
|
||
|
NULL respectively, unless you are using the DUH_SIGTYPE_DESC struct
|
||
|
elsewhere.
|
||
|
|
||
|
Because 'load_signal' is never used, you must provide an array of pointers
|
||
|
to the data that 'load_signal' would otherwise have returned. This will
|
||
|
be passed to the other functions as 'signal'. Once again, the array of
|
||
|
pointers can be destroyed as soon as the function returns. As for the
|
||
|
pointers themselves:
|
||
|
|
||
|
If an 'unload_signal' function is provided, then that will be used to
|
||
|
deallocate the pointer when you finally destroy the DUH. If the function
|
||
|
is not provided, then you are responsible for deallocating any memory
|
||
|
referenced by that pointer yourself. This applies individually to each
|
||
|
signal.
|
||
|
|
||
|
If this function fails and returns NULL, then any 'unload_signal'
|
||
|
functions you provided will have been called. You do not have any extra
|
||
|
work to do if it fails.
|
||
|
|
||
|
|
||
|
********************************
|
||
|
*** 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()).
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
|
||
|
***********************************************
|
||
|
*** Allegro Datafile Registration Functions ***
|
||
|
***********************************************
|
||
|
|
||
|
|
||
|
void register_dat_duh(void);
|
||
|
|
||
|
If you wish to put a DUH file in an Allegro datafile, you must use "DUH "
|
||
|
for the type. The grabber will have a box for the type when you insert a
|
||
|
new object. The grabber will treat the DUH file as binary data, which
|
||
|
means the datafile will contain an exact copy of the DUH file on disk.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
TODO: make it possible to choose the type...
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
You must then call register_dat_duh() 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 need to check the type of the object for whatever reason, you can
|
||
|
use DAT_DUH, defined as follows:
|
||
|
|
||
|
#define DAT_DUH DAT_ID('D','U','H',' ')
|
||
|
|
||
|
The following example iterates through all the DUHs in disan.dat:
|
||
|
|
||
|
DATAFILE *dat;
|
||
|
int n;
|
||
|
|
||
|
register_dat_duh();
|
||
|
dat = load_datafile("disan.dat");
|
||
|
|
||
|
for (n = 0; dat[n].type != DAT_END; n++) {
|
||
|
if (dat[n].type == DAT_DUH) {
|
||
|
DUH *duh = dat[n].dat;
|
||
|
/* Insert code here to play 'duh' or whatever you want to do. */
|
||
|
}
|
||
|
}
|
||
|
|
||
|
unload_datafile(dat);
|
||
|
|
||
|
|
||
|
void register_dat_it(void);
|
||
|
|
||
|
Inserting an IT file in an Allegro datafile is the same as inserting a DUH
|
||
|
file, except the type has to be "IT ", the registration function is
|
||
|
register_dat_it(), and the following definition is available for use
|
||
|
instead of DAT_DUH:
|
||
|
|
||
|
#define DAT_IT DAT_ID('I','T',' ',' ')
|
||
|
|
||
|
Once the datafile is loaded, the 'dat' field indeed points to a DUH
|
||
|
struct. There are no differences other than those listed above.
|
||
|
|
||
|
|
||
|
*************************************
|
||
|
*** 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.
|
||
|
|
||
|
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, provided
|
||
|
any custom signal types are designed properly. 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.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
NOTE: IS THAT TRUE ON ALL SYSTEMS?
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
|
||
|
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_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_RENDERER 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. In other words, your music will not
|
||
|
be cut off prematurely.
|
||
|
|
||
|
In case you were wondering, it is definitely not safe to call
|
||
|
al_poll_duh() from an interrupt context. Not only is no part of DUMB
|
||
|
locked in memory, but many signals and many core library functions
|
||
|
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 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. However, even if you do not think
|
||
|
you are targeting DOS, it is worth considering that calling this function
|
||
|
regularly from your main loop is likely to be much more efficient than
|
||
|
relying on task switching to do it for you.)
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
NOTE: HOW TO GET AROUND THIS?
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
DUH_RENDERER *al_duh_get_renderer(AL_DUH_PLAYER *dp);
|
||
|
|
||
|
This function returns to you the DUH_RENDERER underlying the specified
|
||
|
AL_DUH_PLAYER. It has no practical use in this release, but it
|
||
|
TODO: Write this. Also see if it should go in howto.txt.
|
||
|
|
||
|
|
||
|
******************
|
||
|
*** Conclusion ***
|
||
|
******************
|
||
|
|
||
|
|
||
|
I conclude that... DUMB is the bestest music player in the world because...
|
||
|
Complete this sentence in fifteen words or fewer... D'OH!
|
||
|
|
||
|
|
||
|
Ben Davis
|
||
|
entheh@users.sf.net
|
||
|
IRC EFnet #dumb
|
||
|
See readme.txt for details on using IRC.
|