LLX > Neil Parker > Apple II > DLOWRES

DLOWRES: Draw Double Low-Resolution Graphics in Applesoft

Shortly after the Apple IIe was introduced, it gained two new graphics modes not found on earlier Apple II models: double low-resolution and double high-resolution. These are more or less 80-column extensions of the traditional low-resolution ("lores") and high-resolution ("hires") modes. The double hires mode was extensively documented and plenty of software was available to use it, but Apple published little or nothing about double lores graphics. Even when the Apple IIc and Apple IIGS were released, with modifications to Applesoft BASIC to support double lores graphics (the code for this occupies the space that was reclaimed by deleting the cassette tape routines, which weren't needed on machines with no cassette tape hardware), Apple never advertised or documented the double lores Applesoft enhancements.

The reason for this isn't hard to understand: By the time the IIe was released, few people still cared about lores graphics, and a new mode that doubled its horizontal resolution didn't spark much excitement.

But still, the new mode is available, and Applesoft programmers might enjoy being able to use it, even on the IIe, where Applesoft never got the double lores enhancements.

Double lores graphics provides a resolution of 80 by 40 blocks (or 80 by 48 if the four lines of text at the bottom are turned off), with sixteen colors. This is done in exactly the same manner as 80-column text, by putting all the even-numbered columns in the alternate-bank text page. The color bit patters for the odd-numbered columns (in the main memory bank) are identical to the classic low-resolution colors, but the even-column (alternate bank) colors are rotated one bit to the right.

Double-resolution graphics are enabled by enabling 80 columns, and turning off annunciator 3 (POKE 49246,0 in Applesoft, or LDA $C05E in assembly language). On the IIc and IIGS, but not the IIe, Applesoft low-resolution commands will then use the double-lores screen, accepting X coordinates as large as 79. (The SCRN function in this mode has a bug: If the X coordinate is even, the returned color number has its low-order bit replaced by 0.)

For the Applesoft programmer who wants to use this mode on an Apple IIe, a couple of options are available: Beagle Bros' Beagle Graphics includes a set of commands similar to, but not quite as fancy as, the ones described here, and since 2020, there's Dr. Marc A. Golombeck's DOLORES package, which is quite a bit fancier, but requires a 65C02 and DOS 3.3. And now there's my effort.

The software downloadable from this page provides a new set of ampersand (&) commands that Applesoft programmers can use to draw double lowres graphics on any Apple II that supports it, including the Apple IIe. Of course this requires compatible hardware:

On the Apple IIe, there are additional requirements:

DLOWRES and its source code are freeware, and may be used and redistributed in accordance with the terms in the included LICENSE file (a three-clause BSD license).

Basic Usage

  1. BRUN DLOWRES
  2. PR#3
  3. Put & in front of any Applesoft lores command, and in front of TEXT. Replace SCRN( x,y) with USR (x)(y).

DLOWRES also supports a couple of additional features beyond just letting the X coordinate go up to 79. Read on for the details.

The Details

BRUN DLOWRES

This command installs the double lores commands. It checks to make sure you have at least an Apple IIe with 80 columns, and fails with NO BUFFERS AVAILABLE (under ProDOS) or ?OUT OF MEMORY ERROR (under DOS 3.3) if the hardware isn't sufficient. If installation succeeds, it consumes 1024 bytes above the file buffers under ProDOS, or 800 bytes above HIMEM under DOS 3.3. BRUNning it again consumes more memory, so provisions have been made for detecting whether or not DLOWRES has already been installed.

DLOWRES will appear to install successfully on an Apple IIe with a revision A motherboard, or with an 80-column card whose double-resolution jumper isn't installed, but the commands described below won't work properly (the right values are stored in display memory, but only the classic single-resolution lores screen will be visible). I don't know of any way for a program to detect a revision A motherboard, or a missing jumper.

DLOWRES initially loads at memory location 8192 ($2000), and then moves itself to high memory. It has been designed to coexist peacefully with other high-memory modules, and unlike some such modules, it need not be the first one loaded.

& "DLOWRES"

 & "DLOWRES"

This command does nothing. Its purpose is to help your program figure out whether DLOWRES is already installed. It's intended primarily for ProDOS (though it's available in DOS 3.3 too), where it might be used like this:

10  ON  PEEK (116) > 146 OR  PEEK (1015) = 190 GOTO 40: ONERR  GOTO 30
20  & "DLOWRES": POKE 216,0: GOTO 50
30  CALL 62248: POKE 216,0
40  PRINT  CHR$ (4);"BRUN DLOWRES"
50  PRINT  CHR$ (4);"PR#3": PRINT  CHR$ (12)
60  REM The rest of your program starts here

Line 10 tests whether HIMEM is too high to accommodate DLOWRES, or whether the & hook hasn't been used yet. Line 20 uses & "DLOWRES" to test whether DLOWRES is already installed.

