F18A Programming Introduction

0.0 F18A Register Use Spreadsheet

The register use spreadsheet is essential to programming the F18A and shows how all the extra VDP registers are used and what features they provide.

Download the F18A_Register_Use Spreadsheet

1.0 Introduction

Programming the F18A is very similar to the original 9918A VDP.  Because the F18A is a pin-compatible replacement for the 9918A, the host system interface and all of the 9918A core functionality is identical.  If you already know how to program the 9918A, then using the enhanced features of the F18A is a simple extension of what you already know.

To be effective with this documentation I have to assume you have some basic understanding of the following:

1.  An assembly language for any systems that uses the 9918A, 9928, or 9929.

2.  The basics of binary and hexadecimal, and how, for example, “1010” in binary is equal to >A (or $A if you prefer) in hexadecimal.

3.  How bits and bytes correlate to pixel and colors.

4.  How memory addresses are represented with bits, and the place values that each bit represents.

5.  That indicating something like “2 bits per …” means there are four possible combinations, “3 bits” is eight possible combinations, etc.

None of those are really specific to the F18A, except the first item, and writing an in depth tutorial on those topics could fill a chapter or two in any book.  I might have time to write something in the future, but for right now I’m going to defer you to Google if you don’t understand some of those topics.  Trying to cover that information now would also slow down the information I’m trying to convey, i.e. programming the F18A.

1.1 Conventions and Terms

These are some conventions, abbreviations, and terms that I use throughout the documentation:

1.  MSB is Most Significant Byte.  LSB is Least Significant Byte.

2.  MSb (lower case ‘b’) or MSbit is Most Significant Bit.  LSb or LSbit is Least Significant Bit.

3.  A Byte is 8-bits, a Word is 16-bits.

4.  To represent a hexadecimal number I will use the TI 9900 convention of a greater than sign ‘>’ before the number.  The 8-bit CPU’s generally used a dollar sign ‘$’.  I apologize to those users, but the dollar sign looks as funny to me as the greater than sign probably looks to you.

5.  To write a binary digit, i.e. ‘1’ or ‘0’, I will use single quotes around the digit to distinguish it from the letter ‘L’ or the letter ‘O’.  A binary number longer than one bit will be written out and may have double quotes around it “01”, “1101”, etc.  Both of these are HDL conventions.

6.  Binary bit numbering.  For this documentation I will follow TI’s numbering convention for the bits in a byte, word, and addresses to avoid unnecessary confusion with legacy documentation.  For whatever reason, TI decided to number their bits backwards compared to the rest of the industry.  The *place value* of a bit does not change, only the numbering.  For example:


So, the MSbit *number* is seven for everyone else and zero for TI, but the *value* of the bit at that location is still 128.  The number here is still 76 no matter how the bits are numbered.  It is very important that you do not get this confused.  Getting it backwards will cause you lots of hair pulling and debugging.  If you are used to programming the 9918A already, then you should already be familiar with TI’s convention.

7.  VR is VDP Register, and VRn [n = 0..63] (VR0, VR18, etc.) represents a specific VDP Register.  VR should not be confused with ‘Rn’, i.e. R0, R1, etc. used in the TMS9900 assembly language to represent the 9900’s registers.  The F18A has sixty four VRs, numbered VR0 to VR63, however not all of the VRs are used.  VRs are all one byte is size from a programmer’s perspective.

8.  SR is VDP Status Register, and SRn [n = 0..15] is a specific Status Register.  The 9918A has only one Status Registers, while the F18A has sixteen SRs, numbered SR0 to SR15, however not all of the SRs are used.

9.  PR is an F18A’s Palette Register, and PRn [n = 0..63] is a specific Palette Register.  The F18A has sixty four 12-bit programmable palette registers, numbered PR0 to PR63.

10.  ECM is Enhanced Color Mode.  The F18A supports enhancements to the number of bits per pixel, represented by an ECM of 0 to 3, with zero being the original color mode of the 9918A, and 1, 2, or 3 being the enhanced color modes with the corresponding number of bits per pixel.  For example, ECM2 is the Enhanced Color Mode with 2-bits per pixel.  Tiles and Sprites can set their ECM independently, thus ECMT is the Enhanced Color Mode Tile, and ECMS is Enhanced Color Mode Sprite.

