Programming the F18A: Getting Started

This is the first part of my tutorial on programming the F18A installed in an Apple II.  I cover installing the card and finding software.  Future parts will cover more interesting topics, such as the tile layer, sprites, and F18A-specific features.

Throughout, I’ll use VDP (Video Display Processor) to refer to the original TMS9918A, F18A to refer to the modern FPGA recreation of the VDP, and AppleTi to refer to the Apple II card holding the F18A.  Sometimes, I use AppleTi and F18A interchangeably since you cannot have one without the other in an Apple II.

For background, I recommend my AppleTi and F18A at KansasFest post.

Installing the AppleTi Hardware

I assume you’ve assembled your AppleTi card and are ready to make it do something interesting.  You may install it in any slot.  Unlike the vintage Synetix SuperSprite or Third Millennium Engineering Arcade Board, the AppleTi does not support combining Apple II video and sprite card video on one monitor.  Therefore, the AppleTi does not need any additional connections or have slot restrictions.  Obviously, you need a separate VGA monitor for the AppleTi.  If you have an Apple IIgs, be sure to set the slot to “Your Card” in the control panel.

Double-check the orientation of the card.  The component-side of the AppleTi should face the power supply, and the card has an arrow clearly indicating the correct orientation.  If you get the card, F18A, or 7400 IC backwards, you’ll likely be stuck repairing your computer instead of playing with graphics.

Getting the Software

I recommend the AmpArcade software originally distributed with the Arcade Board.  This software provides a convenient “ampersand vector” interface for programming the AppleTi with Applesoft BASIC.  Graphics and fast animation are usually challenging in BASIC, but the AppleTi does not share these challenges due to unique hardware features.

AmpArcade works with DOS 3.3, but I prefer ProDOS.  Specifically, AmpArcade’s memory usage conflicts with ProDOS BASIC.SYSTEM buffers.  At first, AmpArcade appears to work, but you’ll soon notice ProDOS commands failing and strange crashes.  Fortunately, this is straightforward to fix: BASIC.SYSTEM provides a GETBUFR programming interface for reserving memory in exactly the address range that AmpAracde requires.  Here’s a short program that loads AmpArcade under ProDOS:

 10  REM   Amparcade is not ProDOS compatible because it overwrites the BASIC.SYSTEM buffers.
 20  REM   This loader modifies Amparcade to function under ProDOS/BASIC.SYSTEM.
 100  REM  Step 1: Reserve memory from $8800-$9975 via a GETBUFR call to BASIC.SYSTEM.
 110  DATA  165, 14, 32, 245, 190, 96
 111  REM  LDA $E; JSR GETBUFR; RTS
 120  FOR I = 0 TO 5: READ N: POKE 768 + I,N: NEXT I: CALL 768
 200  REM  Step 2: Load Amparcade and remove inbuilt adjustment of HIMEM.  GETBUFR already did this.
 210  PRINT  CHR$ (4);"BLOAD AMPARCADE"
 220  POKE 34832,234: POKE 34833,234
 230  POKE 34836,234: POKE 34837,234
 300  REM  Step 3: Run Amparcade.
 310  CALL 34816

Download my disk image containing AmpArcade, ProDOS, and the above loader here.  After running this loader, you should see a copyright message from Third Millennium Engineering and a few garbage characters on your AppleTi video output.  The garbage is the result of AmpArcade trying to initialize sound and video switch hardware missing on the AppleTi, and you may ignore the garbage characters.  AmpArcade scans all slots and will find the AppleTi in any slot.

Look at all the Pretty Colors

AmpArcade adds “ampersand vector” commands to BASIC.  These are commands that begin with “&” and allow you to communicate with the AppleTi card.

After loading AmpArcade, we must choose a video mode and initialize the F18A.  We have several choices:

  • 40-Column Text Mode (TXT1)
  • Multi-Color Mode (MCM) – This mode is similar to Apple II lo-res graphics.
  • Graphics Mode I (GM1) – This is the most commonly used mode.
  • Graphics Mode II (GM2) – This mode extends GM1 with more flexibility in the pattern/tile layer; however, this mode is also more difficult to program.
  • 80-Column Text Mode (TXT2) – This mode is unique to the F18A and not present on the VDP.

The modes have advantages and disadvantages, but most software uses Graphics Mode I (GM1).  GM1 offers a good compromise on features and ease of use, so we’ll start with this mode.

The F18A, like the VDP, has dedicated video memory that’s separate from the Apple II memory, and the hardware offers a lot of flexibility with memory layout and usage.  AmpArcade provides four possible memory layouts for GM1, labelled A, B, C, and D.  Memory layout matters for advanced uses, but they don’t matter for our application.  We’ll arbitrarily choose layout A:

REM Initialize Graphics Mode I, memory layout variant A.
&GM1A

Next, we’ll set the backdrop color, which is the color that appears behind everything else we draw.

&BCOL,13

The integer (13) selects a color from among 15 possible choices:

# Color Sample
0 Transparent (the absence of color) (transparent)
1 Black
2 Medium green
3 Light green
4 Dark blue
5 Light blue
6 Dark red
7 Cyan
8 Medium red
9 Light red
10 Dark yellow
11 Light yellow
12 Dark green
13 Magenta
14 Gray
15 White

So, we can create a simple program that cycles through the available colors:

FOR C=1 TO 15 : &BCOL,C : NEXT C

Notice how fast the colors change.  Try modifying the code to wait for a key press before advancing to the next color.

This is it for part 1.  We’ve figured out how to initialize the AppleTi and show pretty backdrop colors.  Next, we’ll investigate the pattern layer, also known as the tile layer.  This capability allows us to display text and is the heart of backgrounds in most games.