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. In particular, the page
breaks will be all messed up if you try to print it out.



Game Music System 1.1


      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 mixed together 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 tracker 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. Only a very fast computer can run a game at a decent speed
while doing sample tracking.
       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. 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. Unfortunately, MIDI music always sounds best when
played through the same hardware it was composed on, and may not sound very
good at all when played through anything else. 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).
  * Samples can be played in parallel with the FM music.
  * Music "subroutines" can divert from the main tune to play a subtune.
  * FM-based effects can be played in parallel with the music.
  * Public domain play routine, with full source code.
  * Open module and instrument formats, fully documented.
  * A sane user interface.


    With the release of GMS 1.1, I believe I have succeeded in my ambition
to make GMS the best and most full-featured FM tracker available for the PC.
The only feature of any significance which has not been implemented is OPL3
4-operator mode, and I consider this not to be useful enough to be worth
doing. My new goal, which will be explored in Game Music System 2.0 and
beyond, is to make GMS the best tracker, FM or otherwise, 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. The SPECIAL Menu :::::::::::::::::::::::::::::::::::::::::::::::::::::::18
12. Effect Commands :::::::::::::::::::::::::::::::::::::::::::::::::::::::::19
13. Keyboard Shortcuts:::::::::::::::::::::::::::::::::::::::::::::::::::::::21
14. Some Questions And Their Answers:::::::::::::::::::::::::::::::::::::::22
15. Registration:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::23
16. Legal Stuff::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::24
17. 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 386 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.
    Also, the MIDI loader code expects to find a directory called "midi" in
the current directory. If this directory is not found, no instruments will
be loaded when a MIDI file is loaded.
    Other than that, GMS has no particular directory structure requirements and
can be placed anywhere on your hard disk you wish.



                                        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 Mouse Pointer option, and hit RETURN until the
desired level of mouse support is displayed.
    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. You can also use the page
up/down keys to move up or down more quickly.
    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+--- 0000 OFF 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 or effect slot will erase whatever is already there.
    Pressing the DELETE key will delete the note-line under the cursor, and
move all of the note-lines below it on the track up by one space. The INSERT
key will insert an empty note-line under the cursor, moving the old
note-line and all those below it on the track down by one space.
    Pressing SHIFT-INSERT will insert a blank track where the cursor is. The
old track will be moved to the right, as will all tracks to the right of it.
SHIFT-DELETE will delete the track under the cursor, and all the tracks to
the right of the cursor will be moved left one space.
    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.
    By using the right mouse button, you can select a range of tracks and
lines to use the range-based editing commands with. Press and hold the right
mouse button over one corner of the rectangle, drag the cursor to the other
corner, and release the button. This is functionally equivalent to using the
Mark Range Start and Mark Range End gadgets, but easier.



Special notes for sampled sounds
    Unlike FM instruments, sample instruments are not controlled by a
particular track. To play a sample instrument, place its instrument number
in the instrument slot of any track, and leave the note slot blank. (If the
note slot is not blank, the FM channel associated with that track will be
keyed on, which is usually not what you wanted to do.)
    Only one sample can be playing at a time, even in a Soundblaster Pro
mode. Unfortunately, stereo samples are implemented on the Soundblaster Pro
by interleaving the sample data, and not by having two separate DMA
channels. Providing the illusion of two separate channels would take a
significant amount of CPU power, so GMS does not do it. Playing a sample
always cancels any other sample that may be playing, regardless of the types
of the two samples.
    A sample instrument cannot be affected by notes or effects appearing on
the track display. It always plays back at the frequency you set with the
Sample Frequency gadget in the INST menu. It is not affected by the setting
of the Global Volume gadget. Once a sample is started playing, the only way
to stop it prematurely is to start playing another sample. (If this is a
problem, you can work around it by making a "silent" sample and using it to
stop other samples.)




                                        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 displaying all of 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/1.1 and RAD 1.0/1.1 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. If the instrument file contains only a synth or
only a sample component, the instrument slot's current sample or synth
component, respectively, will be preserved.
    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
block after 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. It can play monaural samples at frequencies
ranging from 4000 Hz to 44100 Hz.
    There were actually three versions made of the original Soundblaster
card. Version 2.0 (which GMS is designed to support) can play samples at the
frequencies mentioned above. Versions 1.0 and 1.5 only have a frequency
range of 4000-23000 Hz.
    When GMS is in one of the Soundblaster modes, 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 I can play back either monaural or stereo samples.
However, it can only play back stereo samples at *exactly* 11025 or 22050
Hz.

    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.
    The Soundblaster Pro II's sample-playing capabilities are the same as
the Soundblaster Pro I's.



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.



