CoCoVGA BASIC Extension

Introduction

The CoCoVGA BASIC Extension (CCVBASIC) was initially created in early 2022 as a way to help gain access to CoCoVGA enhancements using DECB without having to worry about loading USR() routines to call and to avoid management of a shadow copy of CoCoVGA registers.

Requirements

CCVBASIC requires a 64k CoCo 1 or 2 with Extended Color BASIC and CoCoVGA. FPGA revision 0.92 is recommended, but some features may operate on earlier revisions.

Usage

To load this extension on your 64k Color Computer 1 or 2 (first step assumes usage of a CoCoSDC):

DRIVE0,"CCVBASIC
LOADM"CCVBASIC
EXEC

The commands implemented by the CoCoVGA BASIC Extension include:

  1. VRESET
  2. VPALETTE slot, red, green, blue, now
  3. VFONT font, lowercase, inversevideo
  4. VARTIFACT coloron, swap, mode
  5. VBORDER mode, quiet
  6. VLOADCHARS [address]
  7. VSCANLINES on
  8. VWIDTH width

VRESET

VRESET accepts no arguments and updates the CoCoVGA shadow register bank to reset CoCoVGA back to power-on defaults. It issues the CoCoVGA program sequence, so results are immediate.

VPALETTE slot, red, green, blue, now

VPALETTE requires 5 comma-separated arguments:

  1. Palette slot number
  2. Amount of red component (max 31, min 0)
  3. Amount of green component (max 31, min 0)
  4. Amount of blue component (max 31, min 0)
  5. Immediate (1) or delay (0)

The palette slot number can be calculated from http://cocovga.com/documentation/software-mode-control/ using the CoCoVGA register addresses section. Specifically, slot = (page_0_register_address - 32) / 2. A few examples:

  • Byte addresses 32 and 33 contain semigraphics palette slot 0 (typically black): (32-32)/2 = 0
  • Byte addresses 34 and 35 contain semigraphics palette slot 1 (typically green): (34-32)/2 = 1
  • Byte addresses 64 and 65 contain artifact (or VG6) palette slot 0: (64-32)/2 = 16

Alternatively, use the following table:

Slot Number Controls
0 black SG and text (unless VFONT color is 2)
1 green SG and text (unless VFONT color is 2)
2 yellow SG
3 blue SG
4 red SG
5 buff SG
6 cyan SG
7 magenta SG
8 orange SG
9 dark green SG
10 dark orange SG
16-31 CSS 1 artifact (buff, black, red, blue, etc.) and VG6
31-47 CSS 0 artifact (greens) and VG6
48 text foreground (when VFONT color is 2)
49 text background (when VFONT color is 2)
50 border color (when VBORDER mode is 3)
51 scanline color (when VSCANLINES on is 1)

The now argument controls whether VPALETTE only programs the CoCoVGA shadow register bank in your CoCo's RAM (0) or also issues the CoCoVGA program sequence (1). Delaying issue of the CoCoVGA program sequence can be useful for palette cycling animations in which modification of multiple palette slots at the same time is desirable.

To change a single color immediately, in this example, red (slot 4) to green-blue (teal):

VPALETTE 4,0,31,15,1

To change 3 colors (black to gray, green to blue, yellow to red), but only apply the changes during the last palette slot write:

VPALETTE 0,15,15,15,0
VPALETTE 1,0,10,31,0
VPALETTE 2,31,0,0,1

VFONT font, lowercase, color

VFONT affects the text and semigraphics video modes and requires 3 integer arguments:

  1. font selects between:
    1. the original 6847 character set (0)
    2. the 6847T1 a.k.a. XC80652 character set (1)
    3. a character set uploaded to CoCoVGA character RAM (see VLOADCHARS) (2)
  2. lowercase enables (1) or disables (0) lowercase characters. Note that this is ignored when font is 2 (using CoCoVGA character RAM).
  3. color enables (1) or disables (0) reverse video text, or alternatively applies font foreground and background colors (palette slots 48 and 49, respectively) when set to 2. When enabled, this effectly swaps usage of palette slots 0 and 1 or 0 and 8, depending on CSS as in SCREEN 0,CSS.

VFONT issues the CoCoVGA program sequence, so results are immediate.

VARTIFACT coloron, swap, mode

VARTIFACT affects appearance of the PMODE 4 (RG6) video mode. It requires 3 integer arguments:

  1. coloron enables (1) or disables (0) artifact colors. When disabled (0), coloron causes CoCoVGA to produce monochrome video. This must be enabled in order for swap and mode to have an effect on appearance.
  2. swap is either 0 or 1 and selects between the two different clock phase alignments in the CoCo. This swaps the red and blue colors.
  3. mode selects between the following:
    1. all enhancements off - full 256x192 resolution in 4 colors (0)
    2. fat bits - double-wide pixels, 4 colors (1)
    3. smartifact - 6 tap filter, 8 colors (2)
    4. MESS - Multi-Emulator-Super-System emulator 6-tap filter, 16 colors (3)

VARTIFACT issues the CoCoVGA program sequence, so results are immediate.

VBORDER mode, quiet

