Files
VCCPlusOSS/sdk/cmoc/include/vcc/ssc.h
T

114 lines
6.2 KiB
C

// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_SSC_H
#define VCC_SSC_H
// CoCo guest interface to the Tandy Speech/Sound Cartridge.
// The command latch is shared. Give one foreground producer exclusive access
// until each phrase or effect has been submitted, including the terminator.
#define SSC_OK 0
#define SSC_TIMEOUT 1
#define SSC_INVALID 2
#define SSC_PENDING 3
#define SSC_READY 0x80
#define SSC_SPEECH_IDLE 0x40
#define SSC_EFFECT_IDLE 0x20
#define SSC_MAX_TEXT 62
// Raw documented status bits. Test SSC_READY before every output byte. The two
// IDLE signals can take time to respond after an execution command. Reading
// this port cannot reliably detect a cartridge on every physical CoCo.
unsigned char ssc_status(void);
unsigned char ssc_try_write(unsigned char value); // 1 submitted, 0 busy
// Choose the cartridge input on the CoCo audio mux and enable the speaker.
// Restore the saved token after playback. Joystick/cassette routines share
// this mux: after any that change it, reselect the cartridge for listening.
// Keep the original token for the final restore. These calls preserve PIA IRQ
// settings. Neither call resets the cartridge or waits for sound to finish.
unsigned int ssc_route_audio(void);
void ssc_restore_audio(unsigned int saved);
// Reset the cartridge, discarding speech, effects and saved cartridge buffers.
// Use explicitly to recover from an interrupted/partially timed-out command.
void ssc_reset(void);
typedef struct {
const char *next;
unsigned char remaining;
} ssc_phrase;
// Say 1..SSC_MAX_TEXT printable ASCII characters. Lowercase letters are sent
// as uppercase. A space and carriage return are supplied. Keep text unchanged
// until SSC_OK from ssc_service; ssc_begin_phrase sends nothing. Service once
// per main-loop iteration; each call attempts at most one byte. SSC_OK means
// submitted. Allow the firmware time to start playback before testing IDLE.
unsigned char ssc_begin_phrase(ssc_phrase *phrase, const char *text);
unsigned char ssc_service(ssc_phrase *phrase);
// Synchronous submission with a maximum number of status polls PER BYTE.
// A zero limit returns SSC_TIMEOUT without writing. Text is reusable upon
// return. The sound can still be playing. On timeout some bytes may already
// have been submitted; reset before starting an unrelated command.
unsigned char ssc_say(const char *text, unsigned int poll_limit);
// Play a fixed-amplitude effect using cartridge sound buffer 0, replacing its
// contents. Channels A/B/C are 0/1/2, volume is 0..15. Tone period is 1..4095;
// noise period is 0..31. Duration (0..255) uses the cartridge's current timer
// base. Both effects include a final silence. The per-byte poll limit has
// the same meaning as in ssc_say.
unsigned char ssc_play_effect(unsigned char channel, unsigned int period,
unsigned char volume, unsigned char duration,
unsigned int poll_limit);
unsigned char ssc_play_noise(unsigned char channel, unsigned char period,
unsigned char volume, unsigned char duration,
unsigned int poll_limit);
// Stored English text and allophones share eight speech slots, numbered 0..7.
// Play a slot with the function matching the data most recently stored there.
// Slots are volatile cartridge RAM. Store once, then play repeatedly. Loading
// sends no execute command. SSC_OK from play means submitted, as for ssc_say.
// Wait for playback to finish before replacing a slot that is in use.
unsigned char ssc_store_phrase(unsigned char slot, const char *text,
unsigned int poll_limit);
unsigned char ssc_play_phrase(unsigned char slot, unsigned int poll_limit);
// SP0256-AL2 allophone addresses, in chip order. PA1..PA5 are pauses.
// Use unsigned char arrays for pronunciations. Each element occupies one byte.
enum {
SSC_AL_PA1 = 0, SSC_AL_PA2, SSC_AL_PA3, SSC_AL_PA4, SSC_AL_PA5, SSC_AL_OY, SSC_AL_AY, SSC_AL_EH,
SSC_AL_KK3, SSC_AL_PP, SSC_AL_JH, SSC_AL_NN1, SSC_AL_IH, SSC_AL_TT2, SSC_AL_RR1, SSC_AL_AX,
SSC_AL_MM, SSC_AL_TT1, SSC_AL_DH1, SSC_AL_IY, SSC_AL_EY, SSC_AL_DD1, SSC_AL_UW1, SSC_AL_AO,
SSC_AL_AA, SSC_AL_YY2, SSC_AL_AE, SSC_AL_HH1, SSC_AL_BB1, SSC_AL_TH, SSC_AL_UH, SSC_AL_UW2,
SSC_AL_AW, SSC_AL_DD2, SSC_AL_GG3, SSC_AL_VV, SSC_AL_GG1, SSC_AL_SH, SSC_AL_ZH, SSC_AL_RR2,
SSC_AL_FF, SSC_AL_KK2, SSC_AL_KK1, SSC_AL_ZZ, SSC_AL_NG, SSC_AL_LL, SSC_AL_WW, SSC_AL_XR,
SSC_AL_WH, SSC_AL_YY1, SSC_AL_CH, SSC_AL_ER1, SSC_AL_ER2, SSC_AL_OW, SSC_AL_DH2, SSC_AL_SS,
SSC_AL_NN2, SSC_AL_HH2, SSC_AL_OR, SSC_AL_AR, SSC_AL_YR, SSC_AL_GG2, SSC_AL_EL, SSC_AL_BB2
};
#define SSC_MAX_ALLOPHONES 62
// Provide 1..62 codes in the range 0..63. The SDK adds the final quiet pause
// and terminator. Invalid input leaves the slot alone. After a timeout during
// a load, use ssc_reset and reload your buffers before issuing new commands.
unsigned char ssc_store_allophones(unsigned char slot, const unsigned char *codes,
unsigned int count, unsigned int poll_limit);
unsigned char ssc_play_allophones(unsigned char slot, unsigned int poll_limit);
// Store a single tone using the AY's hardware volume envelope, followed by
// silence on that channel. Sound slots 0..7 are separate from the speech slots.
// ssc_play_effect and ssc_play_noise replace sound slot 0. Channel is 0..2,
// tone period is 1..4095, shape is 0..15, envelope period is 1..65535.
// Envelope period controls the fade rate; duration (0..255) is in the current
// cartridge timer units. The one envelope generator is shared by all channels.
#define SSC_ENV_DECAY 0 // loud to silent once
#define SSC_ENV_REPEAT_DECAY 8 // repeating downward ramp
#define SSC_ENV_REPEAT_RISE 12 // repeating upward ramp
#define SSC_ENV_TRIANGLE 14 // repeating rise and fall
unsigned char ssc_store_enveloped_tone(unsigned char slot, unsigned char channel,
unsigned int tone_period, unsigned char shape,
unsigned int envelope_period, unsigned char duration,
unsigned int poll_limit);
unsigned char ssc_play_stored_effect(unsigned char slot, unsigned int poll_limit);
#endif