ref: 75c25767bcae8a13eb08b00fd46c4922619c34b6
parent: 50e839d4f51e1ff6fcbe68d39519475d7da74c4a
author: Chris Moeller <[email protected]>
date: Fri Sep 27 07:21:57 EDT 2013
Added documentation from the original project
--- /dev/null
+++ b/dumb/licence.txt
@@ -1,0 +1,77 @@
+/* _______ ____ __ ___ ___
+ * \ _ \ \ / \ / \ \ / / ' ' '
+ * | | \ \ | | || | \/ | . .
+ * | | | | | | || ||\ /| |
+ * | | | | | | || || \/ | | ' ' '
+ * | | | | | | || || | | . .
+ * | |_/ / \ \__// || | |
+ * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque
+ * / \
+ * / . \
+ * licence.txt - Conditions for use of DUMB. / / \ \
+ * | < / \_
+ * If you do not agree to these terms, please | \/ /\ /
+ * do not use DUMB. \_ / > /
+ * | \ / /
+ * Information in [brackets] is provided to aid | ' /
+ * interpretation of the licence. \__/
+ */
+
+
+Dynamic Universal Music Bibliotheque, Version 0.9.3
+
+Copyright (C) 2001-2005 Ben Davis, Robert J Ohannessian and Julien Cugniere
+
+This software is provided 'as-is', without any express or implied warranty.
+In no event shall the authors be held liable for any damages arising from the
+use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not claim
+ that you wrote the original software. If you use this software in a
+ product, you are requested to acknowledge its use in the product
+ documentation, along with details on where to get an unmodified version of
+ this software, but this is not a strict requirement.
+
+ [Note that the above point asks for a link to DUMB, not just a mention.
+ Googling for DUMB doesn't help much! The URL is "http://dumb.sf.net/".]
+
+ [The link was originally strictly required. This was changed for two
+ reasons. Firstly, if many projects request an acknowledgement, the list of
+ acknowledgements can become quite unmanageable. Secondly, DUMB was placing
+ a restriction on the code using it, preventing people from using the GNU
+ General Public Licence which disallows any such restrictions. See
+ http://www.gnu.org/philosophy/bsd.html for more information on this
+ subject. However, if DUMB plays a significant part in your project, we do
+ urge you to acknowledge its use.]
+
+2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+
+3. This notice may not be removed from or altered in any source distribution.
+
+4. If you are using the Program in someone else's bedroom on any Monday at
+ 3:05 pm, you are not allowed to modify the Program for ten minutes. [This
+ clause provided by Inphernic; every licence should contain at least one
+ clause, the reasoning behind which is far from obvious.]
+
+5. Users who wish to use DUMB for the specific purpose of playing music are
+ required to feed their dog on every full moon (if deemed appropriate).
+ [This clause provided by Allefant, who couldn't remember what Inphernic's
+ clause was.]
+
+6. No clause in this licence shall prevent this software from being depended
+ upon by a product licensed under the GNU General Public Licence. If such a
+ clause is deemed to exist, Debian, then it shall be respected in spirit as
+ far as possible and all other clauses shall continue to apply in full
+ force.
+
+We regret that we cannot provide any warranty, not even the implied warranty
+of merchantability or fitness for a particular purpose.
+
+Some files generated or copied by automake, autoconf and friends are
+available in an extra download. These fall under separate licences but are
+all free to distribute. Please check their licences as necessary.
--- /dev/null
+++ b/dumb/readme.txt
@@ -1,0 +1,541 @@
+/* _______ ____ __ ___ ___
+ * \ _ \ \ / \ / \ \ / / ' ' '
+ * | | \ \ | | || | \/ | . .
+ * | | | | | | || ||\ /| |
+ * | | | | | | || || \/ | | ' ' '
+ * | | | | | | || || | | . .
+ * | |_/ / \ \__// || | |
+ * /_______/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
[email protected]
--- /dev/null
+++ b/dumb/release.txt
@@ -1,0 +1,561 @@
+/* _______ ____ __ ___ ___
+ * \ _ \ \ / \ / \ \ / / ' ' '
+ * | | \ \ | | || | \/ | . .
+ * | | | | | | || ||\ /| |
+ * | | | | | | || || \/ | | ' ' '
+ * | | | | | | || || | | . .
+ * | |_/ / \ \__// || | |
+ * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque
+ * / \
+ * / . \
+ * release.txt - Release notes for DUMB. / / \ \
+ * | < / \_
+ * | \/ /\ /
+ * \_ / > /
+ * | \ / /
+ * | ' /
+ * \__/
+ */
+
+
+*******************************************
+*** DUMB v0.9.3, released 7 August 2005 ***
+*******************************************
+
+Hello! Welcome to a long-awaited-or-probably-just-given-up-on-by-everybody
+release! New to this release are lower memory usage, faster mixing loops,
+loading of text fields in the module files, and faster load functions for
+projects that don't need to seek within the module or know its length.
+Additionally, Chad Austin has contributed a dumb2wav tool for converting
+modules to .wav files and updated the Visual Studio 6 project files to
+compile all the examples as well as the library. Users of Unix-like systems
+will be pleased to know that on Chad's suggestion I have made the build
+system cope with variables such as $HOME or ${HOME} in the prefix.+
+Chad has also contributed an Autotools build system, but neither of us
+recommends its use. The Autotools are an evil black box, we haven't quite
+managed to get it right, and goodness help you if it happens not to work for
+you. The files are available in a separate download if you absolutely need
+them. Notice that that download is almost twice as large as the rest of DUMB!
+
+Maybe we'll do SCons next time.
+
+Thanks to Chad for all his work. Chad is the author of Audiere, a portable
+sound library which has started using DUMB for its module playback! Wahoo!
+
+ http://audiere.sf.net/
+
+There are three main optimisations that went into the mixing loops.
+
+First, I downloaded ModPlugXMMS and had a peek at the mixing code, which is
+Public Domain. It uses look-up tables for the cubic mixing. I pinched the
+idea, and that sped DUMB's cubic (best quality) resamplers up by a factor of
+two or three.
+
+Secondly, the samples loaded from the file are now kept in 8-bit or 16-bit
+format, whereas previously they were being converted to 24-bit-in-32-bit on
+loading. This means the samples occupy a half or a quarter of the memory they
+used to occupy. It also had the side-effect of speeding up the mixing loops,
+but it meant I had to duplicate the resampling code. (It is all done with
+macros in the source code, but it becomes two copies on the binary level.)
+
+Secondly, stereo samples and stereo mixing buffers are now kept in
+interleaved format, where previously the two channels were done separately to
+keep the code simpler. This change has made the library quite a bit bigger,
+but has made the code run almost twice as fast for stereo output (tested for
+modules whose samples are mostly mono)!
+
+DUMB is now as fast as ModPlugXMMS on my system.
+
+Some people have also commented that DUMB seems to take a long time loading
+files. This is because immediately upon loading the file it runs the playback
+engine over it up as far as the point of first loop, taking snapshots at 30-
+second intervals to be used as references for fast seeking and finally
+storing the playback time. Of course, most games don't need this. You can now
+skip it by calling the _quick versions of the dumb_load_*(), dumb_read_*() or
+dumb_register_dat_*() functions. Should you need the data later, you can call
+dumb_it_do_initial_runthrough() to calculate it. Please note that this cannot
+currently be done safely from a concurrent thread while the music is playing.
+
+As mentioned, DUMB loads the text fields in module files now. You can
+retrieve the song title with duh_get_tag(). Sample names and file names and
+instrument names and filenames, and the song message for IT files, are
+available with a call to duh_get_it_sigdata() and various dumb_it_sd_*()
+functions. Please note that text fields added as extensions by ModPlug
+Tracker are not supported.
+
+DUMB's timing is ever so slightly more accurate. This is hardly noticeable,
+but it has meant that the length computed will increase very slightly.
+
+There are many small playback fixes in this release:
+
+* The Lxx effect in XM files (set envelope position) is now supported.
+
+* Pattern looping is now correct for XM files. Bizarrely, an ordinary pattern
+ loop whose start point isn't the first row seems to cause the next pattern
+ to start at the row corresponding to the loop start point. That must have
+ been a headache for people creating XM files! Nevertheless, DUMB now
+ emulates this behaviour. If you have an XM file that was written in a
+ tracker other than Fast Tracker II and breaks in DUMB, you can get around
+ it by putting a D00 effect (break to row 0) right at the end of the pattern
+ containing the loop.
+
+* XM pattern looping can be infinite. DUMB should detect this and call the
+ loop callback when it happens. Specifically, it has a loop counter for each
+ channel, so each time it sets or decrements that counter, it remembers the
+ loop end point for that channel. When the loop terminates, the loop end
+ point is reset to 0. If the loop end point ever decreases during a loop,
+ the loop callback is called. If anyone manages to get around this check and
+ prevent DUMB from calling the callback, please let me know and send me an
+ illustrative XM file!
+
+* For IT files, notes are now removed from channels if they have faded out,
+ even if they are still in the foreground. After this has happened, a row
+ with a note and Gxx (tone portamento) specified will cause a new note to
+ start playing, which is what Impulse Tracker does in this scenario.
+ (Normally, Gxx prevents the new note from playing and instead causes the
+ old note to start sliding towards the new note.)
+
+* If a tone portamento command occurred when no note was playing, the effect
+ value wasn't stored. This has been fixed. Thanks to Maim from #trax on
+ EFnet for discovering this bug.
+
+* DUMB now treats the parameter to the undocumented XM key off effect Kxx as
+ a delay, consistent with Fast Tracker II's behaviour. It has also been made
+ not to clear the note, so a subsequent volume command will restore it, as
+ in Fast Tracker II.
+
+* DUMB used to process the first row when you created the
+ DUMB_IT_SIGRENDERER. This happened before you had a chance to install any
+ callbacks. If an F00 effect occurred on the first row, the music would stop
+ immediately and the xm_speed_zero callback would be called if it were
+ present. Unfortunately, it wasn't present, and the algorithm for
+ calculating the length subsequently went into an endless loop while waiting
+ for it. Worse still, the same algorithm accumulated data for fast seeking,
+ and never stopped, so it pretty quickly consumed all the resources. DUMB
+ will now not process the first row until you first request some samples,
+ provided you pass zero for pos. Of course, any MOD or XM file with F00 in
+ the very first row won't do much anyway, but such files won't crash the
+ library now.
+
+* There was a subtle bug that affected a few XM files. For instruments with
+ no associated samples, the array mapping notes to samples is uninitialised.
+ This became a problem if such instruments were then used, which does happen
+ sometimes. On many systems, memory is initialised to zero when first given
+ to a program (for security reasons), so the problem didn't come up most of
+ the time. However, on platforms like DOS where memory isn't initialised, or
+ in programs that reuse memory later on (this includes the XMMS plug-in with
+ which I discovered the bug), a rogue note would occasionally play. This has
+ now been fixed.
+
+* DUMB's envelope handling for IT files was subtly wrong. Upon note off, it
+ stopped obeying the sustain loop points one tick too early. Notes were
+ often shorter than they should have been, and in pathological cases a whole
+ extra iteration of the sustain loop section might have been skipped. The
+ envelope code has now been rewritten. Thanks go to Allefant for Valgrinding
+ the new code!
+
+Finally, there were two build problems in the last version, which were fixed
+in the download marked with -fixed. They are of course correct in this
+version. For the record:
+
+* The make/config.bat file, responsible for generating make/config.txt, wrote
+ a crucial line to the wrong place, causing it to be left out of the file.
+ As a result, the makefile would fail to install everything for Allegro
+ users, and enter infinite recursion for other users. This applied to people
+ using DJGPP and MinGW.
+
+* DUMB's Makefile was supposed to install the example programs on Unix-based
+ platforms, but it wasn't doing. The fix was to edit Makefile and change the
+ one occurrence of $COMSPEC to $(COMSPEC).
+
+That's it! I hope you enjoy this long-awaited-or-probably-just-given-up-on-
+by-everybody release of DUMB!
+
+
+******************************************
+*** DUMB v0.9.2, released 2 April 2003 ***
+******************************************
+
+Yes, there really has been a release. This is not a day-late April fools'
+joke.
+
+DUMB's full name has changed! The old "Dedicated Universal Music
+Bastardisation" was rather silly, and not much more than a forced attempt at
+finding words beginning with D, U, M and B. I spent weeks and weeks browsing
+dictionaries and hopelessly asking others for bright ideas, until the
+brilliant Chris "Kitty Cat" Robinson came up with "Dynamic". I decided to
+keep the U as Universal, since a DUH struct can hold digital music in any
+format. Now all that remained was the B, but it didn't take me long to come
+up with Bibliotheque, which, despite looking French, is indeed considered an
+English word by Oxford English Dictionary Online, to which my university has
+a subscription. So there you have it - the name now makes sense.
+
+The two most significant additions to the project would have to be the new
+thread safety (with an important restriction, detailed in docs/dumb.txt), and
+the new build system. The silly 'makeall' and 'makecore' scripts are gone. If
+you are a GCC user, all you need do now is run 'make' and 'make install', as
+for other projects. You don't even have to run a 'fix' script any more! There
+are some caveats, which are covered in readme.txt. If you use Microsoft
+Visual C++ 6, you no longer need to obtain GCC and GNU Make - there is a
+project file just for you.
+
+Huge thanks go to Steve Terry for testing on Windows XP - about five times -
+and to lillo for testing on BeOS and Mac OS X. Thanks also to X-G for testing
+on a Windows system that has consistently posed problems for DUMB's old
+makefiles.
+
+There was a bug whereby al_poll_duh() would sometimes cause the music to
+resume playing if you called it after al_pause_duh(). Whether this was DUMB's
+fault for misusing Allegro's API, or a bug in Allegro, is unclear, but this
+release makes it work.
+
+In one of my projects, I found that my AL_DUH_PLAYER stopped playing when
+there were lots of other sound effects. In order to fix this, I programmed
+DUMB to set the priority of the stream's voice to 255, the maximum. I also
+added al_duh_set_priority(), so you can set the priority yourself if you need
+to.
+
+The resampling code has undergone a transformation. The bad news is that the
+linear average code is no longer in use. The good news is that where DUMB's
+resamplers used to require three extra samples' worth of memory to be
+allocated and initialised, it now copes with just the sample data. And it
+does a very good job at bouncing off loop points and otherwise hurtling
+around the sample. The resampling code is considerably more complicated, but
+the code that uses the resamplers is considerably simpler - and if you
+noticed a slight click in some bidirectionally looping samples, you'll be
+pleased to know that that click is gone!
+
+I have also devoted some effort to optimisation. It seemed hopeless for a
+while, but then I actually figured out a way of making it faster AND more
+accurate at the same time! DUMB is now quite a bit faster than it was, and it
+mixes not with 16-bit precision, but with 24-bit precision. (It used 32-bit
+integers all along, but the difference is that it now makes use of 256 times
+as much of the integer's range.)
+
+There have been the usual improvements to playback. The last release occurred
+rather too soon after I had fixed the XM effect memories; EAx and EBx, fine
+volume ramps, had been neglected. These are now handled properly.
+
+In previous versions of DUMB, muted channels in IT were actually played with
+surround sound panning (where the right-hand channel is inverted). This has
+been fixed, so muted channels will really be muted now.
+
+There were also some subtle problems with the way DUMB handled New Note
+Actions for IT files. It turned out that, in all releases of DUMB so far,
+pitch, filter and panning envelopes and sample vibrato were not being
+processed for any note that was forced into the background by a new note on
+the same channel! This only affected IT files. Not only has this been fixed,
+but envelope interpolation is much more accurate. Long trailing envelope-
+driven fade-outs sound a lot better now!
+
+Since panning and filter envelopes are more precise, extra fields have been
+added to the DUMB_IT_CHANNEL_STATE struct, used by
+dumb_it_sr_get_channel_state(). These fields hold the 'decimal' parts of the
+pan and filter cut-off. See dumb.txt for details.
+
+Mxx (set channel volume) now correctly only modifies the last note played on
+the channel, not any previous notes that have been forced into the background
+by New Note Actions, and filter effect processing is now closer to what
+Impulse Tracker does.
+
+The XM loader was slightly flawed and could crash on files containing samples
+with out-of-range loop points. One such file was given to me. This has been
+fixed.
+
+Finally, the legal stuff. Julien Cugniere has been added to the list of
+copyright owners. He deserves it, for all the work he did on the XM support!
+And the licence has been changed. You are no longer required to include a
+link to DUMB in a project that uses DUMB; the reasons for this relaxation are
+explained in licence.txt. However, the request is still there ...
+
+As usual, enjoy!
+
+
+**********************************************
+*** DUMB v0.9.1, released 19 December 2002 ***
+**********************************************
+
+Hi again! Lots to say this time, so I shall cut right to the chase.
+
+DUMB now supports Impulse Tracker's low-pass resonant filters! Huge thanks go
+to Jeffrey Lim, author of Impulse Tracker, for giving me what information he
+still had regarding the algorithm; to cut a long story short, modifying
+ModPlug Tracker's source code (which is in the Public Domain) led to an
+algorithm whose output matched Impulse Tracker's perfectly.
+
+Please note that ModPlug Tracker's filters as they stand do not match Impulse
+Tracker's, and I have no interest in supporting ModPlug Tracker's variant
+(especially not the integer rounding problems). Please see docs/modplug.txt,
+new in this release, for details.
+
+Thanks also go to Fatso Huuskonen for motivating me to add filter support,
+and providing me with several great IT files to test it with!
+
+The other important feature added for this release is click removal. Up until
+now, DUMB has generated clicks when cutting notes, starting samples in the
+middle, and so on. This version of DUMB will remove any such clicks. Note
+that DUMB does not use volume ramps to accomplish this; the algorithm will
+not take the bite out of the music!
+
+In other news, DUMB now supports sample vibrato for IT files, and instrument
+vibrato for XM files. A slight bug in New Note Action handling for IT files
+has been fixed; Note Fade will not break the sustain loops of the sample and
+envelope, as it did before. Tremor handling (Ixy) had a strange bug in it,
+which has been fixed.
+
+Support for XM files has been greatly enhanced. The XM envelope handling new
+in the last release contained a huge bug, resulting in notes seeming not to
+stop when they should; this has been fixed. Some XM files crashed DUMB, while
+others failed to load; these problems have been solved. Effect memories now
+work properly for XM and MOD files, to the best of my knowledge. Some other
+differences between IT and XM have been accounted for, most notably the
+Retrigger Note effects, Rxy and E9x.
+
+DUMB's sound quality and accuracy are not the only areas that have been
+enhanced. The API has been expanded, at last. You can now detect when a
+module loops, or make it play through just once. You can ask DUMB to inform
+you every time it generates some samples; this is useful for visualisation.
+For IT files, you can intercept the MIDI messages generated by Zxx macros,
+enabling you to synchronise your game with the music to some extent. (There
+is no such method for XM, S3M or MOD files yet; sorry. Also note that the
+function will be called before you actually hear the sound; I cannot improve
+this until DUMB has its own sound drivers, which won't be for a while.) You
+can query the current order and row. Finally, operations like changing the
+speed and tempo are now possible, and you can query the playback state on
+each channel.
+
+Some parts of DUMB's API have been deprecated. Simple programs that use
+Allegro will be unaffected, but if you get some compiler warnings or errors,
+please review docs/deprec.txt. This file explains why those parts of the API
+were deprecated, and tells you how to adapt your code; the changes you need
+to make are straightforward. Sorry for the inconvenience.
+
+For various reasons, I have made DUMB's makefiles use different compiler
+flags depending on your GCC version (unless you are using MSVC). There is no
+elegant way of getting the makefiles to detect when GCC is upgraded. If you
+upgrade GCC, you should execute 'make clean' in order to make DUMB detect the
+GCC version again. Otherwise you may get some annoying error messages. (It is
+wise to do this in any case, so that all the object files are built with the
+same GCC version.)
+
+DUMB's example players have been unified into a single player called
+'dumbplay'. The player has been enhanced to display messages when the music
+loops, and when XM and MOD files freeze (effect F00; more information on this
+in docs/howto.txt).
+
+Finally, as noted on DUMB's website, the release notes from the last release
+were inaccurate. It has been verified that DUMBOGG v0.5 does still work with
+that release, and still works with this release. The esoteric DUMBOGG v0.6
+has not been created yet, since DUMBOGG v0.5 still works.
+
+Please scroll down and read through the indented paragraphs in the notes for
+the last release; they are relevant for this release too.
+
+That's all folks! Until next time.
+
+
+*******************************************
+*** DUMB v0.9, released 16 October 2002 ***
+*******************************************
+
+MOD support is here! DUMB now supports all four of the common module formats.
+As usual, there have also been some improvements to the way modules are
+played back. Most notably, handling of tone portamento in IT files has been
+improved a lot, and XM envelopes are now processed correctly.
+
+The other major change is that DUMB now does a dummy run through each module
+on loading. It stores the playback state at thirty-second intervals. It stops
+when the module first loops, and then stores the playback time. This results
+in a slightly longer load time and a greater memory overhead, but seeking is
+faster (to any point before the module first loops) and the length is
+calculated! duh_get_length() will return this and is now documented in
+docs/howto.txt and docs/dumb.txt.
+
+DUMB's build process has been changed to use 'mingw' wherever it used
+'mingw32' before; some directories have been renamed, and the 'fix' command
+you had to run for MinGW has been changed from 'fix mingw32' to 'fix mingw'.
+
+Last time, I directed you to scroll down and read the notes from a past
+release, but ignore this point, and that point applies to something else, and
+so on. Did anyone do so? Well, if you're reading this at all, you probably
+did. Nevertheless, this time I shall be much less confusing and restate any
+relevant information. So the least you can do is read it!
+
+- If your program ever aborts with exit code 37 while loading an IT file,
+ PLEASE LET ME KNOW! The IT file in question has a stereo compressed sample
+ in it, and the format is unspecified for this case (Impulse Tracker itself
+ doesn't use stereo samples at all). I will need the IT file in question,
+ and any information you can give me about how the IT file was created (e.g.
+ what program). (If you don't get to see an exit code, let me know anyway.)
+
+- If your program ever outputs a line resembling "Inst 01 Env: 0,64 8,32
+ 15,48" to stderr while loading an IT file, PLEASE LET ME KNOW! You have an
+ old IT file (saved by an Impulse Tracker version older than 2.00), and
+ support for such files is STILL untested.
+
+- Not all parts of DUMB's API are documented yet. You will find some
+ functions in dumb.h which are not listed in docs/dumb.txt; the reason is
+ that these functions still need work and will probably change. If you
+ really, really want to use them, talk to me first (IRC EFnet #dumb is a
+ good place for this; see readme.txt for details on using IRC). I intend to
+ finalise and document the whole of DUMB's API for Version 1.0.
+
+There have been some changes to the naming conventions in DUMB's undocumented
+API. DUMBOGG v0.5 will not work with this and subsequent releases of DUMB;
+please upgrade to DUMBOGG v0.6. These changes should not break anything in
+your own code, since you didn't use those parts of the API, did you ;)
+
+There is still a great deal of work to be done before DUMB's API can be
+finalised, and thus it will be a while before DUMB v1.0 comes out. It should
+be worth the wait. In the meantime, there will be 0.9.x releases with
+additional functionality, improved playback, and possibly support for some
+extra file formats.
+
+Finally I should like to offer an apology; there is a strong possibility that
+some of DUMB's official API will change in the near future. There will not be
+any drastic changes, and the corresponding changes to your source code will
+be simple enough. If I didn't make these changes, DUMB's API would start to
+become limited, or messy, or both, so it's for the better. I apologise in
+advance for this.
+
+Now scroll down and read the notes for the first r... oh wait, we already did
+that. I guess that's it then. You can stop reading now.
+
+Right after you've read this.
+
+And this.
+
+Off you go.
+
+Bye.
+
+
+********************************************
+*** DUMB v0.8.1, released 11 August 2002 ***
+********************************************
+
+This is a minor release that fixes a few bugs. One of these bugs, however,
+was pretty serious. dumb_register_dat_xm() was never coded! It was prototyped
+in aldumb.h, so code would compile, but there would be an unresolved symbol
+at the linking stage. This has been fixed.
+
+Platforms other than Unix did not have a working 'make veryclean' target;
+this has been fixed. In addition, the makefiles now use 'xcopy' instead of
+'copy', since on some systems GNU Make seems to have trouble calling commands
+built in to the shell.
+
+Contrary to the errata that was on the DUMB website, the makeall.sh and
+makecore.sh scripts actually DID install in /usr. This has now been
+corrected, and regardless of whether you use these scripts or call make
+directly, the files will now be installed to /usr/local by default.
+
+The XM loader used to treat stereo samples as mono samples with the data for
+the right channel positioned after the data for the left channel. This
+generally resulted in an unwanted echo effect. This has been fixed.
+
+When playing XM files, specifying an invalid instrument would cause an old
+note on that channel to come back (roughly speaking). Fast Tracker 2 does not
+exhibit this behaviour. This has been fixed.
+
+The GCC makefiles used -mpentium, which is deprecated in gcc 3.x. This was
+generating warnings, and has now been fixed.
+
+In XM files, the length of a sample is stored in bytes. DUMB was assuming
+that the length of a 16-bit sample would be even. I had two XM files where
+this was not the case, and DUMB was unable to load them. This has been fixed.
+
+In order to accommodate the extra part of the version number,
+DUMB_REVISION_VERSION has been added. DUMB_VERSION has also been added in
+order to facilitate checking if the version of DUMB installed is sufficient.
+See docs/dumb.txt for details.
+
+As a last-minute fix, the XM "Break to row" effect is now loaded properly. It
+was necessary to convert from binary-coded decimal to hexadecimal (those who
+have experience with Fast Tracker 2 will know what I mean). In short, this
+means the effect will now work properly when breaking to row 10 or greater.
+
+DUMB v0.8 had faulty release date constants; DUMB_MONTH and DUMB_DAY were
+swapped! For this reason, DUMB_DATE should not be compared against any date
+in 2002. This note has been added to docs/dumb.txt and also to dumb.h.
+
+Please scroll to the end and read the release notes for the first version,
+DUMB v0.7. Most of them apply equally to this release. However, the
+non-portable code was rewritten for DUMB v0.8, so that point does not apply.
+The point about length not being calculated also applies to XM files.
+
+Enjoy :)
+
+
+****************************************
+*** DUMB v0.8, released 14 June 2002 ***
+****************************************
+
+Welcome to the second release of DUMB!
+
+In addition to these notes, please read below the release notes for the
+previous version, DUMB v0.7. Most of them apply equally to this release.
+However, the non-portable code has been rewritten; DUMB should now port to
+big-endian platforms.
+
+The main improvement in this release of DUMB is the support for XM files.
+Enormous thanks go to Julien Cugniere for working on this while I had to
+revise for my exams!
+
+There was a mistake in the makefiles in the last release. The debugging
+Allegro interface library was mistakenly named libaldmbd.a instead of
+libaldmd.a, meaning you had to compile with -laldmbd, contrary to what the
+docs said. Apologies to everyone who lost sleep trying to work out what was
+wrong! The reason for using libaldmd.a is to maintain compatibility with
+plain DOS, where filenames are limited to eight characters (plus a three-
+letter extension). The makefiles have now been changed to match the
+information in the docs, so you may have to alter your project files
+accordingly.
+
+The example programs were faulty, and crashed on Windows if they were unable
+to load the file. It was also difficult to work out how to exit them (you had
+to click the taskbar button that didn't have a window, then press a key).
+They have been improved in both these respects.
+
+I have now added a docs/faq.txt file (Frequently Asked Questions), which is
+based on problems and misconceptions people have had with the first release.
+Please refer to it before contacting me with problems.
+
+Thanks to networm for touching up the Unix makefile and writing the
+instructions on using it.
+
+Incidentally, today (Friday 14 June) is the Robinson College May Ball at
+Cambridge Uni. God knows why it's called a May Ball if it's in June. I'm not
+going myself (72 GBP, and I'd have to wear a suit, ugh), but with all the
+noise outside I shall enjoy pumping up the speakers tonight!
+
+
+****************************************
+*** DUMB v0.7, released 2 March 2002 ***
+****************************************
+
+This is the first release of DUMB, and parts of the library are not
+crystallised. Don't let this put you off! Provided you don't try to use any
+features that aren't documented in docs/dumb.txt, the library should be rock
+solid and you should be able to upgrade more or less without problems.
+
+Here are some notes on this release:
+
+- There is some non-portable code in this release of DUMB. It is likely that
+ the library will fail to load IT files with compressed samples on
+ big-endian machines such as the Apple Macintosh.
+
+- If your program ever aborts with exit code 37 while loading an IT file,
+ PLEASE LET ME KNOW! The IT file in question has a stereo compressed sample
+ in it, and the format is unspecified for this case (Impulse Tracker itself
+ doesn't use stereo samples at all). I will need the IT file in question,
+ and any information you can give me about how the IT file was created (e.g.
+ what program). (If you don't get to see an exit code, let me know anyway.)
+
+- If your program ever outputs a line resembling "Inst 01 Env: 0,64 8,32
+ 15,48" to stderr while loading an IT file, PLEASE LET ME KNOW! You have an
+ old IT file (saved by an Impulse Tracker version older than 2.00), and
+ support for such files is untested.
+
+- The length of IT and S3M files is not currently calculated. It is just set
+ to ten minutes.