Groovy Bytes: Behind the Moon

home *** CD-ROM | disk | FTP | other *** search

/ Groovy Bytes: Behind the Moon / groovybytes.iso / GROOVY / SND_TOOL / CRYS250.ZIP / CRYSENG.DOC < prev next >

Wrap

Text File | 1995-01-11 | 19.8 KB | 605 lines

────────────────────────────────── CRYSTAL PLAYER Version 2.50 ──────────────────────────────────────── (C)opyright 1994 Sébastien GRANJOUX ──────────── WARNING: You are using this software at your own risks! In no events should I be liable for any damage or loss resulting from the use, misuse or inability to use Crystal Player. There are no warranties, except that this program will occupy disk place. Table of contents │ ───────────────────┘ I ........................................... Licence II .................................. Archive content III ........................................ Features IV ................................... The MOD player V ........................ Using Crystal Sound System VI ....................... Frequently Asked Questions VII ......................................... History VIII ......................................... Thanks IX ............................. Contact informations X ................................Distributions Sites I - Licence │ ─────────────┘ This program enables you to play music files in the MOD format and can be included in your own programs, as long as these terms are respected: You can freely include Crystal Player in any public domain software (freeware), if you credit me as the author of the sound system. For any commercial use (including shareware), contact me to discuss about further terms and to obtain my agreement. This program is provided with its full sources in order to enable you to modify and adapt them in order to fit your particular needs. These modifications should be kept personnal, but I'll be glad to receive any improvement to Crystal Player. I just want to keep Crystal Player under control, in order to prevent bugged versions from floating around. You can freely distribute this program, as long as you don't charge more than 5 US dollars for shipping fees and you keep all the original files in the archive. Contact informations are located at the end of this file. III - Archive Content │ ───────────────────────┘ The archive should be called CRYSxxxl, where xxx is the version (for instance 240 means version 2.40). The letter l doesn't exist in public releases. B means that it is a beta version, some files may be missing, and some bugs could be present. The usual archive contains these 15 files: C0MULTI.ASM contains starting code for Crystal Player in asm. CRYS.EXE is an executable version of the modplayer. CRYS26.ASM contains all routines to play a MOD file. CRYS26.OBJ is an object file generated by Turbo Assembleur of the previous file. That's the file you need to include in your C or ASM source to use Crystal Player routines. CRYSEXP.CPP is an example of the use of Crystal Player routines in Turbo C++ CRYSEXP.PAS same as above, but for Turbo Pascal. CRYSTAL.ASM is the main code of the MOD player. You may consider it as an example for asm. CRYSENG.DOC is the file you are now reading. CRYSFR.DOC same as above, but in french. CRYSTAL.INC contains some constants definitions for an asm program, like error codes and soundcards number. CRYSTAL.PAS contains the source of the Turbo Pascal unit needed to use Crystal Player routines. CRYSTAL.TPU contains the unit for Turbo Pascal programs. FILE_ID.DIZ description for BBSes. STINTER.ASM contains some routines to get some variables from CRYS26 like current track number. STMODE3.ASM contains routines for text mode 3 (80x25 16 colors) II - Features │ ───────────────┘ This program is entirely coded in asm and contains 386 instructions. It don't works on XT and 286 based PCs. It supports four sound devices: the internal speaker, a DAC (digital to analog convertor) on a parallel port (like Covox), a Sound Blaster card, and a Gravis UltraSound card (GUS). Be aware that the Sound Blaster needs to use the DMA channel 1 and an IRQ inferior or equal to 7. It only plays MOD files with 15 or 31 instruments and 4, 6 or 8 channels. Moreover, it only accept 64 patterns and each sample should be smaller than 63 Kb. The following effects aren't recognized: E3,E4,E5,E7,EF. On the other hand, it uses 8 octaves like MOD files tracked with Scream Tracker 3. As you will notice by reading the history, this program has been constantly evolving, so it isn't very easy to understand. It contains a few bugs, and if something don't works, maybe you've just discovered a new one. ;) In this case, contact me. Usually, I correct bugs rather quickly. If it's a particular MOD file which don't work, I would like you to send it to me (at least the name and the place where I cand find it). IV - The MOD player │ ─────────────────────┘ The MOD player contained in the archive isn't meant to concurrence other MOD players, and it has only few options. It is provided so that you can easily see the qualities (and lacks) of the sound routines. It also gives you an example to use them in asm. It uses internal informations of the routines, so you can look how to use them if you really need them. You can code a new MOD player with these routines but they doesn't really be made for that. It can be easily used, and if you run it without any parameter, it will display a help page. You should at least give the name of a .MOD file. It will then choose itself the best sound device that it will find in your environment variables. You can force a sound device, even if it doesn't exist in your environment variables, or change the default mixing frequency (18.6 kHz) by using these options: /FRxxx Mixing frequency in hundreds of Hertz /SK Internal Speaker /DCp DAC on port p (1 to 4) /SBp,i Sound Blaster on port p (in hexadecimal 220 for instance) with IRQ i. /GSp Gravis UltraSound on port p (hexadecimal) You don't need to provide p or i parameters (but leave the , ): the player will look for those values in environment variables. If they don't exist, it uses default values. V - Using Crystal Sound System │ ────────────────────────────────┘ Source was assembled by Turbo Assembler in ideal mode, and needs a 386. Sound routines are gathered in CRYS26.ASM. To use them, you only need to include the CRYS26.OBJ or the pascal TPU unit. Every function uses the pascal format to take parameters. They can send back a 16 bits error code, but restore ES,DS,DI and SI. Other registers may be altered. To play music, you need to call in order FLOADMOD or MLOADMOD to load the module in memory, then SETMOD to tell which sound device you wish to use and frequency, and finally STARTMOD to start playing the music. You will then need to call MAKEMOD 50 times a second. To stop the music, call STOPMOD. You can continue the music by calling STARTMOD again. If you want to change the module, you will need to call UNLOADMOD, then FLOADMOD or MLOADMOD and SETMOD again. There's also a function called DETECTSND which looks for environment variables to determine the sound device to use. Here's a detailed description of those functions. FLOADMOD Function: Load a MOD in memory from a file. Input: A far pointer on the file name, finished by a nul character. Output: An error code different from 0 if an error has occured. Remark: This function takes itself the memory needed for the module. Each sample use 764 bytes more than in the file. Each sample can't be bigger than 64Ko and there must be less than 64 pattern. MLOADMOD Function: Load a mod already in memory Input: A far pointer on the module in memory Output: An error code different from 0 if an error has occured. Remark: This function exactly do the same thing that FLOADMOD, except that it doesn't load the module from a file. Notice that the module will be twice in memory, and that you can dispose of the memory previously used in memory by the module. OLOADMOD Function: Load a MOD in memory from a overlay. Input: The starting position of the module in your program file on 32 bits. Output: An error code different from 0 if an error has occured. Remark: This function acts like FLOADMOD and has the same restriction. It uses only the position of the module and search itself the name of the program. UNLOADMOD Function: Free the memory used by the module. Input: Nothing Output: Nothing Remark: This function should be called at the end of the program or before loading another module. SETMOD Function: Define sound device and frequency Input: In pascal order, you must give frequency in hundreds of Hertz on 16 bits, sound device number on 8 bits, port on 16 bits and IRQ on 8 bits. Output: An error code different from 0 if an error has occured. Remark: Number for sound devices are: 0 = no sound 1 = internal speaker 2 = DAC 3 = Sound Blaster 4 = Gravis Ultrasound For the DAC, the port isn't an address, but the number of the port the DAC is on. (1 to 4) If you give 0 as the frequency, Crystal Player uses a default value of 18.6 kHz. Every card doesn't use all parameters. On GUS, modules are played at 44 kHz. The IRQ is only needed for Sound Blaster card. Sound Blaster always use DMA 1 and IRQ less than 7. This is this function that load samples in GUS memory. STARTMOD Function: Start the music Input: Nothing Output: Nothing Remark: This functions disable all interrupts, except timer and keyboard. But since the timer is used by every sound device except Sound Blaster, you would better not use it. Try not to call any function which masks interrupts as it would decrease music quality. MAKEMOD Function: Calculate 1/50 second of music Input: Nothing Output: Nothing Remark: You MUST call this function in the main loop of your program. Before filling the buffer, this function tests if it isn't already full, so you can (and you should) call it more than fifty times a second. If you can't call it for more than 1/50 second, call MAKEMOD several times before. Buffer size is 2 Kb. STOPMOD Function: Stop music Input: Nothing Output: Nothing Remark: This function allow you to definitively stop the music or only pause it and continue it later by calling STARTMOD again. It restore the interrupts in their initial state. There may be some problems with Sound Blaster cards. DETECTSND Function: Detect installed sound device by looking for environment variables. Input: In order,four far pointer on a byte for the sound device number, a word for the port, a byte for IRQ and a byte for DMA. Output: Nothing Remark: If you give different values from 0, this routine won't change them. So you can detect the configuration of a particular sound card. If you give 5 as the sound device number, the routine will take the card with the greater number. If it doesn't find any sound device, it will output 1 (PC speaker). (put SET DAC=p (p=1 to 4) in your autoexec.bat if you use a DAC) CHANGEVOL Function: Set master volume. Input: A byte for the volume (0 to 255). Output: Nothing Remark: Just change the volume for all voices but it's not instantaneous, there is a delay of about 250ms. It depends mainly on the mixing frequency. VI - Frequently Asked Questions │ ─────────────────────────────────┘ How can I use variables from the mod playing routines, to display the current pattern for instance? > In order to keep Crystal Player easy to understand, I've only documented the mod playing functions, and the Turbo Pascal unit only contains those functions. But there are other public symbols and I use them in the mod player. You can look into CRYS26.ASM for the symbols, and in STINTER.ASM to see how to use them. Why the sound isn't as good as other MOD players? > First, to keep Crystal Player fast, I mix sample from the different channels on 8 bits whereas the majority of other players use 16 bits. Moreover, I don't use every sound card at its best. I don't use stereo on Sound Blaster Pro for instance. (but it may change) Finally, the mixing default value is 18.6 kHz. More would be alter the sound on the internal speaker. With a Sound Blaster, you can raise it up to 22 kHz to gain more quality. Why can't I test my program in the Turbo Pascal environment? > To play music on PC, I need to intercept hardware interrupts and do some other tricky things that many program won't accept. Why is the player so slow with EMM386 or QEMM386? > Extended memory managers put the system in virtual 86 mode, the system isn't in real mode anymore, and interrupts last much longer. Since the player uses many of them, those managers slow it. I've tried to add some code to the Turbo Pascal unit, but nothing works anymore. Why? > Every routines playing the module are in the same segment and it has to got a special organization. In particular, the code must start at address 0 of the segment. If you add code, it won't work, but you can add declarations. How can I know that a function went right? > Functions send back 0 and the carry is clear if everything went right. Else, they send back an error code (look in CRYSTAL.INC). Why does the function FLOADMOD or MLOADMOD return an error code with the right file name ? > Probably because the function can't find enough memory to load the samples. Normaly a program takes all the available memory when the DOS load it. To correct this, use the SMALL memory model in a C program, use the $M option in a pascal program or give back all the unused memory with the DOS function 4Ah in a asm program. How can I use a overlay module ? > First,you have to compile and link your program with passing a dummy value to OLOADMOD. You can compress your program now and then you take note of your program's length. You replace the dummy value by the program's length and you compile, link and possibly compress your program again.The program must have the same length than before. Now, you have just to add the module at the end of your program with using, by example, "copy /b program+module". VII - History │ ───────────────┘ As I've already said it in the introduction, I've coded this program like a snowball falling, getting bigger and bigger. Three years ago, I started to write a program which only worked on the internal pc speaker, then I added more and more features. Here's the list of improvements which were made since version 1.3, the first one to have a documentation. Version 1.3 Rewrite of the code (more modular) Changeable mixing frequency Speed up the PC speaker routines (+20%) Correct portamento tone and vibrato Correct picth of the notes Correct use of tempo Best doc Version 1.5 Use Sound Blaster Use MOD with 31 samples Version 1.6 Correct bugs from version 1.5 !! Correct arpeggio Version 1.7 Common recorrect of effects Add portamento+volume slide,vibrato+volume slide,extended tempo,tremolo,play end part of sample,fine portamento,fine volume slide and loop Version 1.8 Add some animation during replay The speaker sound a little better Version 1.9 Add some small details Code a pascal unit and some example in pascal and C Add some options during replay (change pattern...) Speed up the routines (+4%) Version 2.0 Speed up all the routines (+20%) Add a function to load MOD in memory Correct effect E6 Add the following effects: pattern delay,cut note,note delay,rettrig sample Version 2.1 Recorrect portamento tone Add the no sound option Correct a bug with pattern jump Partially correct bug on pause with Sound Blaster Correct effect 9 Version 2.2 Use GUS Correct another bug with Sound Blaster Add function to detect installed sound card Version 2.3 Load and play 8 voices MOD Use 8 octave of Scream Tracker 3 Version 2.4 Use the byte from fine tune. Fixed some bugs. Examples in Turbo Pascal and C were rewritten. Complete rewrite of documentation. Version 2.5 Sound better with GUS Add a master volume Load and play 6 voices MOD Use overlay And in the future... Support for new sound cards. (I need informations on every sound cards, including but not limited to GUS MAX, SB PRO, SB 16, SB AWE, PAS etc.. and a mean to make tests) Total rewrite of code. Support for new module formats. (Informations wanted too!) Support for the last effects not used. Sound mixing on 16 bits. VIII - Thanks │ ───────────────┘ I want to thank these persons who have played and continue to play a part in this program: William Petiot for GUS tests and adjustements. Stéphane Gigandet for numerous SoundBlaster tests and moral support. Tchi Southivong for numerous tests with Gravis UltraSound. Stéphane Scherrer for informations on Sound Blaster. Vincent Negrier for SoundBlaster tests. Francis Gastellu for the name of the player. Mark J.Cox for showing me that mods could be played on PC. Bisounours / Nuage for the translation of this file. VLA for informations on DMA. CASCADA for GUSPLAY. IX - Contact informations │ ────────────────────────────┘ If you want to include my routines in a commercial program, if you have found bugs, if you want some particular improvements, if you need more informations or have any remark, you can contact me by using the following ways: Send Mail to: M. Sébastien Granjoux 17 rue de Paris 92190 Meudon France You can also leave me a message on one of this French BBS (near Paris): Dune BBS +33-1-47-02-25-97 24.0 Bps Deadline BBS +33-1-46-48-67-63 14.4 Bps +33-1-46-44-57-96 28.8 Bps Eden BBS +33-1-34-15-39-67 28.8 Bps +33-1-34-13-95-28 14.4 Bps Or by email. (I'm absolutely not sure that it works!) sebastien.granjoux_barnabo@sparkhq.fdn.org Don't hesitate to contact me, I will always pleased to answer you, and it will give me the feeling that all this work wasn't worth nothing. X - Distribution Sites │ ────────────────────────────┘ Crystal Player latest version will always be availlable at these BBSes, free for download: - France: Dune BBS +33-1-47-02-25-97 24.0 Bps Deadline BBS +33-1-46-48-67-63 14.4 Bps +33-1-46-44-57-96 28.8 Bps Eden BBS +33-1-34-15-39-67 28.8 Bps +33-1-34-13-95-28 14.4 Bps More sites wanted!!! If you are a sysop and want to distribute Crystal Player, call one of those boards. Sébastien Granjoux, 01/11/95