Initial check in dumb 0.9.2 - has a few usages of floating point that should

be rewritten to fixed point. seems to compile cleanly for iriver.


git-svn-id: svn://svn.rockbox.org/rockbox/trunk@6197 a1c6a512-1295-4272-9138-f99709370657

1 files changed, 421 insertions, 0 deletions

diff --git a/apps/codecs/dumb/readme.txt b/apps/codecs/dumb/readme.txt
new file mode 100644
index 0000000000..45abd1a17a
--- /dev/null
+++ b/apps/codecs/dumb/readme.txt
@@ -0,0 +1,421 @@
+/*  _______         ____    __         ___    ___
+ * \    _  \       \    /  \  /       \   \  /   /       '   '  '
+ *  |  | \  \       |  |    ||         |   \/   |         .      .
+ *  |  |  |  |      |  |    ||         ||\  /|  |
+ *  |  |  |  |      |  |    ||         || \/ |  |         '  '  '
+ *  |  |  |  |      |  |    ||         ||    |  |         .      .
+ *  |  |_/  /        \  \__//          ||    |  |
+ * /_______/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