Chrome II

More Double Hi-Res Graphics Commands For Applesoft

Zachary T. Smith

Last month we presented “Chrome,” a powerful double hi-res extension for Applesoft BASIC. “Chrome II” adds several new features to its predecessor, including FILL, enhanced HPLOT and ELLIPSE modes, box draw, windowing support, and more. For the Apple lie (Revision B), IIc, and IIGS computers. DOS 3.3 is required.

“Chrome,” presented in the October issue of COMPUTE!, was an extension of Applesoft's graphics capabilities, providing a new ELLIPSE command and a revised HPLOT command with horizontal resolutions of 560 pixels in monochrome or 140 pixels in 16 colors.

“Chrome II” complements Chrome with new and extended commands to produce a graphics toolbox. Chrome II was designed to help you write your own drawing program or personal typesetter.

Setting Up The Disk

First, note that you must have a working copy of the original Chrome program to be able to use Chrome II.

Type in a copy of Chrome II using the Apple version of the “MLX” machine language entry program found elsewhere in this issue. When you run MLX, you'll be asked for a starting and an ending address for the data you'll be entering. For Chrome II, use the following values:

STARTING ADDRESS?	0C00
ENDING ADDRESS?	1347

After you have entered all the data, be sure to save a copy to disk before leaving MLX.

To use Chrome II, copy it onto a disk that contains a copy of Chrome. Then edit the setup program given in the October issue to read as follows:

10 PRINT CHR$ (4) “PR#3”
15 PRINT “DOUBLE HI-RES EXTENDED APPLESOFT BEING LOADED”
20 PRINT CHR$ (4) “BLOAD CHROME”
25 PRINT CHR$ (4) “BRUN CHROME II”
30 NEW

Lines 20 and 25 assume that the Chrome and Chrome II programs are saved with the filenames CHROME and CHROME II, respectively. You may need to change those lines to reflect the names you actually used. Remember to resave this as the disk's HELLO program so that it will run automatically when the disk is booted. When you boot your computer with this disk, Chrome II should be installed.

Program 2 is a demonstration program which shows off the capabilities of Chrome II. Type it in and save a copy before trying it out. Perhaps the best way to learn how to use Chrome II is by studying and altering the demo. It uses all of the new features except the auxiliary RAM data-mover command.

The New Commands

Chrome II offers six new commands, all of which are designed for the 560-point monochrome mode. This mode is selected with the DOUBLE command provided in the original Chrome. For quick reference, the tables located near the end of the article show the syntax of the new commands. Of course, all of the old commands from the original Chrome are still functional.

LINE is similar to HPLOT, except that it can draw only horizontal lines. The syntax is

LINE x1, x2, x3

where x1 and x2 are, respectively, the left and right endpoints of the line (0–559), and y is the line's vertical position (0–191). As with HPLOT, the type of line drawn is determined by the setting of the HCOLOR = command. When the HCOLOR mode is 0, 1, or 2, LINE simply draws a horizontal line as HPLOT would with the same HCOLOR = setting. In these modes, LINE x1,x2, y is the same as HPLOT x1, y TO x2, y. HCOLOR mode 0 sets bits, turning on pixels to draw white lines. Mode 1 clears bits, turning pixels off. You can think of this either as erasing lines or as drawing black lines. Mode 2 inverts (toggles) the state of the pixels in the line.

The real power of LINE becomes obvious when the HCOLOR mode is set to 3 (HCOLOR = 3). In this case, LINE draws a patterned line. The default pattern looks like bricks, but you can change the pattern with the SETPTN (set pattern) command, described below.

Actually, you won't see the brick pattern if you draw just a single line. The complete pattern is eight lines tall, so you must use the LINE command on eight successive lines to see the full pattern. Each screen line has a fixed relationship to the pattern. For example, when you use the LINE command on screen lines 0, 8, 16, 24, and so forth, the line drawn will take its pattern from line 0 (the top line) of the pattern definition. Lines drawn on screen lines 2, 10, 18, 26, and so forth, will have the pattern of line 2 (the third line) of the pattern definition. Note that nothing will be drawn if you use the LINE command on a screen line for which the corresponding pattern definition line is blank.

