VGA¶

Video Graphics Array

Introduction¶

The RP6502 Video Graphics Array (VGA) is virtual video hardware modeled on the home computers and arcades of the 8-bit and early-16-bit era. A program sets it up with a few register writes and puts the graphics in XRAM. From then on, the VGA system draws the video canvas on its own while the 6502 keeps running the program.

It has the parts that the games of that era were built from. Text in cells, tile maps, and bitmaps all scroll to the pixel. Sprites in 1-, 2-, 4-, or 8-bit color can each have their own palette, and sprites in 16-bit color can rotate and scale. Three planes stack all of these from back to front, with transparency, so a status bar can sit over a scrolling playfield. A plane can also switch from a bitmap to text partway down the screen, without a scanline interrupt.

Getting Started¶

Your program draws on the canvas, a grid of pixels such as 320x240. The VGA system has six rendering modes:

Mode	Draws
Mode 0	The console, with the text that your program prints.
Mode 1	Colored text in cells, for menus and status bars.
Mode 2	A tile map, for the playfield of a game.
Mode 3	A bitmap, in which every pixel can be its own color.
Mode 4	Sprites in 16-bit color, which can rotate and scale.
Mode 5	Sprites in 1-, 2-, 4-, or 8-bit color, each with its own palette.

A mode can render on only a portion of the canvas, a range of scanlines (rows of pixels). This lets you program several modes, one below another, without using interrupts.

Most modes need a configuration structure in XRAM. It holds the address of the mode’s data and where that data goes on the canvas. The console, mode 0, needs nothing in XRAM.

Putting a picture on the canvas takes four steps.

1. Select a canvas, for example with xreg_vga_canvas(CANVAS_320X240). You get a blank canvas, with no scanlines programmed.

2. Load the data into XRAM: a bitmap, a tile map and its tiles, or sprite images, plus any palette or font that they use.

3. Write the configuration structure for each mode into XRAM. For a sprite mode, write its sprite array.

4. Program the scanlines with mode macros, such as xreg_vga_mode3(). Each call programs a range of scanlines with one mode.

Here are the four steps in a program, the start of a graphical text adventure. It splits the canvas in two: a picture at the top, and the console under it, where you type. The split takes just two calls.

A 320 by 240 canvas. Mode 3 draws a bitmap of sky and grass on scanlines 0 to 159, and mode 0 draws the console on scanlines 160 to 239.

You lay out XRAM in your program’s xram.h, which XRAM Memory Map in the SDK covers in full. The file below makes room for the bitmap and its configuration structure. The comment at the top lists the code blocks to copy in from this page. After them comes the layout, xram_layout_t, with a member for each thing in XRAM. It is the only part that you write yourself:

xram.h¶

// From the Programming part of the VGA page, copy the
// code blocks of Canvas Types, Mode 0, and Mode 3 here.

typedef struct
{
    uint8_t bitmap[320u * 160];
    mode3_config_t bitmap_config;
} xram_layout_t;

#define XRAM_BITMAP offsetof(xram_layout_t, bitmap)
#define XRAM_BITMAP_CONFIG offsetof(xram_layout_t, bitmap_config)

The two compilers differ only in how the program fills in the configuration structure:

llvm-mos

main.c¶

#include <rp6502.h>
#include <stdio.h>
#include "xram.h"

int main(void)
{
    mode3_config_t config;
    char line[40];

    // 1. Select a canvas.
    xreg_vga_canvas(CANVAS_320X240);

    // 2. Load the data: sky, then grass.
    xram0_set(XRAM_BITMAP, 111, 320u * 110);
    xram0_set(XRAM_BITMAP + 320u * 110, 34, 320u * 50);

    // 3. Write the configuration structure.
    config = (mode3_config_t){
        .width_px = 320,
        .height_px = 160,
        .xram_data_ptr = XRAM_BITMAP,
        .xram_palette_ptr = 0xFFFF,
    };
    xram0_write(XRAM_BITMAP_CONFIG, &config, sizeof(config));

    // 4. Program the scanlines: the bitmap above, the console below.
    xreg_vga_mode3(MODE3_8BPP, XRAM_BITMAP_CONFIG, 0, 0, 160);
    xreg_vga_mode0(0, 160);

    puts("\fYou are standing in an open field.");
    while (1)
    {
        printf("> ");
        fgets(line, sizeof(line), stdin);
        puts("Nothing happens.");
    }
}

