Graphics in Atari BASIC: Modes, COLOR, SETCOLOR, PLOT, DRAWTO and FILL

A GRAPHICS 7 rectangle outlined with PLOT and DRAWTO and filled solid green by XIO 18, with FILLED! in the text window

The Atari's operating system includes a complete screen handler, and Atari BASIC exposes it through a handful of simple statements. With nothing but GRAPHICS, COLOR, PLOT and DRAWTO you can draw in a dozen modes and get colours that other 1980s BASICs could not touch. The only real stumbling block is the way colour numbers work — and this guide spends time untangling that.

You will learn: what each BASIC graphics mode offers, how text windows and the +16/+32 options work, writing text in large-character modes, the relationship between COLOR and SETCOLOR, plotting and lines, reading pixels back, and filling shapes.

You need: Atari BASIC on any 8-bit Atari. Modes 9–11 need the GTIA chip, fitted to all XL/XE machines; early 400/800s with the older CTIA chip lack them.

1. The GRAPHICS modes

GRAPHICS n (abbreviated GR.) clears the screen and switches mode. Modes 0–2 are text modes; 3–11 are bitmap ("map") modes that you draw on with PLOT.

Mode Type Full screen With text window Colours Memory used
0 Text, 40 columns 40 × 24 — 1 hue, 2 lums 992
1 Text, double width 20 × 24 20 × 20 5 672
2 Text, double width & height 20 × 12 20 × 10 5 420
3 Graphics 40 × 24 40 × 20 4 432
4 Graphics 80 × 48 80 × 40 2 696
5 Graphics 80 × 48 80 × 40 4 1,176
6 Graphics 160 × 96 160 × 80 2 2,184
7 Graphics 160 × 96 160 × 80 4 4,200
8 Graphics, hi-res 320 × 192 320 × 160 1 hue, 2 lums 8,138
9–11 GTIA modes 80 × 192 none 16 / 9 / 16 8,138

Coordinates start at 0,0 in the top-left corner, so GRAPHICS 7 runs from 0–159 across and 0–95 down (0–79 with a text window).

Two numbers can be added to the mode:

  • +16 removes the four-line text window: GRAPHICS 7+16 (or GRAPHICS 23) gives a full-screen 160 × 96 display.
  • +32 switches mode without clearing screen memory.

Full-screen (+16) modes have one catch: when the program ends, BASIC needs a text screen for READY, so it drops straight back to GRAPHICS 0 and your picture vanishes. End such programs with a loop such as 90 GOTO 90 (and press BREAK to stop).

2. Text modes and PRINT #6

In modes 1 and 2, plain PRINT writes to the text window at the bottom. To write in the big characters above, print to channel 6, which BASIC opens to the screen for you:

10 GRAPHICS 2
20 POSITION 4,2:PRINT #6;"ATARI"
30 POSITION 4,4:PRINT #6;"atari"
40 POSITION 4,6:PRINT #6;CHR$(65+128)
50 PRINT "THIS LINE IS IN THE TEXT WINDOW"

Modes 1 and 2 show only 64 different characters, but each in one of four colours chosen by case and inverse: upper case uses colour register 0, lower case register 1, inverse upper case register 2 and inverse lower case register 3. So "atari" in line 30 appears in capitals of a second colour, and line 40's inverse A in a third. (POKE 756,226 switches to the lower half of the character set, giving lower-case letters instead — but then you cannot show capitals at the same time.)

POSITION only moves the cursor in the main display. To position text inside the text window, POKE its cursor directly: location 656 (TXTROW, 0–3) and 657 (TXTCOL, 0–39).

3. COLOR and SETCOLOR — the confusing part

There are two different statements and they use different numbers:

  • SETCOLOR register,hue,luminance decides what colour a hardware colour register holds. Registers 0–4 correspond to memory locations 708–712.
  • COLOR n chooses which register the next PLOT, DRAWTO or fill will draw with — but n is not the register number, and the mapping changes with the mode.

In summary:

Mode COLOR SETCOLOR register Location Used for
3, 5, 7 (4-colour) 1 0 708 drawing colour 1
2 1 709 drawing colour 2
3 2 710 drawing colour 3
0 4 712 background and border
4, 6 (2-colour) 1 0 708 drawing colour
0 4 712 background and border
8 1 1 709 pixel luminance (hue comes from 710)
0 2 710 background
0 — 1 709 character luminance
— 2 710 background
— 4 712 border

In GRAPHICS 0 and 8 you only get one hue: register 2 sets the background colour and register 1 only sets the brightness of the characters or pixels. (Graphics 8 can show extra colours on NTSC televisions through "artifacting" — a separate guide.)