LINE can also be used to read data from the screen into RAM. To do this, set the HCOLOR mode to 4 (HCOLOR = 4). The syntax for this is LINE x1, x2, y [AT address]

The optional address value specifies the starting location of the area of memory to which the data will be transferred. If this parameter is omitted, the address value in memory locations 96 and 97 (in low byte/high byte order) determines the starting address for the operation. The address in these locations is automatically updated as each byte is stored. Thus, when reading a series of lines from the screen, you do not need to manually update the address for each line—only for the first line to be read. The number of bytes required to store the data read from a single screen line can be calculated with the expression INT((x2-z1+7)/7).

LINE can also move data from memory to the screen, reversing the process described above. This is achieved by setting the HCOLOR mode to 5 (HCOLOR = 5). The syntax of the LINE command in this case is identical to that used for reading from the screen in HCOLOR mode 4. Remember that the address value is automatically incremented during each reading or writing operation. If you use HCOLOR mode 4 to read a line from the screen, you must reset the address before using HCOLOR mode 5 to write that line back to the screen.

When restoring data to the screen with HCOLOR mode 5, you must maintain the horizontal bit-position alignment with which the data was saved. If you restore the data at the same horizontal position from which it was saved, you'll have no problem. However, data restored at a different horizontal position will be distorted unless the new pixel position has the same bit position within its screen memory byte. The bit position for pixel position x can be determined by the expression ((x/7) - INT (x/7))* 7.

AREA performs the same function as a series of executions of the LINE command. Therefore, it uses HCOLOR modes in the same way that LINE does (see the explanation above). Its syntax is AREA x1, y1, x2, y2 [AT address]

The first coordinate pair—x1, y1—specifies the upper left corner of the area to be affected, and the second pair—x2, y2—specifies the lower right corner. By selecting the proper HCOLOR modes, AREA can whiten, blacken, invert, pattern fill, save, or restore any rectangular portion of the screen. When saving screen data, the number of bytes of memory required can be calculated using the expression INT((x2-xi + 7)/7)*(y2-y1+1).

FILL is perhaps the most exciting of the new commands. It can flood fill any enclosed screen area with the current pattern. Its syntax is FILL x, y buffer address, autofill

The x and y values specify the horizontal and vertical coordinates, respectively, at which the fill operation is to begin. These can be any- where within the enclosed figure to be filled. Be careful that the figure being filled is completely enclosed by set (white) pixels. If there are any gaps in the figure boundaries, the fill operation will spill out through the gaps into adjacent areas of the screen.

The algorithm used for the FILL routine first generates a list of the starting and ending addresses in memory of each screen line to be filled and then proceeds to fill in the lines. The buffer address parameter in the command allows you to specify the starting address for the area of memory to be used to hold this list. You can choose any address you want for the buffer area, but it's best to place the buffer at the top of memory.

Fill operations stop when FILL is finished or when the buffer pointer goes above 38143 ($94FF hex), which is considered an overflow. Thus, you should set the buffer address sufficiently far below that address to provide space for the list. The larger and more irregular the area you are filling, the more room will be required for the list. (The entry for each screen line to be filled requires four bytes.) For example, a buffer address value of 37376 provides 768 bytes of line-list buffer space.

To prevent the FILL command from corrupting BASIC variables as the list is generated, you should include a HIMEM command at the beginning of your program to restrict variables to the area below the list. The syntax for the command is HIMEM: address

where address is one location above the highest address used for variables. In this case, specify the value of the lowest buffer address used in any FILL statement in your program. For instance, if you were using the buffer address value in the example above, your program should begin with the statement HIMEM: 37376.

