542 lines
23 KiB
Plaintext
542 lines
23 KiB
Plaintext
/* _______ ____ __ ___ ___
|
|
* \ _ \ \ / \ / \ \ / / ' ' '
|
|
* | | \ \ | | || | \/ | . .
|
|
* | | | | | | || ||\ /| |
|
|
* | | | | | | || || \/ | | ' ' '
|
|
* | | | | | | || || | | . .
|
|
* | |_/ / \ \__// || | |
|
|
* /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque
|
|
* / \
|
|
* / . \
|
|
* readme.txt - General information on DUMB. / / \ \
|
|
* | < / \_
|
|
* | \/ /\ /
|
|
* \_ / > /
|
|
* | \ / /
|
|
* | ' /
|
|
* \__/
|
|
*/
|
|
|
|
|
|
********************
|
|
*** Introduction ***
|
|
********************
|
|
|
|
|
|
Thank you for downloading DUMB v0.9.3! You should have the following
|
|
documentation:
|
|
|
|
readme.txt - This file
|
|
licence.txt - Conditions for the use of this software
|
|
release.txt - Release notes and changes for this and past releases
|
|
docs/
|
|
howto.txt - Step-by-step instructions on adding DUMB to your project
|
|
faq.txt - Frequently asked questions and answers to them
|
|
dumb.txt - DUMB library reference
|
|
deprec.txt - Information about deprecated parts of the API
|
|
ptr.txt - Quick introduction to pointers for those who need it
|
|
fnptr.txt - Explanation of function pointers for those who need it
|
|
modplug.txt - Our official position regarding ModPlug Tracker
|
|
|
|
This file will help you get DUMB set up. If you have not yet done so, please
|
|
read licence.txt and release.txt before proceeding. After you've got DUMB set
|
|
up, please refer to the files in the docs/ directory at your convenience. I
|
|
recommend you start with howto.txt.
|
|
|
|
|
|
****************
|
|
*** Features ***
|
|
****************
|
|
|
|
|
|
Here is the statutory feature list:
|
|
|
|
- Freeware
|
|
|
|
- Supports playback of IT, XM, S3M and MOD files
|
|
|
|
- Faithful to the original trackers, especially IT; if it plays your module
|
|
wrongly, please tell me so I can fix the bug! (But please don't complain
|
|
about differences between DUMB and ModPlug Tracker; see docs/modplug.txt)
|
|
|
|
- Accurate support for low-pass resonant filters for IT files
|
|
|
|
- Very accurate timing and pitching; completely deterministic playback
|
|
|
|
- Click removal
|
|
|
|
- Facility to embed music files in other files (e.g. Allegro datafiles)
|
|
|
|
- Three resampling quality settings: aliasing, linear interpolation and cubic
|
|
interpolation
|
|
|
|
- Number of samples playing at once can be limited to reduce processor usage,
|
|
but samples will come back in when other louder ones stop
|
|
|
|
- All notes will be present and correct even if you start a piece of music in
|
|
the middle
|
|
|
|
- Option to take longer loading but seek fast to any point before the music
|
|
first loops (seeking time increases beyond this point)
|
|
|
|
- Audio generated can be used in any way; DUMB does not necessarily send it
|
|
straight to a sound output system
|
|
|
|
- Can be used with Allegro, can be used without (if you'd like to help make
|
|
DUMB more approachable to people who aren't using Allegro, please contact
|
|
me)
|
|
|
|
- Makefile provided for DJGPP, MinGW, Linux, BeOS and Mac OS X
|
|
|
|
- Project files provided for MSVC 6
|
|
|
|
- Autotools-based configure script available as a separate download for
|
|
masochists
|
|
|
|
- Code should port anywhere that has a 32-bit C compiler; instructions on
|
|
compiling it manually are available further down
|
|
|
|
|
|
*********************
|
|
*** What you need ***
|
|
*********************
|
|
|
|
|
|
To use DUMB, you need a 32-bit C compiler (GCC and MSVC are fine). If you
|
|
have Allegro, DUMB can integrate with its audio streams and datafiles, making
|
|
your life easier. If you do not wish to use Allegro, you will have to do some
|
|
work to get music playing back. The 'dumbplay' example program requires
|
|
Allegro.
|
|
|
|
Allegro - http://alleg.sf.net/
|
|
|
|
|
|
**********************************************
|
|
*** How to set DUMB up with DJGPP or MinGW ***
|
|
**********************************************
|
|
|
|
|
|
You should have got the .zip version. If for some reason you got the .tar.gz
|
|
version instead, you may have to convert make/config.bat to DOS text file
|
|
format. WinZip does this automatically by default. Otherwise, loading it into
|
|
MS EDIT and saving it again should do the trick (but do not do this to the
|
|
Makefiles as it destroys tabs). You will have to do the same for any files
|
|
you want to view in Windows Notepad. If you have problems, just go and
|
|
download the .zip instead.
|
|
|
|
Make sure you preserved the directory structure when you extracted DUMB from
|
|
the archive. Most unzipping programs will do this by default, but pkunzip
|
|
requires you to pass -d. If not, please delete DUMB and extract it again
|
|
properly.
|
|
|
|
If you are using Windows, open an MS-DOS Prompt or a Windows Command Line.
|
|
Change to the directory into which you unzipped DUMB.
|
|
|
|
If you are using MinGW (and you haven't renamed 'mingw32-make'), type:
|
|
|
|
mingw32-make
|
|
|
|
Otherwise, type the following:
|
|
|
|
make
|
|
|
|
DUMB will ask you whether you wish to compile for DJGPP or MinGW. Then it
|
|
will ask you whether you want support for Allegro. (You have to have made and
|
|
installed Allegro's optimised library for this to work.) Finally, it will
|
|
compile optimised and debugging builds of DUMB, along with the example
|
|
programs. When it has finished, run one of the following to install the
|
|
libraries:
|
|
|
|
make install
|
|
mingw32-make install
|
|
|
|
All done! If you ever need the configuration again (e.g. if you compiled for
|
|
DJGPP before and you want to compile for MinGW now), run one of the
|
|
following:
|
|
|
|
make config
|
|
mingw32-make config
|
|
|
|
See the comments in the Makefile for other targets.
|
|
|
|
Note: the Makefile will only work properly if you have COMSPEC or ComSpec set
|
|
to point to command.com or cmd.exe. If you set it to point to a Unix-style
|
|
shell, the Makefile won't work.
|
|
|
|
Please let me know if you have any trouble.
|
|
|
|
As an alternative, MSYS users may attempt to use the configure script,
|
|
available in dumb-0.9.3-autotools.tar.gz. This has been found to work without
|
|
Allegro, and is untested with Allegro. I should appreciate feedback from
|
|
anyone else who tries this. I do not recommend its use, partly because it
|
|
creates dynamically linked libraries and I don't know how to stop it from
|
|
doing that (see the section on compiling DUMB manually), and partly because
|
|
autotools are plain evil.
|
|
|
|
Scroll down for information on the example programs. Refer to docs/howto.txt
|
|
when you are ready to start programming with DUMB. If you use DUMB in a game,
|
|
let me know - I might decide to place a link to your game on DUMB's website!
|
|
|
|
|
|
******************************************************
|
|
*** How to set DUMB up with Microsoft Visual C++ 6 ***
|
|
******************************************************
|
|
|
|
|
|
If you have a newer version of Microsoft Visual C++ or Visual Something that
|
|
supports C++, please try these instructions and let me know if it works.
|
|
|
|
You should have got the .zip version. If for some reason you got the .tar.gz
|
|
version instead, you may have to convert some files to DOS text file format.
|
|
WinZip does this automatically by default. Otherwise, loading such files into
|
|
MS EDIT and saving them again should do the trick. You will have to do this
|
|
for any files you want to view in Windows Notepad. If you have problems, just
|
|
go and download the .zip instead.
|
|
|
|
Make sure you preserved the directory structure when you extracted DUMB from
|
|
the archive. Most unzipping programs will do this by default, but pkunzip
|
|
requires you to pass -d. If not, please delete DUMB and extract it again
|
|
properly.
|
|
|
|
DUMB comes with a workspace Microsoft Visual C++ 6, containing projects for
|
|
the DUMB core, the Allegro interface library and each of the examples. The
|
|
first thing you might want to do is load the workspace up and have a look
|
|
around. You will find it in the dumb\vc6 directory under the name dumb.dsw.
|
|
Note that the aldumb and dumbplay projects require Allegro, so they won't
|
|
work if you don't have Allegro. Nevertheless, dumbplay is the best-commented
|
|
of the examples, so do have a look.
|
|
|
|
When you are ready to add DUMB to your project, follow these instructions:
|
|
|
|
1. Open your project in VC++.
|
|
2. Select Project|Insert Project into Workspace...
|
|
3. Navigate to the dumb\vc6\dumb directory and select dumb.dsp.
|
|
Alternatively, if you know that you are statically linking with a library
|
|
that uses the statically linked multithreaded runtime (/MT), you may wish
|
|
to select dumb_static.dsp in the dumb_static subdirectory instead.
|
|
4. Select Build|Set Active Configuration..., and reselect one of your
|
|
project's configurations.
|
|
5. Select Project|Dependencies... and ensure your project is dependent on
|
|
DUMB.
|
|
6. Select Project|Settings..., Settings for: All Configurations, C/C++ tab,
|
|
Preprocessor category. Add the DUMB include directory to the Additional
|
|
Include Directories box.
|
|
7. Ensure that for all the projects in the workspace (or more likely just all
|
|
the projects in a particular dependency chain) the run-time libraries are
|
|
the same. That's in Project|Settings, C/C++ tab, Code generation category,
|
|
Use run-time library dropdown. The settings for Release and Debug are
|
|
separate, so you'll have to change them one at a time. Exactly which run-
|
|
time library you use will depend on what you need; it doesn't appear that
|
|
DUMB has any particular requirements, so set it to whatever you're using
|
|
now. (It will have to be /MD, the multithreaded DLL library, if you are
|
|
statically linking with Allegro. If you are dynamically linking with
|
|
Allegro than it doesn't matter.)
|
|
8. If you are using Allegro, do some or all of the above for the aldumb.dsp
|
|
project in the aldumb directory too.
|
|
|
|
Good thing you only have to do all that once ... or twice ...
|
|
|
|
If you have the Intel compiler installed, it will - well, should - be used to
|
|
compile DUMB. The only setting I [Tom Seddon] added is /QxiM. This allows the
|
|
compiler to use PPro and MMX instructions, and so when compiling with Intel
|
|
the resultant EXE will require a Pentium II or greater. I don't think this is
|
|
unreasonable. After all, it is 2003 :)
|
|
|
|
[Note from Ben: the Intel compiler is evil! It makes AMD processors look bad!
|
|
Patch it or boycott it or something!]
|
|
|
|
If you don't have the Intel compiler, VC will compile DUMB as normal.
|
|
|
|
This project file and these instructions were provided by Tom Seddon (I hope
|
|
I got his name right; I had to guess it from his e-mail address!). Chad
|
|
Austin has since changed the project files around, and I've just attempted to
|
|
hack them to incorporate new source files. I've also tried to update the
|
|
instructions using guesswork and some knowledge of Visual J++ (you heard me).
|
|
The instructions and the project files are to this day untested by me. If you
|
|
have problems, check the download page at http://dumb.sf.net/ to see if they
|
|
are addressed; failing that, direct queries to me and I'll try to figure them
|
|
out.
|
|
|
|
If you have any comments at all on how the VC6 projects are laid out, or how
|
|
the instructions could be improved, I should be really grateful to hear them.
|
|
I am a perfectionist, after all. :)
|
|
|
|
Scroll down for information on the example programs. When you are ready to
|
|
start using DUMB, refer to docs/howto.txt. If you use DUMB in a game, let me
|
|
know - I might decide to place a link to your game on DUMB's website!
|
|
|
|
|
|
******************************************************
|
|
*** How to set DUMB up on Linux, BeOS and Mac OS X ***
|
|
******************************************************
|
|
|
|
|
|
You should have got the .tar.gz version. If for some reason you got the .zip
|
|
version instead, you may have to strip all characters with ASCII code 13 from
|
|
some of the text files. If you have problems, just go and download the
|
|
.tar.gz instead.
|
|
|
|
You have two options. There is a Makefile which should cope with most
|
|
systems. The first option is to use this default Makefile, and the procedure
|
|
is explained below. The second option is to download
|
|
dumb-0.9.3-autotools.tar.gz, extract it over the installation, run
|
|
./configure and use the generated Makefile. Users who choose to do this are
|
|
left to their own devices but advised to read the information at the end of
|
|
this section. I strongly recommend the first option.
|
|
|
|
If you are not using the configure script, the procedure is as follows.
|
|
|
|
First, run the following command as a normal user:
|
|
|
|
make
|
|
|
|
You will be asked whether you want Allegro support. Then, unless you are on
|
|
BeOS, you will be asked where you'd like DUMB to install its headers,
|
|
libraries and examples (which will go in the include/, lib/ and bin/
|
|
subdirectories of the prefix you specify). BeOS has fixed locations for these
|
|
files. You may use shell variables here, e.g. $HOME or ${HOME}, but ~ will
|
|
not work. Once you have specified these pieces of information, the optimised
|
|
and debugging builds of DUMB will be compiled, along with the examples. When
|
|
it has finished, you can install them with:
|
|
|
|
make install
|
|
|
|
You may need to be root for this to work. It depends on the prefix you chose.
|
|
|
|
Note: the Makefile will only work if COMSPEC and ComSpec are both undefined.
|
|
If either of these is defined, the Makefile will try to build for a Windows
|
|
system, and will fail.
|
|
|
|
Please let me know if you have any trouble.
|
|
|
|
Scroll down for information on the example programs. Refer to docs/howto.txt
|
|
when you are ready to start programming with DUMB. If you use DUMB in a game,
|
|
let me know - I might decide to place a link to your game on DUMB's website!
|
|
|
|
Important information for users of the configure script follows.
|
|
|
|
The Makefile generated by the configure script creates dynamically linked
|
|
libraries, and I don't know how to stop it from doing so. See the section
|
|
below on building DUMB manually for why I recommend linking DUMB statically.
|
|
However, if you choose to use the configure script, note the following.
|
|
|
|
The default Makefile is a copy of Makefile.rdy (short for 'ready'), and it
|
|
must exist with the name Makefile.rdy in order to work. The configure script
|
|
will overwrite Makefile, so if you want the default Makefile back, just run:
|
|
|
|
cp Makefile.rdy Makefile
|
|
|
|
Do not use a symlink, as that would result in Makefile.rdy getting
|
|
overwritten next time the configure script is run!
|
|
|
|
You can also access the usual build system by passing '-f Makefile.rdy' to
|
|
Make.
|
|
|
|
|
|
********************************************************
|
|
*** How to build DUMB manually if nothing else works ***
|
|
********************************************************
|
|
|
|
|
|
Those porting to platforms without floating point support should be aware
|
|
that DUMB does use floating point operations but not in the inner loops. They
|
|
are used for volume and note pitch calculations, and they are used when
|
|
initialising the filter algorithm for given cut-off and resonance values.
|
|
Please let me know if this is a problem for you. If there is enough demand, I
|
|
may be able to eliminate one or both of these cases.
|
|
|
|
All of the library source code may be found in the src/ subdirectory. There
|
|
are headers in the include/ subdirectory, and src/helpers/resample.c also
|
|
#includes some .inc files in its own directory.
|
|
|
|
There are four subdirectories under src/. For projects not using Allegro, you
|
|
will need all the files in src/core/, src/helpers/ and src/it/. If you are
|
|
using Allegro, you will want the src/allegro/ subdirectory too. For
|
|
consistency with the other build systems, the contents of src/allegro/ should
|
|
be compiled into a separate library.
|
|
|
|
I recommend static-linking DUMB, since the version information is done via
|
|
macros and the API has a tendency to change. If you static-link, then once
|
|
your program is in binary form, you can be sure that changes to the installed
|
|
version of DUMB won't cause it to malfuction. It is my fault that the API has
|
|
been so unstable. Sorry!
|
|
|
|
Compile each .c file separately. As mentioned above, you will need to specify
|
|
two places to look for #include files: the include/ directory and the source
|
|
file's own directory. You will also need to define the symbol
|
|
DUMB_DECLARE_DEPRECATED on the command line.
|
|
|
|
Do not compile the .inc files separately.
|
|
|
|
You may need to edit dumb.h and add your own definition for LONG_LONG. It
|
|
should be a 64-bit integer. If you do this, please see if you can add a check
|
|
for your compiler so that it still works with other compilers.
|
|
|
|
DUMB has two build modes. If you define the symbol DEBUGMODE, some checks for
|
|
programmer error will be incorporated into the library. Otherwise it will be
|
|
built without any such checks. (DUMB will however always thoroughly check the
|
|
validity of files it is loading. If you ever find a module file that crashes
|
|
DUMB, please let me know!)
|
|
|
|
I recommend building two versions of the library, one with DEBUGMODE defined
|
|
and debugging information included, and the other with compiler optimisation
|
|
enabled. If you can install DUMB system-wide so that your projects, and other
|
|
people's, can simply #include <dumb.h> or <aldumb.h> and link with libraries
|
|
by simple name with no path, then that is ideal.
|
|
|
|
If you successfully port DUMB to a new platform, please let me know!
|
|
|
|
|
|
****************************
|
|
*** The example programs ***
|
|
****************************
|
|
|
|
|
|
Three example programs are provided. On DOS and Windows, you can find them in
|
|
the examples subdirectory. On other systems they will be installed system-
|
|
wide.
|
|
|
|
dumbplay
|
|
This program will only be built if you have Allegro. Pass it the filename
|
|
of an IT, XM, S3M or MOD file, and it will play it. It's not a polished
|
|
player with real-time threading or anything - so don't complain about it
|
|
stuttering while you use other programs - but it does show DUMB's fidelity
|
|
nicely. You can control the playback quality by editing dumb.ini, which
|
|
must be in the current working directory. (This is a flaw for systems
|
|
where the program is installed system-wide, but it is non-fatal.) Have a
|
|
look at the examples/dumb.ini file for further information.
|
|
|
|
dumbout
|
|
This program does not need Allegro. You can use it to stream an IT, XM,
|
|
S3M or MOD file to raw PCM. This can be used as input to an encoder like
|
|
oggenc (with appropriate command-line options), or it can be sent to a
|
|
.pcm file which can be read by any respectable waveform editor. This
|
|
program is also convenient for timing DUMB. Compare the time it takes to
|
|
render a module with the module's playing time! dumbout doesn't try to
|
|
read any configuration file; the options are set on the command line.
|
|
|
|
dumb2wav
|
|
This program is much the same as dumbout, but it writes a .wav file with
|
|
the appropriate header. Thanks go to Chad Austin for this useful tool.
|
|
|
|
|
|
*********************************************
|
|
*** Downloading music or writing your own ***
|
|
*********************************************
|
|
|
|
|
|
If you would like to compose your own music modules, then this section should
|
|
help get you started.
|
|
|
|
The best programs for the job are the trackers that pioneered the file
|
|
formats:
|
|
|
|
Impulse Tracker - IT files - http://www.lim.com.au/ImpulseTracker/
|
|
Fast Tracker II - XM files - http://www.fasttracker2.com/
|
|
Scream Tracker 3 - S3M files - No official site known, please use Google
|
|
|
|
MOD files come from the Amiga; I do not know what PC tracker to recommend for
|
|
editing these. If you know of one, let me know! In the meantime, I would
|
|
recommend using a more advanced file format. However, don't convert your
|
|
existing MODs just for the sake of it.
|
|
|
|
Fast Tracker II is Shareware. It offers a very flashy interface and has a
|
|
game embedded, but the IT file format is more powerful and better defined. By
|
|
all means try them both and see which you prefer; it is largely a matter of
|
|
taste (and, in some cases, religion). Impulse Tracker and Scream Tracker 3
|
|
are Freeware, although you can donate to Impulse Tracker and receive a
|
|
slightly upgraded version. DUMB is likely to be at its best with IT files.
|
|
|
|
These editors are DOS programs. Users of DOS-incapable operating systems may
|
|
like to try ModPlug Tracker, but should read docs/modplug.txt before using it
|
|
for any serious work. If you use a different operating system, or if you know
|
|
of any module editors for Windows that are more faithful to the original
|
|
trackers' playback, please give me some links so I can put them here!
|
|
|
|
ModPlug Tracker - http://www.modplug.com/
|
|
|
|
If you have an x86 Linux system with VGA-compatible hardware (which covers
|
|
all PC graphics cards I've ever seen), you should be able to get Impulse
|
|
Tracker running with DOSEMU. You will have to give it access to the VGA ports
|
|
and run it in a true console, as it will not work with the X-based VGA
|
|
emulation. I personally added the SB16 emulation to DOSEMU, so you can even
|
|
use filters! However, it corrupts samples alarmingly often when saving on my
|
|
system - probably a DOSEMU issue. If you set this up, I am curious to know
|
|
whether it works for you.
|
|
|
|
DOSEMU - http://www.dosemu.org/
|
|
|
|
BEWARE OF WINAMP! Although it's excellent for MP3s, it is notorious for being
|
|
one of the worst module players in existence; very many modules play wrongly
|
|
with it. There are plug-ins available to improve Winamp's module support, for
|
|
example WSP.
|
|
|
|
Winamp - http://www.winamp.com/
|
|
WSP - http://www.spytech.cz/index.php?sec=demo
|
|
|
|
(There is a Winamp plug-in that uses DUMB, but it is unreliable. If anyone
|
|
would like to work on it, please get in touch.)
|
|
|
|
While I am at it I should also point out that Winamp is notorious for
|
|
containing security flaws. Install it at your own risk, and if it is your
|
|
work computer, check with your boss first!
|
|
|
|
Samples and instruments are the building blocks of music modules. You can
|
|
download samples at
|
|
|
|
http://www.tump.net/
|
|
|
|
If you would like to download module files composed by other people, check
|
|
the following sites:
|
|
|
|
http://www.modarchive.com/
|
|
http://www.scene.org/
|
|
http://www.tump.net/
|
|
http://www.homemusic.cc/main.php
|
|
http://www.modplug.com/
|
|
|
|
Once again, if you know of more sites where samples or module files are
|
|
available for download, please let me know.
|
|
|
|
If you wish to use someone's music in your game, please respect the
|
|
composer's wishes. In general, you should ask the composer. Music that has
|
|
been placed in the Public Domain can be used by anyone for anything, but it
|
|
wouldn't do any harm to ask anyway if you know who the author is. In many
|
|
cases the author will be thrilled, so don't hesitate!
|
|
|
|
A note about converting modules from one format to another, or converting
|
|
from MIDI: don't do it, unless you are a musician and are prepared to go
|
|
through the file and make sure everything sounds the way it should! The
|
|
module formats are all slightly different, and MIDI is very different;
|
|
converting from one format to another will usually do some damage.
|
|
|
|
Instead, it is recommended that you allow DUMB to interpret the original file
|
|
as it sees fit. DUMB may make mistakes (it does a lot of conversion on
|
|
loading), but future versions of DUMB will be able to rectify these mistakes.
|
|
On the other hand, if you convert the file, the damage is permanent.
|
|
|
|
|
|
***********************
|
|
*** Contact details ***
|
|
***********************
|
|
|
|
|
|
If you have trouble with DUMB, or want to contact me for any other reason, my
|
|
e-mail address is given below. Please do get in touch, even if I appear to
|
|
have disappeared!
|
|
|
|
If you wish to chat online about something, perhaps on IRC, that can most
|
|
likely be arranged. Send me an e-mail.
|
|
|
|
|
|
******************
|
|
*** Conclusion ***
|
|
******************
|
|
|
|
|
|
This is the conclusion.
|
|
|
|
|
|
Ben Davis
|
|
entheh@users.sf.net
|