BASIC 7.80

An 80-column graphics extension
to BASIC 7.0 on the Commodore 128

The Commodore 128 comes with a very powerful BASIC: version 7.0. Like the Plus/4 and C=16, it offers easy-to-use commands for creating bitmap graphics (among other nice features). Unfortunately, these commands only work on the 40-column VIC chip. To have bitmap graphics on the 80-column VDC chip, you either need to use assembly/machine language (not recommended unless you're hard core) or you need a BASIC language extension.

A long time ago (1986, I believe), a nice solution came out called BASIC 8. It offers pretty much the same functionality as the 40-column graphic commands and it adds several unique commands. Since nobody else made an 80-column graphics extension (that I know of), it became pretty popular. Unfortunately it does have some problems. First, some tasks are more difficult (or impossible) in BASIC 8 compared to BASIC 7. Second (and for me, more important) is the syntax of BASIC 8 is 100% incompatible with BASIC 7 in regards to bitmap graphic commands (most non-graphic commands operate the same). Third, attempting to execute BASIC 7 graphic commands will actually crash the system. Fourth, it steals about 21K of BASIC RAM from Bank 0. To be fair, this is with the disk-based version; I haven't tested the ROM version to see how much RAM (if any) it steals from BASIC. Fifth, error trapping (with TRAP / RESUME) works differently... I would say it is broken, but you might find some kludgy way to work around the problems.

So this software, BASIC 7.80, is my solution. It does not add any new commands, so it is not as powerful as BASIC 8. On the other hand, all the commands are compatible with BASIC 7.0, with 3 notable exceptions: no multi-color mode, no split-screen mode, and no sprites. This is due to the hardware. In theory, sprites could be emulated very slowly in software, split-screen could be poorly emulated with CIA interrupts, but (in reality) there is no way to invoke multi-color (an emulation based on interlace might work). On a positive note, here are the commands and functions that now work in 80 column mode:

BOX
CHAR
CIRCLE
COLOR
DRAW
GRAPHIC
GSHAPE
LOCATE
PAINT
RCLR()
RDOT()
RGR()
SCALE
SCNCLR
SSHAPE
WIDTH

For more information about those commands (and functions) consult the C128 System Guide that originally came with your Commodore 128. If you don't have it, you might be able to get it from Bombjack. You might also try my on-line BASIC reference. With a few exceptions described below, those commands operate identically in BASIC 7.80, except that in 80-column mode the screen is 640 pixels wide instead of 320 pixels.

Start Up

To start using BASIC 7.80, you want to RUN the BASIC install program called "BASIC 7.80" (surprise!). This is the first program on D64 disk image, and it is also easily accessible as a raw PRG-type file in the main folder of the distribution. If you have this disk in drive 8 when the computer is turned on, it should auto-boot. When ran, it checks that high RAM in BANK 0 has not been claimed by another utility program, copies code into various parts of BANK 0, it checks the size of video RAM for your VDC chip, and then patches 4 BASIC vectors: iMain, iError, iGone, and iEval. For BASIC programming, you don't need to understand anything about those vectors (that's just some trivia for the assembly programmers out there). Anyway, it then prints a message telling you BASIC 7.80 is installed and the number of bytes available for BASIC.

If your C128 only has 16K video RAM, then the start-up message will be printed below anything else you typed on the screen. For example, below the command RUN used to start the install. If your C128 has 64K video RAM, then the VDC has to be switched to 64K mode and the fonts re-uploaded into video RAM. This memory re-arrangment also means the screen must be cleared. This is needed because some KERNALs do not set VDC RAM correctly (mainly when the V-RAM was upgraded from 16K to 64K). So you should see the start-up message at the top of a cleared screen. (If the program is run in 40-column mode, the message will not be at the top of the screen, because although the 80-column screen is cleared, the message is printed on the 40-column screen.)

In regards to system memory use (not VDC RAM), it requires more than I like, but if you only program in BASIC it shouldn't be a problem. It uses virtually all of the RS-232 buffers at $c00~$dff, virtually all of the utiltity RAM at $1300~$1bff, and about 3K of BASIC high RAM from Bank 0 (approximately $f400~$feff). Unfortunately this means that most utility programs or RS-232 programs will not work. Maybe somebody will make a ROM version without these nasty problems?! (By the way, BASIC 8 also uses all RAM in the popular $1300~$1bff utility area.)

General Use

