GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/demo/dosound/effdocs.lst

File List | 1992-03-26 | 12KB | 238 lines

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.