11.  BML is Bitmap Layer.  The F18A has a full pixel-addressable bitmap “layer” that supports 2-bits per pixel, with one byte of memory holding four pixels.  The BML is not a “mode”, it can be enabled in any of the graphics modes and can be sized and placed anywhere on the screen.  It can be roughly thought of as a big sprite with a programmable width and height, however is does not interact with the sprite layer.

12.  VRAM is VDP RAM.  This is the dedicated RAM that is used by the VDP to display the image on the screen.  The host system does not have direct access to the VRAM and must go “through” the VDP to read or write to this memory.  The VRAM holds the bit pattern, color, and attribute information used to display the tiles and sprites on the screen.

1.2 VDP Registers

The primary means to “program” the F18A is via the VDP Registers, or VRs.  The 9918A has eight “write only” (once set you cannot read the value back) VRs numbered VR0 to VR7.  The F18A supports these original VRs, plus adds about forty more VRs to provide the enhanced functionality.  By setting specific values in the VRs you can enable or disable certain VDP functionality, or change the location of various “tables” in the VRAM.

There is nothing magical about the VRs, you need to simply understand what each one controls and you will be able to use the VDP.  Some VRs control one VDP feature, like the location of a table or the horizontal scroll offset, and some VRs control multiple VDP features via specific bits in the register.

1.3 VDP Tables

The VDP’s “tables” are simply locations in VRAM where the VDP looks to get the information it needs to build up the image on the screen.  Not all the VRAM is required to display a screen, and how much VRAM is required depends on the current video mode (GM1, GM2, MCM, T40, or T80), the color mode (ECM0..3), if sprites are being used, if the BML is enabled, etc.

Certain VRs are dedicated to allowing the programmer to specify where in the VRAM certain tables will be located.  While this gives you a lot of flexibility over the use of VRAM, it also complicates the use of the VDP somewhat.  However, once you set up the location of the various tables, you generally don’t change them again during the execution of your program.

1.4 Tiles, Names, and Patterns

The 9918A, and thus the F18A, is a “tile based” VDP.  The typical graphics mode is GM1, which provides a display grid of 32×24 tiles, with each tile being displayed as an 8×8 pixel pattern.  In the 99/4A realm, the term “tile” is replaced with the term “character”.  Since I grew up on the 99/4A, “character” is my default, however it is not the term used in the 9918A datasheet or on other platforms that use the 9918A.  Therefore I will be using the term “tile” to mean a single pattern location on the 32×24 grid.

Patterns are the pixels used to represent a single tile.  A single tile in ECM0 (original 9918A color mode) requires eight bytes, 1-bit per pixel, to build up a tile’s 8×8 pixel pattern.  In ECM2 and ECM3, sixteen and twenty four bytes respectively, are required to define a tile’s pixel color.

The “name table” is a chunk of VRAM that holds the “names” of the tiles to display at a specific location on the 32×24 grid.  Since each memory location in VRAM is a single byte, each “name” is a number between 0 and 255.  Thinking of a number as a name takes a little getting used to, but it is not uncommon (OpenGL uses a similar convention for objects).

So that is the crash course on the very basics of starting to use the F18A VDP.  Next I will explain the specifics of each of the VRs used in the F18A and what each one does.  After that I’ll get into specific programming examples for each of the F18A’s specific features.  If you need more information or understanding of the 9918A’s core functionality, at this time I have to defer you to the multiple sources already available.  The 9918A datasheet itself has a lot of “programmer level” information, and there are many other texts from the various platforms that use the 9918A, i.e. ColecoVision and MSX1.  I will try to revisit some of this core information once I get the F18A specific documentation done.

4 comments to F18A Programming Introduction

  • Erik Olson

    Just got my F18A installed and working. It is great! I am looking forward to information on the new VDP registers and modes, especially details on implementing smooth scrolling. I would be willing to write some tutorials and sample code for TI-99/4A, if you can post enough bare details to go on.

    • matthew

      Great, I’m glad you like your F18A. As for programming, I’m working on the docs as fast as I can given the spare time I have right now (which unfortunately is not much). However, on the Atari Age forum (the TI-99/4A Programming subforum) I have a lot of details. The “register use” spreadsheet is a good place to start since all the new functionality is accessed via the enhanced registers.

  • Ryan

    Can you post more programming info? Looking forward to programming some ColecoVision stuff.

    • matthew

      More examples and documentation is on my TODO list. Until I get some spare time, check out the AtariAge forums, the CV and 99/4A subforums for F18A programming.