There are 2 graphic modes that are (potentially) available with BASIC 7.80. GRAPHIC 6 is a monochrome bitmap: only two colors may be used on the entire bitmap (how restrictive!). GRAPHIC 8 is a "full color" bitmap where each 8x8 cell may have its own two colors, but this mode is only available if you have 64K of video RAM. GRAPHIC 7 and GRAPHC 9 are reserved for split-screen mode, if anybody cares to implement that! The source code is included if you want to try. (It was assembled with 'xa' by Andre Fachat on a Windows PC; 'xa' is availble for other platforms too.)

Because there is no split-screen mode, you will probably want to use an emulator that shows both 40 and 80 column screens, or have access to both video modes with your real C=128. This is because, while programming, you would have to type "blind" if you don't have access to both 40 and 80 column screens. Once you have a working program, you shouldn't need both video modes. (By the way, BASIC 8 has the same problem because it lacks split-screen as well.)

You must issue either a GRAPHIC 6 or GRAPHIC 8 command before using any of the other commands that read or write to the bitmap. Otherwise BASIC will default to the VIC screen and you will get the error NO GRAPHICS AREA (unless you previously used a VIC bitmap). You will also see NO GRAPHICS AREA if you have only 16K video RAM in these situations:

Attempting to invoke color bitmap (GRAPHIC 8)
Using bitmap commands from the 80-column text screen

Both cases are due to insufficient memory; maybe it should say OUT OF MEMORY instead? In the first case, there is not enough RAM for color attributes and the bitmap pixels. In the second case, there is not enough RAM for even a monochrome bitmap when the 80-column text mode is in use. So if you only have 16K V-RAM, you will have to use the the 40-column display if you want to enter bitmap commands in direct mode. Of course you can use the 80-column text mode to enter a program, and have the program invoke GRAPHIC 6 when it runs. (See also the debugging section later.)

If you have 64K V-RAM, then you can issue bitmap commands from the 80-column text mode, as long as you remember to first setup your 80-column bitmap. For example,

GRAPHIC 6,1 : GRAPHIC 5

