DoEffect

  The DoEffect program is a utility designed to create sound effects for 
the Atari Sound Chip.  Up to 10 sound effects can be created and saved as 
one file.  Each sound effect may have up to four frames of information.  
Each frame may have up to three special looping messages.  Each frame may 
be repeated up to three times, and each effect may be repeated up to nine 
times.

Frames:

  One frame of information is defined as one set of values for all thirteen
of the sound chip registers.  The idea is that with each sound effect, you 
can change any or all of the sound chip registers up to four times.

Loops:

  Within each frame you can specify up to three special looping messages.  
A looping message allows you to cycle through a series of values for one of
the thirteen sound chip registers.  These loops require the following 
information:

  The register to loop at (0-13).
  The initial value for the register (0-255).
  The direction of the loop (positive or negative).
  The value to increment with (0-127).
  The final value for the register that should end the loop (0-255)

  Any of the Sound Chip registers may be specified as the register to loop 
at.  In order for the loop to be activated, the button in the top left of 
the dialog box must be selected.  This allows you to turn loops on and off 
for testing.  When a frame is played back, each of the three loops that are
active will be played successively.  That is to say that after loop one is 
completed, loop two will begin, and after loop two is done, loop three will
begin.

  The possibilities for these loops are almost endless.  An example for 
their use is to create a siren.  This would be done by specifying register 
0 (for example) with an initial value of 0, a positive increment of 1, and 
a final value of 255.  When played back, the tone for channel A will cycle 
from a tone of 0 to 255 in increments of 1.  Each 'step' in the loop process
last for 1/50 of a second, so in this example, the loop will last for about
5 seconds.  It is worth noting that if a bad combination of initial value, 
increment, and final value is specified, the final value may never be 
reached, creating an endless loop.  However, this may be used creatively 
for special purposes.

  It is also important to note that when you are looping at a register 
which is complemented with another register to achieve some result (such 
as register 0, which is only the low byte of the tone period for channel A),
the complementary register must be considered to understand the resulting 
effect.  For example, let us consider the looping message described above 
for register 0.  If the tone period for channel A was specified as say 479 
within the frame,  the loop in register 0 will actually cause the channel 
A tone to cycle through the values of 256 to 511.  This is because register
1 will be loaded with the high nibble of 479 which is 256.  Register 0 will
cycle through the values of 0 to 255, but they will be added to the value 
of register 1 to create the tone for channel A.  If the desired effect is 
to actually cause the tone for channel A to cycle from 0 to 255, then a 
tone period of less than 256 must be specified so that register 1 is loaded
with the value of 0.

  One last note on loops.  When the loop is completed, the initial value 
specified for that register before the loop began is placed back into that 
register.

Play:

  When a frame is played back, all of the values specified for the thirteen
registers are played first (with the durations specified).  Then the loop 
message for that frame are played.  Then the entire frame is repeated by 
the number of times specified (if greater than one).  For each effect, this
process is then repeated for each frame.  Then if the entire effect is to 
be repeated more than once, the whole process is repeated the number of 
times specified.  The following diagram shows this process.

   Do Effect-Repeat times.
      Do Frame-1-Repeat times.
         Play initial registers.
         Play Loop 1.
         Play Loop 2.
         Play Loop 3.
      End Do.
      Do Frame-2-Repeat times.
         Play initial registers.
         Play Loop 1.
         Play Loop 2.
         Play Loop 3.
      End Do.
      Do Frame-3-Repeat times.
         Play initial registers.
         Play Loop 1.
         Play Loop 2.
         Play Loop 3.
      End Do.
      Do Frame-4-Repeat times.
         Play initial registers.
         Play Loop 1.
         Play Loop 2.
         Play Loop 3.
      End Do.
   End Do.

If the Effect is inactive, nothing will happen.  If a frame is inactive, 
it will be skipped.  If a loop is inactive for a frame, it will be skipped.
To play an effect, either click on the play button with the left mouse key 
or hit the enter key on the keyboard.

Active:

  Any or all of the frames within an effect may be activated or inactivated
with the active button.  If a frame of information is inactive, it will not
be played.  Some effects may not need four frames of data.  Therefore the 
un-needed frames should be deactivated.  The active state of a frame is 
also useful for testing and pinpointing undesirable results.  An active 
frame is indicated by black text, while an inactive frame is indicated by 
light text.  The active frame is indicated by a solid button.  To switch 
frames, simply click on another frame button with the left mouse key.

Edit Effect:

  Any or all of the effects may be activated or deactivated with the Edit 