Percussion Mode
    When this gadget is set to Off, the sound card operates in the normal
melodic mode. When On, it is in percussion mode. In this mode, three of the
melodic channels are lost but five percussion channels become available.
They are: bass drum, snare drum, tom-tom, cymbal, and hi-hat.
    The percussion instruments are more limited than the normal melodic
instruments. Only the bass drum uses two operators. Each of the others uses
only one, the modulator. The cymbal and hi-hat always play at the same
frequency, regardless of which note is used on their channels. All of the
percussion instruments always play in mono, regardless of the settings of
the Sound System and Stereo gadgets.
    There seem to be problems with percussion mode, probably due to my lack
of solid information on this mode. The percussion channels may not turn off
properly when the song stops playing. Also, they don't seem to work well in
Soundblaster Pro II mode. I recommend not using percussion mode unless you
have a good reason to.



Highest Stereo Left
Lowest Stereo Right
    When Sound System is set to Soundblaster Pro I or II, these gadgets
control which tracks are on which stereo side. All tracks whose numbers are
equal to or less than the highest stereo left will be heard on the left
side. All tracks with numbers equal to or greater than the lowest stereo
right will be heard on the right side. By setting these gadgets
appropriately, some tracks can be heard on both sides, or on neither side.
    If Sound System is set to Adlib or Soundblaster, the values of these
gadgets are 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 visible 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 block will be placed at the end of the block
sequence.



Add Block Here
    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
Cut Note
Copy Note
Paste Note
Swap Note
    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.
    Cut Note, Copy Note, Paste Note, and Swap Note operate on only one
note-line at a time. The note-line under the cursor is the one affected.
    Note that all of these gadgets use the same clipboard. Mixing block, track,
and note operations is likely to have an unpredictable effect.



Trans. Block +
Trans. Block -
Trans. Track +
Trans. Track -

    These gadgets transpose the notes in a block or track. The + gadgets
transpose upwards by one half-step (a C will become a C sharp, an E will
become an F, and so on). The - gadgets transpose downwards by one half-step.



Split Block

    This gadget causes the current block to be split into two blocks. The first
block will contain all of the lines above the cursor position. The second
block will contain the line under the cursor and all lines below it.



Join Block

    This joins the current block together with the next block.



Clear Note Effects

    This gadget removes all of the effects attached to the note-line the cursor
is on.



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
                --- 0000                               --- 0C18
                --- 0000                               --- 0C20
                F#4 3C29                               F#4 3C29
            Before slide command                 After Make Volume Slide


                                       12
                             Chapter 8: The BLOCK Menu




    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.



Components

    An instrument can be composed of two components: a synth component
and/or a sample component. Each component is optional. This gadget shows
which components (if any) are present in the current instrument. It cannot
be selected.



Show Sample/Synth

    The gadget window only has enough space to display information on one of
the instrument components at a time. Selecting this gadget will toggle which
component's information is displayed.



Add Synth
Delete Synth
Delete Sample

    These gadgets allow you to add or delete instrument components. A gadget
will only be visible if its function is appropriate to the current
situation. For example, if the current instrument has a synth component, and
it is being displayed, the Delete Synth gadget will be visible.
    There is no "add sample" gadget. A sample component is automatically
created when you load an instrument file which contains sample data.



    If the instrument's synth component is being displayed (assuming it has
one), there will be two table gadgets in the window. A table gadget is a
special kind of gadget that can contain other gadgets. If the instrument
does not have a synth component, the message "No synth component" will be
displayed instead of the tables.
  A 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.



    If the instrument's sample component is being displayed, the following
gadgets will be visible:



Sample Type

    This gadget cannot be selected. It indicates whether the sample is
monaural or stereo.



Sample Length

    This gadget cannot be selected. It displays the length (in bytes) of the
sample.



Playback Frequency

    This gadget sets the frequency, in Hertz, at which the sample will be
played back. The explanation of the Sound System gadget lists what
frequency ranges are supported by each sound card.
    One of the documentation files I've read commented that some
Soundblaster-series clones can only play back samples reliably at 11025,
22050, and 44100 Hz. For that reason, you might want to use a sample editor
to convert your samples to one of those frequencies before importing them
into GMS.


Repeat Start
Repeat Length

    These gadgets can be used to make part of the sample repeat (infinitely)
after the entire sample has been played once. Repeat Start holds the offset,
in bytes, of the repeating section from the beginning of the sample. Repeat
Length indicates the length, in bytes, of the repeating section. If Repeat
Length is zero, none of the sample will be repeated.
    For a stereo sample, Repeat Length should be an even number. Setting