will setup (and clear) the monochrome bitmap and then revert to text mode where you can issue bitmap commands if you want (you won't the see the results until you use GRAPHIC 6 to switch back to bitmap mode). Don't do this with a 16K system, because the bitmap will be lost as soon VDC text mode is invoked (GRAPHIC 5). Of course the same idea applies for color bitmaps, but in that case use

GRAPHIC 8,1 : GRAPHIC 5

When using the graphing commands (like BOX, etc.) you choose one of two selected colors for plotting pixels; the "color source" as it is called in Commodore documentation. This will be either 0 or (typically) 1. Zero is the "background" color which is why one is normally used (called the "foreground"). So a typical command would be:

BOX 1,40,40,400,140

To actually set which of the 16 possible colors is used for the foreground/background, use the COLOR command. Use COLOR 6,n to set the VDC background color (both text and bitmap) and COLOR 1,n to set the VDC foreground color (bitmap only). To set the VDC text color, use COLOR 5,n but this only works if the VDC is the active text editor. (If for some reason the VIC text editor was active, the VIC text color would be changed instead.) Kind of strange, but hey, that's how BASIC 7.0 sets the VIC and VDC text colors.

Porting Software

With BASIC 7.80, you can take any BASIC program for the 40-column high-resolution (not multi-color or split-screen) bitmap mode that has been written for the C128, Plus/4, or C=16 and very easily port it to 80-column mode. This assumes the BASIC program does not rely on any sneaky POKE or SYS commands which are hardware-specific. Essentially you just find a line that says something like GRAPHIC 1,1 and change it to GRAPHIC 6,1 or GRAPHIC 8,1. You also should change any COLOR 0,n to COLOR 6,n.

If you do just that, the program should work fine on the 80-column display. However once it is running, you may want to tweak it some more. For example, you might want to change a few COLOR statments. In particular, the VDC does not have ORANGE or MEDIUM GRAY. You might want to substitute MEDIUM GRAY with DARK CYAN (COLOR s,13 -> COLOR s,12) and replace ORANGE with BROWN (COLOR s,9 -> COLOR s,10). Of course if the program doesn't use ORANGE or MEDIUM GRAY then this is not needed.

I almost forgot! The Plus/4 and C=16 use the TED video chip which has more colors than either the 40 or 80 column screen of the C=128. This means if you are porting a program from one of those computers, then the third (luminance) parameter of the COLOR statement will be ignored and the RLUM() function is simply not available (Commodore's decision, not mine).

A slightly more difficult problem is re-sizing the output. If you don't change anything, then most programs will only draw to the left half of the screen. If the program used the SCALE command, you can probably just change that and the program will magically fill the whole screen. Unfortunately many BASIC programs do not use SCALE, so that means you would need to manually change coordinate values. I can't be very specific here, because it really depends on how the program was written. However, the general idea is that the X ordinate will be about twice the value as before; while the Y ordinate should remain unchanged.

Some sample BASIC programs are included that were ported just like described above. These are all on the D64 disk image, and available as raw PRG-type files in the distribution in the SAMPLE.BAS folder. It should be noted that two of them will give an error when run on a C=128 with the original ROMs (start-up message says copyright 1985). This is not a problem of BASIC 7.80, but of the original ROM. Specifically the parsing of values for graphic coordinates will give an error for negative values. The graphic routines were designed (and actually function) just fine when passed a negative value. It is just somebody goofed up in the original ROM and did a "float to unsigned integer" instead of "float to signed integer" conversion. That's just some assembly language mumbo-jumbo for you! If you don't know what it means, don't feel bad... the programmer(s) at Commodore didn't know either!

When Errors Occur

You can skip this section if you write 100% perfect programs on the first try. If you are like most humans, errors will slip into your code. When this happens, an error message will be printed. However if you only have 16K video RAM (really, any time you use GRAPHIC 6) then the message will be printed on the 40-column VIC screen. Unfortunately this means you can't read it unless you view the VIC screen. Yet another reason to upgrade to 64K V-RAM! This is because if an error message were to be printed to the 80-column text screen, the bitmap would have to be cleared to make room in RAM for the font and text display. Often the state of drawing on the screen gives vital clues to the error that would be lost if the bitmap were cleared (assuming the error is with graphics and not something else like a math function or disk file).

When using GRAPHIC 8 (only possible if you have 64K V-RAM), the 80-column display is switched to text mode (normally) when an error occurs. However the bitmap screen is not lost. You can just issue GRAPHIC 8 after reading the text message if you want to look at the progress (or lack thereof) of your bitmap generation.

If you are stuck with using GRAPHIC 6 and don't have a 40-column video display, here is the recommended action:

Examine the bitmap carefully to see how things are working (or not)
Press the F1 key, then the number 5, then Return. (i.e., enter the command GRAPHIC 5)
The VDC text screen will be redrawn (blank / clear the bitmap) and "READY." will appear.
- Enter the command: PRINT ERR$(ER) (this will tell you the type of error)
- Or, if the error occured in a program, you can simply press the HELP key.

The sharp readers out there already noticed I said that, when using GRAPHIC 8 bitmap, an error normally causes the VDC to switch to text mode and print the error message. This is true if you are not using the 40 column display. For example, if you start on the 80 column text display (GRAPHIC 5), change to color bitmap mode (GRAPHIC 8), and an error occurs, then the VDC will change back to text mode and print the error message. However, if you start in 40 column text, or if you use the command GRAPHIC 0 (activate 40-column text mode) after you setup the 80-column bitmap, then the error message will be printed on the 40-column screen instead (the 80-column screen will be unchanged).

That behavior may seem strange, but is is to be compatible with BASIC 7.0 which does the same thing when working with the 40-column VIC screen. For example, with BASIC 7.0 (or BASIC 7.80), if you start in 80-column text mode and generate a 40-column bitmap with GRAPHIC 1, then when an error occurs the 40-column bitmap is unchanged and the error is printed on the 80-column VDC screen. See, told you that two monitors could be useful! (Not required, but useful.)

History

Back in the late 1980's and/or the early 1990's, I made a generic language extender. It allowed you to easily add new BASIC commands and functions, and/or modify the existing ones. This was by a look-up table accessed "properly" through the vectors set-up by the operating system. This is notably different than the slower kludge of hacking the ChrGet or Error routines (often used on the C=64 and also used by BASIC 8).

In the new millenium, I got another C128 and the equipment to retrieve my software from my dying floppies. Around 2006, I was playing with the VDC and this software. I got the simple stuff working, like GRAPHIC, DRAW, BOX and CIRCLE. But then I started running out of memory (only using the $1300~$1bff area). Well I gave up on it at that point.

But recently (2013) I was playing around with VDC programming again. I was inspired by Tokra's VDC Mode Mania, and also my own attempts at video playback on the 80-column display. I guess I was frustrated with video and was looking to take a break and do something else for a while. After mentioning BASIC 7.80 to Miro (Mirkosoft), I decided I should finish it up. I got everything except RDOT() and RGR() working... or so I thought. This was late 2013 or early 2014. Anyway, he tested it and reported problems. Well here it is 2014. I fixed those problems and finally added RDOT() and RGR(). Enjoy!