LLX > Neil Parker > Apple II > DLOWRES
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).
BRUN DLOWRES
PR#3
&
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.
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. BRUN
ning 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.
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.