PLEASE NOTE: This manual was written in TeX format and has been reduced to .txt format by a conversion program. The results of this were somewhat less than optimal. I have gone through it by hand and cleaned up what I could, but you may run across something that I missed. Game Music System 1.0 USER MANUAL Introduction _______________________________________________________________________________ If you want to make music on your PC, there are basically five ways you can do it: Use a sample tracker. Sample trackers use digitized instruments which are algorithmically combined on-the-fly to produce music. The quality of the sound produced can be anywhere from very good to abysmal, depending upon which program is used and how much CPU power is being directed towards producing the sound. The advantage of using a sample track er is that it produces music that sounds a lot like real-world music, because the instruments it uses are (usually) digitized versions of real instruments. The disadvantage is that it takes a great deal of CPU power to play a sample module at an acceptable level of sound quality - enough to make most games slow down to a crawl. Use an FM tracker. This kind of program plays music through the frequency modulation generators built into the Adlib and Soundblaster cards. FM modules are much smaller than sample modules, and take a lot less CPU power to play back. Some people don't like FM music because it sounds too "electronic". Others like it, for precisely the same reason. Burn a CD and play it back with a CD drive. This, of course, produces the best sound quality of all and takes no CPU power to speak of. But to the average shareware game author, the cost of burning CDs is prohibitive. Use a MIDI program. Commercial companies like doing this because the MIDI format is general enough to be played back under multiple audio systems. The music can be played back under FM, or sample, or dumped to CD. MIDI wasn't designed for games, however. For non-commercial projects it may be overkill. Because they're so general, MIDI files tend to be quite big. You also have to find drivers to play the music back as FM, sample, or CD-quality. If you can, you end up with the advantages and disadvantages of those individual methods. Use the PC's internal speaker. The PC speaker compares favorably with many household appliances. It has a wider frequency range than the average touch-tone phone, and can be more irritating to listen to than most electric blenders. Unfortunately, the average game player is a little more discriminating than this. Game Music System is the second kind of program _ an FM tracker. It's a tool for the creation of music for (shareware) games and demos. FM music is a reasonable option for many games, and in some situations it may be the only one. GMS has the following advantages when compared to other FM trackers: * Supports Adlib, Soundblaster, and Soundblaster Pro I and II as separate modes. * Compose in 18-channel stereo (when in one of the Soundblaster Pro modes). * Public domain play routine, with full source code. * Open module and instrument formats, fully documented. * A sane user interface. It is my goal to make GMS the best and most full-featured FM tracker available for the PC. If you've never used a tracker before, you should find Appendices E and F helpful. They describe how FM instruments work and how music is composed using the tracker system. The main chapters of this manual assume that you have at least a basic understanding of these concepts. TABLE OF CONTENTS _______________________________________________________________________________ 1. Setting Up GMS:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::1 2. The GMS Editing Environment::::::::::::::::::::::::::::::::::::::::::::::2 3. The Track Display::::::::::::::::::::::::::::::::::::::::::::::::::::::::::3 4. The Status Bar:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 5. The FILE Menu:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::6 6. The PLAY Menu::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::7 7. The SONG Menu::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::9 8. The BLOCK Menu:::::::::::::::::::::::::::::::::::::::::::::::::::::::::11 9. The INSTRUMENT Menu :::::::::::::::::::::::::::::::::::::::::::::::::14 10. The MISC Menu ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::17 11. Effect Commands :::::::::::::::::::::::::::::::::::::::::::::::::::::::::19 12. Keyboard Shortcuts:::::::::::::::::::::::::::::::::::::::::::::::::::::::21 13. Some Questions And Their Answers:::::::::::::::::::::::::::::::::::::::22 14. Registration:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::23 15. Legal Stuff::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::24 16. Acknowledgements::::::::::::::::::::::::::::::::::::::::::::::::::::::::25 APPENDICES A. The GMS Module Format::::::::::::::::::::::::::::::::::::::::::::::::::27 B. The GMI Instrument Format:::::::::::::::::::::::::::::::::::::::::::::::30 C. Playing GMS Modules: Programmer Documentation::::::::::::::::::::::::31 D. External Formats :::::::::::::::::::::::::::::::::::::::::::::::::::::::::36 E. How Synthetic Instruments Work:::::::::::::::::::::::::::::::::::::::::::37 F. An Introduction To Tracker Composition :::::::::::::::::::::::::::::::::::39 1. Setting Up GMS _______________________________________________________________________________ To use GMS, you'll need the following: * A 286 or better computer running MS-DOS. * An Adlib, Soundblaster series, or 100% compatible soundcard. * A mouse (this is optional, but makes editing much easier). Upon startup, GMS looks for a configuration file called "GMS.CFG" in the current directory. (This file can be created with the Save Configuration gadget in the MISC menu.) If the file doesn't exist, GMS uses its internal defaults. Therefore, if you've created a configuration file somewhere you have to cd to that directory before running GMS. Other than that, GMS has no particular directory structure requirements and can be placed anywhere on your hard disk you wish. Be sure to take a look at the file ERRATA.TXT. It describes any errors in the program or documentation that were discovered after this manual was printed. 1 2. The GMS Editing Environment _______________________________________________________________________________ The GMS screen is composed of four major parts: The gadget window, the menu selector window, the status bar, and the track display. The gadget window contains the gadgets that help you edit and play the song. The gadgets that appear here can be used to cut and paste blocks, change the tempo, alter the pattern list, and more. The most important functions have keyboard equivalents. (See the Keyboard Shortcuts chapter for more information.) The menu selector window controls which menu of gadgets appears in the gadget window. For example, when FILE is selected, only gadgets relating to file operations will appear in the gadget window. Each menu has its own chapter in this manual. The status bar shows important information about the current song, and reports the results of some commands. The status bar is covered in Chapter 4. The track display is where the "hands on" editing of the song takes place. When the track display is selected you can move around within the current block and add notes or effects. The track display is described further in Chapter 3. GMS has two "metakeys" which can be used to move around the screen. The TAB key moves the cursor between the track display, the menu selector window, and the gadget window (the status bar cannot be selected). The back prime key ( ` ) moves the cursor from one gadget to another when in the gadget window, and from one menu to another when in the menu selector window (the back prime key has no effect when the cursor is in the track display window). You can also use a mouse, if your computer has one (this makes things MUCH easier). The mouse is disabled by default. To enable it, move the cursor to the MISC window, select the Use Mouse option, and hit RETURN. There are four basic kinds of gadgets that can appear in the gadget window: BUTTON GADGETS perform a one-shot operation, such as "copy track". To activate them, select them with a metakey and press RETURN or click on them with the mouse. TOGGLE GADGETS can take on a small range of values (usually "yes" or "no"). To change the value, select them with a metakey and press RETURN or click on them with the mouse. NUMERIC GADGETS can take on a large range of values. (For example, the Block Length gadget can hold a number from 1 to 256.) To change the value, select the gadget and modify the displayed number, then press RETURN to lock it in. (If you don't press return, the gadget will revert to the old value when you unselect it.) Clicking on the gadget with the mouse will select it and move the cursor to the place you clicked at. ALPHANUMERIC GADGETS are like numeric gadgets, but can hold letters as well as numbers. (The Filename gadget is an example of this kind of gadget.) There are a few gadgets which don't fit this mold, and their operation is described when they are introduced. You can usually use the cursor keys to move between gadgets, but when some gadgets are selected the cursor keys do other things. (In numeric gadgets, for example, the left/right cursor keys move the cursor around within the gadget.) 2 3. The Track Display _______________________________________________________________________________ The track display is where notes and effects are added to (or removed from) the song. The track display can show one block at a time. To move about within the block, use the cursor keys. The cursor up/down keys move the cursor up or down one line. The cursor left/right keys move the cursor from one track element to another, or to the next track over. In the middle of a typical editing session, the track display might look something like this: Ln# <03> <04> <05> <06> <07> <08> <09> <10> 035 --- 0000--- 0000 --- 0137 --- 0000 --- 0000 --- 0481+--- 0000--- 0000 036 --- 0000--- 0000 --- 0137 --- 0000 --- 0000 --- 0481+--- 0000--- 0000 037 --- 0000--- 0000 C#2 12BA --- 0000 --- 0000 F-4 0482+--- 0000OFF 0000 038 --- 0000--- 0000 --- 02B9 --- 0000 --- 0000 --- 0482+--- 0000--- 0000 039 --- 0000--- 0000 --- 02BA --- 0000 --- 0000 --- 0482+--- 0000--- 0000 The numbers along the left side of the track display are line numbers. The ones along the top, surrounded by angle brackets, are track numbers. If the Sound System gadget in the SONG menu is set to one of the Soundblaster Pro modes, a vertical bar will appear among the track numbers. All tracks to the left of the bar are on the stereo left, and all tracks to the right of it are on the stereo right. Each line of each track can contain a note, an instrument number, and an unlimited number of effect commands. On line 37 of the above example, at least three of the tracks (5, 8, and 10) are being used. The remaining visible ones are empty. (In this example we can't see what's in tracks 1 and 2, if anything, or if any tracks beyond 10 are being used.) Track 5's note position contains C#2, which means C sharp in octave 2. The instrument position contains 1, which means that instrument number 1 will be used to play the C sharp. The effect number is 2 (the slide down effect), and the effect data byte is BA (which will produce a rapid decrease in frequency). Track 8's note position contains F-4, which is an F in octave 4. Unlike track 5, no instrument has been specified. When GMS processes this track, it will change the track's frequency to F-4, but will not replay the instrument. In other words, the instrument's ADSR will not be reset. The reverse (specifying an instrument, but not a note) is also allowed, and will cause the instrument to be replayed without resetting the track's frequency. Track 8 has an effect number of 4 and a data byte of 82. Because effect number 4 is vibrato, the 82 will give the vibrato a speed of 8 (moderate) and a range of 2 (low, but usually desirable). Notice the plus sign to the right of track 8. In GMS, a note can have an unlimited number of effect commands associated with it. But due to the limitations of the display system, only one command is visible at a time. The presence of the plus sign means that the note has at least one hidden non-zero effect. Pressing the RETURN key while the cursor is over a track will cycle through all of the note's effect commands. Track 10 has nothing but a key-off in it. This will make the track's instrument (if one is playing) enter its decay phase. Changing an instrument, effect number, or effect data byte is simple; move the cursor to the appropriate place and press a number or letter key. Changing the note, however, is a little less straightforward. When the cursor is over the note slot, GMS sees the PC keyboard in a way that resembles an actual piano keyboard. Q through P and Z through M are white keys. 2 through 0 and S through J are black keys. The note that GMS puts into the note position depends upon which key you press. The octave that GMS puts next to the note depends both on which key you press and what the current edit octave is. (The current edit octave is shown in the status bar and can be changed with the left/right b racket keys.) If a key between Q and U is pressed, the current edit octave will be used as the note's octave. Pressing a key between I and P will use the current edit octave plus one. Pressing a key between Z and M will used the current edit octave minus one. For example, if the current edit octave is 5, pressing the 3 key will result in GMS placing down D#5, pressing N will result in A-4, and pressing I will result in C-6. No note can have an octave higher than eight (or lower than one). 3 Chapter 3: The Track Display Pressing the slash ("/") key while the cursor is over the note slot will put a key-off into it. Pressing the BACKSPACE key while the cursor is over a note slot will erase whatever is already there. A GMS module can have up to 35 different instruments. To play a note with an instrument higher than 9, place a letter from A to Z in the instrument slot. "A" plays the note with instrument 10 and "Z" plays it with instrument 35. 4 4. The Status Bar _______________________________________________________________________________ The status bar is always visible and shows important information about the song. In the middle of a typical editing session, the status bar might look like this: Sequence: 02/17 Block: 04/05 Instrument: 00/03 Edit Octave: 4 Active tracks: 1:2:3_4:5:6:7:8:9:0:1:2 The top line of the status bar shows the current and highest line in the play sequence, the currently- selected and highest block, the currently-selected and highest instrument, and the current edit octave. The bottom line of the status bar usually shows a list of which tracks are active. (It is sometimes used to temporarily display messages.) Each track in the song has a number in the active-track list, but only the least significant digit is shown. For example, the song in the above example has 12 tracks - the 0, 1, and 2 at the right-hand side of the active-track list represent tracks 10, 11, and 12, respectively. Any track which is inactive will have its number dimmed out. The active/inactive status of tracks 1-10 can be toggled by pressing the 1 through 0 keys at any time when those keys don't do something else. For example, pressing the 4 key when a button gadget is selected will toggle the status of track 4, but pressing it when a numeric gadget is selected will simply enter a 4 into the numeric gadget. The status of tracks 11-18 can be toggled at any time by holding down the ALT key and pressing the 1 through 8 keys. Any track which is inactive is not processed by the music playing routine. No notes on that track will be played, and none of the effect commands will do anything (including "general" effects like tempo changes or position jumps). Being able to turn off tracks in this fashion is simply an editing convenience, so active track information is not saved with the song. If the Sound System gadget in the SONG menu is set to one of the Soundblaster Pro modes, a vertical bar will appear in the active track list. All tracks to the left of the bar are on the stereo left, and those to the right of it are on the stereo right. 5 5. The FILE Menu _______________________________________________________________________________ The FILE menu's gadgets are used to load and save songs and instruments. Filename The contents of this gadget are used by the Load/Save Song/Instrument gadgets, described below. The Filename gadget can hold up to 50 characters and can contain a complete pathname, including drive specification. Select Filename From Directory Selecting this gadget brings up a window containing the names of all the files and subdirectories in the current directory. Use the up/down cursor keys to scroll through the list, and press RETURN to select a filename. Selecting a subdirectory will bring up a list of all the filenames and subdirectories it contains. This gadget can be used to generate a pathname of up to 255 characters, but only the first 50 characters will be visible in the Filename gadget. Load Song Save Song Load Instrument Save Instrument All four of these gadgets use the filename specified in the Filename gadget. The Load Song gadget loads the specified song. GMS is able to load GMS 1.0 and RAD 1.0 modules. Which type of module GMS believes the file to be can be controlled with the Song Loading gadget in the MISC menu. The Save Song gadget saves the song in memory as a GMS module. It is suggested that you use the extension ".GMS" for GMS modules. The Load Instrument gadget loads a GMS instrument into the currently selected instrument slot, replacing whatever instrument is already there. The Save Instrument gadget saves the currently selected instrument in GMI instrument format. It is suggested that you use the extension ".GMI" for GMS instruments. 6 6. The PLAY Menu _______________________________________________________________________________ The PLAY menu's gadgets control the overall playing of the song. Play Sequence The Play Sequence gadget controls the order in which the song's blocks are played. When this gadget is selected, the cursor up/down keys move the cursor up or down within the pattern list. The cursor left/right keys move the cursor between the two digits in each pattern number. The numeric keys change the number of the digit that the cursor is on top of. The INSERT key adds a new pattern number at the current cursor position, the DELETE key deletes the pattern number under the cursor, and the BACKSPACE key deletes the pattern number on the line above the cursor. If the play sequence is changed while the song is being played, the changes will not take effect until the play routine finishes playing the current block. While the song is playing, the music routine uses the play sequence's cursor to show which line of the sequence is currently being played. If you move the cursor up or down in the play sequence, the song will "jump" to the new position when the play routine finishes playing the current block. Tempo Secondary Tempo Both of these gadgets control the speed at which the song plays. The setting of the Tempo gadget determines how many times a second the music playing routine is called. The higher the number in this gadget, the more rapidly the song will play. (The setting of this gadget is often referred to as the primary tempo.) The number in the Secondary Tempo gadget is how many times the music playing routine must be called before it advances a line in the song. The lower the number in this gadget, the more rapidly the song will play. A subtle but important effect of changing the secondary tempo is that it will make most note effects sound different. The reason for this is that effect commands are processed every time the music playing routine is called, whether or not it advances a line. To illustrate this, imagine that you've attached the effect 102 to a note. This is a slide up with a data byte of 2. If the current secondary tempo is 6, this effect will be processed 6 times, for a total frequency increase of 12. But if the secondary tempo is 2, the effect will be processed only 2 times, increasing the track's frequency by 4. In practical terms, this means that if you change the secondary tempo you'll usually have to go through the entire song and rethink any effects you used. Failing to do this will make the frequency slides sound mangled and the volume slides go too fast or too slow. This is a major hassle, so unless you have a good reason to change the secondary tempo I recommend you leave it at the default value of 6 and use the primary tempo to control the song's speed. Play Song This plays the song, starting from the first line of the play sequence. Continue Song This plays the song, starting from the current play sequence cursor position and track display cursor line. 7 Chapter 6: The PLAY Menu Play Block This plays the block that is shown in the track display. The play routine will play the block repeatedly until it is stopped or another playing gadget is used. Continue Block This plays the block shown in the track display, starting from the line that the track display cursor is on. Stop Playing This turns off the music playing routine and silences all channels. 8 7. The SONG Menu _______________________________________________________________________________ The SONG menu is used to set parameters that are specific to the particular song in memory. Sound System This gadget toggles between the four basic sound card types that GMS supports: Adlib, Soundblaster, Soundblaster Pro I, and Soundblaster Pro II. The Adlib sound card is based around the Yamaha OPL2 chip, which is capable of 9-channel monaural sound. When GMS is in this mode, only tracks 1-9 are played. Any tracks after 9 (if they exist) are ignored. The base address of the sound card is assumed to be 388 hex. The Soundblaster sound card is basically an Adlib card with the ability to play digitized sound samples. GMS does not (yet) support sampled sound instruments, so the only difference between this mode and Adlib is that the Soundblaster Base Address in the MISC menu is used instead of 388 hex. The Soundblaster Pro I sound card produces stereo sound by using two OPL2 chips - one connected to the stereo left and the other connected to the stereo right. Up to 18 notes can be played at once, but no more than 9 can be on either side. When GMS is in this mode, it uses the setting of the Stereo Left gadget to determine which tracks should be on which side. If this would cause more than 9 tracks to be on a side, the excess tracks are ignored. The Soundblaster Pro II sound card is based around the Yamaha OPL3 chip. This chip has several advantages over its predecessor. First, the chip has 18 channels, each of which can be set to be on the right, left, or both on a channel-by-channel basis. When in this mode, the Stereo Left gadget determines which tracks are on which side. Second, each of the chip's operators has 8 waveforms - 4 more than the OPL2 chip. When Sound System is set to this mode, the Waveform gadgets in the INST menu will cycle through the extra OPL3 waveforms as well as the OPL2 ones. Finally, the OPL3 chip can be accessed much more quickly by the play routine than the OPL2 chip can. See Appendix C for more information on this. Tracks This gadget is used to set the number of tracks your song uses. All blocks in the song have the same number of tracks. When this gadget's value is changed, tracks are added to or deleted from all blocks to conform with the new setting. Stereo Left When Sound System is set to Soundblaster Pro I or II, this gadget controls which tracks are on the stereo left. All other tracks are on the stereo right. For example, if there are 8 tracks in the song and Stereo Left is set to 3, tracks 1-3 will be heard through the left speaker and tracks 4-8 will be heard through the right. If Sound System is set to Adlib or Soundblaster, the value of this gadget is ignored. Song Name This gadget allows you to give your song a better name than the MS-DOS file system permits. The contents of the gadget are saved as part of your song. Info Page Selecting this gadget makes a window with a cursor in it pop up. The cursor keys move the cursor around. 9 Chapter 7: The SONG Menu Text can be entered into this window and edited using the INSERT, DELETE, and BACKSPACE keys. Anything you write in this window will be saved with your song. Pressing RETURN closes the window and saves its contents. Deep Vibrato This gadget affects the Apply Vibrato gadgets found in the INST menu. When this gadget is set to YES the effect of the Apply Vibrato gadgets, if they are used, will be doubled. Deep Amplitude Modulation The setting of this gadget affects the Apply Amplitude Modulation gadgets in the INST menu. If this gadget is set to YES the effect of the Apply Amplitude Modulation gadgets, if they are used, will be magnified by a factor of approximately 5. 10 8. The BLOCK Menu _______________________________________________________________________________ The BLOCK menu contains gadgets that operate on blocks and tracks. Current Block This gadget cannot be selected. It shows the number of the block which is v isible in the track display. Next Block This makes the next highest numbered block appear in the track display, unless the last block in the song is already being displayed. Previous Block This makes the next lowest numbered block appear in the track display, unless the first block in the song (block zero) is already being displayed. Block Length This gadget changes the number of lines in the current block. Lines will be added to or removed from the end of the current block to make it conform to the new setting. Add Block This gadget creates a new block and adds it to the song. The length of the new block is determined by the contents of the Default Block Lines gadget in the MISC menu. The currently selected block and all higher-numbered blocks will have their block numbers increased by one to make room for the newly-added block. The play sequence will be automatically adjusted to reflect the renumbering. Delete Block This gadget deletes the currently selected block. All higher-numbered blocks will have their numbers decreased by one to fill the empty slot. The play sequence is automatically adjusted to reflect the renumbering. Cut Block Copy Block Paste Block Swap Block Cut Track Copy Track Paste Track Swap Track All of these gadgets use an invisible region of buffer memory referred to as the clipboard. The clipboard can hold, at most, one block's worth of data. Any gadget which writes to the clipboard destroys the old data as part of the writing process. Cut Block copies the currently selected block to the clipboard, then "blanks out" the block, removing 11 Chapter 8: The BLOCK Menu all note, instrument, and effect data. Copy Block copies the currently selected block to the clipboard without blanking it out. Paste Block replaces the current block with the contents of the clipboard. Swap Block swaps the contents of the current block with the contents of the clipboard. Cut Track, Copy Track, Paste Track, and Swap Track perform the same functions as the above gadgets, but they operate on one track at a time instead of the entire block. The position of the track display's cursor determines which track is affected. Note that the block-oriented and track-oriented gadgets both use the same clipboard. Mixing track and block operations is likely to have unpredictable effects. Make Normal Slide Make Portamento Slide These two gadgets make GMS create frequency slides. GMS will do all the necessary calculations to make the slide start and end where you want it to. Make Normal Slide makes slides that use the 1 (slide up) and 2 (slide down) commands. Make Portamento Slide makes slides that use the 3 (portamento) command. To use these gadgets, you must first use the track display to lay down a start note at some place on the track before where you want the slide to begin, and lay down an end note on the line right after where you want the slide to end. Then, move the cursor to the line where you want the slide to start and select the appropriate gadget. For example: C-4 5000 C-4 5000 C-4 5000 --- 0000 --- 0000 --- 0000 --- 0000 --- 015E F#4 535E --- 0000 --- 015F --- 035F F#4 5000 F#4 5000 --- 0000 Before slide command After Make Normal Slide After Make Port. Slide In the above example, the cursor is on the third line prior to using the slide-making gadgets. Make Normal Slide will delete any existing 1 or 2 effects between the start and end lines before it lays down the new ones, and Make Portamento Slide will do the same with any existing 3 effects. The start and end notes can be removed once the slide has been created (except in the case of a portamento slide, where the end note must be present in order to indicate the portamento destination). In practice, using the 1 and 2 commands seems to produce better-sounding slides (though the difference is very slight). This is why I refer to 1- and 2-based slides as "normal" slides. Note: the total frequency change resulting from a 1, 2, or 3 command depends upon both the value of the data byte and the current secondary tempo. GMS takes the current secondary tempo into account when it calculates what value to place in the data bytes of the slide commands. Therefore, you should make sure that the secondary tempo is set to whatever value is normal for your song (or that part of your song) before using the slide gadgets. Make Volume Slide This gadget is very similar to the frequency-slide-making gadgets. It creates volume slides based around the C (volume change) command. To use this gadget, set the start volume on the line where you want the slide to start, and the end volume on the line where you want the slide to end. Then move the cursor to any line between the start and end lines and use the Make Volume Slide gadget. For example: C-4 3C10 C-4 3C10 --- 0000 --- 0000 12 Chapter 8: The BLOCK Menu --- 0000 --- 0C18 --- 0000 --- 0C20 F#4 3C29 F#4 3C29 Before slide command After Make Volume Slide In the above example, the cursor is on the third line prior to using the volume slide gadget. C-command-based volume slides are most useful when the slide is spread over a large number of lines (6 or more is a good rule of thumb). If the number of lines involved is small, the D command (volume slide) usually produces a smoother and better-sounding volume change. 13 9. The INST Menu _______________________________________________________________________________ The INST menu's gadgets are used to create and modify the current song's instruments. Instrument # This gadget cannot be selected. It shows the number of the currently selected instrument. Name You can use this gadget to give the instruments you create a name of up to 36 characters long. The name is included with the instrument when it is saved. Next This gadget selects the next highest numbered instrument in the song, unless the highest-numbered instrument is already selected. Previous This gadget selects the next lowest numbered instrument, unless the lowest- numbered instrument (instrument 1) is already selected. Add Creates a new instrument. The instrument is placed into the instrument list right before the currently selected instrument. The currently selected instrument and all higher-numbered instruments are renumbered to open up a slot for the new instrument. All instrument numbers in all blocks are automatically adjusted to make the renumbering transparent. Delete Deletes the currently selected instrument. All higher-numbered instruments are renumbered to fill the empty slot. All instrument numbers in all blocks are automatically adjusted to make the renumbering transparent. In this gadget window are two table gadgets. This is a special kind of gadget that can contain other gadgets. The table can be scrolled through by selecting it and using the cursor up/down keys. The gadgets in the table on the left affect operator 1. The gadgets in the table on the right are for operator 2. The following gadgets are in both tables: Freq Mult This gadget sets the modulator frequency multiple of the operator. When set to "normal", the operator produces sound at the frequency specified when the note is played. The other settings cause the operator's frequency to be different. 14 Chapter 9: The INST Menu Keyboard Scaling Rate If this gadget is set to YES, the note's frequency affects the speed with which the operator passes through its ADSR envelope. The higher the frequency, the more rapidly the operator moves through the ADSR phases. Hold At Sustain Level This gadget affects what happens when the operator enters the sustain phase. If it is set to YES, the operator's volume stays at the sustain level until a key off occurs (in other words, it behaves normally). If set to NO, the sustain phase is skipped and the release phase begins immediately. Apply Vibrato If this gadget is set to YES, the operator's frequency will "waver". The depth of the vibrato is controlled by the Deep Vibrato gadget in the Song menu. If that gadget is set to YES, the depth will be 14 cents. Otherwise, it will be 7 cents. Apply Amplitude Modulation If this gadget is set to YES, the operator's volume will "waver". The amplitude modulation's depth is controlled by the Deep Amplitude Modulation gadget in the Song menu. If that gadget is set to YES, the depth will be 4.8 decibels. If not, it will be 1 decibel. Volume This gadget controls the operator's volume (technically speaking, its output level). The volume range is from 0 to 63, with 0 being silent and 63 being maximum volume. Scaling Level When this gadget is set to None, the operator's frequency will have no direct effect upon its volume. When on one of the other settings, a higher frequency will make the operator produce sound at a lower volume. The particular setting chosen determines how rapidly the volume decreases as frequency increases. Attack This gadget sets the speed of the attack phase of the ADSR envelope, from 0 to 15. The higher the setting, the more rapidly the operator will reach its maximum volume. Decay This gadget controls the speed of the decay phase of the ADSR envelope, from 0 to 15. The higher the setting, the faster the operator's volume will fall to the sustain level. Sustain This gadget sets the sustain level, from 0 to 15. 0 is silence, 15 is maximum volume, and all of the numbers in between represent fractions of the maximum volume. 15 Chapter 9: The INST Menu Release This gadget controls the speed of the release phase of the ADSR envelope, from 0 to 15. The higher the setting, the more rapidly the operator's volume will fall from the sustain level to silence. Waveform This gadget sets the operator's waveform. When in Adlib, Soundblaster, or Soundblaster Pro I mode, 4 waveforms are available. When in Soundblaster Pro II mode, 8 waveforms are available. These gadgets are in operator 1's table only: Feedback Strength If the value in this gadget is not zero, operator 1 will modulate itself with its own output. The higher the value, the more modulation will occur. The maximum feedback strength is 7. Additive Synthesis If this gadget is set to YES, the instrument will use additive synthesis. Otherwise, it will use frequency modulation. Filename Select File From Dir Load Save These gadgets are for loading and saving instruments. They function identically to their counterparts under the FILE menu. 16 10. The MISC Menu _______________________________________________________________________________ The MISC menu contains gadgets whose settings are not dependent upon the particular song that is loaded. Keep Sound System When Loading When a song is saved, GMS saves the Sound System setting from the SONG menu along with it. If this gadget is set to YES, that setting will be ignored when a song is loaded, and Sound System will remain set to whatever it was before the load occurred. If this gadget is set to NO, Sound System will be set to whatever was saved with the song. This option exists so that people with an older sound card (such as an Adlib) won't have to change the sound system every time they load a song written for a newer card. Soundblaster Base Address This gadget allows you to set the base address of your Soundblaster card, in hexadecimal. This base address is used when Sound System in the SONG menu is set to Soundblaster, Soundblaster Pro I, or Soundblaster Pro II. (When Sound System is set to Adlib, a base address of 388 hex is always used.) Soundblaster cards are normally at 220 hex, but this is user-configurable. Other commonly-used base addresses are 210 and 240. If you don't know what the base address of your card is, consult the documentation and/or configuration utilities that came with it. Song Loading This gadget affects what happens when you try to load a song. When the gadget is set to Autodetect, GMS will try to determine what kind of module the song is, and call the appropriate loader routine if it can make this determination. When the gadget is set to Assume type, GMS will bypass the identification phase and try to load the module as whatever you say it is. (The loader routine still does its own double-checking, though, and may refuse to load the module.) The two module formats that GMS currently supports (GMS and RAD) are both easily identifiable, so this gadget has little use at the moment. It's mostly intended for the future. Instrument Loading This gadget affects what happens when you try to load an instrument. When the gadget is set to Autodetect, GMS will try to figure out what kind of instrument you're attempting to load, and call the correct loader routine if it can. When the gadget is set to Assume type, GMS will skip the identification phase and try to load the instrument as whatever you say it is. (The loader routine does its own double-checking, though, and may reject the instrument.) This gadget is intended for the future. At present, GMS supports only one instrument type (its own). Default Block Lines This gadget affects the size of blocks created with the New Block gadget in the BLOCK menu. All blocks that are created will have the number of lines specified in this gadget. 17 Chapter 10: The MISC Menu Use Mouse This gadget can be used to turn on and off GMS's mouse support. When it is set to YES, the mouse can be used as an input device. When NO, the mouse cursor will be turned off. Show Interrupt This gadget lets you see just how long the interrupt routine that plays the music is actually taking. When set to YES, the play routine will turn the screen's background red just after it starts up and back to black right before it finishes. This will manifest itself as a red bar moving up or down the screen. The bar can be most easily seen when the tempo is set to about 130 (the exact value varies from one PC system to another). Notice that the interrupt routine executes much more quickly when Sound System in the SONG menu is set to Soundblaster Pro II than when it is set to anything else. This is due to differences between the OPL2 and OPL3 chips and is explained in more detail in Appendix C. Save Configuration This gadget saves the contents of certain gadgets to a file called "GMS.CFG" in the current directory. When GMS starts up, it automatically reads this file in (if it exists) and sets those gadgets up appropriately. The following gadgets are saved to the configuration file: Soundblaster Base Ad dress, Sound System, Keep Sound System When Loading, Song Loading, Instrument Loading, Default Block Lines, Use Mouse, and Show Interrupt. 18 11. Effect Commands _______________________________________________________________________________ All commands consist of a one-digit effect number and a two-digit effect byte. The meaning of the effect byte depends upon the particular effect. This chapter lists all of the commands that can be used in GMS modules. If an effect number not listed here is used, the play routine will simply ignore it. Slide Up (1) This effect raises the track's frequency by the amount specified in the data byte. The actual audible effect of this depends upon the track's current frequency and the amount of the slide. If you want to make a slide from one note to another, the recommended method is to use the Make Normal Slide gadget in the BLOCK menu. Making slides "manually" is rather tedious and mostly done when making sound effects. Slide Down (2) This effect lowers the track's frequency by the amount specified in the data byte. Portamento Slide (3) A portamento slide is similar to the basic slide up (1) and slide down (2) commands, but puts more of the burden on the play routine. To make a portamento slide, you must specify a destination. You do this by placing a note on the same line as the portamento slide command. For example: E-5 2000 --- 0000 D-4 233A --- 033A --- 033A Portamento slide from E-5 to D-4 This note is not played; instead, the play routine remembers the note as the portamento destination. Thereafter, whenever the portamento slide command is used, the track's current frequency will be shifted towards the portamento destination by the amount specified in the data byte. Th is is a lot like the other slide commands, except that the play routine decides on-the-fly whether a 1 or a 2 slide should be used. Once the track's current frequency reaches the portamento destination, it will "lock" there. Any further portamento commands will have no effect until the track's frequency is changed by some other method or the portamento destination is changed. Vibrato (4) The vibrato effect makes a track's frequency "waver" back and forth. The first digit of the effect byte is the vibrato speed. The second is its depth. Change Secondary Tempo (9) This effect changes the song's current secondary tempo. The change is permanent unless altered by another 9 command. The entire data byte can be used to specify the new secondary tempo, but in practice the second digit is more than enough. 19 Chapter 11: Effect Commands Position Jump (B) This changes the "flow of control" within the song and makes the music routine start playing at a different point in the play sequence. The position jump will occur as soon as the current line is done playing; any remaining lines in the current block will be ignored. The data byte indicates which position in the play sequence to jump to. If the data byte is zero it means the first position in the list, if the data byte is five it means the sixth position in the list, and so on. The position jump command is usually used to make a song that has a part th at only plays once and another part that repeats over and over. If you want the entire song to repeat there's usually no need to use this command, because the play routine will start the song over anyways after it plays the last block in the play sequence. Volume Change (C) This command sets the volume of the track to the number contained in the data byte. Legal values are from 0 (silent) to 63 (full volume). If a number higher than 63 is given, the track's volume will be set to 63. Volume Slide (D) This command smoothly slides the track's volume up or down. If the data byte's second digit is zero, the track's volume will be increased by the value of the first digit. If the data byte's first digit is zero, the track's volume will be decreased by the value of the second digit. Only one of the data byte's digits should be nonzero. If both are nonzero, the effects are unpredictable. Miscellaneous Command (F) What the F command does depends upon the value of its data byte. Block End (F00) The Block End command means that the music routine should treat the current line as if it was the last line in the block. As soon as the current line is done playing, the music routine will go to the next block in the play sequence. Any lines in the block after the Block End command will be ignored. This command exists mostly for compatibility with other tracker programs. If you want a block to end sooner than normal it's usually best just to change its length in the BLOCK menu's Block Length gadget. Change Tempo (F01-FFE) This command changes the song's primary tempo to the value of the data byte. The change is permanent unless overriden by a later tempo change. Stop Playing (FFF) This command makes the song stop playing. 20 12. Keyboard Shortcuts _______________________________________________________________________________ This chapter lists all of the keys and key combinations that have special meaning to GMS. Most of the entries below are shortcuts for functions that can be accessed through the gadgets, but there are a few that are functions in their own right. TAB - This key causes the cursor to move between the gadget window, gadget window selector, and track display. ` - This key moves the cursor from one gadget or window selector to another. It has no effect when the cursor is in the track display. ALT-L - Makes GMS redraw the entire screen. Useful if part of the display has been corrupted by the mouse cursor. [ - Decreases the edit octave by one, if the track display is selected. ] - Increases the edit octave by one, if the track display is selected. ALT-[ - Moves the cursor to the previous line in the Play Sequence gadget in the PLAY menu. ALT-] - Moves the cursor to the next line in the Play Sequence gadget in the PLAY menu. ALT-semicolon - Shortcut for Previous Block in the BLOCK menu. ALT-apostrophe - Shortcut for Next Block in the BLOCK menu. ALT-period - Shortcut for Previous in the INST menu. ALT-slash - Shortcut for Next in the INST menu. ALT-P - Shortcut for Play Song in the PLAY menu. ALT-C - Shortcut for Continue Song in the PLAY menu. ALT-B - Shortcut for Play Block in the PLAY menu. ALT-R - Shortcut for Continue Block in the PLAY menu. 1 through 0 - Changes the active status of tracks 1-10. ALT-1 through ALT-8 - Changes the active status of tracks 11-18. F1 - Shortcut for Cut Block in the BLOCK menu. F2 - Shortcut for Copy Block in the BLOCK menu. F3 - Shortcut for Paste Block in the BLOCK menu. F4 - Shortcut for Swap Block in the BLOCK menu. F5 - Shortcut for Cut Track in the BLOCK menu. F6 - Shortcut for Copy Track in the BLOCK menu. F7 - Shortcut for Paste Track in the BLOCK menu. F8 - Shortcut for Swap Track in the BLOCK menu. F12 - Exit program. Quits out of GMS and returns to the MS-DOS prompt. There is no gadget equivalent to this key. 21 13. Some Questions And Their Answers _______________________________________________________________________________ When I try to play a song in GMS the program seems to be working but no sound comes out. What's wrong? Some programs leave the sound card in a strange state when they exit. (The OPL3 driver in the Linux operating system does this.) Cycling through all of the Sound System gadget's settings should fix the problem. If it doesn't, try turning the computer off and on again and loading GMS before you load anything else. Does GMS work under Windows (95), OS/2, or Linux DOS emulation? Somewhat to my surprise, it does work under Windows 3.1. (It needs to be run on its own screen, though, or the tempo will be messed up.) I haven't tried it on the other operating systems. 22 14. Registration _______________________________________________________________________________ Game Music System is shareware, try-before-you-buy software. It is the result of hundreds of hours spent designing, coding, and testing. If you find GMS useful to you, please register it. Aside from a feeling of righteousness, registration gives you the following tangible advantages: * A printed copy of the documentation. * A version of the program without the annoying registration window. * Free updates, mailed on the day they are released, until the major version number changes. * A signed letter of thanks. Registration is $30 (in U.S. funds) and should be mailed to: Roland Acton 8001 Bluebird Lane La Palma, CA, 90623 U.S.A. Internet address: malyon@netcom.com 23 15. Legal Stuff _______________________________________________________________________________ The Game Music System player code, consisting of the files globals.h, inst.cpp, inst.h, block.cpp, block.h, song.cpp, song.h, musdrv.cpp, musdrv.h, and player.cpp, is hereby placed in the public domain. The module and instrument formats described in Appendices A and B are also placed in the public domain. You can use or modify these files and formats in any way you want. All other parts of the Game Music System package - including, but not limited to, the editor program and documentation - are copyrighted by Roland Acton. These parts of the package are released as shareware. If you find this program useful, you are legally and morally required to register it as described in Chapter 14. Continuing to use the program without registering it may result in pangs of guilt, loss of hair and/or appetite, and indigestion. (Registration is a decent thing to do.) Companies who wish to distribute Game Music System as part of a shareware collection may do so, provided that the package is distributed in complete and unaltered form. I, Roland Acton, make no warranties of any kind with respect to this program. No guarantees are given that this program will work as described, or even that it will work at all. I am not responsible for loss of data, loss of work, or loss of sleep as the result of using this program. I am to be held blameless in the event of any earthquakes, plane crashes, nuclear wars, or other natural or unnatural disasters that occur as a direct or indirect result of you, me, or someone else making use of this program. In other words, you the user take full responsibility for anything that happens as a result of using this program. 'Nuff said. 24 16. Acknowledgements _______________________________________________________________________________ Any worthwhile enterprise can be successful only as a result of the time and effort invested by a number of people. This chapter tries to give some credit where it is due. The following people contributed (without their knowledge) to the development of Game Music System: Richard Stallman and the FSF development team, for providing the excellent GCC compiler and support tools. Jeffrey Lee for the Soundblaster OPL2 mode documentation. Vladimir Arnost for the Soundblaster OPL3 mode documentation. Linus Torvalds for creating the Linux operating system. Writing an MS-DOS application under Unix is "interesting", to say the least. Joseph Allen for making his "joe" text editor. Much, much better than "vi" or (*choke*) "edit". Donald Knuth for the TeX typesetting system, under which this manual was written. Without the efforts of the above people, this project would have gone nowhere fast. 25 APPENDICES A. The GMS Module Format _______________________________________________________________________________ The following table shows what a GMS 1.0 module looks like when it's stored on disk: _bytes____description_________________________________ 8 magic cookie "GMS-RCAx" (x = module format version) 1-51 song name, null-terminated 14-784 info page lines (14 lines, each null-terminated) 1 deep vibrato/am byte 1 highest track 1 tempo 1 secondary tempo 1 sound system 1 highest stereo left _____1____number_of_instruments_(always__1)___________ 1-31 instrument name, null-terminated 1 operator 1 am_vib byte 1 operator 1 scaling_volume byte 1 operator 1 a_d byte 1 operator 1 s_r byte 1 operator 1 waveform byte 1 operator 2 am_vib byte 1 operator 2 scaling_volume byte 1 operator 2 a_d byte 1 operator 2 s_r byte 1 operator 2 waveform byte _____1____op1mod_feedback_byte________________________ 1 highest play sequence number 1-100 play sequence _____1____highest_block_number________________________ 1 highest line __2-32____track_numbers_______________________________ 0-??? track data The purpose of all the fields is not obvious, so let's take a look at the steps the GMS loader routine needs to go through to load a song. The first thing the loader routine does is to compare the first seven bytes of the file with the string "GMS-RCA". All GMS modules begin with this string. If the module passes this test, the loader reads in the next byte, the module format version. If this byte is zero, the module is a GMS 1.0 song. If it's something else, the loader rejects the module. The loader then reads in the song name and the 14 lines of the info page. Each of the 14 info page lines has 0-55 characters followed by a null terminator. It then reads in the deep vibrato/am byte, the highest track byte (a number from 0 to 17), the tempo and secondary tempo, and the sound system. The sound system byte is the integer cast of the sound_cards enumeration, so adlib = 0, sb = 1, sbpro1 = 2, and sbpro2 = 3. Then it reads in the highest stereo left byte (a number from 0 to 17) and the number of instruments in the song. The next part of the module consists of all of the instruments, one after the other, starting with instrument 1. The loader creates as many instruments as necessary, fills them in with instrument data read from the module file, and adds them to the song. After reading in all instruments, the loader reads in the highest play sequence number (a number from 0 to 99) and the play sequence. The length of the play sequence is equal to the highest play sequence number plus one. For example, if the highest play sequence number is 4, it will be followed by 5 bytes which, taken 27 Appendix A: The GMS Module Format together, are the song's pattern list. Next, the loader reads in the highest block number (a number from 0 to 99). To explain the next part, it's necessary to digress slightly and describe some of what the GMS save routine does when it saves a module. Before it saves any of the blocks, the save routine looks through all of the tracks in all of the blocks in the song. It's looking for two things: first, for any tracks that are completely empty and have no notes or effects on them. Second, for any tracks that are exact duplicates of any other tracks in the song. The save routine uses the results of this search to build up a table that lists all of the unique tracks in the song. It assigns each of those tracks a number, starting with 1. Then it saves all of the unique tracks as part of the module, and attaches a set of tables that describe which tracks are used by which blocks. After the loader routine reads in the highest block number, it expects to find that set of tables right after it _ one table for each block used in the song. For example, if the highest block number is 10, there will be 11 tables. The first number in each table is the highest line number in the block (0 to 255). This is followed by a series of 16-bit numbers - one number for each track in the song. The numbers are stored in big-endian format. This means that each number's high byte appears in the file before its low byte. The numbers are the numbers of the unique tracks identified by the save routine. The number zero means that the track was completely empty. As an example, let's say we're loading in one of the block tables in a song which has 3 tracks. The loader reads in 7 bytes, which (in decimal) are: 63 0 17 0 18 0 0. The first number, 63, is the highest line number in the block. The next number is the unique track number that corresponds to the first track in the block. The unique track number is 17. This track may or may not be used elsewhere in the song; we don't know (and it doesn't matter). The block's second track uses unique track number 18. The third track's number is zero. This means that the third track is completely blank and contains no notes or effects. Because of this, it can be ignored by the play routine. After reading in all of the block tables, the loader reads in the unique tracks. Each track is stored (both on disk and in memory) in a compressed format. Each line of each track can consist of a note byte, an instrument byte, and one or more effect number bytes, each followed by an effect data byte. However, not all of those bytes have to be present. Only the note byte is required to be there. The loader routine reads in the first line's note byte and looks at the lower 7 bits of the byte. It interprets the value according to the following chart: number______interpretation_ 0 no note; blank 1 C, octave 1 2 C sharp, octave 1 3 D, octave 1 4 D sharp, octave 1 5 E, octave 1 6 F, octave 1 7 F sharp, octave 1 8 G, octave 1 9 G sharp, octave 1 10 A, octave 1 11 A sharp, octave 1 12 B, octave 1 13 C, octave 2 14 C sharp, octave 2 : : : : : : 95 A sharp, octave 8 96 B, octave 8 127 key off 28 Appendix A: The GMS Module Format If the note's high bit is clear, it means that the note (if there is one) is all there is on this line; the instrument and effect fields are blank. If, however, it is set, it means that the next byte is the instrument byte. The lower 7 bits of the instrument byte are the instrument number (or zero). If the high bit of the instrument byte is clear, it means that the effect field is blank. But if the high bit is set, there is at least one effect on this line. The lower 7 bits of the effect number byte are the effect number. If the high bit is set, there is another effect number and data byte pair following this one. If not, this is the last effect on this line. The loader routine then moves on to the next byte in the module, which it assumes to be the note byte of the next line. It continues reading in lines until the entire track has been read, and repeats the process for each unique track in the module. Although the number of unique tracks and the length of each unique track are not stored in the module, they can be determined by examining the block tables and "manually" stepping through the tracks. After loading all of the unique tracks, the loader routine sets the track pointers in all of the blocks to point to the correct tracks, then exits. 29 B. The GMI Instrument Format _______________________________________________________________________________ This table shows what a GMS instrument file looks like: bytes_____description___________________________________ 8 magic cookie "GMI-RCAx" (x = instrument format version) 1-31 instrument name, null-terminated 1 operator 1 am_vib byte 1 operator 1 scaling_volume byte 1 operator 1 a_d byte 1 operator 1 s_r byte 1 operator 1 waveform byte 1 operator 2 am_vib byte 1 operator 2 scaling_volume byte 1 operator 2 a_d byte 1 operator 2 s_r byte 1 operator 2 waveform byte 1 op1mod_feedback byte An instrument format version number of zero means that the file is a GMS 1.0 instrument. 30 C. Playing GMS Modules: Programmer Documentation _______________________________________________________________________________ The first step is to integrate the GMS player code into your project. If your project is written in C or C++, add the GMS .cpp files to your project file, makefile, or whatever system your compiler uses. The play routine was written for Borland C++ 3.1. Using it with other compilers may require minor adjustments to be made to the code. Note: the play routine may not work properly when compiled with a protected-mode compiler. The DJGPP protected-mode compiler's documentation warns that interrupt routines need to have their virtual pages locked down and need to provide for interrupt reflection from real to protected mode. The current player code does not do this. I hope to have GMS 1.1 working properly in protected mode. Until then, you're on your own in this area. If your project is written in another language (such as assembly), you'll need to use a C++ compiler to compile the player code into an object file and link it with your own code. The exact method for call- ing the GMS routines will vary depending upon the particular compiler you use. Consult your compiler's documentation for more information. The Borland documentation warns that programs that use an interrupt routine (as GMS does) need to be compiled with stack overrun checking turned off and register variables disabled. The former is definitely necessary; the latter may or may not be. (I suspect they just said "disable them" because they didn't want to go into a long discussion about when they need to be disabled and when they don't). You should be able to turn on all other optimizations except for "assume no pointer aliasing" _ certain parts of the play routine DO have aliased pointers. Once the code is integrated into your project, the following GMS functions will become available to you: Prototype: void reset_card() Class: music_driver Description: This function completely resets the user's sound card. It examines the soundsystem variable in the song class to determine what needs to be done to reset the card. If the setting of the sound system is wrong, the user's sound card may not be correctly reset. Prototype: void set_up_card() Class: music_driver Description: This function initializes the user's sound card and prepares it for music playback. re- set_card() should be called before calling this routine. Prototype: unsigned int load_gms(FILE *module) Class: music_driver Description: This function loads a GMS module into memory and prepares it for playing. Only one GMS module can be loaded at a time; the old one, if any, is discarded when loading begins. The module parameter is a pointer to a FILE structure, returned by a prior call to fopen(). The return value indicates the success of the loading operation. If nonzero, the loading was successful. If zero, the loading failed for some reason. Prototype: int wedge_player() Class: music_driver Description: This function wedges the timer_int() interrupt routine into the timer ISR chain. It sets the timer interrupt frequency to the correct value based on the song's tempo. The return value indicates the success of the wedging. If a nonzero value is returned, the interrupt routine was wedged successfully. If a zero is returned, the interrupt routine was already wedged. Prototype: int remove_player() Class: music_driver 31 Appendix C: Playing GMS Modules: Programmer Documentation Description: This function removes the timer_int() interrupt routine from the timer ISR chain. The return value indicates the success of the removal. If a nonzero value is returned, the player was removed successfully. If a zero is returned, the player was never installed. Prototype: unsigned int compute_timer_setting(unsigned int tempo) Class: music_driver Description: This function takes a GMS (primary) tempo value and returns a number for use with set_timer(). Legal GMS tempo values range from 1 to 255. If a number outside this range is used, the number returned by this routine will be invalid. Prototype: void update() Class: music_driver Description: This routine is called by the timer_int() routine every time there is an interrupt. If you're not using interrupts, or you're using your own interrupt routine, you'll need to call update() yourself at the proper times. Prototype: void set_timer(unsigned int new_setting) Class: music_driver Description: This function reprograms the PC's timer. The new_setting parameter is usually obtained through a prior call to compute_timer_setting(). Prototype: void start_playing() Class: music_driver Description: This function makes the song start playing from its current position. Prototype: void stop_playing() Class: music_driver Description: This function halts the song's playback. Prototype: void position_jump(unsigned int new_pattern, unsigned int new_line = 0) Class: song Description: This function makes the play routine start playing from a different point in the song. (If the song is not currently playing, nothing obvious happens, but the internal position variables are reset to point to the new song position.) The required first parameter is the number of a line in the play sequence (0 is the first line, 3 the fourth, and so on). The optional second parameter is the line within that block where playing should start. Presently there are two global variables defined, music and song_obj, which are instances of the mu- sic_driver and song classes, respectively. These two variables should be used to access the member functions of those classes. In a future release the variables will be eliminated and the class members will be made static. (The current setup came about because of an early design decision which later turned out to be unnecessary.) Also, two of the variables in the classes are of particular significance: the soundsystem variable in the song class and the sb_base_address variable in the music_driver class. So, how do you use all of this? Setting up for playing The first order of business when your program starts up is to find out what kind of sound card the user has and what its base address is. There are a number of methods for "automagically" determining these, but usually the simplest and most effective one is just to ask the user. Not all Soundblaster clones "look" like a Soundblaster, even if they operate like one. 32 Appendix C: Playing GMS Modules: Programmer Documentation Next, load the GMS module into memory. Then, set the soundsystem and sb_base_address variables to reflect the user's particular system. (You can set the sb_base_address variable at any time, but you have to set the soundsystem variable after loading the module because load_gms() sets soundsystem to the value saved in the module.) Sometimes you can skip the above steps. For example, if you know that the module was composed under the Adlib sound system, and you want it to play back in monaural, all you really need to know is whether or not the user has at least an Adlib card. If, however, the module was composed in one of the Soundblaster Pro sound systems, you definitely want to find out what kind of sound card the user has. The two kinds of Soundblaster Pros work quite differently from one another, and playing the module back under the wrong sound system will result in garbled-sounding music. Whenever possible, music should be composed and played back in Soundblaster Pro II mode. The reason is that the Soundblaster Pro II is based around the Yamaha OPL3 chip, while the earlier sound cards are based around the OPL2 chip. Whenever the play routine wants to write to an OPL2-based card, it has to do these things: 1. Write the desired sound card register to the register select port (1 outp instruction). 2. Wait around while the OPL2 chip does internal processing (6 inp instructions). 3. Perform the actual write (1 outp instruction). 4. Sit on its hands while the OPL2 chip processes this (*35* inp instructions!). This takes a VERY LONG TIME! The OPL3 chip, on the other hand, is much faster and requires hardly any wait time. The difference can be seen visually by using the Show Interrupt gadget under the MISC menu. Playing the music There are two basic ways to play the music. First, you can use the wedge_player() function to put the play routine into the timer ISR chain. This is the simplest and easiest method. The interrupt routine runs automatically, so your program can more or less ignore it. The disadvantage of this method is that (from the program's point of view) the interrupts occur at unpredictable times. For some programs this makes no difference, but for others (such as those that synchronize themselves to the vertical blank) it will result in screen flicker or graphic glitches. For these kinds of programs it's necessary to use the second method, which is to call the update() function from your own code _ either your own interrupt routine or your game's main loop. An implementation of this method might look something like this: for (;;) { wait_for_vertical_blank(); flip_screens(); music.update(); read_controllers(); undraw_sprites(); update_all_objects(); draw_sprites(); } This code makes the (possibly incorrect) assumption that all of the loop's processing can be completed in one display frame. If it can't, the music will sound jerky and/or play more slowly than it should. For this reason, it's usually best to call the update() routine from an interrupt, even if it makes the code more complicated. A disadvantage of the second method is that it forces the update() routine to be called a fixed number of times a second. In the popular video mode 13h there are 50 display frames per second, so if the example given above used mode 13h it would call update() 50 times a second. The problem with this is that it 33 Appendix C: Playing GMS Modules: Programmer Documentation effectively locks the song's primary tempo at one number, since the primary tempo is normally used to set how many times a second the interrupt routine is called. The only way to affect the song's speed is to change the secondary tempo, which has a much lower resolution and may require some of the song's effects to be changed (this is explained in the description of the Secondary Tempo gadget under the PLAY menu). The following table shows some common frame rates and their equivalent GMS primary tempo settings. frames/second_____GMS_primary_tempo_setting_ 18.2 1 50 80 60 105 70 130 For example, if you were composing music to be used with the code shown above, you would set the primary tempo to 80. Whichever one of the two methods you decide to use, you also need to call start_playing() and stop_playing() at appropriate times to start and stop the music, respectively. Putting multiple songs in one GMS module The fact that the GMS player code can only hold one module in memory at a time might seem to be very restrictive. In practice, it isn't. As the musician, you simply have to compose all of the game's tunes in one module. This section explains how to do that, and how to make use of the resulting module. Let's say that you've already composed one of the game's tunes. It uses blocks 0 through 2, and the play sequence looks like this: 00 00 01 01 02 Now you want to compose another tune. Instead of starting from block 0, as you normally would, you start from the first unused block _ block 3 in this example. When you write the second tune's play sequence, you add it onto the end of the existing play sequence. If the second tune's play sequence consisted of 03, 03, 04, the overall play sequence would look like this: 00 00 01 01 02 03 03 04 If you want to add additional tunes to the module, you do so in the same manner. To play back these tunes, you use the position_jump() function. In the example above, calling posi- tion_jump() with 0 would start playing the first tune, and calling it with 5 would start playing the second tune. One thing you have to make sure of is that all of the module's tunes are "closed off" from one another. Each tune needs to end with either a B command (position jump) or an FFF command (stop playing) to prevent it from falling through to any of the module's other tunes. (Unless you want it to fall though - but that's unusual.) 34 Appendix C: Playing GMS Modules: Programmer Documentation After playing Before your program exits, it should call stop_playing() and reset_card(). Nothing else needs to be done. The song destructor function will perform all other necessary cleanup operations. The player program player.cpp, included with the play routine source code, is an example of how to load and play a GMS module. 35 D. External Formats _______________________________________________________________________________ In the future, GMS will be capable of loading modules and instruments from many other tracker programs. The internals of these programs work differently from GMS; sometimes they work very differently. GMS compensates for as many of the differences as it can, but almost all modules will require some human attention before they sound correct under GMS. This appendix gives a brief description of the external formats that GMS supports and lists what GMS can and cannot do during the conversion process. At the moment, GMS supports only RAD modules, and no instrument formats other than its own. Look for this to change in the near future. RAD Reality Adlib Tracker (RAD) is an FM tracker written by Shayde, Rogue, and Void of the demo group Reality. GMS is able to load modules made with version 1.0 of RAD. RAD's tempo control is equivalent to GMS's secondary tempo. It also has two overall operating modes, "normal" and "slow-timer", which control how often the play routine is called. These are equivalent to the GMS primary tempos 80 and 1, respectively, and will be converted as such. RAD tunes can have a description included in them, like GMS can with its Info Page. The RAD description window and the GMS info page are different sizes, though, so the text formatting is likely to be wrecked by the conversion process. RAD uses a different internal method of representing frequencies than GMS does. GMS tries to compensate for this during the loading process, but frequency slide and portamento commands may not sound right in the converted module. The RAD volume slide command has a greater maximum value than the GMS one (49 for RAD and 15 for GMS). Any volume slides that have a rate greater than 15 will be set to 15 during the loading process. The RAD pattern break command lets you specify a line in the next pattern for playing to continue at. The GMS counterpart (F00) does not. RAD's position jump commands are included in the play sequence, instead of in the blocks as they are in GMS. GMS handles this by creating a one-line block with a position jump in it and inserting it into the proper place in the play sequence. This may cause a "hop" effect when playing the song. 36 E. How Synthetic Instruments Work _______________________________________________________________________________ Synthetic instruments ("synthsounds") are based around something from music theory called the ADSR envelope. ADSR stands for attack-decay-sustain-release. Every note goes through all four of these phases. The idea is that when a note is played, the volume is initially zero (the note is inaudible). The volume then rises to the maximum volume that the sound card can produce. This is the attack phase. The note's volume starts dropping immediately. This is the decay phase. The volume decay continues until the note reaches the sustain volume. It holds at that volume for the remainder of the time the note is supposed to be played. Then it enters the release phase, and the note tapers off into silence. To understand this better, imagine an eager but inexperienced musician playing, say, a clarinet. When he first begins to play a note he sends too much air through the instrument, making the note sound too loud (attack phase). He quickly corrects for this, lowering the volume to what he wants it to be (decay phase). He then maintains that level of air flow until the note has played for the proper length of time (sustain phase). Then he touches his tongue to the reed, and the note fades away release phase). These things still happen even when an expert plays the instrument, but you don't notice it unless he wants you to. All notes played by all instruments (real or electronic) can be represented by the ADSR envelope. In a real-world instrument, the envelope is part of the way the instrument is played (flutes, for example, have a noticeable ADSR envelope). In a computer-generated instrument, such as a synthsound, the envelope is created by the musician. This is done by specifying an attack rate, a decay rate, a sustain level, and a release rate. The attack, decay, and release rates determine how fast the note's volume changes in the attack, decay, and release phases of the envelope. The sustain level determines what volume the decay phase ends at. The length of the sustain phase is controlled by you, the musician, using the key off command. The sound chip has a conception of the note being in one of two states: either it is "keyed on", which means that the note is going through the attack, decay, or sustain phases, or it is "keyed off", which means that the note is in the release phase. (These two states get their names from the sound chip being designed for use in a synthesizer keyboard, where you would actually be pressing and releasing keys.) Whenever an instrument is played, GMS automatically keys it on for you. If you never use the key off command, the note will stay in the sustain phase until the next note on the track is played, which will cancel the old one. (Technically, GMS does do a key off right before it plays the next note, but the time spent in the release phase is miniscule.) It's possible to "get rid" of the ADSR envelope by setting the attack, decay, and release rates to very high values. At any given time, such an instrument would be either keyed on and playing at full volume, or keyed off and silent. There would be nothing in between these two extremes. This kind of instrument sounds very harsh and "electronic". Sometimes this is what you want, but usually a more complicated instrument will make your music sound better. In addition to an ADSR envelope, each instrument has a waveform. The type of waveform determines the overall sound of the instrument. For example, the sine waveform produces a smooth, bell-like note. The square waveform produces a more harsh-sounding note. Like the ADSR envelope, the waveform controls the note's volume. But the waveform repeats over and over, and is played much faster - usually thousands of times a second. Because of this, we don't directly hear the volume changes the waveform causes. They blend into our overall impression of the note. As you probably already know, it is the frequency at which the waveform is repeated that controls the pitch of the note. The more times per second the waveform is repeated, the higher in tone the note sounds. The above discussion is general enough to apply to most synthsound-producing chips on the market today. Now let's talk about some issues specific to the OPL2 chip, which is the basis for the Adlib and Soundblaster cards. Each of the 9 channels on the OPL2 chip has not one but two "operators" assigned to it. Each of these operators can produce a tone. Each has its own ADSR envelope and waveform. Each has a lot of other options which can be used to control the kind of sound it produces. A few of these, like frequency, can only be set on a channel-by-channel basis; both of a channel's operators always produce sound at the same frequency. But most can be set on an operator-by-operator basis. Sound complicated? It is! 37 Appendix E: How Synthetic Instruments Work There are two basic modes each channel can be in: In additive synthesis mode, the two operators are independent. The settings of one operator do not affect the sound produced by the other operator. In frequency modulation mode, operator 1 produces no sound. Instead, it feeds its output into operator 2. The sound produced by operator 2 depends upon its own settings and upon the output of operator 1. Frequency modulation mode can produce more complex-sounding instruments, which usually means better-sounding. But it's much more difficult to use. When combined, the operators may produce a sound wholly different from what they produced separately. You don't always have to make instruments yourself _ many times you can "borrow" them from tunes other people have created. But at some point you're probably going to need a sound that you don't have. If that happens, you'll have to make it yourself. I suggest you experiment with additive synthesis mode first. Set one of the operators so that it's inaudible and play with the other one, particularly the ADSR envelope. When you've gained some familiarity with it, turn the other operator on and see how they both sound together. After that you can take a crack at frequency modulation mode. 38 F. An Introduction To Tracker Composition _______________________________________________________________________________ All tracker programs are based (at least in functionality) on the original Amiga program called Sound- tracker. Soundtracker 1.0 was written by Karsten Obarski in 1987. The source code found its way into the hands of various European demo groups, many of whom released their own "improved" versions. (There was an amusing incident where one group released a Soundtracker 2.0 and another group released a Soundtracker 1.3 shortly thereafter. Neither group had been aware of the other's work.) This resulted in a lot of confusion all around (the .MOD files produced by one program were usually slightly incompatible with all the other programs) but eventually resulted in a flexible, powerful system of music composition. Some of the material in this appendix is specific to GMS, but much of it applies to tracker programs in general. One of the fundamental concepts behind a tracker program is that music is repetitive. The percussion parts of contemporary music usually consist of the same rhythm, repeated over and over again. The back- ground chords cycle between the same series of notes. And significant portions of the song are repeated with minor (or no) changes. A tracker program divides the entire song up into small sections called blocks (some trackers call them patterns). Each block is assigned a number, starting from zero. The musician can control when each block is played by using the play sequence (sometimes called the pattern list or order list). The play sequence is simply a list of block numbers. The tracker steps through this list, one number at a time, playing the block listed there and then moving on to the next one. The block numbers can appear in any order at all, and a particular block can be repeated in the list as many times as necessary. The idea here is to take advantage of the repetitiveness of music to save memory. Sections of the song can be repeated simply by repeating their block numbers in the play sequence (and possibly copying and editing a few blocks to make smooth transitions). This way of doing things also makes the editing phase easier. In a more conventional music program, repeating part of the song might result in a copy being made of the repeated section. If you later wanted to make changes to that section, you'd also have to change each of the copies of it. Having to do this is extremely irritating - particularly if you miss a section and don't notice until it's too late. Let's look now at blocks in detail. Each block is composed of tracks and lines: Ln# <01> <02> <03> <04> <05> <06> <07> <08> 022 C-3 1000E-3 1000 G-3 1000 --- 0000 --- 0000 --- 0000 --- 0000C-5 2000 023 --- 0000--- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000--- 0000 024 --- 0000--- 0000 --- 1000 --- 0000 --- 0000 --- 0000 --- 0000G-4 2000 025 --- 0000--- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000--- 0000 026 --- 0000--- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000C-4 2000 Lines 22-26, tracks 1-8. Each track represents one of the sound card's output channels. Each line represents a small bit of time that can be used to play a note. When the tracker plays a block, it starts at the first line in that block and processes all of the tracks on that line. After a certain amount of time passes (determined by the tempo) the tracker moves to the next line and processes all of its tracks. This continues until the entire block is played, at which point the tracker starts playing the next block in the play sequence. Each line of each track can contain a note, an instrument number, an effect number, and an effect data byte. These four components, taken together, are sometimes called a note-line. All of them are optional. All numbers in the track display are in hexadecimal. This is mostly because they would take up too much screen space if they weren't (though there are a few other reasons). It's easy to forget this during an intense editing session. If things aren't sounding the way they're supposed to, make sure you didn't use a decimal number by mistake. The note part of a note-line consists of the actual note (D, D#, etc) and an octave number. The first character is the note letter. The second character is a hash mark if the note is sharp, or a dash if it isn't. The 39 Appendix F: An Introduction To Tracker Composition third character is the octave number. "No note" is represented by a dash in all three character positions. The note part can also contain the word OFF. This means that the channel should be keyed off, which sends the instrument playing on the channel into the release phase. Normally if the note-line contains a note it also contains an instrument number. The instrument number indicates which instrument the note should be played with. An instrument number of zero means "no instrument". It's highly unusual (but allowed) to put down a note without an instrument, or vice versa. If a note is put down without an instrument, the channel's frequency is changed but the instrument's ADSR envelope is not reset. If an instrument is put down without a note, the ADSR envelope is reset without changing the channel's frequency. Let's try setting down some notes. Select the track display and move the cursor to line 0 of the current block. Move the cursor into the note part of track 1. Press the q key. Move the cursor down two lines. Press the w key. Repeat this process with the e, r, and t keys. The upper part of track 1 should now look like this: Ln# <01> 000 C-4 1000 001 --- 0000 002 D-4 1000 003 --- 0000 004 E-4 1000 005 --- 0000 006 F-4 1000 007 --- 0000 008 G-4 1000 009 --- 0000 Select the Play Block gadget from the PLAY menu. Well, it isn't really music, but it's audible. Notice that each time a note is played, the previous note is cancelled. Each track can have one - and only one - note playing at a time. The number of tracks in your song determines the number of notes you can have playing at one time. How many you need depends upon your song. Let's add something more. Use the cursor keys and the slash key to add key-offs to the track so that it looks like this: Ln# <01> 000 C-4 1000 001 OFF 0000 002 D-4 1000 003 OFF 0000 004 E-4 1000 005 OFF 0000 006 F-4 1000 007 OFF 0000 008 G-4 1000 009 OFF 0000 Play the block again. If you don't notice a difference, try using the Tempo gadget to make the song play more slowly. An entire song can be created using just the note and instrument parts of the note-line. Such songs are rare, however. Virtually all songs use the remaining two parts of the note-line: the effect number and effect data byte. Taken together, they are referred to as an effect command (sometimes simply as an effect or a command). Effect commands let you exercise greater control over the sound produced by a track. Let's start with a simple effect command. Move the cursor to line 3 and change the note-line to look like 40 Appendix F: An Introduction To Tracker Composition this: OFF 0C1E Now play the block. Effect C is the volume change command. This command overrides the track's current volume, changing it to the value of the data byte. When the tracker processes line 2, it sets the track's volume to the volume of operator 2 in instrument 1. When it reaches line 3, it sets the track's current volume to the value of the data byte (1E, equivalent to decimal 30). This is lower than the previous volume, so the note suddenly becomes softer. If this command had been placed on line 2, the note would have been played at 1E in the first place. Now let's try a frequency slide. Move the cursor to line 5. Go to the BLOCK menu. Select the gadget called Make Normal Slide. The note-line should now look like this: --- 0122 Play the block. The tracker has a conception of a "current frequency" for each track. The note part of a note-line sets a track's current frequency. But it can also be modified by the effect commands, as we did here. Command 1, the slide up command, causes the track's frequency to increase. But not by a total of 34 - by a total of 204! A very important thing to understand is the relationship between the effect commands and the Secondary Tempo gadget in the PLAY menu. Effect commands are processed every time the music playing routine is called from the interrupt code. The Secondary Tempo controls how many times the music playing routine is called before a line is advanced. If the secondary tempo is 6, the first time the routine is called it will play line 5's note and effects. The second time it's called it will play only line 5's commands, skipping the note. Ditto for the third, fourth, fifth, and sixth time. The seventh call will cause it to play line 6's note and effects, the eighth will play only line 6's effects, and so on. Every time line 5's effects are processed, the track's frequency will be increased by 22 hex (34 decimal). (Including the first time - the effects are always processed after the note and instrument are.) But since the default secondary tempo is 6, the total frequency increase will be 6 * 34, or 204. Let's finish by getting in a little experience with the play sequence. Go to the BLOCK menu and select Add Block. This will add a new (blank) block to the song, numbered 1. Go to the PLAY menu and select the Play Sequence gadget. Using the INSERT and cursor keys, edit the play sequence so that it looks like this: 00 00 01 This play sequence will play block 0 twice in a row, then play block 1 once, then start over (because the song loops around automatically). Use the Play Song gadget to listen to it. Before actually trying to compose anything yourself, I strongly advise that you spend some time looking at other peoples' songs. They don't have to be GMS songs; the basic techniques are the same from one tracker to another. Study how these people pulled off the musical effects they used. Take the song apart in your mind and figure out what makes it tick. What parts of the song are essential, and prevent the song from sounding lame? What parts just add a little extra kick? This is time well spent, because music is both a technical and creative art. You have to know what goes into a good song, and you have to know how to get your song into the tracker and make it sound good. (And, by the way, I'm still learning too.) Good luck! 41