// iigs/sound.h - convenience wrappers for the SoundManager toolset.
//
// What's here today: the simplest correct wrappers around the existing
// toolbox calls — SysBeep, FFStartSound on a pre-loaded DOC RAM region,
// FFStopSound, FFSoundDoneStatus polling.  Lower-level than std::sound
// but a thin layer above iigs/toolbox.h.
//
// What's NOT here: arbitrary in-RAM sample → DOC RAM upload.  The
// SoundManager wants samples already staged in the Ensoniq DOC's
// 64 KB of dedicated audio RAM.  That involves WriteRamBlock and
// bank-tracking work that's bigger than the convenience this header
// is meant to provide.  Use the raw toolbox.h calls if you need that.
//
// Caller must have started up the SoundManager before any of these
// functions are called.  startdesk() in iigs/desktop.h does that for
// you; if you're not using the desktop framework call SoundStartUp()
// yourself first.
#ifndef IIGS_SOUND_H
#define IIGS_SOUND_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>


// SoundParm block consumed by FFStartSound.  Layout per Apple Tech
// Note #51 / Sound Manager reference.  Fields in struct order — DO
// NOT reorder; the toolset reads by offset.
typedef struct {
    uint8_t  waveStart;     // DOC RAM page where the waveform begins ($00..$FF, 256-byte units)
    uint8_t  waveSize;      // wave length in 256-byte pages
    uint16_t freqOffset;    // pitch offset added to the channel's base freq
    uint8_t  volume;        // 0..255
    uint8_t  channel;       // 0..15, channel pair for stereo
} __attribute__((packed)) IigsSoundParmT;


// ---- one-call wrappers --------------------------------------------

// System beep.  Same as the toolbox SysBeep but named consistently.
void iigsBeep(void);


// Play a sample that has already been written into DOC RAM.  Returns
// immediately (asynchronous); use iigsSoundWait() to block until done.
//   docPage  the DOC RAM page where the sample starts ($00..$FF, 256-
//            byte units).
//   pages    length in 256-byte pages.
//   pitch    DOC pitch byte ($00..$FF; higher = lower-pitched).
//   volume   0..255.
//   channel  0..15 — generator pair.
void iigsPlayDocSample(uint8_t docPage, uint8_t pages,
                       uint8_t pitch, uint8_t volume, uint8_t channel);


// Stop playback on the given generator (0..15).  Pass 0xFF to stop
// all generators.
void iigsSoundStop(uint8_t generator);


// Block until generator 0 finishes playing.  Polls FFSoundDoneStatus.
void iigsSoundWait(void);


#ifdef __cplusplus
}
#endif

#endif  // IIGS_SOUND_H