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