Hue and luminance. Hue is 0–15 and luminance an even number 0–14. The value stored in the register is hue*16+luminance, so SETCOLOR 0,4,6 is the same as POKE 708,70. Using POKE saves memory, and it is the only way to set the player colour registers 704–707, which have no SETCOLOR. These names are approximate — colours vary between sets and between NTSC and PAL machines:

Hue Colour Hue Colour
0 Grey (black to white) 8 Medium blue
1 Rust 9 Dark blue
2 Red-orange 10 Blue-grey
3 Dark orange 11 Olive green
4 Red 12 Medium green
5 Dark lavender 13 Dark green
6 Cobalt blue 14 Orange-green
7 Ultramarine blue 15 Orange

Every GRAPHICS command and every press of RESET put the registers back to their power-up values (708=40, 709=202, 710=148, 711=70, 712=0), so set your colours after the GRAPHICS statement.

Changing a register instantly recolours everything already drawn with it — the basis of "colour rotation" effects that make a still picture appear to move.

4. PLOT, DRAWTO and LOCATE

PLOT x,y sets one pixel in the current COLOR; DRAWTO x,y draws a line from the last point plotted. COLOR 0 draws in background colour, which is how you erase.

10 GRAPHICS 7+16
20 SETCOLOR 0,4,8:SETCOLOR 1,12,10:SETCOLOR 2,8,8
30 FOR C=1 TO 3:COLOR C
40 FOR X=0 TO 159 STEP 8
50 PLOT X,0:DRAWTO 159-X,95
60 NEXT X:NEXT C
70 GOTO 70

LOCATE x,y,V reads back the colour number of a pixel (or the character code in a text mode) into V — handy for simple collision tests in games:

200 LOCATE PX,PY,V:IF V<>0 THEN PRINT "CRASH!"

Two things to remember: LOCATE moves the graphics cursor, and any coordinate outside the current mode's range stops the program with ERROR 141 (cursor out of range).

5. Filling shapes with XIO 18

Atari BASIC has no FILL keyword. Instead you call the screen handler's fill function directly with XIO 18,#6,0,0,"S:" (you will also see the same call written as XIO 18,#6,12,0,"S:"; both forms appear in published listings). The procedure:

  1. Draw the right-hand edge and the bottom edge of the shape.
  2. Move the cursor with POSITION to the top-left corner.
  3. POKE the fill colour (the COLOR number) into location 765 (FILDAT).
  4. Execute the XIO.

The handler draws a line from the last point plotted to the POSITION point and, from each point on that line, fills to the right until it meets a pixel that is not background.

10 GRAPHICS 7
20 COLOR 1
30 PLOT 120,10:DRAWTO 120,70
40 DRAWTO 40,70
50 POSITION 40,10
60 POKE 765,2
70 XIO 18,#6,0,0,"S:"
80 PRINT "FILLED!"

Because the fill runs rightwards until it hits something, any gap in the right-hand edge lets the colour run on past where you intended. Draw the boundary first, then fill. Odd shapes can be filled in several passes.

6. Where is the screen?

Locations 88 and 89 (SAVMSC) hold the address of the first byte of screen memory: SC=PEEK(88)+PEEK(89)*256. POKEing there writes straight to the display — the fastest way to draw from BASIC, and the starting point for saving pictures to disk.

Troubleshooting

  • ERROR 141: a PLOT, DRAWTO, POSITION or LOCATE went outside the current mode. Remember the text window reduces the height.
  • ERROR 147 (insufficient memory for screen mode) or a garbled display after a big DIM: the 8K modes need room below RAMTOP. Choose the mode before DIMming large arrays.
  • My colours are wrong: you set a SETCOLOR register number where a COLOR number was expected, or vice versa — check the table above. Or you set them before the GRAPHICS statement.
  • The picture disappears when the program stops: it is a +16 mode; keep the program running.
  • Lower-case letters print as capitals in GR.1/2: that is how the four-colour text works; they are capitals in register 1's colour.

Further reading

  • Atari Color Graphics — Joseph W. Collins (Arrays, 1984).
  • Understanding Atari Graphics — Michael Boom (Alfred Publishing, 1982).
  • COMPUTE!'s First Book of Atari Graphics (Small System Services, 1982) and COMPUTE!'s Second Book of Atari Graphics (1984).
  • Atari Sound and Graphics — Herb Moore, Judy Lower and Bob Albrecht (Wiley, 1982).

Credits