BASIC Examples

AVAILABLE AS OF 4/30/2022: COCOVGA BASIC EXTENSIONS. Documentation here. Download here. If these BASIC extensions don't provide the desired features, please read on.

There are a few options available for interfacing CoCoVGA software mode controls with BASIC. Because the software mode controls operate through exact timing with vsync, it's necessary to have some sort of machine language routine involved.

Some tools and routines have been created to help with this. One such tool is CCVCONF (for CoCoVGA Configuration) on the UTILS.DSK image.

Creating a BASIC-Loadable CoCoVGA Configuration Using CCVCONF

Below is a method by which you may edit your CoCoVGA palette colors and then be able to restore them from within your own BASIC games or utilities.

  1. Mount the UTILS.DSK image in your drive and run CCVCONF.BAS.
  2. Press <P> to enter the palette editor.
  3. Use <S> to rotate through the color options of the 6847 text display to edit.
    Use <E> to enable an alternate (non-6847 default) color or <D> to go back to the 6847 default. Once <E>nabled, use the red/green/blue sliders to change the color.
    Press any of <R>, <G>, or <B> to select the component to change and then either use the up- and down-arrow keys or the numbers from 0 to 7 to select the amount of the component's level.
  4. Once you are satisfied with your color selections, press <Q> to quit from the palette editor.
  5. Press <S> to save your CoCoVGA configuration. (Note that it is possible to save many other customizations, however, this example is oriented towards the color palette.)
  6. Press <S> again to pick a filename to save the config to. Type the filename without extension and hit <ENTER>. For this example, we will use the filename EXAMPLE.
  7. Press <Q> to quit from CCVCONF.BAS.
  8. Now, if you use DIR to look at your drive's directory listing, you should see new files which start with the filename used earlier. In this example, 2 files should be found, EXAMPLE.DAT (the configuration itself) and EXAMPLE.BAS (a BASIC loader for the configuration). These were the files written out by CCVCONF.
  9. You may now copy these EXAMPLE.DAT and EXAMPLE.BAS files, along with the machine code routine SG4PG2.BIN to wherever you need them. You can run EXAMPLE.BAS following boot to enable the desired CoCoVGA configuration or you may merge the 4 lines of BASIC code within EXAMPLE.BAS with your own BASIC program.

Some Technical Details

In this example, the SG4PG2.BIN machine language routine will be loaded starting at address $6C00. The EXAMPLE.DAT configuration image will be loaded at $7000. This means that enough space needs to be set aside for these. The upside, however, is that if a static configuration is desired, all of this memory between $6C00 and ($7000 + 512 = $71FF) may be recovered after the configuration is uploaded to CoCoVGA.

If a dynamic configuration is desired, wherein the CoCoVGA mode changes throughout your game or utility, you can attack that in either of two ways:

  • Create multiple configurations using CCVCONF.BAS and save each one out as a new filename. Then, in your BASIC program, simply LOADM the configuration and call A=USR0(INT(&H7000/512)).
    - OR -
  • Use the offsets described on Software Mode Control in the CoCoVGA register addresses to poke into the region between $7000 and $71FF to alter your configuration and then call A=USR0(INT(&H7000/512)).

How the BASIC CoCoVGA Configuration Loader Works

In the example above, 3 files were needed. Two of them were generated from CCVCONF and the other was already on the UTILS.DSK for use by CCFCONF and any resulting configuration.

SG4PG2.BIN

This is a binary machine language routine which is used to upload the configuration to CoCoVGA

EXAMPLE.DAT

This is a binary configuration data file which matches the offsets described in http://cocovga.com/documentation/software-mode-control/

EXAMPLE.BAS

10 'COCOVGA CONFIGURATION
20 'GENERATED VIA CCVCONF
30 LOADM"SG4PG2.BIN"
40 DEFUSR0=&H6C00
50 LOADM"EXAMPLE.DAT"
60 A=USR0(INT(&H7000/512))

In the BASIC configuration loader code, above:

  1. Lines 10 and 20 are comments and may be ignored
  2. Line 30 loads the machine language binary utility to address $6C00.
  3. Line 40 configures BASIC to understand that $6C00 is the entry point for the machine language routine we just loaded when USR0 is invoked
  4. Line 50 loads the EXAMPLE.DAT CoCoVGA configuration image into address $7000-$71FF.
  5. Line 60 calls the machine language routine SG4PG2.BIN which in turn unlocks CoCoVGA during the vertical blanking period, programs the SAM to point to the configuration while the next video screen is being fed to CoCoVGA, and then at the following vertical blanking period, switches the SAM back to point to the video RAM to be displayed.