The autofill parameter specifies whether the area is to be filled solidly or with the current pattern. An autofill value of 0 specifies a solid-white fill (all pixels set in filled area), while a value of 1 specifies a pattern fill.

REFILL takes advantage of the two-phase structure of FILL to provide a quick way to change the pattern of the most recently filled area. It uses the list created by the most recent FILL operation to fill the same area with the current pattern. For example, you could use a FILL command with an autofill value of 0 to solidly fill an area and then use a series of SETPTN and REFILL commands to paint a variety of different patterns in the area.

SETPTN allows you to define the fill pattern used by LINE, AREA, FILL, REFILL, and ELLIPSE. Its syntax is

SETPTN address

where address is the starting location of a 32-byte area of RAM containing the definition of a 28×8- pixel pattern.

Pattern definitions are stored in memory just as they are on the screen, with the highest bit (bit 7) unused. Thus, one simple way to create pattern definitions is to design the pattern in a 28×8 area of the screen using HPLOT, LINE, and the other drawing commands and then use an AREA command in HCOLOR mode 4 to copy the contents of that screen area into the memory to be used for the pattern.

You can place pattern definitions anywhere in memory that you want, but the 1K of unused RAM at 2048–3071 ($800–$0BFF hex) is a good choice. If you've used HIMEM to reserve space for the FILL list, there will also be 256 bytes available at 38144–38399 ($9500–$95FF), just below the start of DOS 3.3 at 38400 ($9600). The FILL Operation doesn't use any locations above 38143.

One special case of the command is SETPTN —1, which restores the default pattern.

AUXMOVE, the last of the new commands, isn't a drawing command like the others. Instead, it provides a handy way of moving data to and from the 64K RAM in the auxiliary bank of a 128K system. The command calls the ROM subroutine of the same name to transfer any length of data from one bank to the other. One practical use for this command is to store the original contents of screen windows for later replacement. Its syntax is

AUXMOVE Direction, source start, source end, destination

The direction parameter speciafies the direction of the transfer. Use a value of 1 to transfer data from main memory to auxiliary memory, and use a value of 0 to transfer from auxiliary memory to main memory. The source start and source end parameters specify, respectively, the starting and ending addresses of the area of memory to be copied to the other bank.The destination parameter specifies the starting address of the area in main or auxiliary memory to which the data is to be copied.Because of the limitations of the ROM routine used, AUXMOVE cannot be used for moves to or for moves to or from screen RAM, control RAM (the first 512 addresses, hex $0000-$01FF),and high RAM (the 16k RAM cards for each bank). Thus the allowable areas are $0200-$03FF and $4000-$95ff in the main bank,and $0200-$1FFF and $4000-$BFFF in the auxiliary bank.

QUICK REFERENCE—Chrome II Commands

LINE x1, x2, y [AT address]

Draws,saves,or restores horizontal lines according to the current HCOLOR mode setting.

AREA x1, x2, y2 [AT address]

Draws,saves,or restores rectangular areas of the screen according to the current HCOLOR mode setting.

FILL x, y, buffer address, autofill

Fills enclosed ares of the screen.An autofill value of 1 means fill with the current Pattern, a 0 means solid fill.

REFILL

Uses the last line-fill list to refill an area with the current pattern.

SETPTN address

Specifies the location of a 32-byte area of memory to be used as the current pattern defnition.

SETPTN—1

Selets the default (brick) pattern.

AUXMOVE dirction, source start, source end, destination.

Employs the AUXMOVE subroutine in ROM to move data to and from auxiliary memory. A direction vaiue of 1 means transfer from main to auxiliary RAM,and a 0means transfer from auxiliary to main RAM.

HPLOT

A new HCOLOR mode 4 draws dotted lines.

ELLIPSE xr,yr,mode [AT xc,yc] [AT address]

New mode values allow filled ellipses.Add 16 to the mode value to fill the lower half, and add 32 to fill the upper half. The current HCOLOR setting determines how the outline of the ellipse will be drawn,and the current COLOR setting determines how filled protions of the ellipse will be drawn.

