"sound"

"sound" activates the speaker.


Format:		(XCALL "sound" <select> <freq> <duration> <freq-1> <freq-2>)

Parameters:	<select> is a number in the range 0..4 which determines
		which sound command to execute.

		<freq> is the frequency in Hz.  Very low and very high
		frequencies are mapped to 20 Hz.  This number is used for
		timer control of the speaker.

		<duration> is a number in the range 1..65535.
		Zero is mapped to 65536.  The speaker is activated for 
		this many "ticks".

		<freq-1>, <freq-2> are numbers in the range 1..65535.
		Zero is mapped to 65536.  These numbers are used
		for manual control of the speaker, and the sum 
		<freq-1> + <freq-2> determines the size of 1 "tick".
		The length of a tick is processor-speed dependent.

		All arguments are optional.  Once given, they remain in effect
		until explicitly changed.  Also, the meaning of some arguments
		may vary depending on <select>.

Explanation:	The PC has limited sound generation capabilities, lacking,
		among other things, volume control, multiple voices, and
		envelope control.  The only control is over the pitch and
		duration of a sound.  However, the PC provides two different
		ways for generating pitches, which can be combined for a
		sort of timbre control, and even volume can be simulated.

		The first approach uses the timer chip.  After being set
		to a given frequency, the timer can run the speaker
		independently of the processor.  Since processor speed
		does not affect the timer, a given set of parameters run on
		machines of different speeds will yield identical sounds.

		The second approach is to control the speaker yourself.
		This amounts to you pushing the speaker cone in and out
		at the appropriate rate.  Since the rate at which you can
		do this depends on the processor speed, a given set of
		parameters run on machines of different speeds will give
		different sounds.

		The two approaches can be combined, where you drive the
		speaker at one rate while the timer drives it at a
		different rate.  This adds timbre to the sound, making it
		more interesting.

		<select> = 0 selects overall sound control.  <freq> = 0
		disables sound commands and <> 0 enables them.  The speaker
		is turned off.  Sound is initially enabled.

		<select> = 1 selects timer control.  The <freq> is the
		frequency in Hz of the sound to be generated.  The sound
		lasts for <duration> ticks, except for <duration> = 0,
		which leaves sound running while control returns to Scheme.

		<select> = 2 selects manual control.  <freq> is ignored--any
		number will do as a placeholder.  The sum <freq-1> + <freq-2>
		determines the pitch through the use of delay loops.  The
		speaker is off for a delay count of <freq-1> and on for
		<freq-2>.  Different sums adding up to the same number 
		give various timbres to the basic pitch.  Larger sums decrease
		the pitch--doubling the sum will drop the sound one octave,
		for example.  The sound lasts for <duration> ticks before
		returning to Scheme.

		<select> = 3 combines 1 and 2.  The timer superimposes its
		<freq> value on top of the manual control.  Otherwise,
		operation is the same as selection 2.




		<select> = 4 turns off the speaker.  If <freq> = 0, the
		speaker is turned off and control returns immediately to
		Scheme.  If <freq> <> 0, control returns only after 
		<duration> ticks.

Examples:	(XCALL "sound" 0 1)
			;enable sound commands if they were disabled

		(XCALL "sound" 1 440 2000 200 200)
			;on any computer, gives the "A" (= 440 Hz) 
			;above middle C.  The last 3 parameters are duration
			;values--increasing them give longer durations.
			;The sum 200+200 determines the length of 1 tick
			;and the sound lasts for 2000 ticks.

		(XCALL "sound" 1 256)
			;an example of defaulting--the frequency changes
			;to middle C (= 256 Hz) and other parameters are
			;unchanged

		(XCALL "sound" 2 256 200 1075 1075)
			;on a TI Business-Pro (turbo mode), gives roughly the
			;same "A" above middle C.  The sum 1075+1075 determines
			;the pitch and the sound lasts for 200 ticks.  
			;The "256" argument is ignored.

		(XCALL "sound" 3 256 200 1075 1075)
			;sounds similar to previous example except now a
			;256 Hz sound (middle C) is superimposed

		(XCALL "sound")
			;repeats the previous sound

		(XCALL "sound" 1 440 0)
			;sound "A" and return to Scheme, leaving the sound on

		(XCALL "sound" 4 0)
			;turn off the sound