cc65

main.c¶

#include <rp6502.h>
#include <stdio.h>
#include "xram.h"

int main(void)
{
    mode3_config_t config;
    char line[40];

    // 1. Select a canvas.
    xreg_vga_canvas(CANVAS_320X240);

    // 2. Load the data: sky, then grass.
    xram0_set(XRAM_BITMAP, 111, 320u * 110);
    xram0_set(XRAM_BITMAP + 320u * 110, 34, 320u * 50);

    // 3. Write the configuration structure.
    config.x_wrap = false;
    config.y_wrap = false;
    config.x_pos_px = 0;
    config.y_pos_px = 0;
    config.width_px = 320;
    config.height_px = 160;
    config.xram_data_ptr = XRAM_BITMAP;
    config.xram_palette_ptr = 0xFFFF;
    xram0_write(XRAM_BITMAP_CONFIG, &config, sizeof(config));

    // 4. Program the scanlines: the bitmap above, the console below.
    xreg_vga_mode3(MODE3_8BPP, XRAM_BITMAP_CONFIG, 0, 0, 160);
    xreg_vga_mode0(0, 160);

    puts("\fYou are standing in an open field.");
    while (1)
    {
        printf("> ");
        fgets(line, sizeof(line), stdin);
        puts("Nothing happens.");
    }
}

That is a lot to take in at once, and you do not need to understand every line yet. Each step below points to where this page explains it.

Step 1 selects the 320x240 canvas. Canvas Types lists the other canvas sizes that you can choose.

Step 2 draws the picture in XRAM. The first call to xram0_set() makes the sky: 110 rows of color 111, a light blue. The second makes the grass under it: 50 rows of color 34, a green. Both colors come from the built-in palette. In 8-bit color, each byte is one pixel, so each row is 320 bytes. Mode 3: Bitmap describes how pixels pack into bytes at every color depth.

Step 3 fills in the bitmap’s configuration structure and copies it into XRAM. The structure holds the bitmap’s size, 320x160, and where the bitmap is in XRAM. To use the built-in palette, the program sets the palette address to $FFFF. Mode 3: Bitmap declares mode3_config_t and explains each member. The llvm-mos program sets just four members, because C99 designated initializers set the rest to 0. cc65 does not have designated initializers, so its program sets every member.

Step 4 programs the scanlines, and the picture appears. xreg_vga_mode3() puts the bitmap on scanlines 0 to 159. xreg_vga_mode0() puts the console on the scanlines from 160 down. It leaves off END, so the console runs to the bottom of the canvas. The first 0 in each call is the plane, which Planes describes. Modes explains the range of scanlines, and Mode 3: Bitmap and Mode 0: Console give each macro’s arguments.

Last, the program prints “You are standing in an open field.” Then, after each line that you type, it prints “Nothing happens.” This is a placeholder for the text adventure that the program could become.

How It Works¶

Everything starts with the canvas, which is made of three planes stacked back to front. Modes render on the layers of the planes, where each scanline can have its own mode. Most modes read a structure in XRAM to know what to draw. VSYNC is about timing: when to change the picture so that it doesn’t tear.

Canvas¶

The canvas is where you draw your picture, on a grid of pixels such as 320x240. Your program selects its size from six choices: 320x240 and 640x480, which are 4:3, 320x180 and 640x360, which are 16:9, and 320x200 and 640x400, which are 16:10. Canvas Types gives the CANVAS value of each size.