Repeat start to an odd number with a stereo sample will result in an unusual
(and possibly desirable) effect.



    If the instrument has no sample component, the message "No sample
component" will be shown instead of the above gadgets.



IMPORTANT: You should *not* make an instrument with both a synth and sample
component. This was intended to be a GMS 2.0 feature, but for technical
reasons it made sense to write the code for it now. Currently both the
synth and sample components of such an instrument will be played, but GMS
2.0 will handle things differently. There is little benefit in making a
dual-component instrument under GMS 1.1 - please don't do it.



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.



Interrupt Number

    This gadget allows you to set the interrupt number used by your
Soundblaster card. This is normally 5, but it is user-configurable. If this
gadget is set to the wrong number, samples will not play back correctly.



DMA Channel

    This gadget allows you to set the DMA channel used by your Soundblaster
card. This is normally 1, but it is user-configurable. If this gadget is set
to the wrong number, samples will not play back at all.



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.)

    The main use for this gadget is to be able to load raw sample files as
instruments.



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.



Mouse Pointer

    This gadget can be used to select GMS's mouse support. When set to
Disabled, the mouse is ignored. When set to Cursor, the standard block
cursor will be used. When set to Graphical1 or Graphical2, a
pixel-resolution mouse pointer will be used. On slow computers, Graphical1
has less flicker, but may also cause display glitches. (Changing your BIOS
settings to have video ROM shadowed will usually help with the flicker.)



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.



Global Volume

    This gadget sets the overall volume of the FM music. Its value can range
from 0 to 63, with 0 indicating silence and 63 meaning full volume. Sample
instruments are not affected by the setting of this gadget.



MIDI Quantize
    When loading a MIDI file, the number in this gadget determines how many
MIDI time-values are mapped to one GMS line. See Appendix D, External
Formats, for more information.



Max Effects Per Note-Line

    This gadget sets the maximum number of effects that can be attached to a
note-line during editing. Setting this number higher will make the editor
use more memory, but this is not likely to be significant.

    The setting of this gadget only affects the editing phase. It has no
effect on the amount of space that a GMS module takes up when on disk or
when loaded into memory for playing.



Saves To Existing Files

    This gadget affects what happens when you try to save a song to a file that
already exists. When set to Overwrite, the old file is destroyed. When set
to Rename, the old file is renamed with a numbered extension. (For example,
COOLTUNE.GMS might be renamed to COOLTUNE.001.) When set to Ask, a requester
will pop up and ask what should be done.



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
Address, Sound System, Keep Sound System When Loading, Song Loading,
Instrument Loading, Default Block Lines, Mouse Pointer, Show Interrupt,
Interrupt Number, DMA Channel, Global Volume, Max Effects Per Note-Line, and
Saves To Existing Files.


                                       17

11.  The SPECIAL Menu

_______________________________________________________________________________



    The SPECIAL menu contains gadgets for "special" operations. At the
moment, it contains the gadgets that work with ranges of music data.



Mark Range Start
Mark Range End
    These gadgets set the boundries of the current range. Mark Range Start
sets the upper-left hand corner of the range to be at the current cursor
position; Mark Range End sets lower-right hand corner of the range. The
selected range is block-independent. It will be shown in the track display
as a blue rectangle.



Hide Range
    If the range block becomes too annoying, this gadget will make it
disappear.

Cut Range
Copy Range
Paste Range
Swap Range
    These gadgets work in the expected way. Cut Range copies the range to
the clipboard and then blanks out that section of music data. Copy Range
leaves the data intact. Paste Range pastes the range in the clipboard at the
current cursor position. Swap Range swaps the range in the clipboard with
the music data at the current cursor position. These gadgets use the same
clipboard as the block, track, and note gadgets, so mixing them will have
unpredictable results.


                                       18

12.  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.



Arpeggio (0)
    When this command is used, the track's frequency will flip between three
different frequencies. Each digit of the data byte represents a number of
half-steps. The frequency will change between that of the original note, the
original note plus the number of half-steps in the first digit, and the
original note plus the number of half-steps in the second digit. For
example, 047 will produce a major chord, and 037 will produce a minor one.
    In days past, arpeggio was used on computers like the Commodore 64 to
simulate extra channels. Nowdays, arpeggio is mostly useful to create
musical effects.



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. This 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 12: 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
that 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. If this command is encountered
while within a subroutine, it will end the subroutine and make the main tune
start playing again. If this command is encountered by an effect, the effect
will be cancelled.



                                       20