VBORDER controls border appearance. It requires 2 integer arguments:

  1. mode selects between the following:
    1. standard 6847-style border color (0)
    2. 6847T1-style border color (1)
    3. disable border - always black (2)
    4. override with custom border colors using extra palette border slots (3)
  2. quiet disables video mode change status updates. A value of 1 turns off these pop-up notifications whereas a value of 0 leaves them on.

VBORDER issues the CoCoVGA program sequence, so results are immediate.

VLOADCHARS [address]

VLOADCHARS takes a single optional address argument. This address is a pointer to the start address of a 3072-byte character set previously loaded into RAM. If no address is supplied, &HE00 is used. This is a common default location for character sets to be loaded while in 32-column text mode. This load address can be reconfigured in the header of the character set .CHR file itself using CCVEDIT.

The &HE00 region is used by BASIC for graphics or 64-column text mode, so if access to multiple character sets within a single program invocation is desired, a suggested location for another 3072 byte region is between &HE000 and &HEBFF. (See address map, below.)

Example:

LOADM"LOWERKIT.CHR
VLOADCHARS
VFONT 2,0,0

VLOADCHARS issues the CoCoVGA program sequence, so results are immediate.

VSCANLINES on

VSCANLINES requires a single integer argument. A value of 1 turns on scanline emulation. A value of 0 turns off scanline emulation.

VSCANLINES issues the CoCoVGA program sequence, so results are immediate.

VWIDTH width

VWIDTH requires a single integer argument which must be either 32 (for 32-column text mode) or 64 (for 64-column text mode).

Note that a patch to Color BASIC and Extended Color BASIC is applied for 64-column mode and then reverted upon returning to 32-column mode when using VWIDTH 32. Also, when in 64-column text mode, the video RAM is 2048 bytes in size and starts at &HE00, as opposed to 32-column text mode of 512 bytes in size and starting at &H400.

VWIDTH issues the CoCoVGA program sequence, so results are immediate.

Currently Known Bugs

Rev 0.1

  1. Custom border colors not operational because extra palette not enabled in VBORDER mode = 3.
  2. Custom scanline colors not operational because extra palette not enabled when VSCANLINES on = 1.
  3. Extra palette generally inaccessible per 1 and 2, above, as well as with custom text colors.
  4. VRESET does not revert the BASIC patch applied when 64-column text mode is entered. Therefore, it's necessary to potentially reset the CoCo and EXEC again to reapply the CCVBASIC extension patch.
  5. CSS is sticky while in 64-column text mode. This means that SCREEN 0,1, when applied, does not revert automatically to SCREEN 0,0 as it does in 32-column text mode.

Rev 0.2

  1. Resolved custom border color issue from rev 0.1, enabling VBORDER mode = 3.
  2. Resolved custom scanline color issue from rev 0.1.
  3. Enabled access to extra palette for above and custom text colors.
  4. VRESET has been repaired to unpatch if CoCoVGA and the ROM patch is in 64-column mode.
  5. Sticky CSS issue in 64-column mode is still present.

Theory

The CoCoVGA BASIC Extension reuses the WIDTH64 patch methodology for reconfiguring BASIC to optionally use a 64x32 character console (see http://www.cocovga.com/resources/presentations/CoCoVGA_TandyAssembly2017.pptx) as needed as well as learnings from:

  • Color Basic Unravelled II
  • Extended Basic Unravelled II - COMVEC (per William Astle)
  • Disk Basic Unravelled II
  • Pierre Sarrazin's (http://sarrazip.com/) newcmd.c
  • Cooking with CoCo September 1984 (per R. Allen Murphy)

Patch Process (ccvbasic.c -> CCVBASIC.BIN)

  1. Enter all-RAM mode while copying BASIC ROMs to upper RAM at the same address
  2. Load ccvbasov.s (CCVBASOV.BIN) overlay into upper RAM between the Disk ROM and I/O space. This overlay contains:
    1. new instruction subroutines,
    2. command string lookup table, and
    3. token lookup table
  3. Update user command table hook at 0x13e (COMVEC+30) with information such as:
    1. number of instructions provided by CCVBASOV.BIN
    2. the command string lookup table
    3. the token interpreter routine, which indexes into a table in order to branch to the command routine of interest
  4. Call initialization function in CCVBASOV.BIN
  5. Display banner with version and copyright information

Memory Map

CCVBASIC uses the 64k RAM in the following way:

0x0000 - 0x0DFF - CB, ECB, and DECB RAM, including 32-column text mode console (0x0400-0x05FF)
0x0E00 - ...... - hi-res graphics pages (also, typical CoCoVGA 64-column text mode video and charset temporary load address)
...... - 0x7FFF - user space and stack
0x8000 - 0x9FFF - ECB ROM (remapped to RAM and copied)
0xA000 - 0xBFFF - CB ROM (remapped to RAM and copied)
0xC000 - 0xDFFA - Disk ROM (remapped to RAM and copied)
0xEC00 - 0xEDFF - CoCoVGA shadow register bank
0xEE00 - 0xF28D - CoCoVGA BASIC command tables (strings/tokens) and subroutines
0xFF00 - 0xFFFF - Peripheral I/O area