DOCUMENTATION FOR SOUND.C

Documentation dated 8/89.
Copyright (c) 1989, E.R.I.  All rights reserved.

INTRODUCTION
     SOUND.C is the source file for using the 8253 counter timer chip on the IBM
PC and compatibles.  The chip is used to generate sound on the computer's
speaker and to time intervals.  The sound is defined from approximately 20 Hz to
approximately 16 KHz.  The timer returns time in 1/100ths of seconds, but time
is only resolved to 1/18.2ths of a second.  You should think of the maximum
resolution as 1/20th second (0.05 sec).  Most of the functions in this file are
just calls to sound() with hard-wired frequency and duration arguments, so I
don't have to remember what frequency I use for a given alerting signal.

SOUND.C EXTERNALLY-VISIBLE FUNCTIONS
     The externally-visible functions in SOUND.C are declared in the header file
sound.h.  You should always include that file in programs that use these
functions.

FUNCTION: alternate_warning_sound()
TYPE: void
ARGUMENTS: none.

     alternate_warning_sound() generates a tone appropriate for alerting users
to some condition.



FUNCTION: beep_beep()
TYPE: void
ARGUMENTS: none.

     beep_beep() produces a double beep, and is useful as a "positive
reinforcement" signal.



FUNCTION: blaat()
TYPE: void
ARGUMENTS: none.

     blaat() is a low, irritating sound that we use as the "wrong answer"
signal.



FUNCTION: error_msg()
TYPE: void
ARGUMENTS:none.

     error_msg() is a generic prompt with sound effects that says that a given
entry was inappropriate.



FUNCTION: mouse_warning_sound()
TYPE: void
ARGUMENTS: none.

     mouse_warning_sound() is the tone I generate in menu.c when the user holds
a mouse button down when he should release it.



FUNCTION: pause()
TYPE: void
ARGUMENTS: one double.

     pause(duration) pauses duration seconds.



FUNCTION: read_timer()
TYPE: unsigned long int
ARGUMENTS: none.

     read_timer() returns the time of day in hundredths of a second.  Remember,
the reading is not good to better than 1/20th second, but the formnat is
hundredths.  Thus, a returned value of 1200 would be 12 seconds after midnight,
etc.



FUNCTION: ready_beep()
TYPE: void
ARGUMENTS: none.

     ready_beep() produces a quick alerting beep.



FUNCTION: sound()
TYPE: void
ARGUMENTS: one unsigned int and one double.

     sound(freq, duration) produces a sound of freq frequency for duration
seconds on the computer's speaker.