13.  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.
    SPACE - Halts music playback and silences all channels.
    [ - 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-0 - Changes the active status of tracks 11-20.
    ALT-X - Shortcut for Clear Note Effects in the BLOCK menu.
    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.
    F9 - Shortcut for Cut Note in the BLOCK menu.
    F10 - Shortcut for Copy Note in the BLOCK menu.
    F11 - Shortcut for Paste Note in the BLOCK menu.
    F12 - Shortcut for Swap Note in the BLOCK menu.
    ALT-F1 - Shortcut for Mark Range Start in the SPECIAL menu.
    ALT-F2 - Shortcut for Mark Range End in the SPECIAL menu.
    ALT-F3 - Shortcut for Hide Range in the SPECIAL menu.
    ALT-F5 - Shortcut for Cut Range in the SPECIAL menu.
    ALT-F6 - Shortcut for Copy Range in the SPECIAL menu.
    ALT-F7 - Shortcut for Paste Range in the SPECIAL menu.
    ALT-F8 - Shortcut for Swap Range in the SPECIAL menu.
    ALT-F12 - Exit program.  Quits out of GMS and returns to the MS-DOS
prompt. There is no gadget equivalent to this key.



                                       21

14.  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?

    It does work under Windows 3.1 and Windows 95. Under 3.1, you'll need to
run it on its own screen or the tempo will be messed up. Under 95, Windows
will complain now and then about GMS being a DOS program and not working
well under Windows. This can be turned off by a checkbox under one of the
tabs in the properties window.
    As for the other ones, I haven't tried it.



    Why does the system time get all messed up when GMS is running?

    There are actually two clocks inside your PC. One is in hardware, and is
connected to the CMOS battery. The other is in software, and is maintained
by MS-DOS. It is this software clock that provides the time-stamp attached
to files (and reported by the date command).

    When MS-DOS starts up, it sets the software clock to the same time as the
hardware clock. Thereafter, it updates the software clock on its own and
ignores the hardware clock. But since GMS takes over the timer interrupt,
the clock gets updated at the wrong rate. This is why the time can be many
hours out of date when you exit GMS.

    There are ways around this problem, but I didn't think they were worth
bothering with. They also tend to make life more difficult for you when you
try to use the play routine in your program. The hardware clock is still
accurate, so rebooting the computer will set things right again.


                                       22

15.  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.


    E-Mail: malyon@netcom.com
    WWW: ftp://ftp.netcom.com/pub/ma/malyon/top.html



                                       23

16.  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

17.  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.


    DJ Delorie and his team, for the DJGPP port of GCC.


    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.1 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    lowest stereo right
_____1____percussion_mode_____________________________
___???____GMI_instrument_data_(35_instruments)________
     1    highest play sequence number
 1-100    play sequence
_____1____highest_block_number________________________
     1    highest line
__2-32____track_numbers_______________________________
     2    track bytes
 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
loader is actually implemented a little differently than described here, but
it is functionally the same.)
    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 one, the module is a GMS 1.1
song. If it's zero, it's 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), lowest stereo right
byte, percussion mode byte, 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 instruments are stored in
the GMI format described in Appendix B, with the exception that they don't
have a magic cookie header.
    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 is not
stored in the module, it can be determined by examining the block tables.
    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     synth component?
    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     sample component?
    1     presence
    4     sample length
    4     repeat start
    4     repeat length
    2     playback frequency
0-???     sample data


    An instrument format version number of one means that the file is a
GMS 1.1 instrument, and a version number of zero means that it is a GMS 1.0
instrument.
    The fields "synth component?" and "sample component?" indicate whether
or not the instrument has that component. If a field is nonzero, then the
instrument has the appropriate component. If it is zero, it does not, and
none of the data for that component will actually appear in the file. For
example, if "synth component?" is equal to zero, then the next byte in the
file is the "sample component?" field.
    The "presence" field is the integer cast of an enumeration that
indicates whether the sample is monaural or stereo.
    All sample data is stored as signed 8-bit values.



                                       30

C. Playing GMS Modules:  Programmer Documentation

_______________________________________________________________________________



    PLEASE NOTE: If you were using the GMS 1.0 player code, reread this
appendix carefully. You need to do different things in 1.1 to set up and use
the player code.
    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 will
work with Borland C++ 3.1 and DJGPP 2.0/2.01. Using it with other compilers
may require some adjustments to be made to the code.
    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 calling 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. reset_card() should be called before calling this
routine.


Prototype: void set_up_class()
Class: song
Description: This function sets up the song class's internal variables. It
should be called before anything else is done with the play routine.


Prototype: void shut_down_class()
Class: song
Description: This function returns the memory used by the song class to the
system. It should be called before your program terminates.


Prototype: void set_up_driver(song::sound_cards sound_sys,
    unsigned int sb_base, unsigned int sb_int_num, unsigned int dma_chan)