The size that you choose is the resolution that you draw at. Standard VGA is 640x480, so on a VGA display, the VGA system scales a 320x240 canvas up to 640x480. The emulator scales the canvas to fit its window. Any canvas size works on any display.

In this manual, a scanline is one row of the canvas, not a line of the display. The display almost always shows the canvas scaled up, so its lines rarely match the rows of the canvas. To the program, the display renders as many scanlines as the canvas has rows: a 320x240 canvas has 240 scanlines, even on a 640x480 display.

Your ROM starts on the console canvas, which shows only the console and cannot be programmed. Before you draw, select a graphics canvas in one of the six sizes. It starts blank, without even the console. Anything that you print stays hidden until you put mode 0 on a plane. When your ROM stops, the VGA system goes back to the console canvas.

Planes¶

The VGA system draws the canvas from three planes. Each plane has two layers: one for a fill mode, such as text, tiles, or a bitmap, and one for a sprite mode, drawn over the fill. The six layers stack like the layers of an image editor, with plane 0 at the back and plane 2 at the front. In the figure, a program draws a picture on plane 0, a tile map on plane 1, and a status bar on plane 2, with sprites on each.

A pixel in a transparent color shows the layer behind it. The fill layer of plane 0 is at the back of the stack, so it ignores transparency and draws every pixel in its own color. Where no layer draws, the canvas is black. Colors and Palettes describes which colors are transparent.

The VGA system has a fixed time for each scanline, which limits how many sprites it can draw. On a canvas 320 pixels wide, it can usually draw more sprites than the 6502 can move each frame. If you’re planning a game with a lot of sprites, read Sprite Limits in PORT first.

Modes¶

Each mode’s section in Programming provides a macro and constants for that mode. The macro programs scanlines with the mode, making the xreg() call for you. This line from the earlier text adventure puts an 8-bit bitmap on plane 0, on scanlines 0 to 159:

xreg_vga_mode3(MODE3_8BPP, XRAM_BITMAP_CONFIG, 0, 0, 160);

Every name in this line comes from your xram.h: the macro and MODE3_8BPP from the code block of Mode 3: Bitmap, and XRAM_BITMAP_CONFIG from your layout. A macro takes its arguments in the order of the register table in its mode’s section. Modes 1 to 3 take these:

OPTIONS holds the mode’s options, such as its color depth. MODE3_8BPP selects 8-bit color.
CONFIG is the XRAM address of the configuration structure.
PLANE is the plane, 0 to 2.
BEGIN and END set the range of scanlines.

The sprite modes add LENGTH after CONFIG. Their CONFIG is the XRAM address of the sprite array, and LENGTH is the number of sprites in it. Mode 0 takes only PLANE, BEGIN, and END.

BEGIN is the mode’s first scanline, and END is one past its last, so BEGIN 0 and END 160 cover scanlines 0 to 159. With an END of 0, the mode runs to the bottom of the canvas. Arguments that you leave off the end of a call are 0, so xreg_vga_mode3(MODE3_8BPP, XRAM_BITMAP_CONFIG) puts mode 3 on plane 0, over the whole canvas.

You can reprogram scanlines at any time. When you change scenes, say from a bitmap to a tile map, program the same scanlines with the new mode, and it replaces what its layer had there. The other scanlines keep their modes. To start a scene from a blank canvas, select the canvas again.

Structures¶

After you program the scanlines, you change the picture by changing XRAM. Write a new position into a configuration structure, and the image scrolls. Write a sprite’s new position into its sprite array, and the sprite moves. Write new pixels into a bitmap, and the picture changes. You can make these changes at any time, without programming the scanlines again.

In modes 1 to 3, the configuration structure gives the XRAM address of the image and its palette, the size of the image, where it goes on the canvas, and whether it repeats. The section of each mode lists the members of its structure.

