DOLORES Double LORES Library

Jan 5, 2023 · 8 min read · double lores ·

Double LORES Mode (80x48 pixels)

From the Apple //e enhanced onwards a Double LORES mode with 80 x 48 pixels in 16 colors is available. Documentation about this mode is rather sparse and ways to access this mode are fairly complicated for AppleSoft programmers and need machine language tricks in order to get things going on an Apple //e.

If you are a lucky owner of an Apple IIc or IIgs things are easier: with some POKE-commands the double LORES mode can be activated and then standard PLOT-commands from AppleSoft can be used for drawing. However, the SCRN-function is reported to yield unrealiable results in this mode.

The Double LORES mode was always a great center of attraction for me and I wanted to write my own tools in order to access this "hidden" graphics mode. After some first experiments I was pointed to the idea by some fellow Apple ][ enthusiasts to create a library that makes use of the AppleSoft &-feature (Ampersand) which enables an easy link from AppleSoft Basic to new machine routines.

The result is a series of versions of an ampersand-library which enables an easy access to AppleSoft double LORES graphic routines using the &-command. Read more technical details and instructions on how to use the library below or in the oversight article Behind the Scenes: DOLORES Library!

Latest stable release of the library is V12 which includes a sprite engine hence the library requires more memory space. If one does not need sprite functionalities one can use V11 which is much leaner in memory requirements.

Getting the Library

The library is free of charge. However, we charge for sending you a physical copy of the library on floppy disk.

Physical Copy

Interested in a physical copy of the library on 5.25" floppy disk? Drop us an email in order to receive information about availability and pricing.

Free DSK-Images

Visit our shop to receive your free DSK-images for using the library in your favourite emulator or to use it with your floppy emu! The library is free for download there:

How to use the Library

The library V11 is about 5.5 kB in size and is loaded at memory location $8000. V12 of the library has increased in size (about 8.5 kB) and is thus loaded at $7000. Before the library can be used it needs to be BRUNned which sets up the ampersand-vector at $03F5. The address that is stored in this memory location is the jump destination when the &-command is encountered in an AppleSoft program.

Here the vector is set to the address $808B (V12: $708B) where the small command parser of the library is located. When a &-command is encountered control is transferred to the command parser and the command itself as well as its parameters are checked for valid input values. If an unknown command, missing or out of range parameters are encountered a SYNTAX ERROR or ILLEGAL QUANTITY ERROR is thrown and the AppleSoft program terminates.

Since the library is designed to support three double LORES pages (memory range from $400-$7FF and $800-$BFF, special dump range from $C00-$FFF) with page flipping it is recommended to load your own AppleSoft program to $1000. This can be accomplished by poking to values into memory and loading of your program afterwards. On the supplied DSK-image the HELLO-program performs these and some other important tasks:

POKE 104,16: sets the AppleSoft program start adress to $1000
POKE 4096,0: required by AppleSoft, sets the value of $1000 to $00, AppleSoft-tokens start from $1001
V12: BRUN DLCOREAMP,A$8000: runs the library's V12 init-routine and sets up the ampersand-vector
V11: BRUN DLCOREAMP,A$7000 MAXFILES 1: sets the number of DOS 3.3 file buffers to 1, which is required since the V11 lib table data exceeds the limit of $9600 which is the start adress of a DOS file buffer.
HIMEM: 32768 (V11) or HIMEM: 28672 (V12): needed in order to keep AppleSoft variable data storage out of the way of the library!

As you can see on the DSK-image by using a small startup program the system can be easily prepared to use the double LORES mode.

Command Overview

After installation of the library the following ampersand-commands are available:

Basic Commands

&GR: switches to double LORES mode and clears the screen
&TEXT: returns to 40-column text mode
&COLOR=: sets the plotting color (range: 0..15)
&PLOT X,Y[,COLOR]:* plots a pixel at X,Y. The parameter COLOR is optional.
&SCRN(X,Y,C%): reads out MAIN or AUX memory depending on the given coordinates and returns the color value C% of the selected pixel (range: $00..$0F / 0..15)
&VLIN Y1,Y2,X[,COLOR]: plots a vertical line from Y1 to Y2 at column X. The parameter COLOR is optional.
&HLIN X1,X2,Y[,COLOR]: plots a horizontal line from X1 to X2 at row Y. The parameter COLOR is optional.
&L X1,Y1,X2,Y2[,COLOR]: plots an oblique line from X1/Y1 to X2/Y2 using a fast Bresenham algorithm. The parameter COLOR is optional. When the algorithm detects a pure horizontal or vertical line the HLIN/VLIN-algorithms are called automatically.
&C XM,YM,RADIUS[,FILLCOLOR,BORDERCOLOR]: plots a circle with midpoint XM/YM and radius RADIUS with the color that was previously set by the &COLOR=-command. If FILLCOLOR is given, a filled disk is drawn, if BORDERCOLOR is set the border of the disk can be drawn in a different color. It is possible to draw circles/disks that exceed the drawing screen. However, the midpoint of the circle/disk has always to be a valid screen coordinate!
&R X1,Y1,X2,Y2[,FILLCOLOR,BORDERCOLOR]: plots a rectangle from X1/Y1 to X2/Y2 with the color that was previously set by the &COLOR=-command. If FILLCOLOR is given, a filled rectrangle is drawn, if BORDERCOLOR is set the border of the rectangle can be drawn in a different color.

Enhanced Commands:

&F XSEED,YSEED[,COLOR]: Flood fills any polygon on the current drawing screen with the currently set color which was set by the command &COLOR= before or given by COLOR as an optional input parameter. The seed point (XSEED,YSEED) must lie inside the desired polygon to fill. The polygon to fill must be "closed" otherwise the fill routine will result in strange results.
&H: Fill the current drawing screen with the currently set color which was set by the command &COLOR=. If the current color = 0 then the current drawing screen will be erased.
&M: toggle between mixed mode double lores / text with 4 lines of text at the bottom of the screen and fullscreen graphics. The cursor is automatically VTABbed to line 21.
&S 1/2: Show page 1 or page 2. This command flips display pages and makes most sense in combination with the following command.
&D 1/2: Selects the active drawing page 1 or page 2.
&SAVE FROM,TO: fast move of graphic page data. FROM and TO need to be in the range of 1..3, other values are ignored.
&G: retrieve PAGE1 from PAGE3 and set fullscreen
&T: switch to text mode and save current PAGE1 graphics to PAGE3, text screen will be blank.
&V: print version information on the text screen

V12 SPRITE Engine and Additional Commands:

&STORE NUM,WIDTH,HEIGHT,MASKCOLOR: store sprite NUM (1..16) into language card buffer. Sprite DATA has to be stored before (POKEd) in the area $9500-$95FF (256 pixels maximum) line per line in a row. Sprite DATA is resembled by simple storage of the color value of each pixel (0..15).
&VAL NUM: set Pixel mask to color NUM (0..15). If NUM = 16 then pixel masking is disabled. After starting DOLORES NUM is initially set to zero.
&DRAW NUM,X,Y: draw sprite NUM at X,Y. Important: the visible screen area is represented by X: 80..159 and Y: 48..95. This enables easy sprite clipping at the screen borders. For using this feature screen offsets have to be taken into account.
&DEL NUM: Delete the last drawn copy of sprite NUM from the screen and restore the background. Important: only the last draw action can be deleted!
&GET NUM,XFROM,YFROM,XTO,YTO,MASKCOLOR: grab a part of the current drawing screen and create a sprite out of it. Sprite area is defined by the rectangle that is created with XFROM,YFROM and XTO,YTO. NUM is the sprite number position where the new sprite will be stored. Any older content in this sprite slot will be deleted. Important: screen coordinates are X: 0..79 and Y: 0..47 here! Maximum number of pixels to grab is 256. There is no automatic range checking!
&INPUT XFROM,YFROM,XTO,YTO: copy part of the current drawing screen into scratch memory for later pasting it back to the image.
&RESTORE X,Y: paste copied image part back to the screen at position X,Y.
&RECALL: undo the last paste operation.
NEW: SPRITE.MAKER tool and TESTICLES demo by Daniel Henderson included on the disk image.

In standard operation mode after intializing the double LORES via &GR the drawing and display page are set to 1 so the user can see all the drawings as they happen. If you want to draw on the other page as the user can see you need to issue e.g. the following commands: &S1 : &D2 for drawing on page 2 while displaying page 1. Page flipping would be done after the drawing has been finished with the sequence &S2 : &D1 and vice-versa.

Allowed values for X are in the range from 0 to 79 and for Y from 0 to 47. Optional values need not to be supplied.