Class: music_driver
Description: This function sets up the music driver's internal variables and
tables. It must be called before the interrupt routines are wedged, but it
can be called either before or after calling load_gms(). The parameters are
the sound system to use, the base address of the Soundblaster card, the
interrupt number used by the Soundblaster card, and the DMA channel used by
the Soundblaster card.


Prototype: gms_function_return_codes load_gms(FILE *module)
Class: song
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.


Prototype: gms_function_return_codes 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. If success is returned, the interrupt routine was
wedged successfully. If failure is returned, the interrupt routine was
already wedged.


Prototype: gms_function_return_codes remove_player()
Class: music_driver
Description: This function removes the timer_int() interrupt routine from
the timer ISR chain. If success is returned, the player was removed
successfully. If failure is returned, the player was never installed.


                                       31
                Appendix C: Playing GMS Modules: Programmer Documentation




Prototype: gms_function_return_codes wedge_dsp_handler()
Class: music_driver
Description: This function wedges the dsp_int() interrupt routine into the
DSP ISR chain. If success is returned, the interrupt routine was wedged
successfully. If failure is returned, the interrupt routine was already
wedged. It is an error (and failure will be returned) to try to use this
routine if the soundsystem variable is set to adlib.


Prototype: gms_function_return_codes remove_dsp_handler()
Class: music_driver
Description: This function removes the dsp_int() interrupt routine from
DSP ISR chain. If success is returned, the routine was removed
successfully. If failure is returned, the routine was never installed.


Prototype: gms_function_return_codes prepare_sample()
Class: instrument
Description: Instrument sample components need to be copied into
conventional memory before they can be used. This function allocates the
necessary conventional memory and performs the copy. Even if you are
compiling for real mode, it is still necessary to call this function, as it
also sets up a variable in the instrument structure. If success is returned,
the sample was successfully copied (or it had already been copied during a
previous call). If failure is returned, there was not enough conventional
memory to hold the sample. The module can still be played, but the sample
will be inaudible.
    It is not necessary (but not an error) to call this function if the
instrument has no sample component. Success will always be returned in that
case.
    Normally prepare_all_samples() will provide all the functionality you
need, and it will not be necessary to call this function directly.


Prototype: void unprepare_sample()
Class: instrument
Description: This function reverses the effect of a prior call to
prepare_sample, freeing the conventional memory used to hold the sample's
copy. If the instrument has no sample component, or the sample was not
prepared, the function call has no effect. Even if you are compiling for
real mode, it is still necessary to call this function, as it also clears a
variable in the instrument structure.
    Normally unprepare_all_samples() will provide all the functionality you
need, and it will not be necessary to call this function directly.


Prototype: gms_function_return_codes prepare_all_samples()
Class: song
Description: This function calls prepare_sample() for all of the instruments
in the song. If any of the calls to prepare_sample() return failure,
prepare_all_samples() will return failure. Otherwise, it will return success.


Prototype: void unprepare_all_samples()
Class: song
Description: This function calls unprepare_sample() for all of the
instruments in the song.


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. If this function is called while a music subroutine is playing, it
will change the point that the subroutine is playing from; the position
variables of the main tune will be unaffected.


Prototype: void start_subroutine(unsigned int subroutine_pattern,
  unsigned int restart_block_on_finish = YES)
Class: song
Description: This function makes the play routine start playing from a
different point in the song, but it remembers the previous point. When the
Stop Playing command (FFF) is encountered, the play routine will go back to
that point instead of halting playback. The required first parameter is the
number of a line in the play sequence. If the optional second parameter is
YES, the old block will be restarted from line zero when the subroutine
ends. If it is NO, playback will resume from the line it was at when the
subroutine was started.
    Music subroutines cannot be nested. If this function is called while a
subroutine is already playing, it will simply do a position jump to the
requested pattern, as the function.


Prototype: void cancel_subroutine()
Class: song
Description: If a music subroutine is playing, it will immediately end and
the main tune will resume playing. If no subroutine is playing, there will
be no effect.


Prototype: unsigned int start_effect(unsigned int effect_pattern)
Class: song
Description: This function starts an effect playing at the specified line in
the play sequence. The effect will play in parallel to the main tune or
subroutine until it reaches a Stop Playing command (FFF), at which point it
will stop. There is no limit to the number of effects that can be playing at
one time. The function returns an effect identifier which can be used with
the cancel_effect() function (or simply ignored).


Prototype: void cancel_effect(unsigned int id_to_cancel)
Class: song
Description: This function cancels an effect. The parameter id_to_cancel is
the effect identifier returned by the original call to start_effect(). If
the effect has already terminated, this function will have no effect.


