NAME

tone, toneon, toneoff - tone generation routines

SYNOPSIS

#include <tone112_u.h>
#include <tone115_u.h>
#include <tone134_u.h>
#include <tone184_u.h>

tone (freq, amp, dur)
short, freq, amp, range;
unsigned dur;

toneon(freq, amp, range)
short freq, amp, range;

toneoff()

DESCRIPTION

Note that these Wavetek-based tone generation routines have largely been supplanted by DMA D/A based tone generation routines (see dmasound(3U).

The tone generation routines generate auditory stimuli of the frequency, amplitute, range and (optionally) duration specified by their parameters.

freq specifies the frequency of the tone in Hertz. The range of legal values for freq depends on the value of range such that: 

range <=freq <= range*10

An additional constraint is that: 

((((10*freq)/range)-10)*68)<2047

range corresponds to the frequency range setting on the tone generation hardware. The hardware currently in use in Department 11221 and PennPsych requires that the user select a base frequency range by setting the appropriate knob on the generator. The value of range should correspond to the setting on this knob.

amp is a number between 1 and 1023 specifiying the relative amplitude of the tone. This number is doubled and passed to D/A converter that outputs a corresponding voltage to a Voltage Controlled Amplifier (VCA). The VCA adjusts the amplitude of the tone produced by the tone generation hardware (see below). While the relationship between amp and the final amplitude of the tone is linear, amp does not represent a particular amplitude scale (e.g. dB). It is the user's responsibilty to calibrate the effective amplitudes produced.

dur specifies the duration of the tone in milliseconds. tone expects the clock to be `ticking' in milliseconds (see clock(3U) ). If the clock is not running when tone is called, tone sets the clock to tick to time a dur millisecond interval. If the clock is running at a speed other than milliseconds or in the wrong mode, tone does not produce a tone and returns -1. The tone routine expects uninterrupted processing. If interrupts that take a long time to process occur while a tone is being generated, the tone may be longer than desired.

toneon initiates the tone specified by freq, amp, and range. The tone is sustained until toneoff is called.

Tone generation hardware provides a 6 millisecond amplitude ramp for tone onset and offset.

The tone-producing routines use D/A channels 1, 2, and 3 as follows: 

Channel:	Interfaced to:
1		Wavetek frequency selector
2		Wavetek on/off trigger
3		Voltage Controlled Amplifier

SEE ALSO

dtoa(3U) , clock(3U)

DIAGNOSTICS

If any arguments to tone or toneoff are out of range, an error message is printed, no tone is generated, and the value 1 is returned.

BUGS

In toneoff, to allow the hardware to perform the amplitude decay, only the D/A channel controlling the amplitude is turned off. (In tone there is a 6 millisecond delay between turning off the amplitude and turning off the Wavetek signals). If equipment is not adjusted properly, a low amplitude signal may remain after calling toneoff.