Effect button.  An inactive frame cannot be played.  The Edit Effect button
also permits you to assign a name to an effect as well as see how many
bytes are needed to play the effect.  An active effect is indicated by 
black text, while an inactive frame is indicated by light text.  The active
effect is indicated by a solid button.  To switch effects, simply click on 
another effect button with the left mouse key.

Copy:

  Frames of information may be copied from one frame to another, or from 
one frame to the clipboard.  All of the information pertaining to that 
frame is copied including the loop messages.  If you wish to copy a frame 
from one effect to a frame in another effect, use the clipboard.  To do 
this, select the desired effect which contains the frame to be copied.  
Click on the Copy button and select the frame number to be copied as the 
source and select the clipboard as the destination.  Now switch to the 
effect that you want to copy this information to.  Select the Copy button 
again and select the clipboard as the source and the frame number you wish 
to copy to as the destination.

Setting the Registers:

  Setting the various Sound Chip registers is quick and easy.  All of the 
buttons are provided on one screen.  There are four sections of the screen 
(shaded differently) for each logical group of information.  There is one 
section for each of the three tone channels.  Within each of these sections,
you specify the tone, volume, and duration of that channel.  The current 
values are displayed next to the text for each item.  These values are 
changed by clicking on the arrow buttons next to each value.  Each click 
of the mouse key changes the value by one in the direction of the arrow 
clicked on.  A double click of the left mouse key on these arrows will 
change the value for that item to its maximum or minimum value depending 
on which arrow is double clicked on.  Holding down either of the two shift 
keys while clicking on the arrows which control the tone and duration has 
a special meaning.  If the left shift key is held down, the values will be 
incremented by ten.  If the right shift key is held down, the values will 
be incremented by five.

  For tone, the range of values are from 0 to 4096.  For volume, the range 
of values are from 0 to 16.  A volume of 0 to 15 indicates a solid tone, 
while a volume of 16 indicates to use the wave envelope and envelope period 
to control the volume.  For duration, the range of values are from 0 to 255
(the duration is measured in 1/50's of a second).  A duration of zero means 
to ignore that channel completely.

  For each tone channel, there are also two buttons used to control the 
enabling for that channel.  To enable a channel for tone, the Enable Tone 
button must be a solid color.  To enable a channel for noise, the Enable 
Noise button must be a solid color.  These buttons are turned on and off 
by clicking on them with the left mouse key.  

  The fourth box of information controls the wave parameters and noise 
period value.  There are eight wave forms available, displayed graphically. 
The active wave envelope is inverted in color.  To change wave envelopes, 
simply click on the desired pattern with the left mouse key.  The current 
envelope period is displayed below the wave envelope buttons.  This is an 
editable text field where you can type in any number (values greater than 
65535 will be considered as 65535).  Below the envelope period is the noise
period.  The range of values for the noise period are from 0 to 31 and are 
changed by clicking on the arrow buttons next to the current noise period 
value.  

Musical / Period:

  The Musical and Period buttons control the way the tone periods for the 
three tone channels are displayed.  In the Musical state, the tones are 
displayed as in musical notation, such as C#3.  The first character 
indicates the note, followed by the accidental, followed by the octave.  
If no accidental is displayed, it is a natural note.  In the Musical state,
the lowest note is C0 and the highest is C7 (although the note can be 0 
which means no tone).  In the Period state, the entire range of tones that 
the Sound Chip can play are accessible.  If you switch from the Period 
state to the Musical state, the tone will be changed to the closest Musical
note (the period value will be changed accordingly).  If you are in the 
Period state, the arrow buttons used to control the tone may at first seem 
backwards.  Since a lower tone period means a higher pitch, the down arrow 
button increases the tone period, while the up arrow button decreases the 
tone period.

Load:

  Loads a previously saved file of ten effects from a disk file.

Save:

  Saves the current ten effects to a disk file.  There are two types of 
files created.  One file with the extension .EFC is the file that DoEffect 
can re-load later so that you may continue to work on it.  This file 
contains all of the information for every effect, frame and loop, whether 
it is active or inactive.  The second file created has the extension .INL.  
This particular file has a header containing the number of effects and 
their offsets, followed by the binary code necessary to replay them.  
Thus the binary code will not contain any information for effects, frames 
and loops which were not active when saved.  This file can be used to 
merge the sound effects you have created into your own programs.  The 
EFFECTS.LST file included with this package shows you how to read the .INL 
file into your programs.

Print:

  Prints the data for the active effect to the printer.  The values 
printed are the actual bytes of code needed by the operating system 
to play that effect.  The code is in XBIOS(32) interrupt format.  

Show:

  Similar to Print except that the data is displayed on the screen.

New:

  Erases from memory all of the information for the current 10 effects.

Quit:

  Quits the DoEffect program.