QUICK REFERENCE—Drawing Modes

Drawing modes for LINE, AREA, and ELIPSE are as fllows:

Mode	Effect
0	Set pixels(white line)
1	Clear pixels (black line)
2	invert (toggle) pixels
3	Set or clear pixels according to pattern
4	Read line to RAM
5	Write RAM to screen line

For LINE and AREA,the modes are set with the HCOLOR = command. For filled areas drawn with ELLIPSE, the modes are set with the COLOR = command.

New Modes For Old Commands

HPLOT,which previously could draw only solid lines,specify HCOLOR mode 4 (HCOLOR=4)The 16-bit definition of the dots and dashes is present, and there is no equivalent to the SETPTN command for changing the dotted-line pattern. However, the widths of the dots or dashes can be manually changed with POKEs to locations 3075 and 3076.

ELLIPSE can now fill in the ellipse as it goes. Chrome's original ELLIPSE command could draw only an outline. The extended syntax is

ELLIPSE x radius, y radius, mode [AT x center, y center] [AT address]

The x radius and y radius values specify the horizontal and vertical radii of the figure, and the optional x center and y center values specify the center point of the figure, just as in the original version of the command. The third parameter, called quadrant in the original command, now uses two additional bits to allow a filled ellipse. Previously, four bits were used to specify which quadrants of the figure's outline were to be drawn. In Chrome II, bit 4 of the mode value specifies whether or not to draw the lower half of the interior of the figure, and bit 5 does the same for the upper half. The effect of various mode values is as follows:

lower right outline	1
lower left outline	2
upper right outline	4
upper left outline	8
lower half filled	16
upper half filled	32

As before, the values are cumulative. For example, to draw a figure with the lower half filled and the upper half outlined, use a mode value of 28 (16 + 8 + 4). The new drawing modes work only in the monochrome (DOUBLE) mode. If Chrome's multicolor (COLOR) mode is selected, the two extra bits are ignored, and only outlines are drawn.

Drawing modes for the enhanced ELLIPSE command are selected differently from the other drawing commands. The HCOLOR = command is used to select the drawing mode for outlines, while the COLOR = command selects the mode for interior areas. For outlines, HCOLOR can take the following values:

HCOLOR =	Effect
0	Set pixels (white outline)
1	Clear pixels (black outline)
2	Invert (toggle) pixels
3	Draw pattern outline
4	Draw dotted outline

The HCOLOR setting has no effect on the interior area of the ellipse, if that is filled. The interior fill is controlled by the current COLOR = mode. For filled ellipses, COLOR can take the following values:

COLOR =	Effect
0	Set pixels (fill with white)
1	Clear pixels (fill with black)
2	Invert (toggle) pixels
3	Fill with pattern
4	Copy data from screen to memory
5	Copy data from memory to screen

With COLOR modes 4 and 5, you can now use the ELLIPSE command to transfer data between memory and an elliptical (or circular) area of the screen. The mode setting determines whether the command reads or writes data for the shape's outline or for its interior area. The optional AT address parameter allows you to specify the starting address of the area of memory to or from which the data is to be transferred. Note that, if you give the AT address parameter, you must also specify the AT x center, y center parameter.

Having the border and interior drawn by two different methods is a powerful feature. You could, for instance, save a portion of the screen (in the shape of an ellipse) and then draw a black outline of an elliptical window as well as fill the inside with white. Later, COLOR mode 5 could be used to restore the background, thus closing the window.

Chrome II And Memory

RAM usage by Chrome II is minimal. It creates no new tables and occupies only RAM from the area just before the original Chrome—3072–5119 ($0C00–$13FF). There is still 1K of unused RAM available at 2048–3071 ($0800–$0BFF), page 3 is still free for machine language programs, and 21.5K of RAM is still available for BASIC programs, excluding the FILL buffer at the top of memory.