DLOWRES's above-HIMEM hiding place under DOS 3.3 isn't safe from FP, INT, or MAXFILES, so it's probably best for a DOS 3.3 progam to just throw away any previously-loaded copy and load it anew. For example,

10  POKE 1013,76: POKE 1014,88: POKE 1015,255: REM Reset & vector
20  PRINT  CHR$ (4);"MAXFILES 3": REM Throw away above-HIMEM buffer
30  PRINT  CHR$ (4);"BRUN DLOWRES"
40  PRINT  CHR$ (4);"PR#3": PRINT  CHR$ (12)
50  REM The rest of your program starts here

Because BRUN DLOWRES moves HIMEM, a DOS 3.3 program should avoid using any string variables until after DLOWRES is installed.

& GR

 &  GR [numeric-epxression[,numeric-expression]]

This command displays and clears the double low-resolution screen. The first argument is the full-screen flag, which (if it's present) must evaluate to a number between 0 and 255. If it's missing or 0, the mixed (40-row) screen is cleared, and there are four lines of text at the bottom. If it's any other number, the full (48-row) screen is cleared, and there are no lines of text at the bottom.

The second argument (which can only be given if the first is given) is a color, and must evaluate to a number from 0 to 15. The screen will be cleared to the given color, or to black if the color is missing. The colors are the classic lores colors.

& GR sets the text scrolling window to the bottom four lines of the screen (even if full-screen mode is selected—of course in that case the program should not try to print text).

The text screen should be in 80-column ("PR#3") mode before using & GR. If & GR is used in 40-column mode, the 80-column display switch is turned on, but the 80-column firmware is not initialized, resulting in a confused and oddly-behaving text display, especially on the original (unenhanced) Apple IIe.

& TEXT

 &  TEXT

This command turns off graphics mode, and sets the text scrolling window to the full 80-column screen. It does more or less what the regular (non-&) TEXT command does, and also turns off the double-resolution graphics switch.

& COLOR=

 &  COLOR= numeric-expression

This sets the color for subsequent drawing commands. The argument must evaluate to a number from 0 to 15. The colors are the classic lores colors.

& PLOT

 &  PLOT [numeric-expression,numeric-expression] [TO numeric-expression,numeric-expression] [TO ...]

This command plots a point or a line. The syntax is the same as the hires HPLOT command, and has the same meaning: If a single coordinate pair is given, a single block is plotted, and each TO clause draws a line from the previous point to the given point. (Of course due to the large size of the blocks, diagonal lines will show an obvious "stair-step" effect.)

Each numeric-expression,numeric-expression represents the X and Y coordinates of a block on the screen; the first expression must be between 0 and 79, and the second expression must be between 0 and 47.

& HLIN

 &  HLIN numeric-expression,numeric-expression AT numeric-expression

This draws a horizontal line. The first two expressions, which must be between 0 and 79, give the starting and ending columns, and the AT expression, which must be between 0 and 47, gives the row.

& HLIN x1,x2 AT y has the same effect as & PLOT x1,y TO x2,y, but may run slightly faster.

& VLIN

 &  VLIN numeric-expression,numeric-expression AT numeric-expression

This draws a vertical line. The first two expressions, which must be between 0 and 47, give the starting and ending rows, and the AT expression, which must be between 0 and 79, gives the column.

& VLIN y1,y2 AT x has the same effect as & PLOT x,y1 TO x,y2, but may run slightly faster.

USR

 USR (numeric-expression)(numeric-expression)

This function returns the color of the block at the coordinates numeric-expression,numeric-expression. As usual, the first expression (the X coordinate) must be between 0 and 79, and the second expression (the Y coordinate) must be between 0 and 47.

The odd syntax, with a pair of parentheses in the middle instead of a comma, is an artifact of the way Applesoft's function parser works.

& USR

 &  USR

This command points the USR vector at DLOWRES's USR function handler. This is normally done by BRUN DLOWRES, but since the USR vector can only be used by one handler at a time, this provides a way to reconnect DLOWRES's USR function after something else has usurped it.

& &

If other & handlers were installed before DLOWRES, they remain available, and can be invoked as if DLOWRES were not present, unless the prior command happens to have the same name as a DLOWRES command. In that case, putting a second & in front of the command passes control to the prior handler.

The same convenience isn't available for USR, because it's not clear how to determine whether a USR call should be passed to another handler. At least with the & USR command, it's possible to reconnect DLOWRES's handler if something else replaces it.

Downloads

Each archive or disk image includes the source code (Merlin Pro assembler), the assembled binary, and a couple of demo programs.

LLX > Neil Parker > Apple II > DLOWRES

Original: December 12, 2021
Modified: August 29, 2023—Marc Golombeck's DOLORES has moved to a different URL.