An image does not have to be the size of the canvas. A smaller image covers part of the canvas. Unless the image wraps, the layer around it is transparent. A larger image shows only the part that is on the canvas. A game that scrolls sideways, for example, uses a tile map wider than the canvas and changes x_pos_px on each frame.

BEGIN and END set which scanlines a mode draws on, but they do not move its image. For example, if a bitmap is at position 0, 0 and you program scanlines 100 and down with mode 3, you see the bitmap’s rows from row 100 down, not its top rows. To show its top rows there, set y_pos_px to 100.

A sprite mode reads a sprite array in place of a configuration structure. This code moves sprite n of a mode 5 sprite array at XRAM_SPRITES to x, y:

unsigned addr = XRAM_SPRITES + n * sizeof(mode5_sprite_t);
xram0_poke16(addr + offsetof(mode5_sprite_t, x_pos_px), x);
xram0_poke16(addr + offsetof(mode5_sprite_t, y_pos_px), y);

A sprite later in the array covers the sprites before it, so put the sprites that you want in front at the end of the array. To hide a sprite, move it off the canvas.

VSYNC¶

The VGA system draws the canvas one scanline at a time, from the top down, 60 times a second. A change to XRAM appears on the next scanline that the VGA system draws. If you change an image partway through a frame, that frame can show the top of the old image and the bottom of the new one. To change the whole picture at once, make your changes between frames. VSYNC, short for vertical sync, marks the start of that time.

The time between frames is a legacy of CRT displays. A 640x480 VGA signal is really 800x525, with 640x480 of it visible. The rest is blanking: time for the beam of the CRT to return to the left edge after each line, and to the top after each frame. Games of that era updated the picture while the beam went back to the top. A Picocomputer program does the same. The RP6502-PICO still sends a real VGA signal, and the other machines keep its timing.

After the VGA system draws the lowest scanline that you have programmed, it sends a VSYNC signal. VSYNC increments the RIA’s VSYNC register and, if you enable it, fires the VSYNC interrupt. Most programs wait for VSYNC in a loop. ria_vsync() returns the value of the VSYNC register without waiting, so the loop calls it until the value changes:

unsigned char frame = ria_vsync();
while (ria_vsync() == frame)
    ;

With 640x480 timing and a 4:3 canvas, the 45 lines of vertical blanking last about 1.4 ms. That’s roughly 11,000 cycles of a 6502 at 8 MHz to get a change in before the first scanline. Changes lower on the canvas have longer. Video Timing gives the time for every canvas and display.

Programming¶

From here on, this page is a reference. It covers everything that you can program the VGA system to do: colors and palettes, the canvas types, and each mode. Each section gives the code blocks to copy into your xram.h or xram.inc, and explains what each macro and register does.

Configuration structures, sprite arrays, and palettes must start at even XRAM addresses. The rp6502_align() call in your CMakeLists.txt checks them, as Symbols in CMake in the SDK describes.

Colors and Palettes¶

Each color is a 16-bit RGB555 value: 5 bits each of red, green, and blue, and an alpha bit. Set the alpha bit, and the color is opaque. Clear it, and the color is transparent.

The code blocks below define COLOR_FROM_RGBA, a macro that builds a color. It takes red, green, blue, and alpha from 0 to 255, and an alpha of 128 or more makes the color opaque. This is opaque red:

uint16_t red = COLOR_FROM_RGBA(255, 0, 0, 255);

xram.h (see XRAM Memory Map)¶

#define COLOR_FROM_RGBA(r, g, b, alpha)                             \
    ((((unsigned)(b) >> 3) << 11) | (((unsigned)(g) >> 3) << 6) | \
     (((unsigned)(alpha) >> 7) << 5) | ((unsigned)(r) >> 3))

ca65

Address	Name	Description
$1:0:01	MODE	0 - Console
$1:0:02	PLANE	The plane, 0-2.
$1:0:03	BEGIN	The first scanline.
$1:0:04	END	One past the last scanline, or 0 for the height of the canvas.

