mirror of
https://github.com/ZDoom/gzdoom-gles.git
synced 2024-12-30 14:21:01 +00:00
01f59fa85f
heavily customized version of DUMB (Dynamic Universal Music Bibliotheque). It has been slightly modified by me: * Added support for Ogg Vorbis-compressed samples in XM files ala FMOD. * Removed excessive mallocs from the replay core. * Rerolled the loops in resample.c. Unrolling them made the object file ~250k large while providing little benefit. Even at ~100k, I think it's still larger than it ought to be, but I'll live with it for now. Other than that, it's essentially the same thing you'd hear in foobar2000, minus some subsong detection features. Release builds of the library look like they might even be slightly faster than FMOD, which is a plus. - Fixed: Timidity::font_add() did not release the file reader it created. - Fixed: The SF2 loader did not free the sample headers in its destructor. SVN r995 (trunk)
421 lines
17 KiB
Text
421 lines
17 KiB
Text
/* _______ ____ __ ___ ___
|
|
* \ _ \ \ / \ / \ \ / / ' ' '
|
|
* | | \ \ | | || | \/ | . .
|
|
* | | | | | | || ||\ /| |
|
|
* | | | | | | || || \/ | | ' ' '
|
|
* | | | | | | || || | | . .
|
|
* | |_/ / \ \__// || | |
|
|
* /_______/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
|