Prototype: void cancel_all_effects()
Class: song
Description: This function cancels all effects.


Prototype: void trigger_sample(unsigned int inst_num)
Class: music_driver
Description: This function plays the sample component of inst_num.


Prototype: void set_global_volume(unsigned int new_volume)
Class: music_driver
Description: This function changes the global volume to a new value. Valid
values range from 0 to 63, with 0 being silence and 63 being full volume.



    A number of the above functions return a value of type
gms_function_return_codes. This is an enumeration defined in the globals.h
file as {gms_function_success, gms_function_failure}.
    The GMS member functions in the song and music_driver classes are
declared as static. This means that you access them by typing (for example)
music_driver::start_playing().


    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. If the user has a Soundblaster Pro, make sure you find out which kind it
is. 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.



                                       32
                Appendix C: Playing GMS Modules: Programmer Documentation


    Call song::set_up_class(). Then load the GMS module into memory and call
set_up_driver(). Loading the module and setting up the driver can be done in
whichever order you wish. If the module is loaded after the call to
set_up_driver(), the soundsystem saved with the module will override the
setting you passed to set_up_driver().
    Next, call wedge_player() to set up the timer interrupt. If you're going
to be playing back a song with samples, you also need to call
wedge_dsp_handler() and prepare_all_samples().
    Finally, call reset_card() and set_up_card() to prepare the card for
playing.
    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