Address	Name	Description
$1:0:01	MODE	1 - Character
$1:0:02	OPTIONS	bit 0:2 - 0=1, 1=4 reversed, 2=4, 3=8, or 4=16 bit color bit 3 - font size 0=8x8, 1=8x16
$1:0:03	CONFIG	The XRAM address of the configuration structure.
$1:0:04	PLANE	The plane, 0-2.
$1:0:05	BEGIN	The first scanline.
$1:0:06	END	One past the last scanline, or 0 for the height of the canvas.

Member	Description
`x_wrap`, `y_wrap`	When `x_wrap` is true, the cells repeat across the canvas. When `y_wrap` is true, they repeat down the canvas.
`x_pos_px`, `y_pos_px`	Where the top left pixel of the first cell goes on the canvas. They can be negative, so the cells can start above or to the left of the canvas.
`width_chars`, `height_chars`	The number of cells across and down.
`xram_data_ptr`	The XRAM address of the cells.
`xram_palette_ptr`	The XRAM address of the palette, or $FFFF for the built-in palette.
`xram_font_ptr`	The XRAM address of the font, or $FFFF for the built-in font.

Address	Name	Description
$1:0:01	MODE	2 - Tile
$1:0:02	OPTIONS	bit 0:2 - 0=1, 1=2, 2=4, or 3=8 bit color bit 3 - 0=8x8, 1=16x16 bit 4:7 - X trim, columns to drop from the right of each tile (0-15) bit 8:11 - Y trim, rows to drop from the bottom of each tile (0-15)
$1:0:03	CONFIG	The XRAM address of the configuration structure.
$1:0:04	PLANE	The plane, 0-2.
$1:0:05	BEGIN	The first scanline.
$1:0:06	END	One past the last scanline, or 0 for the height of the canvas.

Member	Description
`x_wrap`, `y_wrap`	When `x_wrap` is true, the map repeats across the canvas. When `y_wrap` is true, it repeats down the canvas.
`x_pos_px`, `y_pos_px`	Where the top left pixel of the map goes on the canvas. They can be negative, so the map can start above or to the left of the canvas.
`width_tiles`, `height_tiles`	The number of tiles across and down the map.
`xram_data_ptr`	The XRAM address of the map.
`xram_palette_ptr`	The XRAM address of the palette, or $FFFF for the built-in palette. Every tile of the map uses this palette.
`xram_tile_ptr`	The XRAM address of the tiles.

Address	Name	Description
$1:0:01	MODE	3 - Bitmap
$1:0:02	OPTIONS	bit 0:2 - 0=1, 1=2, 2=4, 3=8, or 4=16 bit color bit 3 - reverse the order of the pixels in each byte
$1:0:03	CONFIG	The XRAM address of the configuration structure.
$1:0:04	PLANE	The plane, 0-2.
$1:0:05	BEGIN	The first scanline.
$1:0:06	END	One past the last scanline, or 0 for the height of the canvas.

Member	Description
`x_wrap`, `y_wrap`	When `x_wrap` is true, the bitmap repeats across the canvas. When `y_wrap` is true, it repeats down the canvas.
`x_pos_px`, `y_pos_px`	Where the top left pixel of the bitmap goes on the canvas. They can be negative, so the bitmap can start above or to the left of the canvas.
`width_px`, `height_px`	The size of the bitmap, in pixels.
`xram_data_ptr`	The XRAM address of the bitmap.
`xram_palette_ptr`	The XRAM address of the palette, or $FFFF for the built-in palette.

Address	Name	Description
$1:0:01	MODE	4 - Sprite
$1:0:02	OPTIONS	bit 0 - affine
$1:0:03	CONFIG	The XRAM address of the sprite array.
$1:0:04	LENGTH	The number of sprites in the sprite array.
$1:0:05	PLANE	The plane, 0-2.
$1:0:06	BEGIN	The first scanline.
$1:0:07	END	One past the last scanline, or 0 for the height of the canvas.

