/*  File:         sound.h
 *  Created:      20-10-95
 *  Updated:      30-12-95
 *  Version:      1.0
 *  Project:      Clicker
 *  Owner:        Jeroen Vermeulen
 *  Requirements: KickStart V39+
 *  Legal:        PD
 *  Status:       Release
 */

#define SAMPLELENGTH 12



/* CreateSample():
 * Open audio device and sample.  An IOAudio structure is returned unless either
 * an error occurs or the error string was already non-NULL before the call.
 */
struct IOAudio *CreateSample(STRPTR *const error);


/* Destroy sample and free all resources allocated with it.  This function is
 * overly robust so it can be used from within CreateSample() in case of an
 * error.
 */
void DeleteSample(struct IOAudio *const soundrequest);


/* KeyClick():
 * Make key-click noise.  The soundrequest pointer is assumed to be valid and
 * non-NULL, and point at a properly initialized IOAudio structure.
 */
void KeyClick(struct IOAudio *const soundrequest);


/* SliderToHertz():
 * Converts a prefs window slider position (between -5*12 and 4*12) to a
 * frequency in Hertz, based on a twelve-tone octave centered at the 440 Hz A.
 * This function is forced to take an unused Gadget parameter and to return LONG
 * because it is passed to gadtools.library as a hook function.
 */
LONG SliderToHertz(const struct Gadget *const dum, const WORD sliderpos);


/* HertzToPeriod():
 * Converts human-readable pitch in Hertz to period length suitable for use by
 * audio.device.  As a rule, HertzToPeriod(SliderToHertz(S)) is equivalent to
 * SliderToPeriod(S).
 */
UWORD HertzToPeriod(const LONG Hertz);


/* PeriodToHertz():
 * Converts audio.device period length to human-readable pitch in Hertz.  This
 * is the inverse of HertzToPeriod().  It needs to return LONG, so exact Hertz
 * settings aren't possible.
 */
LONG PeriodToHertz(const UWORD period);


/* SliderToPeriod():
 * Converts a prefs window slider position (between 0 and 9*12) to a period
 * length (in units of 279.365 nanoseconds) suitable for use by audio.device.
 */
UWORD SliderToPeriod(const WORD sliderpos);


/* PeriodToSlider():
 * Inverse of SliderToPeriod().  Takes a period length as an argument and
 * computes the appropriate slider position (between -5*12 and 4*12).  This
 * function can afford to be slow because it's only ever called when the prefs
 * window pops up.
 */
WORD PeriodToSlider(const UWORD period);