mirror of
https://github.com/ZDoom/qzdoom-gpl.git
synced 2024-12-12 21:22:22 +00:00
846 lines
38 KiB
Text
846 lines
38 KiB
Text
|
/* _______ ____ __ ___ ___
|
||
|
* \ _ \ \ / \ / \ \ / / ' ' '
|
||
|
* | | \ \ | | || | \/ | . .
|
||
|
* | | | | | | || ||\ /| |
|
||
|
* | | | | | | || || \/ | | ' ' '
|
||
|
* | | | | | | || || | | . .
|
||
|
* | |_/ / \ \__// || | |
|
||
|
* /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque
|
||
|
* / \
|
||
|
* / . \
|
||
|
* howto.txt - How To Use DUMB. / / \ \
|
||
|
* | < / \_
|
||
|
* See readme.txt for general information on | \/ /\ /
|
||
|
* DUMB and how to set it up. \_ / > /
|
||
|
* | \ / /
|
||
|
* | ' /
|
||
|
* \__/
|
||
|
*/
|
||
|
|
||
|
|
||
|
********************
|
||
|
*** Introduction ***
|
||
|
********************
|
||
|
|
||
|
|
||
|
Welcome to the DUMB How-To! It is assumed here that you have already set DUMB
|
||
|
up on your system, with or without Allegro. If not, please see readme.txt.
|
||
|
|
||
|
|
||
|
*********************************
|
||
|
*** Adding music to your game ***
|
||
|
*********************************
|
||
|
|
||
|
|
||
|
These instructions will help you add a piece of music to your game, assuming
|
||
|
your music is stored in a stand-alone IT, XM, S3M or MOD file. If you wish to
|
||
|
use a different method (such as putting the music file in an Allegro
|
||
|
datafile), please follow these instructions first, test your program, and
|
||
|
then follow the instructions further down for adapting your code.
|
||
|
|
||
|
|
||
|
1. You need to include DUMB's header file. If you have Allegro, add the
|
||
|
following line to the top of your source file (or at the top of each file
|
||
|
where you wish to use DUMB):
|
||
|
|
||
|
#include <aldumb.h>
|
||
|
|
||
|
If you do not have Allegro or do not wish to use it, use dumb.h instead.
|
||
|
|
||
|
|
||
|
2. You need to link with DUMB's library file or files. If you are compiling
|
||
|
with GCC from a command line on any platform, you need to add the
|
||
|
following to the command line:
|
||
|
|
||
|
If you are using Allegro: -laldmd -ldumbd
|
||
|
If you are not using Allegro: -ldumbd
|
||
|
|
||
|
If you are using MSVC from the command line:
|
||
|
|
||
|
If you are using Allegro: /link aldmd.lib dumbd.lib
|
||
|
If you are not using Allegro: /link dumbd.lib
|
||
|
|
||
|
With MSVC, you must also add /MD to the command line when compiling (not
|
||
|
when linking).
|
||
|
|
||
|
Note that -laldmd or aldmd.lib must PRECEDE alleg.lib, -lalleg_s,
|
||
|
`allegro-config --libs`, or whatever you are already using to link with
|
||
|
Allegro. For MSVC users, the /MD flag selects the multithreaded DLL
|
||
|
implementation of the standard libraries; since DUMB is statically linked,
|
||
|
you have to use the same library DUMB uses. You would also need this flag
|
||
|
to link statically with Allegro; if you already have it, there's no need
|
||
|
to put it twice.
|
||
|
|
||
|
(If anyone would like to contribute instructions for doing the above using
|
||
|
MSVC's IDE, please contact me. Contact details are at the end of this
|
||
|
file.)
|
||
|
|
||
|
If you are using RHIDE, go to Options -> Libraries. You will need to type
|
||
|
'aldmd' and 'dumbd' in two boxes, making sure 'aldmd' comes above whatever
|
||
|
you are using to link with Allegro (or just put 'dumbd' if you are not
|
||
|
using Allegro). Make sure the box next to each of these libraries is
|
||
|
checked.
|
||
|
|
||
|
The above are the debugging libraries. It is VERY HIGHLY RECOMMENDED that
|
||
|
you use the debugging libraries at first. The reason is as follows.
|
||
|
Although DUMB is supposedly robust against corrupt music files and things
|
||
|
like lack of memory, it will NOT tolerate programmer error. If you write
|
||
|
faulty code, DUMB will probably crash rather than returning an error code
|
||
|
for you. However, the debugging libraries will abort in many cases,
|
||
|
enabling you to find out what the cause is.
|
||
|
|
||
|
Once your program is up and running reliably, you can replace 'aldmd' with
|
||
|
'aldmb' and 'dumbd' with 'dumb'. Don't forget to do this, or DUMB will be
|
||
|
a lot slower than it should be!
|
||
|
|
||
|
|
||
|
3. As you use DUMB, it may claim system resources (memory in particular). You
|
||
|
will need to arrange for these resources to be freed at the end. Doing so
|
||
|
is very easy. Simply write the following line at the top of your main
|
||
|
function, but below allegro_init() if you are using Allegro:
|
||
|
|
||
|
atexit(&dumb_exit);
|
||
|
|
||
|
This arranges for the function dumb_exit() to be called when your program
|
||
|
exits; you do not need to call dumb_exit() yourself. This method is
|
||
|
preferable to calling dumb_exit() manually, as it will free resources even
|
||
|
if your program aborts unexpectedly.
|
||
|
|
||
|
If you are happy with this, please skip ahead to Step 4. If you are
|
||
|
interested in alternative methods, read on, but read on carefully.
|
||
|
|
||
|
In fact it mostly doesn't matter where you put the above atexit() line,
|
||
|
provided it gets called only once, and before you do anything with DUMB.
|
||
|
If you are using DUMB with Allegro, it is recommended that you write the
|
||
|
functions in this order:
|
||
|
|
||
|
allegro_init();
|
||
|
atexit(&dumb_exit);
|
||
|
|
||
|
And then you must NOT call allegro_exit() yourself (because it has to be
|
||
|
called after dumb_exit()). Alternatively, if you prefer not to use
|
||
|
atexit() (or you cannot), you will have to do the following before
|
||
|
exiting:
|
||
|
|
||
|
dumb_exit();
|
||
|
allegro_exit();
|
||
|
|
||
|
|
||
|
4. DUMB does not automatically do any of its own file input. You have to tell
|
||
|
it how to read files. Don't worry, it's easy. Simply call the following
|
||
|
function near the beginning of your program, after your atexit() call:
|
||
|
|
||
|
dumb_register_stdfiles();
|
||
|
|
||
|
This tells DUMB to use ordinary stdio FILE structs for reading and writing
|
||
|
files. If you are using Allegro and would rather DUMB used PACKFILEs, call
|
||
|
the following function INSTEAD:
|
||
|
|
||
|
dumb_register_packfiles();
|
||
|
|
||
|
In the latter case, DUMB will be affected by any password you set with
|
||
|
packfile_password() in the same way that other PACKFILEs are.
|
||
|
|
||
|
Note that the procedure for loading datafiles with embedded music is
|
||
|
independent of these two functions; even if you will be loading datafiles,
|
||
|
you can use either of these functions. If you are loading datafiles, your
|
||
|
executable might be slightly smaller if you use dumb_register_packfiles().
|
||
|
On the other hand, dumb_register_stdfiles() will probably be faster. If
|
||
|
you are only ever going to load datafiles and never stand-alone files, you
|
||
|
can actually leave this step out; but I would recommend you put this in,
|
||
|
test your code with a stand-alone file, then follow the instructions in
|
||
|
the next section in order to adapt your code to use the datafile (you will
|
||
|
be reminded that you can remove the function call).
|
||
|
|
||
|
|
||
|
5. If you are using Allegro, you'll have to initialise Allegro's sound
|
||
|
system. In most cases the following line will do the job:
|
||
|
|
||
|
install_sound(DIGI_AUTODETECT, MIDI_NONE, NULL);
|
||
|
|
||
|
You may like to initialise a MIDI driver though; see Allegro's docs for
|
||
|
details. Put this line after allegro_init().
|
||
|
|
||
|
|
||
|
6. All pieces of music are stored in memory in DUH structs. To handle these,
|
||
|
you must define pointers to them. Such pointers look like this:
|
||
|
|
||
|
DUH *myduh;
|
||
|
|
||
|
You can of course replace 'myduh' with anything you like. If you are
|
||
|
unfamiliar with pointers, please see ptr.txt. It is very important that
|
||
|
you understand these if you wish to use DUMB correctly.
|
||
|
|
||
|
You do not have direct access to the contents of a DUH struct, so do not
|
||
|
try. DUMB's functions provide everything you need; if you disagree, please
|
||
|
let me know and I shall see what I can do. Contact details are at the end
|
||
|
of this file.
|
||
|
|
||
|
Given the above definition, you can load a piece of music using one of the
|
||
|
following lines, depending on what file format you want to load:
|
||
|
|
||
|
myduh = dumb_load_it("a_one.it");
|
||
|
myduh = dumb_load_xm("a_two.xm");
|
||
|
myduh = dumb_load_s3m("a_one_two.s3m");
|
||
|
myduh = dumb_load_mod("three_four.mod");
|
||
|
|
||
|
Obviously you can use relative or absolute paths as normal. You should
|
||
|
always use forward slash (/), not backslash (\), when coding in C and
|
||
|
similar languages.
|
||
|
|
||
|
Every piece of music you load must be unloaded when you've finished with
|
||
|
it. When you type the above line in, it is good practice to type the
|
||
|
following line in at the same time, but put it at the end of the program:
|
||
|
|
||
|
unload_duh(myduh);
|
||
|
|
||
|
You will now be able to use the DUH struct anywhere in between the two
|
||
|
lines you just added. There is no need to check the return value; if the
|
||
|
DUH failed to load for one reason or another (this could be due to lack of
|
||
|
memory as well as the file not being there), then DUMB will do nothing -
|
||
|
safely.
|
||
|
|
||
|
|
||
|
7. From this step onwards, it will be assumed you're using Allegro. If not,
|
||
|
please read these steps anyway, and then see the section entitled
|
||
|
"Rendering music into a buffer". You will have to write your own playback
|
||
|
code using whatever sound output system is available. Alternatively you
|
||
|
may like to write data to a file (especially if you have a file that
|
||
|
consumes a lot of processor time), but beware that any streaming audio
|
||
|
format is likely to be substantially larger than the module file you
|
||
|
generate it from, and formats like MP3 will be lower quality. You might
|
||
|
not be able to hear the difference between the MP3 and the original, but
|
||
|
many people can and don't like it, so please consider them. I'm one of
|
||
|
them. If you really want to use a lossy compression format, I highly
|
||
|
recommend Ogg Vorbis:
|
||
|
|
||
|
http://www.vorbis.com/
|
||
|
|
||
|
But I digress.
|
||
|
|
||
|
In order to play the DUH you loaded, you need to define a pointer to an
|
||
|
AL_DUH_PLAYER struct:
|
||
|
|
||
|
AL_DUH_PLAYER *dp;
|
||
|
|
||
|
Two of the functions you will need are prototyped as follows:
|
||
|
|
||
|
AL_DUH_PLAYER *al_start_duh(DUH *duh, int n_channels, long pos,
|
||
|
float volume, long bufsize, int freq);
|
||
|
|
||
|
void al_stop_duh(AL_DUH_PLAYER *dp);
|
||
|
|
||
|
As you can see, al_start_duh() returns a pointer to an AL_DUH_PLAYER
|
||
|
struct when you call it. You then pass this pointer to all the other
|
||
|
functions. Again, if it is a NULL pointer for whatever reason (usually
|
||
|
lack of memory), DUMB will safely do nothing. When you call al_stop_duh(),
|
||
|
the pointer becomes invalid and you should not use it again; if there's
|
||
|
any risk of the pointer being used again, it is wise to set it to NULL at
|
||
|
this point. You can reassign the variable with a new call to
|
||
|
al_start_duh() of course.
|
||
|
|
||
|
Set 'n_channels' to 1 or 2 for mono or stereo respectively. Note that this
|
||
|
parameter has nothing to do with the number of samples that can play at
|
||
|
once in a music module. Set 'pos' to 0 to play from the beginning; each
|
||
|
time you add 65536, you will have advanced one second into the piece. As a
|
||
|
general rule, set the volume to 1.0f and adjust it later if the music is
|
||
|
too loud or too quiet - but see Allegro's set_volume_per_voice() function
|
||
|
first.
|
||
|
|
||
|
'bufsize' can generally be set to 4096. If your music stutters, try
|
||
|
increasing it; if your game freezes periodically, try reducing it. Find a
|
||
|
happy medium. Set 'freq' to 48000 for the best quality, though 44100 will
|
||
|
do in most cases. 22050 will be fine for a lot of music, though 11025 may
|
||
|
sound muffled. You can choose any other value, higher, lower or in
|
||
|
between. If your music stutters, and increasing 'bufsize' doesn't fix it,
|
||
|
try reducing this value.
|
||
|
|
||
|
Once you have put in a call to al_start_duh(), it is good practice to
|
||
|
insert the call to al_stop_duh() at the same time. You must call
|
||
|
al_stop_duh() before the DUH is unloaded (unload_duh(), Step 6 above).
|
||
|
|
||
|
Don't get impetuous, your program is not ready yet! Proceed to Step 8.
|
||
|
|
||
|
|
||
|
8. DUMB does not play music in the background for you; if you were expecting
|
||
|
it to do so, please see the explanation at the end of this step. For your
|
||
|
music to be played, you have to call another function at regular
|
||
|
intervals. Here is its prototype:
|
||
|
|
||
|
int al_poll_duh(AL_DUH_PLAYER *dp);
|
||
|
|
||
|
Do NOT call this function from inside a timer function unless you really
|
||
|
know what you are doing. The reasons why this is bad are explained
|
||
|
further down. You should call it from your main program.
|
||
|
|
||
|
Simply writing the following line will be sufficient in general, if you
|
||
|
have a variable 'dp' that points to your AL_DUH_PLAYER struct.
|
||
|
|
||
|
al_poll_duh(dp);
|
||
|
|
||
|
As a general rule, calling this once for each logic update will do the
|
||
|
trick. If, however, you are executing time-consuming algorithms such as
|
||
|
software 3D rendering, you may wish to insert calls to this function in
|
||
|
the middle of those algorithms. You cannot call this function too often
|
||
|
(within reason); if it has nothing to do it will return immediately.
|
||
|
|
||
|
Exactly how often you need to call the function depends on the values for
|
||
|
'bufsize' and 'freq' that you passed to al_start_duh():
|
||
|
|
||
|
n = freq / bufsize;
|
||
|
|
||
|
You have to call al_poll_duh() at least n times a second. Do not hesitate
|
||
|
to call it more often for safety; if the sound stutters, you may need to
|
||
|
do just that. (Or you may need to increase the buffer size or reduce the
|
||
|
quality settings; the only way to find out is to try.)
|
||
|
|
||
|
For now, don't worry about al_poll_duh()'s return value. As soon as you
|
||
|
need it, it will be explained.
|
||
|
|
||
|
If you are happy, please skip to Step 9. If you were expecting DUMB to
|
||
|
play your music in the background, please read on.
|
||
|
|
||
|
The natural way to play music in the background on most operating systems
|
||
|
nowadays is to use threads. DOS was not built with multithreading in mind,
|
||
|
and its system operations (notably disk access) assume they will only be
|
||
|
used from a single thread.
|
||
|
|
||
|
Interrupts are the next best thing to threads. A DOS hardware interrupt
|
||
|
could be triggered at any moment, and a handler function will be called.
|
||
|
This is how Allegro's timer functions work. Unfortunately, what you can do
|
||
|
inside an interrupt handler is very limited. For one thing, all code and
|
||
|
data used by the handler must be locked in memory; if not, it could get
|
||
|
written to disk (virtual memory). If the main program was accessing the
|
||
|
disk when it got interrupted, the system would then die a horrible death.
|
||
|
This precludes the possibility of allocating extra memory inside the
|
||
|
handler, and DUMB does a lot of that in al_poll_duh().
|
||
|
|
||
|
Given DUMB's architecture, which cannot change for reasons which will
|
||
|
become apparent in future versions, this renders it impossible to come up
|
||
|
with a portable solution for making DUMB play music in the background.
|
||
|
Having said that, if you wish to write your own wrapper for al_poll_duh()
|
||
|
and use it in a thread, there is nothing stopping you. If you do do this,
|
||
|
you will have to be very careful when stopping the music; see the
|
||
|
description of al_poll_duh() in dumb.txt for more information.
|
||
|
|
||
|
So why not kill DOS? It is all too common a practice among programmers to
|
||
|
quote the phrase, "DOS is as dead as the dodo." Despite being a decidedly
|
||
|
derisible demonstation of the dreary device of alliteration, it shows a
|
||
|
distinct lack of experience. Many embedded systems still use DOS because
|
||
|
it provides hardware access capabilities and real-time possibilities
|
||
|
unparalleled by any current multitasking operating system. For an argument
|
||
|
closer to home, I used to use RHIDE for DOS before I switched to Linux,
|
||
|
and I have not found a single Freeware Windows IDE that measures up to
|
||
|
RHIDE. I'm sure many people are in the same boat, and really appreciate
|
||
|
DUMB's DOS port.
|
||
|
|
||
|
We will not be removing DOS support from DUMB. Any blind suggestions to do
|
||
|
so will be met with fiery flames. You have been warned.
|
||
|
|
||
|
|
||
|
9. Test your program!
|
||
|
|
||
|
If you have trouble, check through the above steps to make sure you didn't
|
||
|
miss one out. Refer to faq.txt to see if your problem is addressed there.
|
||
|
If you still have trouble, contact me; details are at the end of this
|
||
|
file.
|
||
|
|
||
|
|
||
|
**********************************
|
||
|
*** Controlling music playback ***
|
||
|
**********************************
|
||
|
|
||
|
|
||
|
Here I describe some common operations you may wish to perform. The method
|
||
|
for doing so will seem a bit strange sometimes, as will the names of the
|
||
|
structs. However, there is a reason behind everything. If you would like to
|
||
|
do more exotic things, or better understand some of the methods used here,
|
||
|
then see dumb.txt, which covers everything from the ground up.
|
||
|
|
||
|
|
||
|
To control playback quality:
|
||
|
|
||
|
#define DUMB_RQ_ALIASING
|
||
|
#define DUMB_RQ_LINEAR
|
||
|
#define DUMB_RQ_CUBIC
|
||
|
#define DUMB_RQ_N_LEVELS
|
||
|
extern int dumb_resampling_quality;
|
||
|
extern int dumb_it_max_to_mix;
|
||
|
|
||
|
Please note that dumb_resampling_quality has changed in DUMB v0.9.2. See
|
||
|
deprec.txt for more details on the change.
|
||
|
|
||
|
dumb_resampling_quality can be set to any of the DUMB_RQ_* constants
|
||
|
(except DUMB_RQ_N_LEVELS; see below). Resampling is the term given to the
|
||
|
process of adjusting a sample's pitch (in this context).
|
||
|
dumb_resampling_quality defaults to DUMB_RQ_CUBIC, which sounds nice but
|
||
|
takes a lot of processor power. Try reducing it if you have an older
|
||
|
computer or if you are trying to mix an insane number of samples (or
|
||
|
both!). See dumb.txt for details on what the different values actually do.
|
||
|
|
||
|
If you wish to give this option to your user, you can use
|
||
|
DUMB_RQ_N_LEVELS. All the values from 0 to DUMB_RQ_N_LEVELS - 1 will be
|
||
|
valid resampling levels. If a value outside this range is chosen, it is
|
||
|
not the end of the world; DUMB will behave as if you had chosen the value
|
||
|
at whichever extreme you went beyond.
|
||
|
|
||
|
dumb_it_max_to_mix, defaulting to 64, is the maximum number of samples
|
||
|
DUMB will ever mix together when playing an IT, XM, S3M or MOD file.
|
||
|
Unlike many other music systems, DUMB will still keep track of all samples
|
||
|
(up to a fixed maximum of 256 of them, roughly speaking), and then will
|
||
|
just render as many of them as this variable permits, starting with the
|
||
|
loudest ones. When samples are cut or come back in, the exact timings will
|
||
|
not generally be predictable - but nor will they be important.
|
||
|
|
||
|
dumb_it_max_to_mix applies to each currently playing module file
|
||
|
independently. So if you set it to 64, but render two modules
|
||
|
simultaneously, DUMB could end up mixing up to 128 samples.
|
||
|
|
||
|
|
||
|
To pause and resume playback, set the volume, get the current playback
|
||
|
position, or get the length of time a DUH will play for before either looping
|
||
|
or freezing (effect F00 in XM and MOD files, which means no new notes will be
|
||
|
played but any existing notes will continue):
|
||
|
|
||
|
void al_pause_duh(AL_DUH_PLAYER *dp);
|
||
|
void al_resume_duh(AL_DUH_PLAYER *dp);
|
||
|
void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume);
|
||
|
long al_duh_get_position(AL_DUH_PLAYER *dp);
|
||
|
|
||
|
long duh_get_length(DUH *duh);
|
||
|
|
||
|
These functions are pretty self-explanatory. The volume passed to
|
||
|
al_duh_set_volume() and the position returned by al_duh_get_position() are
|
||
|
in the same units as those you passed to al_start_duh(). The length
|
||
|
returned by duh_get_length() is in the same units as the aforementioned
|
||
|
position; see dumb.txt for more information on this function. Be careful
|
||
|
with al_duh_get_position(); it will return a position slightly ahead of
|
||
|
what you can hear, because the system has to keep ahead slightly to avoid
|
||
|
stuttering.
|
||
|
|
||
|
|
||
|
To prevent the music from looping and/or freezing:
|
||
|
|
||
|
DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp);
|
||
|
DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer);
|
||
|
|
||
|
void dumb_it_set_loop_callback(DUMB_IT_SIGRENDERER *sigrenderer,
|
||
|
int (*callback)(void *data), void *data);
|
||
|
void dumb_it_set_xm_speed_zero_callback(DUMB_IT_SIGRENDERER *sigrenderer,
|
||
|
int (*callback)(void *data), void *data);
|
||
|
|
||
|
int dumb_it_callback_terminate(void *data);
|
||
|
|
||
|
If you are unfamiliar with function pointers, please see fnptr.txt.
|
||
|
|
||
|
Note that these functions apply to IT, XM, S3M and MOD files - not just to
|
||
|
IT files. This holds true throughout DUMB, for all functions with "it" in
|
||
|
the name. The xm_speed_zero event can only occur with XM and MOD files.
|
||
|
|
||
|
The first two functions will return a pointer to a struct contained by the
|
||
|
struct you pass. This system is necessary to ensure that these operations
|
||
|
are possible when not using Allegro. Typically you would write the
|
||
|
following code:
|
||
|
|
||
|
{
|
||
|
DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp);
|
||
|
DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer);
|
||
|
dumb_it_set_loop_callback(itsr, &dumb_it_callback_terminate, NULL);
|
||
|
dumb_it_set_xm_speed_zero_callback
|
||
|
(itsr, &dumb_it_callback_terminate, NULL);
|
||
|
}
|
||
|
|
||
|
Once you have done this, the return value of al_poll_duh() becomes
|
||
|
significant. It will be 0 as long as the music is playing. When the music
|
||
|
stops, al_poll_duh() will return nonzero. You can call al_stop_duh() and
|
||
|
do something else as soon as you wish, but calling al_poll_duh() some more
|
||
|
will not do any harm.
|
||
|
|
||
|
al_poll_duh() will also return 1 if the music could not be loaded, or if
|
||
|
memory was short when trying to play it, or if it was a quirky music file
|
||
|
with no music in it (technically one with an empty order list). This
|
||
|
happens regardless of whether or not you execute the above code to disable
|
||
|
looping. Normally you shouldn't need to worry about this.
|
||
|
|
||
|
To undo the above and make DUMB loop or freeze again, pass NULL instead of
|
||
|
&dumb_it_callback_terminate. If you would like to fade on looping, or loop
|
||
|
a finite number of times, or display a message when looping, or whatever,
|
||
|
you will have to write your own callback function. In this case, please
|
||
|
see dumb.txt.
|
||
|
|
||
|
Note that the above code can safely be applied for a DUH that doesn't
|
||
|
contain a music module but contains some other kind of music.
|
||
|
duh_get_it_sigrenderer() will return NULL, and the code will do nothing.
|
||
|
|
||
|
|
||
|
To analyse the audio as it's generated:
|
||
|
|
||
|
typedef int sample_t;
|
||
|
|
||
|
typedef void (*DUH_SIGRENDERER_ANALYSER_CALLBACK)(void *data,
|
||
|
const sample_t *const *samples, int n_channels, long length);
|
||
|
|
||
|
void duh_sigrenderer_set_analyser_callback(DUH_SIGRENDERER *sigrenderer,
|
||
|
DUH_SIGRENDERER_ANALYSER_CALLBACK callback, void *data);
|
||
|
|
||
|
If the above confuses you, see fnptr.txt. These functions, along with
|
||
|
al_duh_get_sigrenderer() from the last section, enable you to register a
|
||
|
callback function. Every time some samples are generated, they will be
|
||
|
passed to this function. This enables you to display an oscilloscope or
|
||
|
spectrum analyser, for example.
|
||
|
|
||
|
Beware: your callback function may occasionally be called with
|
||
|
samples == NULL. This means the main program has decided to skip through
|
||
|
the music without generating any data. You should handle this case
|
||
|
elegantly, typically by returning immediately, but you may wish to make a
|
||
|
note of the fact that the music is being skipped, for whatever reason.
|
||
|
|
||
|
Beware again: if the main program ever calls duh_sigrenderer_get_samples()
|
||
|
on a buffer that isn't all silence, this callback function will be passed
|
||
|
the existing buffer after mixing, and thus it will include the original
|
||
|
data. This will not be an issue if you stick to duh_render(), which always
|
||
|
starts with a buffer filled with silence.
|
||
|
|
||
|
The samples array is two-dimensional. Refer to it as follows:
|
||
|
|
||
|
samples[channel_number][sample_position]
|
||
|
|
||
|
where 0 <= channel_number < n_channels,
|
||
|
and 0 <= sample_position < length.
|
||
|
|
||
|
In addition you can pass any 'data' pointer you like to
|
||
|
duh_sigrenderer_set_analyser_callback(), and this pointer will be relayed
|
||
|
to your callback function each time.
|
||
|
|
||
|
To remove the callback function, pass NULL to
|
||
|
duh_sigrenderer_set_analyser_callback().
|
||
|
|
||
|
|
||
|
Everything below this point assumes some knowledge of how a music module is
|
||
|
constructed. If you do not have this knowledge, talk to whoever is writing
|
||
|
music for you, or download a tracking program and play with it (see
|
||
|
readme.txt).
|
||
|
|
||
|
|
||
|
To start playing an IT, XM, S3M or MOD from an arbitrary order number (the
|
||
|
default being 0, the beginning of the song), use the following:
|
||
|
|
||
|
DUH_SIGRENDERER *dumb_it_start_at_order
|
||
|
(DUH *duh, int n_channels, int startorder);
|
||
|
AL_DUH_PLAYER *al_duh_encapsulate_sigrenderer
|
||
|
(DUH_SIGRENDERER *sigrenderer, float volume, long bufsize, int freq);
|
||
|
|
||
|
The usage of these functions is as follows:
|
||
|
|
||
|
{
|
||
|
DUH_SIGRENDERER *sr = dumb_it_start_at_order
|
||
|
(duh, n_channels, startorder);
|
||
|
dp = al_duh_encapsulate_sigrenderer(sr, volume, bufsize, freq);
|
||
|
}
|
||
|
|
||
|
Replace 'dp' with whatever your AL_DUH_PLAYER pointer is. You also need
|
||
|
to insert suitable values for n_channels, startorder, volume, bufsize and
|
||
|
freq. These have the same meaning as those passed to al_start_duh().
|
||
|
|
||
|
WARNING: after passing a pointer to an "encapsulate" function, do not use
|
||
|
that pointer again. (More specifically, do not use it again if
|
||
|
the function returns NULL, because the function will have
|
||
|
destroyed the pointer if this happens, to help prevent memory
|
||
|
leaks.) There will be a "get" function with which you can obtain
|
||
|
the original pointer if it is still valid, or NULL otherwise.
|
||
|
|
||
|
The above functions will fail (safely) if you try to use them with a DUH
|
||
|
that contains a different type of music.
|
||
|
|
||
|
Notice that there is no 'pos' parameter. If you would like to skip through
|
||
|
the music, you can use this function:
|
||
|
|
||
|
long duh_sigrenderer_get_samples(
|
||
|
DUH_SIGRENDERER *sigrenderer,
|
||
|
float volume, float delta,
|
||
|
long size, sample_t **samples
|
||
|
);
|
||
|
|
||
|
Pass 0 for volume and NULL for samples, and this function will skip
|
||
|
through the music nice and quickly. So insert the following between the
|
||
|
two above statements:
|
||
|
|
||
|
duh_sigrenderer_get_samples(sr, 0, 65536.0f / freq, pos, NULL);
|
||
|
|
||
|
Substitute for 'freq' and 'pos'. An explanation of the 'delta' parameter
|
||
|
can be found further down in this file.
|
||
|
|
||
|
Finally, note that duh_get_length() is only meaningful when you start
|
||
|
playing music from order 0.
|
||
|
|
||
|
|
||
|
If an IT file contains Zxx effects, DUMB will generate MIDI messages, which
|
||
|
will control the low-pass resonant filters unless the IT file actively
|
||
|
specifies something else. In rare cases this may not be what the Zxx effects
|
||
|
were intended to do; if this is the case, you can block the MIDI messages as
|
||
|
follows. Note that this does NOT mean filters are disabled; if an instrument
|
||
|
specifies initial cut-off and resonance values, or has a filter envelope,
|
||
|
then filters will be applied. It only makes sense to use this procedure at
|
||
|
the beginning of playback.
|
||
|
|
||
|
void dumb_it_set_midi_callback(DUMB_IT_SIGRENDERER *sigrenderer,
|
||
|
int (*callback)(void *data, int channel, unsigned char byte),
|
||
|
void *data);
|
||
|
|
||
|
int dumb_it_callback_midi_block(void *data, int channel,
|
||
|
unsigned char byte);
|
||
|
|
||
|
Using some functions described in the previous section, we arrive at the
|
||
|
following code:
|
||
|
|
||
|
{
|
||
|
DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp);
|
||
|
DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer);
|
||
|
dumb_it_set_midi_callback(itsr, &dumb_it_callback_midi_block, NULL);
|
||
|
}
|
||
|
|
||
|
DUMB offers no way of disabling filters completely. Disabling filters is not
|
||
|
recommended as a means to reduce processor usage, as it will completely
|
||
|
damage any piece of music that uses the filters. If you want lower processor
|
||
|
consumption, use a piece of music that does not use filters.
|
||
|
|
||
|
|
||
|
Finally, DUMB offers a myriad of functions for querying and adjusting
|
||
|
module playback. Those beginning with "dumb_it_sd" operate on the
|
||
|
DUMB_IT_SIGDATA struct, which represents the piece of music before it starts
|
||
|
to play. Those beginning with "dumb_it_sr" operate on the DUMB_IT_SIGRENDERER
|
||
|
struct, which represents a currently playing instance of the music. Note that
|
||
|
duh_get_length(), described above, becomes meaningless after some of these
|
||
|
functions are used.
|
||
|
|
||
|
The method for getting a DUMB_IT_SIGRENDERER struct has already been given,
|
||
|
but the function prototypes are repeated here for convenience:
|
||
|
|
||
|
DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp);
|
||
|
DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer);
|
||
|
|
||
|
Getting a DUMB_IT_SIGDATA struct is simpler:
|
||
|
|
||
|
DUMB_IT_SIGDATA *duh_get_it_sigdata(DUH *duh);
|
||
|
|
||
|
For a list of dumb_it_sd_*() and dumb_it_sr_*() functions, please see
|
||
|
dumb.txt. These functions are new, and may not provide exactly what you need;
|
||
|
if not, please let me know.
|
||
|
|
||
|
|
||
|
**************************************************
|
||
|
*** Embedding music files in Allegro datafiles ***
|
||
|
**************************************************
|
||
|
|
||
|
|
||
|
In this section it is assumed you are already reasonably familiar with how
|
||
|
Allegro datafiles are used. If not, please refer to Allegro's documentation.
|
||
|
At the time of writing, the documentation you need is off the beaten track,
|
||
|
so to speak, in allegro/tools/grabber.txt.
|
||
|
|
||
|
To add a piece of music to a datafile, you need to create an object of type
|
||
|
"IT ", "XM ", "S3M " or "MOD " (note the spaces used as padding, although
|
||
|
you do not need to type these into the grabber). Then grab the piece of music
|
||
|
in. The grabber will treat it as a binary object. Save the datafile as usual.
|
||
|
|
||
|
|
||
|
To use a piece of music you added to the datafile, follow these steps:
|
||
|
|
||
|
|
||
|
1. Before loading the datafile, call one or more of these functions,
|
||
|
depending on which music format or formats you'd like to support:
|
||
|
|
||
|
dumb_register_dat_it(DUMB_DAT_IT);
|
||
|
dumb_register_dat_xm(DUMB_DAT_XM);
|
||
|
dumb_register_dat_s3m(DUMB_DAT_S3M);
|
||
|
dumb_register_dat_mod(DUMB_DAT_MOD);
|
||
|
|
||
|
Remember, do not call multiple functions unless you want to support
|
||
|
multiple formats. Calling more functions will add unused code to your
|
||
|
executable.
|
||
|
|
||
|
It is important that you make call these before loading the datafile,
|
||
|
since they tell Allegro how to load the respective files straight from
|
||
|
datafiles in the future. They will not help Allegro interpret any module
|
||
|
files that have already been loaded as binary objects (but if you really
|
||
|
need to interpret a module that has been loaded in this fashion, have a
|
||
|
look at dumbfile_open_memory() in dumb.txt).
|
||
|
|
||
|
If for whatever reason your music objects are identified by a different
|
||
|
type in the datafile, you can tell DUMB what that type is by changing the
|
||
|
parameter to the registration function above. Use Allegro's DAT_ID()
|
||
|
macro, e.g. DAT_ID('B','L','A','H'). This is not really recommended
|
||
|
though, since it would prevent a hypothetical grabber plug-in from being
|
||
|
able to play your music files. Use the above types if possible.
|
||
|
|
||
|
|
||
|
2. Whenever you need a pointer to a DUH struct, simply use the 'dat' field.
|
||
|
Do this in the same way you would for a pointer to a BITMAP struct or
|
||
|
anything else. If it makes you feel more comfortable, you can extract the
|
||
|
pointer in advance:
|
||
|
|
||
|
DATAFILE *dat = load_datafile("smurf.dat");
|
||
|
if (!dat) abort(); /* There are much nicer ways of handling failure! */
|
||
|
DUH *myduh = (DUH *)dat[GAME_MUSIC].dat;
|
||
|
|
||
|
Note that the explicit (DUH *) cast is only necessary for C++, not for C.
|
||
|
However, it does no harm.
|
||
|
|
||
|
Be sure that you do NOT call unload_duh() for anything stored in the
|
||
|
datafile. These DUHs will be freed when you call unload_datafile(), and
|
||
|
freeing them twice is practically guaranteed to crash your program.
|
||
|
|
||
|
|
||
|
3. If you only ever load music as part of a datafile, and you never load any
|
||
|
stand-alone music files, you do not need to register a file input system
|
||
|
for DUMB to use. If you followed the instructions for the first section
|
||
|
you will have one of these two lines in your program:
|
||
|
|
||
|
dumb_register_stdfiles();
|
||
|
dumb_register_packfiles();
|
||
|
|
||
|
You can safely delete this line - but only if you never load any
|
||
|
stand-alone music files. The debugging library will bale you out if you
|
||
|
delete it when you shouldn't; the optimised library won't.
|
||
|
|
||
|
|
||
|
*************************************
|
||
|
*** Rendering music into a buffer ***
|
||
|
*************************************
|
||
|
|
||
|
|
||
|
NOTE: much of the API formerly described in this section has been deprecated,
|
||
|
and you will need to alter your code. See deprec.txt for details. If
|
||
|
you are reading this section for the first time, you can ignore this
|
||
|
note.
|
||
|
|
||
|
Rendering to a buffer is similar to playing using an AL_DUH_PLAYER. However,
|
||
|
you must use a DUH_SIGRENDERER struct instead. Here are the functions:
|
||
|
|
||
|
DUH_SIGRENDERER *duh_start_sigrenderer
|
||
|
(DUH *duh, int sig, int n_channels, long pos);
|
||
|
|
||
|
int duh_sigrenderer_get_n_channels(DUH_SIGRENDERER *sigrenderer);
|
||
|
long duh_sigrenderer_get_position(DUH_SIGRENDERER *sigrenderer);
|
||
|
|
||
|
long duh_sigrenderer_get_samples(DUH_SIGRENDERER *sigrenderer,
|
||
|
float volume, float delta, long size, sample_t **samples);
|
||
|
|
||
|
long duh_render(DUH_SIGRENDERER *sigrenderer,
|
||
|
int bits, int unsign, float volume, float delta, long size, void *sptr);
|
||
|
|
||
|
void duh_end_sigrenderer(DUH_SIGRENDERER *sigrenderer);
|
||
|
|
||
|
The parameters to duh_start_sigrenderer() have the same meanings as those to
|
||
|
al_start_duh(). However, note that the volume is not set at this stage. You
|
||
|
pass the desired volume each time you want to render a block. The 'sig'
|
||
|
parameter should be set to 0 for now.
|
||
|
|
||
|
Notice that there are two rendering functions. duh_sigrenderer_get_samples()
|
||
|
will generate samples in the internal 32-bit format, with a normal range from
|
||
|
-0x800000 to 0x7FFFFF and with each channel in a separate array; duh_render()
|
||
|
will convert to 8 or 16 bits, signed or unsigned, with stereo samples
|
||
|
interleaved, left first.
|
||
|
|
||
|
When you call duh_render(), pass 8 or 16 for 'bits'. If you pass 8, 'sptr' is
|
||
|
expected to be an array of chars. If you pass 16, 'sptr' is expected to be an
|
||
|
array of shorts. Endianness therefore depends on the platform, and you should
|
||
|
not try to interpret 16-bit wave data as an array of chars (unless you're
|
||
|
writing highly system-specific code anyway). Because DUMB renders internally
|
||
|
with 32 bits, there is no significant speed increase in rendering an 8-bit
|
||
|
stream.
|
||
|
|
||
|
If you are rendering in stereo, make sure your 'sptr' array is twice as big!
|
||
|
|
||
|
If you set 'unsign' to a nonzero value, then the samples generated will be
|
||
|
centred on 0x80 or 0x8000, suitably stored in an array of unsigned chars or
|
||
|
unsigned shorts. If 'unsign' is zero, the samples will be centred on 0,
|
||
|
suitably stored in an array of signed chars or signed shorts. Note that 8-bit
|
||
|
WAV files are unsigned while 16-bit WAV files are signed. This convention was
|
||
|
used by the SoundBlaster 16 when receiving samples to be sent to the
|
||
|
speakers. If you wish to write 16-bit sample data to a WAV file, don't use
|
||
|
fwrite(); instead, take the shorts one at a time, split them up into chars as
|
||
|
follows, and write the chars to the file.
|
||
|
|
||
|
short sptr[n];
|
||
|
char lsb = (char)sptr[n];
|
||
|
char msb = (char)(sptr[n] >> 8);
|
||
|
|
||
|
For a 16-bit WAV file, write the LSB (less significant byte) first.
|
||
|
|
||
|
The following applies equally to duh_render() and
|
||
|
duh_sigrenderer_get_samples(), except where otherwise stated.
|
||
|
|
||
|
If you set 'delta' to 1.0f, the sound generated will be suitable for playback
|
||
|
at 65536 Hz. Increasing 'delta' causes the wave to speed up, given a constant
|
||
|
sampling rate for playback. Supposing you want to vary the playback sampling
|
||
|
rate but keep the pitch constant, here's the equation for 'delta':
|
||
|
|
||
|
delta = 65536.0f / sampling_rate;
|
||
|
|
||
|
'size' is the number of samples you want rendered. For duh_render(), they
|
||
|
will be rendered into an array which you pass as 'sptr'. Note that stereo
|
||
|
samples count as one; so if you set n_channels to 2, your array must contain
|
||
|
(2 * size) elements.
|
||
|
|
||
|
For duh_sigrenderer_get_samples() you will have to use the following
|
||
|
functions:
|
||
|
|
||
|
sample_t **create_sample_buffer(int n_channels, long length);
|
||
|
void destroy_sample_buffer(sample_t **samples);
|
||
|
|
||
|
void dumb_silence(sample_t *samples, long length);
|
||
|
|
||
|
create_sample_buffer() allocates the channels sequentially in memory, so the
|
||
|
following technique is valid:
|
||
|
|
||
|
sample_t **samples = create_sample_buffer(n_channels, length);
|
||
|
dumb_silence(samples[0], n_channels * length);
|
||
|
|
||
|
It is necessary to fill the buffer with silence like this because
|
||
|
duh_sigrenderer_get_samples() mixes what it renders with the existing
|
||
|
contents of the buffer.
|
||
|
|
||
|
The return values from duh_render() and duh_sigrenderer_get_samples() tell
|
||
|
you how many samples were actually generated. In most cases, this will be the
|
||
|
same as the 'size' parameter. However, if you reach the end of the DUH (which
|
||
|
will happen if you disable looping or freezing as described further up), this
|
||
|
function will return less. When that happens, you can assume the stream has
|
||
|
finished. In the case of duh_render(), the remainder of the array will not
|
||
|
have been initialised, so you either have to initialise it yourself or avoid
|
||
|
using it.
|
||
|
|
||
|
If for whatever reason duh_start_sigrenderer() returns NULL, then
|
||
|
duh_render() and duh_sigrenderer_get_samples() will generate exactly 0
|
||
|
samples, duh_sigrenderer_get_n_channels() will return 0,
|
||
|
duh_sigrenderer_get_position() will return -1, and duh_end_sigrenderer() will
|
||
|
safely do nothing.
|
||
|
|
||
|
|
||
|
*********************
|
||
|
*** Miscellaneous ***
|
||
|
*********************
|
||
|
|
||
|
|
||
|
Please see dumb.txt for an API reference and for information on thread safety
|
||
|
with DUMB. The API reference has been stripped down, since some functions and
|
||
|
variables are subject to change. If something does not appear in dumb.txt,
|
||
|
please do not use it.
|
||
|
|
||
|
|
||
|
******************
|
||
|
*** Conclusion ***
|
||
|
******************
|
||
|
|
||
|
|
||
|
If you have any difficulties, or if you use DUMB successfully, please don't
|
||
|
hesitate to contact me (see below).
|
||
|
|
||
|
Enjoy!
|
||
|
|
||
|
|
||
|
Ben Davis
|
||
|
entheh@users.sf.net
|
||
|
IRC EFnet #dumb
|
||
|
See readme.txt for details on using IRC.
|