Resolution ][ API Programmer's Manual
=====================================

This document provides information on developing applications using
Resolution ][.

APPLE ][ DOUBLE-HIGH-RESOLUTION GRAPHICS
----------------------------------------

The Apple ][ double-high-resolution graphics mode provides a display
resolution of 560 x 192 pixels for monochrome graphics, or 140 x 192
pixels and 16 colors for color graphics.

Refer to the TECHNICAL.txt file for technical information on the
Apple ][ double-high-resolution graphics mode.

MONOCHROME AND COLOR GRAPHICS
-----------------------------

Resolution ][ provides a display resolution of 560 x 192 using
monochrome graphics . Each pixel is represented by a single bit in
the double-high-resolution graphics memory.

Future releases of Resolution ][ will offer support for drawing an
object by masking the display with XOR operations.

Resolution ][ provides a display resolution of 140 x 192 using color
graphics, with 16 possible colors. Color graphics is achieved by
combining four monochrome pixels using one of 16 bit patterns.
Each pattern is displayed as one solid block of color on a color
monitor or television.

NOTE: Monochrome and color objects may be drawn together on the same
display. However, monochrome objects will appear in distorted color form
when using a color monitor or television. This is expected behavior.
Consult your Apple ][ machine or emulator documentation for instructions
or recommendations on using monochrome graphics with color systems.

For using color graphics, the following table describes each numeric
color value and its corresponding visual color:

Hex    Decimal  Color
Value  Value    Description
---------------------------
0......0........Black
1......1........Dark Red
2......2........Dark Blue
3......3........Violet
4......4........Dark Green
5......5........Dark Gray
6......6........Blue
7......7........Light Blue
8......8........Brown
9......9........Orange
A......10.......Light Gray
B......11.......Pink
C......12.......Green
D......13.......Yellow
E......14.......Light Green
F......15.......White

The colors provided by the Apple ][ double-high-resolution graphics mode are
the same as the colors used in the Apple ][ low-resolution (40 x 48) graphics
mode. Resolution ][ supports all 16 colors.

NOTE: The actual color displayed on the screen may vary. Color variation
depends on the Apple ][ model (//e, //c) or emulator, the quality of the
monitor, the tint and brightness settings on the monitor, and the adjacency
of pixels with particular color values.

USING THE DRAWING ROUTINES
--------------------------

A complete reference of all Resolution ][ drawing routines is given in the
RESOLUTION ][ VARIABLE TABLE and RESOLUTION ][ ROUTINES sections below.

WARNING: All routines, except for resii_graphics_enable, require that the
double-high-resolution graphics mode is enabled. If your program calls a
Resolution ][ routine before enabling double-high-resolution graphics,
memory corruption may result.

After enabling graphics, clear the screen by setting the pen_color value
to 0 and calling resii_fill_background.

To draw a monochrome object, set the use_color variable to zero.
Set the pen_color value to 1 (for white) or to 0 (for black).
The X coordinate value(s) must lie between 0 and 559.
The Y coordinate value(s) must lie between 0 and 191.
Your application will draw the object by calling the appropriate
Resolution ][ API routine.

To draw an object in color, set the use_color variable to a non-zero value
and set the pen_color value to one of the colors listed in the color value
chart. The X coordinate value(s) must lie between 0 and 139.
The Y coordinate value(s) must lie between 0 and 191. Your application
will draw the object by calling the appropriate Resolution ][ API routine.

WARNING: Resolution ][ does NOT perform error checking within its routines.
If you specify a coordinate or color value that is greater than the
maximum value allowed, memory corruption may result. Future versions of
Resolution ][ may implement bounds checking on coordinate and color
parameters.

USING THE DRAWING ROUTINES FROM APPLESOFT BASIC
-----------------------------------------------

A complete reference of all Resolution ][ drawing routines is given in the
RESOLUTION ][ VARIABLE TABLE and RESOLUTION ][ ROUTINES sections below.

AppleSoft BASIC applications must use a series of POKE, PEEK, and CALL
commands to perform a Resolution ][ task. Future versions of
Resoltion ][ will provide an interface for BASIC applications that is
easier to use.

All BASIC programs running under DOS 3.3 or ProDOS must include the
following statement before performing a Resolution ][ function:

    PRINT CHR$(4) "PR#3"
    PRINT CHR$(4) "BLOAD RESOLUTIONII"

The following statment initializes and clears the graphics display:

    CALL 24832 : POKE 24593,0 : CALL 24835

To call a Resolution ][ routine from BASIC, use the POKE command to
set all required variables to their values. Use the CALL command to
invoke the necessary procedure. If there are return values after
calling the procedure, use the PEEK command to read them.

NOTES:

1. Be sure to use DECIMAL addresses and values when calling a
   Resolution ][ routine from BASIC. BASIC does NOT support hexadecimal
   numbers.

2. Only the first two characters AppleSoft BASIC variable names
   are recognized. Ensure that the first two characters in different
   variables are unique.

Many BASIC programs mix text and graphics on the same display. This
feature is not supported directly by Resolution ][. However, it is
possible to mix text and graphics by starting your program with the
following series of statements:

    REM Initialize Resolution ][ for using mixed text and graphics
    PRINT CHR$(4) "PR#3"
    PRINT CHR$(4) "BLOAD RESOLUTIONII"
    CALL 24832 : POKE 24593, 0 : CALL 24835
    POKE 49235, 0

When mixing text and graphics, be sure not to exceed the pixel or line
Y coordinate by more than 159. The lower 32 rows of graphics are not
visible in mixed mode.

Using a Resolution ][ drawing routine typically requires one or
more two-byte parameters to be set. There is no fast way to achieve this
under BASIC since using a two-byte parameter requires multiplication
and division. The following series of statement set a two-byte parameter
to a value.

    TEMP = INT (VALUE / 256)
    POKE PARAM, VALUE - TEMP * 256
    POKE PARAM + 1, TEMP

With this information, we can write a complete example BASIC program.
The following example draws a monochrome line between the upper-left-hand
corner and the lower-right-hand corner of the screen.

    100 REM Initialize Resolution ][
    110 PRINT CHR$(4) "PR#3"
    120 PRINT CHR$(4) "BLOAD RESOLUTIONII"
    130 CALL 24832 : POKE 24593, 0 : CALL 24835
    140 POKE 49235, 0
    150 REM Draw a monochrome line
    160 POKE 24592, 0
    170 POKE 24593, 1
    180 REM Set the pixel coordinates
    190 POKE 24599,0 : REM Start X coordinate, lower byte
    200 POKE 24600,0 : REM Start X coordinate, upper byte
    210 POKE 24601,0 : REM Start Y coordinate
    220 X = 559
    230 Y = 159
    240 TEMP = INT (X / 256)
    250 POKE 24602, X - TEMP * 256 : REM End X coordinate, lower byte
    260 POKE 24603, TEMP : REM End X coordinate, upper byte
    270 POKE 24604, Y : REM End Y coordinate
    280 REM Draw the line
    290 CALL 24868

RESOLUTION ][ VARIABLE TABLE
----------------------------

The memory locations listed in the table below describe variables
available to all public Resolution ][ routines. The format of the table
is as follows:

- Variable name - name of variable
- Memory Location (Offset) - location of the variable relative to the
  start of the variable table
- Memory Location (Hex) - hex memory location of the variable
- Memory Location (Decimal) - decimal memory location of the variable
- Memory Location (Bytes) - number of bytes that the variable occupies
- Description - Description of the variable's functionality

NOTE: The memory addresses described in this table assume that
Resolution ][ was assembled with a variable table address of
Hex $6000 (Decimal 24576). The actual addresses of all variables may
vary if Resolution ][ was assembled with addresses that are different
from the default values.

Variable              Memory Location                 Description
Name         (Offset)  (Hex)  (Decimal)  (Bytes)
----------------------------------------------------------------------------
x_coord......5.........$6005..24581......2........Pixel X Coordinate
y_coord......7.........$6007..24583......1........Pixel Y Coordinate

x_offset.....10........$600A..24586......1........X memory offset
x_page.......11........$600B..24587......1........Page offset
x_bit........12........$600C..24588......1........Pixel bit offset
y_offset.....13........$600D..24589......1........Y memory offset

use_color....16........$6010..24592......1........Whether to use color
pen_color....17........$6011..24593......1........Color or value to write
read_color...18........$6012..24594......1........Color or value read

line_x_start.23........$6017..24599......2........Start X coordinate of line
line_y_start.25........$6019..24601......1........Start Y coordinate of line
line_x_end...26........$601A..24602......2........End X coordinate of line
line_y_end...28........$601C..24604......1........End Y coordinate of line

RESOLUTION ][ ROUTINES
----------------------

A complete list of all Resolution ][ routines are given in this section.
Resolution ][ contains the following routines:

- Graphics Initialization Routines
- Background Routines
- Pixel Memory Offset Calculation Routines
- Pixel Drawing Routines
- Graphics Primitives

Each entry in the list of routines contains the following information:

- Routine name
  The name of the routine and a brief description of its operation

- Address
  The memory address to call when using this routine

- Input parameters
  Set of variables that are read by the routine. The addresses of the
  variables are given in the RESOLUTION ][ VARIABLE TABLE section.

- Output parameters
  Set of variables that are set by calling the routine. The addresses
  of the variables are given in the RESOLUTION ][ VARIABLE TABLE section.

- Description
  A detailed description of the routine's functionality and usage

NOTES:

1. The API reference in this document is kept more up-to-date than the
   comments in the source code.

2. The API format is subject to change in future versions of Resolution ][.
   Hopefully, the API will be stabilized while Resolution ][ is further
   developed and tested.

3. The memory addresses described in the API reference assume that
   Resolution ][ was assembled with a program start address of
   Hex $6100 (Decimal 24832). The actual addresses of all routine calls
   may vary if Resolution ][ was assembled with addresses
   that are different from the default values.

4. After calling a Resolution ][ routine, the A, X, Y, and Status
   registers are modified. Ensure that any important data in these
   registers is stored in a safe memory location before calling a
   Resolution ][ routine.

5. All routines, except for resii_graphics_enable, require that the
   double-high-resolution graphics mode is enabled. If your program calls a
   Resolution ][ routine before enabling double-high-resolution graphics,
   memory corruption may result.

6. Zero page addresses $FA and $FB are reserved for Resolution ][.
   Do not use these memory locations in your programs. Future versions of
   Resolution ][ will not affect any zero page memory locations.

The list of routines is given below:

GRAPHICS INITIALIZATION ROUTINES

Routine name:
	resii_graphics_enable
	Activate the soft switches to enable double-high-resolution graphics
Address:
	program start address (Hex $6100, Decimal 24832)
Input parameters:
	None.
Output parameters:
	None.
Description:
	This routine enables the Apple ][ double-high-resolution graphics
	mode by activating the appropriate soft switches (hardware registers).

	NOTE: This routine DOES NOT clear the screen. To clear the screen,
	set pen_color to 0 and call resii_fill_background.

BACKGROUND ROUTINES

Routine name:
	resii_fill_background
	Fill the display with a background color
Address:
	program start address + 3 (Hex $6103, Decimal 24835)
Input parameters:
	pen_color - one byte -- color to set the background
Output parameters:
	None.
Description:
	This routine fills the double-high-resolution screen with a pen color.
	Refer to the color chart in this document for more information
	about color values.

PIXEL MEMORY OFFSET CALCULATION ROUTINES

Routine name:
	resii_x_offset
	Compute the memory offset of a pixel X coordinate
Address:
	program start address + 6 (Hex $6106, Decimal 24838)
Input parameters:
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	x_coord - two bytes -- pixel X coordinate
Output parameters:
	x_offset - one byte -- memory offset from the first column
	x_page - one byte -- page offset (0 = MAIN, 1 = AUX)
	x_bit - one byte -- pixel bit offset within a frame buffer byte
Description:
	This routine computes the memory offset, page, and bit of a pixel X
	coordinate. The Apple ][ double-high-resolution graphics mode does
	not provide a linear mapping between a set of pixel coordinates and
	the graphics memory. This function is provided to help applications
	translate a pixel X coordinate to a memory location in the
	double-high-resolution graphics memory.

	The pixel X coordinate memory offset information differs between
	monochrome pixels and color pixels. To compute the memory offset
	of a monochrome pixel, set use_color to 0 and keep x_coord smaller
	than 560. To compute the memory offset of a color pixel, set
	use_color to 1 and keep x_coord smaller than 140.

Routine name:
	resii_y_offset
	Compute the memory offset of a pixel Y coordinate
Address:
	program start address + 9 (Hex $6109, Decimal 24841)
Input parameters:
	y_coord - one byte -- pixel Y coordinate
Output parameters:
	y_offset - two bytes -- memory offset from the first row
Description:
	This routine computes the memory offset of a pixel Y coordinate.
	The Apple ][ double-high-resolution graphics mode does not
	provide a linear mapping between a set of pixel coordinates and
	the graphics memory. This function is provided to help applications 
	translate a pixel Y coordinate to a memory location in the 
	double-high-resolution graphics memory. The y_coord parameter
	must be less than 192.

Routine name:
	resii_inc_x_offset
	Increment the memory offset of a pixel X coordinate
Address:
	program start address + 12 (Hex $610C, Decimal 24844)
Input parameters (all are modified except for use_color):
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	x_coord - two bytes -- pixel X coordinate
	x_offset - one byte -- memory offset from the first column
	x_page - one byte -- page offset (0 = MAIN, 1 = AUX)
	x_bit - one byte -- pixel bit offset within a frame buffer byte
Output parameters:
	None. The x_coord, x_offset, x_page, and x_bit input parameters are
	modified.
Description:
	This routine increments the X coordinate and recalculates
	all memory offset parameters. This operation is much faster
	than calling resii_x_offset directly with a new X coordinate.
	This routine is extensively used by all basic drawing
	primitives, since all the pixels in objects such as
	lines and circles are adjacent.

	The pixel X coordinate memory offset information differs between
	monochrome pixels and color pixels. To compute the memory offset
	of a monochrome pixel, set use_color to 0. To compute the memory
	offset of a color pixel, set use_color to 1.

Routine name:
	resii_dec_x_offset
	Decrement the memory offset of a pixel X coordinate
Address:
	program start address + 15 (Hex $610F, Decimal 24847)
Input parameters (all are modified except for use_color):
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	x_coord - two bytes -- pixel X coordinate
	x_offset - one byte -- memory offset from the first column
	x_page - one byte -- page offset (0 = MAIN, 1 = AUX)
	x_bit - one byte -- pixel bit offset within a frame buffer byte
Output parameters:
	None. The x_coord, x_offset, x_page, and x_bit input parameters are
	modified.
Description:
	This routine decrements the X coordinate and recalculates
	all memory offset parameters. This operation is much faster
	than calling resii_x_offset directly with a new X coordinate.
	This routine is extensively used by all basic drawing
	primitives, since all the pixels in objects such as
	lines and circles are adjacent.

	The pixel X coordinate memory offset information differs between
	monochrome pixels and color pixels. To compute the memory offset
	of a monochrome pixel, set use_color to 0. To compute the memory
	offset of a color pixel, set use_color to 1.

Routine name:
	resii_inc_y_offset
	Increment the memory offset of a pixel Y coordinate
Address:
	program start address + 18 (Hex $6112, Decimal 24850)
Input parameters (all are modified):
	y_coord - one byte -- pixel Y coordinate
	y_offset - two bytes -- memory offset from the first row
Output parameters:
	None. The y_coord and y_offset input parameters are modified.
Description:
	This routine increments the Y coordinate and recalculates
	all memory offset parameters. This routine is extensively used
	by all basic drawing primitives, since all the pixels in objects
	such as lines and circles are adjacent.

Routine name:
	resii_dec_y_offset
	Decrement the memory offset of a pixel Y coordinate
Address:
	program start address + 21 (Hex $6115, Decimal 24853)
Input parameters (all are modified):
	y_coord - one byte -- pixel Y coordinate
	y_offset - two bytes -- memory offset from the first row
Output parameters:
	None. The y_coord and y_offset input parameters are modified.
Description:
	This routine decrements the Y coordinate and recalculates
	all memory offset parameters. This routine is extensively used
	by all basic drawing primitives, since all the pixels in objects
	such as lines and circles are adjacent.

PIXEL DRAWING ROUTINES

Routine name:
	resii_draw_pixel_offset
	Plot a pixel using precomputed memory offset values
Address:
	program start address + 24 (Hex $6118, Decimal 24856)
Input parameters:
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	pen_color - one byte -- color or value to write
	x_offset - one byte -- memory offset from the first column
	x_page - one byte -- X coordinate page (1 = MAIN, 1 = AUX)
	x_bit - one byte -- X coordinate bit offset
	y_offset - two bytes -- Y coordinate memory offset
Output parameters:
	None.
Description:
	This routine draws a pixel to the display using precomputed
	memory offsets. This routine is extensively used by all basic
	drawing primitives, since all the pixels in objects such as lines
	and circles are adjacent.

	To draw a monochrome pixel, set the following parameters:
	- set use_color to 0
	- set pen_color to 1 to draw a pixel, or to 0 to erase a pixel

	To draw a color pixel, set the following parameters:
	- set use_color to 1
	- set pen_color from 0 to 16 to denote a color value

Routine name:
	resii_draw_pixel
	Plot a pixel
Address:
	program start address + 27 (Hex $611B, Decimal 24859)
Input parameters:
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	pen_color - one byte -- color or value to write
	x_coord - two bytes -- pixel X coordinate
	y_coord - one byte -- pixel Y coordinate
Output parameters:
	None.
Description:
	This routine draws a pixel to the display using X and Y coordinates.
	This operation is slower than resii_draw_pixel_offset and is
	recommended only for drawing individual pixels, rather than
	pixels used in a custom drawing primitive.

	To draw a monochrome pixel, set the following parameters:
	- set use_color to 0
	- set pen_color to 1 to draw a pixel, or to 0 to erase a pixel
	- keep x_coord smaller than 560

	To draw a color pixel, set the following parameters:
	- set use_color to 1
	- set pen_color from 0 to 16 to denote a color value
	- keep x_coord smaller than 140

PIXEL READING ROUTINES

Routine name:
	resii_read_pixel_offset
	Read a pixel using precomputed memory offset values
Address:
	program start address + 30 (Hex $611E, Decimal 24862)
Input parameters:
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	x_offset - one byte -- memory offset from the first column
	x_page - one byte -- X coordinate page (0 = MAIN, 1 = AUX)
	x_bit - one byte -- X coordinate bit offset
	y_offset - two bytes -- Y coordinate memory offset
Output parameters:
	read_color - one byte -- value of pixel
Description:
	This routine reads a pixel from the display using precomputed
	memory offsets.

	To read a monochrome pixel, set pen_color to 0. After calling
	this routine, the value of read_color is 1 if a pixel is drawn
	or 0 if a pixel is not drawn.

	To draw a color pixel, set pen_color to 1. After calling this
	routine, the value of read_color indicates the color value of
	the pixel at the specified memory offsets.

Routine name:
	resii_read_pixel
	Read a pixel
Address:
	program start address + 33 (Hex $6121, Decimal 24865)
Input parameters:
	x_coord - two bytes -- pixel X coordinate
	y_coord - one byte -- pixel Y coordinate
Output parameters:
	read_color - one byte -- value of pixel (0 = OFF, 1 = ON)
Description:
	This routine reads a pixel from the display using
	X and Y coordinates. This operation is slower than
	resii_read_pixel_offset and is recommended only for reading
	individual pixels, rather than pixels used in a custom regional
	read routine.

	To read a monochrome pixel, set pen_color to 0 and keep x_coord
	smaller than 560. After calling this routine, the value of
	read_color is 1 if a pixel is drawn or 0 if a pixel is not drawn.

	To draw a color pixel, set pen_color to 1 and keep x_coord
	smaller than 140. After calling this routine, the value of
	read_color indicates the color value of the pixel at the specified
	coordinates.

GRAPHICS PRIMITIVES

Routine name:
	resii_draw_line
	Draw a line between any two points
Address:
	program start address + 36 (Hex $6124, Decimal 24868)
Input paramters:
	use_color - one byte -- whether to use color (0 = NO, 1 = YES)
	pen_color - one byte -- color or value to write
	line_x_start - two bytes -- starting X coordinate
	line_y_start - one byte -- starting Y coordinate
	line_x_end - two bytes -- ending X coordinate
	line_y_end - one byte -- ending Y coordinate
Output parameters:
	None.
Description:
	This routine uses the Bresenham midpoint algorithm to
	draw a line between two points.

	To draw a monochrome line, set the following parameters:
	- set use_color to 0
	- set pen_color to 1 to draw a pixel, or to 0 to erase a pixel
	- keep line_x_start and line_x_end smaller than 560

	To draw a color line, set the following parameters:
	- set use_color to 1
	- set pen_color from 0 to 16 to denote a color value
	- keep line_x_start and line_x_end smaller than 140

