mirror of
https://github.com/ZDoom/qzdoom-gpl.git
synced 2024-12-02 16:32:12 +00:00
28afd04aef
Conflicts: src/CMakeLists.txt |
||
---|---|---|
.. | ||
docs | ||
examples | ||
include | ||
src | ||
vc6/dumb_static | ||
ChangeLog | ||
CMakeLists.txt | ||
licence.txt | ||
readme.txt | ||
release.txt | ||
todo.txt |
/* _______ ____ __ ___ ___ * \ _ \ \ / \ / \ \ / / ' ' ' * | | \ \ | | || | \/ | . . * | | | | | | || ||\ /| | * | | | | | | || || \/ | | ' ' ' * | | | | | | || || | | . . * | |_/ / \ \__// || | | * /_______/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