Publish VCC Plus OSS source distribution for 3.6.2 build 60

This commit is contained in:
Brian Holman committed 2026-11-13 00:14:03 -07:00
commit c652a5276d
1192 files changed
+272368

No files matched your search

+31
View File
@@ -0,0 +1,31 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_BANK_H
#define VCC_BANK_H
#define BANK_FIRST_PAGE 0x28
#define BANK_PAGE_SIZE 8192u
#define BANK_CAPACITY 32768u
// Claim the BASIC program's dedicated physical blocks $28-$2B ($50000-$57FFF).
// The caller reserves this RAM for assets. Opening and closing do not clear it.
// Requires stock CoCo 3 BASIC task 0, 512 KiB or more, and a normal CMOC layout
// below $8000. On RAM expansions retain BASIC's default $FF9B bank/prefix and
// map; these write-only settings cannot be reconstructed after custom paging.
// Compatible with gime_open(). Use from foreground code; open with IRQ enabled.
// Return 1 on success, 0 for an unsupported setup or a second open.
unsigned char bank_open(void);
// Transfer exactly length bytes at a byte offset measured from BANK_FIRST_PAGE.
// A transfer may span pages. The complete range must fit BANK_CAPACITY.
// Supply a caller-owned C buffer entirely below $8000; read requires writable
// data, write accepts const data. A zero length needs no buffer and permits
// offset == BANK_CAPACITY. Return 1 on success or 0 before copying any bytes.
// Between calls both MMU tasks and the normal expansion group must stay under
// BASIC's control. Each short copy restores the CPU mapping and interrupt mask.
unsigned char bank_read(unsigned offset, void *destination, unsigned length);
unsigned char bank_write(unsigned offset, const void *source, unsigned length);
// Release the claim. Safe to repeat. RAM contents survive until reused/reset.
void bank_close(void);
#endif
+27
View File
@@ -0,0 +1,27 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_CASSETTE_H
#define VCC_CASSETTE_H
#define VCC_TAPE_OK 0
#define VCC_TAPE_EOF 1
#define VCC_TAPE_IO (-1)
#define VCC_TAPE_INVALID (-2)
#define VCC_TAPE_LONG (-3)
#define VCC_TAPE_BUSY (-4)
#define VCC_TAPE_TYPE (-5)
// One foreground stream at a time. Position the tape and select Record or
// Play before opening. Names are 1-8 printable ASCII characters and are
// case-sensitive, as in BASIC. The guest cannot confirm recording at the port.
int vcc_tape_open_write(const char *name);
int vcc_tape_write_line(const char *line); // printable ASCII, adds one CR
int vcc_tape_open_read(const char *name);
int vcc_tape_read_line(char *line, unsigned capacity); // capacity includes NUL
int vcc_tape_close(void);
// Read returns OK for a complete line (including a blank line), EOF only for
// a checked end block (a final text fragment is delivered first), LONG after
// consuming an oversized line, and IO for a damaged or incomplete recording.
// An unsuccessful read leaves line empty.
// Close releases a reader even after an error and finishes a writer's tape.
#endif
+17
View File
@@ -0,0 +1,17 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_DECIMAL_H
#define VCC_DECIMAL_H
#if !defined(_COCO_BASIC_) || defined(_CMOC_MC6839_) || defined(_CMOC_NATIVE_FLOAT_)
#error vcc_fixed requires the CoCo BASIC floating-point backend
#endif
// Write value with 0 through 3 decimal places. Its magnitude must be below
// 65536 before rounding. Round the represented value to nearest, with ties
// away from zero. A rounded zero is unsigned. Link with vcccompat.
// Return the full character count, excluding the terminator. If capacity is
// positive, write a terminated prefix. NULL is valid only for zero capacity.
// Return -1 for a bad argument or range, emptying a writable destination.
int vcc_fixed(char *dest, unsigned capacity, float value, unsigned char places);
#endif
+35
View File
@@ -0,0 +1,35 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_GIME_H
#define VCC_GIME_H
#define GIME_WIDTH 320
#define GIME_HEIGHT 192
// Open from ordinary IRQ-enabled CoCo 3 BASIC text (WIDTH 32, 40 or 80).
// Requires 512 KB or more, the standard BASIC MMU task 0 and video RAM group,
// and a CMOC program, globals and stack below $8000. Reserve physical RAM
// $40000..$4FFFF for both pages. Opening clears the images in that RAM.
// Raw video/MMU register changes and interrupt-handler calls are unsupported.
// Returns 1 on success, 0 for unsupported hardware/state or an existing session.
unsigned char gime_open(void);
// Draw into the hidden page. Its contents persist when it becomes hidden again.
// Coordinates are unsigned, rectangles are clipped at the right and bottom.
// Empty rectangles, colors above 15 and draws outside a session do nothing.
void gime_plot(unsigned x, unsigned y, unsigned char color);
void gime_fill_rect(unsigned x, unsigned y, unsigned w, unsigned h, unsigned char color);
void gime_clear(unsigned char color);
// Set one of the 16 shared palette entries immediately (GIME six-bit color).
// Out-of-range slots/colors and calls outside a session do nothing.
void gime_set_palette(unsigned char slot, unsigned char rgb);
// Wait for the next BASIC vertical interrupt, then display the finished page.
// Returns 0 if closed or the field timer fails to advance. A failed presentation
// leaves the displayed and drawing pages alone.
unsigned char gime_present(void);
// Restore BASIC's text display and its original palette. Safe to repeat.
void gime_close(void);
#endif
+32
View File
@@ -0,0 +1,32 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_INPUT_H
#define VCC_INPUT_H
#define INPUT_RIGHT 0
#define INPUT_LEFT 1
#define INPUT_PRIMARY 1
#define INPUT_SECONDARY 2
typedef struct {
unsigned char port; // Set by input_init.
unsigned char x, y; // 0..63, increasing to the right and down.
signed char dx, dy; // -1 below 26, 0 from 26 through 37, +1 above 37.
unsigned char held; // Buttons down in this sample.
unsigned char pressed; // Buttons newly down since the preceding sample.
unsigned char released; // Buttons newly up since the preceding sample.
} VccInput;
// Sample the chosen port to establish a baseline. A button already down is
// held, with no press or release event. Use separate state for each player.
// An invalid port gives a neutral, inactive state. A null pointer is ignored.
void input_init(VccInput *input, unsigned char port);
// Take one foreground sample per game update. Transitions between samples
// cannot be observed. Test button fields with INPUT_PRIMARY / INPUT_SECONDARY.
// Uses the standard CoCo analog joystick circuit in BASIC PIA configuration.
// Restores the sound gate, mux, DAC and keyboard column output before return.
// The short PIA transaction masks IRQ/FIRQ and uses normal data-register reads
// (which can acknowledge PIA interrupt flags). Link input followed by bcontrol.
void input_sample(VccInput *input);
#endif
+52
View File
@@ -0,0 +1,52 @@
// 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
+16
View File
@@ -0,0 +1,16 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_PRINTER_H
#define VCC_PRINTER_H
#include <stdarg.h>
// Send formatted text to the CoCo BASIC serial printer from foreground code.
// Use the same integer, character and string conversions as vcccompat snprintf.
// Each C newline goes to the ROM as a carriage return. The return value counts
// formatted characters submitted, up to 32767, or is -1 for a format/count
// error. A prefix may already have been sent. The guest cannot tell whether
// the host captured, saved or printed the report. Link with -lvcccompat.
int vcc_printer_printf(const char *format, ...);
int vcc_printer_vprintf(const char *format, va_list args);
#endif
+51
View File
@@ -0,0 +1,51 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#ifndef VCC_SDC_H
#define VCC_SDC_H
#define SDC_OK 0
#define SDC_END 1
#define SDC_UNAVAILABLE 2
#define SDC_TIMEOUT 3
#define SDC_INVALID 0x84
#define SDC_IO 0x88
#define SDC_NOT_FOUND 0x90
#define SDC_IN_USE 0xa0
#define SDC_PROTECTED 0xc0
#define SDC_READ_ONLY 0x01
#define SDC_DIRECTORY 0x10
typedef struct {
char name[13]; // NUL-terminated 8.3 basename (or "..").
unsigned char attributes;
unsigned long size; // Bytes; zero for a directory.
} SdcEntry;
// Foreground calls from a normal low-memory CMOC program under CoCo 3 BASIC.
// The SDC-DOS cartridge must supply both the selected ROM and I/O. Each
// operation restores normal controller mode and the caller's interrupt mask.
unsigned char sdc_probe(void);
// Start one card-directory search. NULL or "" lists the current directory.
// Use "/" for the card root, e.g. "/GAMES/*.DSK" for a filtered listing.
// Paths use printable ASCII and must fit within 253 bytes. A new search
// replaces the previous one. The card's current directory stays unchanged.
unsigned char sdc_list_begin(const char *pattern);
// Return one entry, SDC_END after the last, or an error. The controller has
// one listing cursor: finish before another program or routine starts a list.
unsigned char sdc_list_next(SdcEntry *entry);
// Inspect drive 0 or 1. SDC_NOT_FOUND means no image is mounted. Entry output
// is valid only on SDC_OK. name is the image basename, including extension.
unsigned char sdc_mounted(unsigned char drive, SdcEntry *entry);
// Mount an image by its exact 8.3 guest filename (including its extension),
// optionally within card directories. Close any files using the target drive
// and finish any decbfile session with a cached FAT before changing media.
// Mounting uses the controller listing cursor and ends the previous search.
// An empty name is invalid. Never ejects or creates media as a fallback.
// After a transport timeout, query the drive before retrying the operation.
unsigned char sdc_mount(unsigned char drive, const char *path);
#endif
+113
View File
@@ -0,0 +1,113 @@
// 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