// SPDX-License-Identifier: GPL-3.0-or-later #ifndef VCC_ORCH90_H #define VCC_ORCH90_H // One frame, in playback order. Each DAC accepts a level from 0 through 255. struct orch90_frame { unsigned char left; unsigned char right; }; #define ORCH90_CLOCK_NORMAL 0 #define ORCH90_CLOCK_FAST 1 // Set both DAC levels. The hardware holds them until another write. void orch90_write(unsigned char left, unsigned char right); // Foreground playback at approximately 4,000 stereo frames/second on a CoCo 3. // Set clock to the CURRENT guest CPU speed. This call leaves that speed, // interrupt masks and timers alone. Interrupt handlers may delay playback. // frames must be CPU-readable and remain mapped for the entire call. // The last frame remains latched. A valid empty block succeeds without writes. // Returns 1 on success, 0 for a bad clock, missing data or an address wrap. // Success confirms the data was sent; this write-only hardware has no ID. unsigned char orch90_play(const struct orch90_frame *frames, unsigned int count, unsigned char clock); // Start asynchronous playback on a CoCo 3 BASIC-based setup. Each stereo // frame lasts four serviced scanlines (about 3,930 frames/s at NTSC timing). // loop: 0 plays once, 1 repeats. count must be nonzero. Keep the whole frame // array readable, mapped and unchanged until playback ends. Keep the program, // its stack and its interrupt handler resident. Call from the foreground. // // clock must describe the current CPU clock. The player uses fast speed for // the duration and restores that setting when done. It borrows the stock BASIC // IRQ trampoline and PIA horizontal IRQ. IRQ and BASIC's vertical IRQ must // be enabled and HSYNC free. Sampling begins on the second vertical interrupt. // Keep these resources exclusive, including the DACs and clock, and allow IRQs // to run. Long interrupt masks or PIA reads can delay audio. BASIC's vertical // interrupt still runs. The GIME timer and FIRQ vector are untouched. // Returns 1 when started, 0 on refusal (including another active playback). unsigned char orch90_start(const struct orch90_frame *frames, unsigned int count, unsigned char loop, unsigned char clock); // 1 while playing, 0 when idle. A one-shot releases its resources after the // final sample interval. The two write-only DACs then rest at midpoint 128. unsigned char orch90_active(void); // Stop immediately and release the IRQ and clock. Safe when already idle. // Always stop before returning to BASIC, unloading or remapping active data. void orch90_stop(void); #endif