Member	Description
`x_pos_px`, `y_pos_px`	Where the top left pixel of the sprite goes on the canvas. They can be negative, so the sprite can start above or to the left of the canvas.
`xram_sprite_ptr`	The XRAM address of the image.
`log_size`	The size of the image, as a power of 2.
`has_opacity_metadata`	True when the image has opacity metadata.
`transform`	In `mode4_asprite_t` only. The affine transform, which rotates and scales the sprite.

Address	Name	Description
$1:0:01	MODE	5 - Sprite
$1:0:02	OPTIONS	bit 0:2 - 0=1, 1=2, 2=4, or 3=8 bit color bit 3:5 - 0=8x8, 1=16x16, 2=32x32, 3=64x64, 4=128x128, 5=256x256, 6=512x512, 7=custom 512x512 only supports 1-bit and 2-bit color. With 7=custom, the VGA system ignores bits 0:2, and each sprite in the sprite array sets its own size and color depth.
$1:0:03	CONFIG	The XRAM address of the sprite array.
$1:0:04	LENGTH	The number of sprites in the sprite array.
$1:0:05	PLANE	The plane, 0-2.
$1:0:06	BEGIN	The first scanline.
$1:0:07	END	One past the last scanline, or 0 for the height of the canvas.

Canvas	Timing	Time	Cycles at 8 MHz
320x240, 640x480	VGA	1.37 ms	10,900
320x200, 640x400	VGA	3.90 ms	31,200
320x180, 640x360	VGA	5.17 ms	41,400
320x240, 640x480	SXGA	1.59 ms	12,800
320x200, 640x400	SXGA	4.09 ms	32,800
320x180, 640x360	SXGA	5.35 ms	42,800
320x180, 640x360	720p	0.58 ms	4,600

Timing	Active	Total	Pixel clock	Refresh	Standard
VGA	640x480	800x525	25.2 MHz	60 Hz	CEA-861
SXGA	1280x1024	1688x1066	108 MHz	60 Hz	VESA DMT
720p	1280x720	1650x750	74.25 MHz	60 Hz	CEA-861

Address	Name	Description
$1:F:00	DISPLAY	Sets the aspect ratio of the display and resets CANVAS to the console canvas. 0 - VGA (4:3) 640x480 1 - HD (16:9) 640x480 and 1280x720 2 - SXGA (5:4) 1280x1024
$1:F:01	CODE_PAGE	Sets the code page of the built-in fonts. It holds the same value as RIA_ATTR_CODE_PAGE.
$1:F:02	SUPPRESS_TERM_REPLY	Suppresses replies from the VGA system’s terminal. The telnet server sets it.
$1:F:03	UART_TX	Carries UART Tx data over the PIX bus while the backchannel uses the UART Tx pin.
$1:F:04	BACKCHAN	Controls the use of UART Tx as the backchannel. 0 - Disable 1 - Enable 2 - Request
$1:F:06	REBOOT_OR_LOCKUP	The RIA sets it after writing the flash of the VGA module. 0 reboots the VGA module. Any other value locks it up, so that the error message of a failed flash write stays on the screen.
$1:F:07	FLASH_PROGRAM	Writes XRAM $0000-$00FF to a 256-byte page of the flash of the VGA module. The value is the number of the page. The VGA module erases the sector of the page first, unless the page already reads as erased.

VGA¶

Introduction¶

Getting Started¶

How It Works¶

Canvas¶

Planes¶

Modes¶

Structures¶

VSYNC¶

Programming¶

Colors and Palettes¶

Canvas Types¶

Mode 0: Console¶

Mode 1: Character¶

Mode 2: Tile¶

Mode 3: Bitmap¶

Mode 4: Sprite 16-bit¶

Mode 5: Sprite 1,2,4,8-bit¶

Video Timing¶

Control Channel $F¶