mirror of https://github.com/ZDoom/qzdoom.git
422 lines
17 KiB
Plaintext
422 lines
17 KiB
Plaintext
/* _______ ____ __ ___ ___
|
|
* \ _ \ \ / \ / \ \ / / ' ' '
|
|
* | | \ \ | | || | \/ | . .
|
|
* | | | | | | || ||\ /| |
|
|
* | | | | | | || || \/ | | ' ' '
|
|
* | | | | | | || || | | . .
|
|
* | |_/ / \ \__// || | |
|
|
* /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque
|
|
* / \
|
|
* / . \
|
|
* readme.txt - General information on DUMB. / / \ \
|
|
* | < / \_
|
|
* | \/ /\ /
|
|
* \_ / > /
|
|
* | \ / /
|
|
* | ' /
|
|
* \__/
|
|
*/
|
|
|
|
|
|
********************
|
|
*** Introduction ***
|
|
********************
|
|
|
|
|
|
Thank you for downloading DUMB! 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
|
|
|
|
- Fast seeking 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
|
|
|
|
- Makefile provided for DJGPP, MinGW, Linux, BeOS and Mac OS X; project file
|
|
provided for MSVC 6 (please contact me if you'd like to submit or request
|
|
support for a new platform; the code itself should port anywhere that has a
|
|
32-bit C compiler)
|
|
|
|
- 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)
|
|
|
|
|
|
*********************
|
|
*** 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/
|
|
|
|
Neil Walker has kindly uploaded some DUMB binaries at
|
|
http://retrospec.sgn.net/allegro/ . They may not always be up to date, so you
|
|
should try to compile it yourself first.
|
|
|
|
|
|
**********************************************
|
|
*** 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. 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.
|
|
|
|
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 the following to install the libraries:
|
|
|
|
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 the following:
|
|
|
|
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.
|
|
|
|
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 ***
|
|
******************************************************
|
|
|
|
|
|
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 now comes with a project file for Microsoft Visual C++ 6. To add DUMB to
|
|
your project:
|
|
|
|
1. Open your project in VC++.
|
|
2. Select Project|Insert Project into Workspace...
|
|
3. Navigate to the dumb\vc6 directory, and select dumb.dsp.
|
|
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.
|
|
|
|
Good thing you only have to do all that once ...
|
|
|
|
If you have the Intel compiler installed, it will - well, should - be used to
|
|
compile DUMB. The only setting I 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 :)
|
|
|
|
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!). They are
|
|
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.
|
|
|
|
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 possibly even 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 use dtou on some or all of the text files.
|
|
If you have problems, just go and download the .tar.gz instead.
|
|
|
|
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. 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.
|
|
|
|
Information on the example programs is just below. 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!
|
|
|
|
|
|
****************************
|
|
*** The example programs ***
|
|
****************************
|
|
|
|
|
|
Two 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. No .wav
|
|
support yet, sorry. 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.
|
|
|
|
|
|
*********************************************
|
|
*** Downloading music or writing your own ***
|
|
*********************************************
|
|
|
|
|
|
If you would like to compose your own music modules, then first I must offer
|
|
a word of warning: not everyone is capable of composing music. Do not assume
|
|
you will be able to learn the art. By all means have a go; if you can learn
|
|
to play tunes on the computer keyboard, you're well on the way to being a
|
|
composer!
|
|
|
|
The best programs for the job are the trackers that pioneered the file
|
|
formats:
|
|
|
|
Impulse Tracker - IT files - http://www.noisemusic.org/it/
|
|
Fast Tracker II - XM files - http://www.gwinternet.com/music/ft2/
|
|
Scream Tracker 3 - S3M files -
|
|
http://www.united-trackers.org/resources/software/screamtracker.htm
|
|
|
|
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.
|
|
|
|
Note that Fast Tracker II is Shareware. It arguably offers the best
|
|
interface, but the IT file format is more powerful and better defined.
|
|
Impulse Tracker and Scream Tracker 3 are Freeware. 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/
|
|
|
|
BEWARE OF WINAMP! Although it's excellent for MP3s, it is notorious for being
|
|
one of the worst module players in existence; very few modules play correctly
|
|
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
|
|
|
|
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 most
|
|
cases the author will be thrilled, so don't hesitate!
|
|
|
|
A note about converting modules from one format to another: 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 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. However, I may be able to help more if you
|
|
come on to IRC EFnet #dumb.
|
|
|
|
IRC stands for Internet Relay Chat, and is a type of chat network. Several
|
|
such networks exist, and EFnet is a popular one. In order to connect to an
|
|
IRC network, you first need an IRC client. Here are some:
|
|
|
|
http://www.xchat.org/
|
|
http://www.visualirc.net/beta.php
|
|
http://www.mirc.com/
|
|
|
|
Getting on to IRC can be a steep cliff, but it is not insurmountable, and
|
|
it's well worth it. Once you have set up the client software, you need to
|
|
connect to a server. Here is a list of EFnet servers I have had success with.
|
|
Type "/server" (without quotes), then a space, then the name of a server.
|
|
|
|
irc.homelien.no
|
|
irc.webgiro.se
|
|
efnet.vuurwerk.nl
|
|
efnet.demon.co.uk
|
|
irc.isdnet.fr
|
|
irc.prison.net
|
|
|
|
If these servers do not work, visit http://efnet.org/ircdb/servers.php for a
|
|
huge list of other EFnet servers to try.
|
|
|
|
Once you're connected, type the following:
|
|
|
|
/join #dumb
|
|
|
|
A window will appear, and you can ask your question. It should be clear
|
|
what's going on from this point onwards. I am 'entheh'. Note that unlike many
|
|
other nerds I am not always at my computer, so if I don't answer your
|
|
question, don't take it personally! I will usually be able to read your
|
|
question when I come back.
|
|
|
|
|
|
******************
|
|
*** Conclusion ***
|
|
******************
|
|
|
|
|
|
This is the conclusion.
|
|
|
|
|
|
Ben Davis
|
|
entheh@users.sf.net
|
|
IRC EFnet #dumb
|