outport instruction).
    2. Wait around while the OPL2 chip does internal processing (6 inport
instructions).
    3. Perform the actual write (1 outport instruction).
    4. Sit on its hands while the OPL2 chip processes this (*35* inport
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 as described above 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_driver::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.
    Unfortunately, the DSP interrupt can cause the same problems the timer
interrupt does, but there is no choice here: if you are using samples, you
must wedge it.
    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.
    Note: if you use any interrupt that locks up the computer for a
significant period of time (such as a vertical retrace simulator), the DSP
interrupt may have to wait to be serviced. This can cause annoying clicking
noises during sample playback. The workaround for this would be to ensure
that none of the conventional memory copies of the sample cross a 64k page.



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 position_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


Subroutines and effects
    Music subroutines help to make the music more a part of the game. A
subroutine can be started with the function start_subroutine() and cancelled
with cancel_subroutine(). When start_subroutine() is called, the play
routine makes a note of the current song position and then starts playing
from the position you specified. When the FFF command (Stop Playing) is
reached, the play routine picks up where it left off before.
    For example, say you've decided that when the player activates a
power-up a little ditty will play. You would compose that ditty using the
method outlined in the previous section, sealing it off from the main tune.
When the power-up is activated, you call start_subroutine() with the
appropriate pattern number...and then move on to other things, because the
play routine will handle it from that point onward.
    If you try to start a subroutine when there is already one playing, the
remainder of the old one will be skipped. This is usually the desirable
effect.
    Effects are similar to subroutines, but have a different purpose.
They're designed to allow you to easily trigger FM-based sound effects
(lasers, for example) from within your game. They can be controlled with
the functions start_effect(), cancel_effect(), and cancel_all_effects().
    When you start an effect, the main music does not stop playing. Rather,
the effect is played *in parallel* with the main music. This is very
powerful, but has some caveats which will be mentioned shortly.
    As an example, say that the player in your game has a laser gun, and you
decide to implement the laser-firing sound synthetically (as opposed to
using a sample). You fiddle with instrument #5 until it sounds suitably
laser-ish, and make a block that looks like this:

000    C-4 5135 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
001    --- 0135 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
002    --- 0135 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
003    --- 0135 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
004    OFF 0135 --- 0FFF --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000

and at the appropriate place in your code you call start_effect() with the
proper pattern number. This block wouldn't be very good as a normal tune, or
even a subroutine, but it does just what we want it to as an effect.
*Anything* that can be scored in the GMS system can be used as an effect -
synthsounds and/or samples, on as many channels as you wish.
    Be careful, though - the channels inside an effect are not "virtual"
channels, or anything of the sort. They're the same channels that you're
using for the main tune of your music. If the leftmost channel is being used
for music at the same time as this effect is running, something is going to
get mangled. Before composing the music, you should set aside one or more of
the channels to be used for effects. For example, under Adlib you might
decide that channels 1-7 were for music, 8 for player-based effects, and 9
for enemy-based effects.
    You should not use any of the tempo change commands in an effect
(they'll change the tempo of the main tune as well), or anything that could
disrupt the main tune. There might, however, be some situations where having
an effect modify the main tune would be useful, so the door has been
deliberately left open.



Snooping the GMS variables
    Sometimes you may want to look at some of GMS's internal variables. For
example, consider this piece of code:

    song::position_jump(32);
    start_explosion_animation();
    while (song::current_pattern == 32)
      {}   // Do nothing.
    clear_screen();

    The intent here is to synchronize the game's graphics with its music.
Presumably, pattern 32 contains the first part of some music or SFX which is
appropriate to the explosion. However, if this code is compiled with
optimization, it loops forever.
    The problem is caused by register variables. The compiler loads
song::current_pattern into a register at the beginning of the loop, and
simply compares the register with 32 from then on. Of course the contents of
the register never change, so this results in an infinite loop. (Most
compilers will warn you about this situation, but don't count on it.)
    The solution to this problem is to edit the GMS header files and add the
volatile modifier to the variables you need. This will make the compiler
reload the variable from memory before each comparison. The volatile
modifier makes things a teeny bit slower, and GMS doesn't need it itself, so
it's not applied to any of the variables in the original source code.



Interrupts and virtual memory
    The discussion in this section applies only to protected mode
programming. If you're compiling only for real mode, you can safely skip it.
    Virtual memory on the PC is implemented using interrupts. When a program
tries to access a piece of memory that has been paged out to disk, the
virtual memory hardware detects this and causes a page fault interrupt. The
page fault interrupt code loads the page into memory and then returns
control to the original program, which is none the wiser that anything out
of the ordinary happened. Through this system you get the illusion that
there's a lot more memory in the computer than there actually is.
    Unfortunately, MS-DOS is not all that it should be, and one thing that
it's not is reentrant. If a page fault occurs during an interrupt it can
wreck the system data area. This causes Bad Things to happen, like the
computer going kablooey.
    Fortunately, the DPMI server will allow you to specify that certain
ranges of memory should never be swapped out. This is called "locking" the
memory. This solves the problem, but only if you know which sections of
memory to lock.
    In order to avoid a page fault, all the code and data that are used by
the interrupt routine must be locked. Locking the data is easy, since the &
operator can be used to find the data's starting address and sizeof() can be
used to determine its length. Locking the code presents quite a problem,
though, since there is no sizeof() for functions and no standard way to
simulate it.
    Under DJGPP, the approach that GMS takes to this problem is to set the
variable _crt0_startup_flags to include the flag _CRT0_FLAG_LOCK_MEMORY.
This causes all memory to be locked automatically when it is allocated.
Since this flag is used by the bootstrap code, the main program will start
up with all of its code and global/static variables locked, and any uses of
malloc(), new, etc, will automatically lock the new memory. This approach
has the advantage of being absolutely safe, but since none of the memory
will be unlocked, none of it can be swapped out. This effectively disables
virtual memory. I chose this approach because (in my opinion) most games
cannot afford the performance hit that virtual memory causes, and won't be
making use of it anyways.
    If you simply must have virtual memory, the approach that most other
people have taken is to put dummy functions around the ones that need to be
locked and lock the range from the first dummy function to the second one.
This, in my opinion, puts far too much reliance on the compiler and linker
putting everything together in the same order. I'm even more surprised that
this technique works (or at least it seems to) when the functions are
compiled into a library.
    Another possible approach is mentioned in the crt0.h header file in the
documentation on _CRT0_FLAG_LOCK_MEMORY. It mentions that "this bit may be
set or cleared during execution". It surprises me that I haven't seen anyone
do this. Perhaps they just don't want to bother with keeping track of when
the flag should be set and when it shouldn't. If you want to try this
approach, be aware that the routines load_gms() and start_effect() both
allocate memory.
    The final approach, of course, is to use the Ostrich Algorithm, and hope
that any problems the user has will be blamed on something else in the
user's computer.



After playing
    Before your program exits, it should call stop_playing(), reset_card(),
and remove_player() (if you wedged it). If you were using samples, you
should also call unprepare_all_samples() and remove_dsp_handler(). Finally,
call song::shut_down_class().
    The player program player.cpp, included with the play routine source
code, is an example of how to load and play a GMS module.



Using the playroutine under Windows 95
    In a word: don't. There is a TARGET_WIN95, but it doesn't work very well
at all. If you're curious and you have some time to waste, you can poke
around in the player95.cpp program. Otherwise, ignore it.



                                       35

D. External Formats

_______________________________________________________________________________



    GMS is capable of loading modules and instruments from 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.



--- Module Formats ---

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
versions 1.0 and 1.1 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. In particular, slides which start in one block and end in another
will almost certainly be mangled.
    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.

AMD
   AMusic (Adlib Music) is an FM tracker written by Conqueror (Steffen
Keifer). This program creates AMD (Adlib Module) files. AMD modules can be
saved in either packed or unpacked form. GMS can load unpacked modules
created with versions 1.0 and 1.1 of Amusic.
    Amusic commands 90x and 91x set the overall amplitude modulation and
vibrato, respectively. GMS does not allow these things to be set with effect
commands, so they are simply ignored.
    Amusic commands 92x, 93x, 94x and 95x make the channel's volume increase
or decrease, rapidly or slowly. They are similar to GMS's Dxx command, but
have a different resolution. GMS converts them all to Dxx commands, but they
don't sound exactly the same. 

MIDI
    MIDI (Musical Instruments Digital Interface) is a protocol used to send
commands to electronic devices that play music. Commands can be sent on any
of 16 channels, each of which can have a different "patch" (instrument)
loaded, and can be playing at a different frequency. The MIDI file format
is similar to this protocol, but with a few changes necessary to properly
organize the music data.
    GM (General MIDI) is an addition to the basic MIDI protocol. One of the
problems with the original protocol was that patch number 10 (for example)
could be a flute on one keyboard and a tuba on another. GM defines the first
128 patch numbers to be certain instruments. Ideally, patch number 26 (for
example) will be a steel guitar, but it will at least be some kind of
guitar. Also, channel 10 is assigned to be the percussion channel, with a
special set of drum patches.
    MIDI files are composed of tracks. These are sort of like GMS blocks, but
they can be of any length. There are three different formats that a MIDI
file can be in. A format 0 file contains only one track, and all of the
song's data is contained within that track. A format 1 file contains
multiple tracks, all of which are played simultaneously. A format 2 file
contains multiple tracks and also a play sequence that indicates when each
track should be played.
    I have never seen a format 2 MIDI file, and the documentation I have on it
is unclear (there are indications that the format of the play sequence is
program-specific). Thus, GMS supports only formats 0 and 1. In a format 0 or
1 file, the only way to repeat part of the song is to physically duplicate
the data. This is why MIDI files tend to be large.
    When loading a MIDI file, you will need to adjust the MIDI Quantize gadget
on the MISC menu. All the commands in a MIDI file are tagged with
time-values that indicate when they should be used. The magnitude of these
time-values is more or less arbitrary, and varies from file to file. The
MIDI Quantize gadget tells the loader routine how many time-values
correspond to one GMS line.
    At the moment, only the note on, note off, and program change commands
are actually used. All other commands are ignored. No special notice is
taken of channel 10.
    When the file has been loaded, GMS will try to load GMS-format
instruments which correspond to the GM instruments used in the file. GMS
will expect to find a directory called "midi" in the current directory which
contains instruments named "midi001.gmi", "midi002.gmi", etc.



--- Instrument Formats ---

WAV
    The sound sample format commonly known as WAV ("wave") is actually a
special case of a more general format called RIFF. RIFF was created by
Microsoft as a general multimedia format. RIFF files can contain video,
audio, and synchronization data. Each type of data is stored in a section of
the file called a "chunk".
    In order for GMS to load a WAV file, the WAV chunk must be the first
chunk in the file, it must contain 8-bit data, and the audio data must be
encoded using basic PCM (Pulse Code Modulation). If the WAV file you have in
mind does not meet those requirements, you'll have to load it into a sample
editor and convert it.

RAW
    As the name implies, RAW files are raw sample data. They have no header
information, so figuring out what frequency to play them back at usually
involves making an educated guess (or sometimes just a guess). Loading
samples as RAW is also useful for dealing with files whose header
information has been mangled or is in some weird format that none of your
utilities can read.
    GMS can load files as either signed or unsigned raw data. Samples coming
from the Amiga will be in signed format, because that is the format used by
the Amiga's hardware. (As a side note, there is no standard Amiga format for
storing samples except the IFF Sound format, and that's too limited for
anyone to use.) Samples originating on the PC tend to be in unsigned format,
because the DSP on the Soundblaster and Soundblaster Pro can only handle
that format. (The Soundblaster 16 and higher can play signed samples as
well.) Loading a file with the wrong kind of signedness will make the sample
sound mangled.
    GMS will never "autodetect" a raw sample. You must explicitly tell it to
load as RAW by using the Instrument Loading gadget in the MISC menu.



                                       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 Soundtracker. 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 background 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 1000 E-3 1000 G-3 1000 --- 0000 --- 0000 --- 0000 --- 0000 C-5 2000
023    --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
024    --- 0000 --- 0000 --- 1000 --- 0000 --- 0000 --- 0000 --- 0000 G-4 2000
025    --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000
026    --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 --- 0000 C-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
