====== Screen Handler ======

The screen handler is a group of routines for generating [[:glossary#f|frame buffer]] images. Included are entries for filling sections of the screen with constant data, the animation of figures, and the display of alphanumerics. 

Many of these routines utilize the [[hardware:magic system|Magic functions]] provided by the Astrocade's [[hardware:custom chips]]. Since the status of these chips cannot be context-switched, many of these routines are not [[:glossary#r|re-entrant]]. The user is responsible for preventing conflicts. This can be done by disabling [[hardware:interrupts]] or implementing a [[:glossary#s|semaphore]].

===== Screen Handler System Routines =====

^ Name ^ Description ^
| [[#blank|BLANK]] | Screen area is blanked to a specified byte |
| [[#chrdis|CHRDIS]] | Display ASCII character at specified screen coordinates | 
| [[#colset|COLSET]] | Set color output registers |
| [[#disnum|DISNUM]] | Display BCD number (converts each nibble into ASCII and displays them) |
| [[#distim|DISTIM]] | Display the system time (GTMINS,GTSECS) in the form MM:SS |
| [[#fill|FILL]] | Fill a contiguous memory range with a constant |
| [[#rectan|RECTAN]] | Paint a rectangle of specified size, color, and coordinates |
| [[#relabs|RELABS]] | Relative to absolute conversion |
| [[#relab1|RELAB1]] | Non-Magic RELABS |
| [[#restore|RESTOR]] | Restores area previously saved (using SAVE) |
| [[#save|SAVE]] | Preserves specified screen area that is 'underneath' a moving pattern |
| [[#scroll|SCROLL]] | Scroll area of screen |
| [[#setout|SETOUT]] | Set display ports (vertical blank line, horizontal color boundary, interrupt mode |
| [[#strdis|STRDIS]] | Display string at specified screen coordinates |
| [[#vblank|VBLANK]] | Blank area with info loaded from vector (i.e., erase vector pattern) |
| [[#vect|VECT]] | Vector move x/y coordinate pair and limit check |
| [[#vectc|VECTC]] | Vector move single coordinate and limit check |
| [[#vwritr|VWRITR]] | Write pattern relative from vector block |
| [[#writ|WRIT]] | Write pattern (with sizes provided) |
| [[#writa|WRITA]] | Write pattern to absolute position (i.e., non-Magic memory) |
| [[#writp|WRITP]] | Write pattern with size lookup |
| [[#writr|WRITR]] | Adds pattern coordinates to pattern's relative (i.e., displacement) coordinates |
===== Screen Handler System Routine Descriptions =====

==== BLANK ====

BLANK AREA

| Calling Sequence: | <code z80>SYSTEM    BLANK</code> or <code z80>SYSSUK    BLANK
DB        (x size)
DB        (y size)
DB        (data to blank to)
DW        (blank address)</code>|
| Arguments: | HL = Blank address (not Magic)\\ B = Data to blank to\\ D = Y size\\ E = X size |
| Description: | The specified area is blanked to whatever is passed in B. |
==== CHRDIS ====

DISPLAY CHARACTER

| Calling Sequence: | <code z80>SYSTEM    CHRDIS</code> or <code z80>SYSSUK    CHRIDS
DB        (x-coordinate)
DB        (y-coordinate)
DB        (options)
DB        (character)</code>|
| Arguments: | A = ASCII character to display\\ C = Standard options byte\\ D = Y-coordinate\\ E = X-coordinate\\ IX = Optional Alternate Font Descriptor address (not loaded) |
| Output: | DE = Updated to next character frame |
| Description: | This is the basic character display primitive. If tabulation is specified, the coordinates are updated, but no actual writing occurs. |
| Notes: | Observe that IX is not loaded by the UPI SUCK facility. If an alternate font is used, IX must first be loaded with the alternate font descriptor address.\\ \\ Since this routine uses [[hardware:magic system|Magic Memory]], it is not [[:glossary#r|reentrant]]. |
==== COLSET ====

SET COLOR REGISTERS

| Calling Sequence: | <code z80>SYSTEM    COLSET</code> or <code z80>SYSSUK    COLSET
DW        (color list address)</code>|
| Arguments: | HL = color list address |
| Description: | This routine sets color registers and saves the color address for use by [[human interface#pizbrk|PIZBRK]] and BLAKOUT for color restoration.\\ \\ The color list starts at COL3L and ends with COL0R. |
==== DISNUM ====

DISPLAY BCD NUMBER

| Calling Sequence: | <code z80>SYSTEM    DISNUM</code> or <code z80>SYSSUK    DISNUM
DB        (x)
DB        (y)
DB        (options)
DB        (extended options)
DW        (number address)</code>|
| Arguments: | B = Extended options\\ C = Standard alphanumeric options byte\\ D = Y-coordinate\\ E = X-coordinate\\ HL = Address of BCD number\\ IX = Optional character font descriptor (not loaded) |
| Output: | DE = Updated to next character frame |
| Description: | This routine converts each nibble into ASCII and displays it. Uses the standard BCD codes 0 through 9. The normally illegal BCD values are displayed as ASCII $2A–$2F (see below). Use [[human interface#incscr|INCSCR]] to increment the memory location pointed to in HL. |

In addition to the standard BCD set, the codes $A–$F are defined as follows:
<code>
A = *
B = +
C = ,
D = -
E = .
F = /
</code>

The extended options byte stored in B is formatted as follows:

^ Bit(s) ^ Function ^ Options ^
| 0–5 | Number of digits to display | 0–63 |
| 6 | Alternate Font | 0 = no alternate font, 1 = alternate font |
| 7 | Zero Suppress | 0 = no zero suppress, 1 = zero suppress |

If leading zero suppress is set, then instead of displaying a leading zero, a space is displayed. The first non-zero nibble encountered terminates leading zero suppression (including A–F). If the number is zero, a single zero is displayed.

If alternate font is set, the routine will display using codes between $AA–$B9 (zero starting at $B0).

(Extended options documentation courtesy of Lance Squire, Nutting Manual++)

**Example:**
<code z80>
        DO      DISNUM          ; UPI DISplay NUMber (4 digits)
        DB      $08             ; ... X = 8
        DB      $02             ; ... Y = 2
        DB      00001011B       ; ... Options (color 2 on color 3)
        DB      11000100B       ; ... Extended (ZERO SUPRS, SMALL font, 4-digit)
        DW      SCORE           ; ... Number Address (SCORE)
</code>
==== DISTIM ====

DISPLAY TIME

| Calling Sequence: | <code z80>SYSTEM    DISTIM</code> or <code z80>SYSSUK    DISTIM
DB        (x-coordinate)
DB        (y-coordinate)
DB        (options)</code>|
| Arguments: | D = Y-coordinate\\ E = X-coordinate\\ C = Options (see below)\\ IX = Alternate Font Descriptor (not loaded) |
| Output: | DE = Updated to next character frame |
| Description: | This routine displays the system time (GTMINS,GTSECS) at the specified coordinates in MM:SS format, where M = minutes, S = seconds. Seconds are optional. |
| Notes: | The small (3x5) character set is used and one level of enlarge factor is permitted.\\ \\ Options are the same as the alphanumeric display routine except that bit 7 = 1 to display colon and seconds; bit 7 = 0 to suppress colon and seconds. |
==== FILL ====

FILL A CONTIGUOUS AREA WITH CONSTANT

| Calling Sequence: | <code z80>SYSTEM    FILL</code> or <code z80>SYSSUK    FILL
DW        (first byte)
DW        (number of bytes)
DB        (data to fill with)</code>|
| Arguments: | A = Data to fill with\\ BC = number of bytes to fill \\ DE = address to begin fill |
| Description: | This routine sets the memory range DE to (DE + BC + 1) to the specified constant. |
| Notes: | FILL can be used for screen clearing or initialization of [[:glossary#s|scratchpad]] RAM. It is [[:glossary#r|reentrant]].\\ \\ There is a FILL macro in HVGLIB that can call the routine in one line:<code z80>
FILLq (start address), (# of bytes), (fill data)</code> |
==== RECTAN ====

PAINT A RECTANGLE

| Calling Sequence: | <code z80>SYSTEM    RECTAN</code> or <code z80>SYSSUK    RECTAN
DB        (x-coordinate)
DB        (y-coordinate)
DB        (x size)
DB        (y size)
DB        (color mask)</code>|
| Arguments: | A = Color mask for rectangle\\ B = Height of rectangle in pixels\\ C = Width of rectangle in pixels\\ D = Y-coordinate for upper-left corner of rectangle\\ E = X-coordinate for upper-left corner of rectangle |
| Description: | A rectangle of specified size of color mask is written at X,Y. RECTAN uses the [[hardware:Magic System|Magic functions]] and is not [[:glossary#r|reentrant]]. |
| Example: | Paint a 3x4-pixel rectangle of color 2 (10B) at screen coordinates (15,13) <code z80>
DO      RECTAN
DB      15
DB      13
DB      3
DB      4
DB      10101010B
</code> |

==== RELABS ====

CONVERT RELATIVE COORDINATES TO ABSOLUTE MAGIC ADDRESS AND SET UP MAGIC REGISTER

| Calling Sequence: | <code z80>SYSTEM    RELABS</code> or <code z80>SYSSUK    RELABS
DB        (Magic register value)</code>|
| Arguments: | A = Magic register value to set\\ D = Y-coordinate\\ E = X-coordinate |
| Output: | A = Magic register value, with proper shift amount set\\ DE = Absolute memory address (Magic) |
| Description: | The [[:glossary#l|low-order]] two bits of the x-coordinate are inserted into the [[hardware:Magic System|Magic Register]] value bit string. The absolute memory address corresponding to the coordinate is computed, taking into consideration the value of the flopped bit. The coordinate systems used are shown below. |

{{:relabs_coords.png}}

Lance Squire: "RELABS converts X/Y to MAGIC RAM addresses plus sets the shift bits for 
the MAGIC register."

==== RELAB1 ====

CONVERT RELATIVE ADDRESS TO ABSOLUTE NORMAL ADDRESS

| Calling Sequence: | <code z80>SYSTEM    RELAB1</code> or <code z80>SYSSUK    RELAB1
DB        (Magic register value)</code>|
| Arguments: | A = Magic register value to combine with shift amount\\ D = Y-coordinate\\ E = X-coordinate |
| Output: | A = Combined Magic register value\\ DE = Absolute normal address (non-Magic) |
| Description: | This routine is identical to [[#relabs|RELABS]] except that a non-Magic address is returned, and the hardware [[hardware:magic system|Magic register]] is not set. The flopped bit is interrogated, and the flopped coordinate system is used, if optioned. |

Lance Squire: "RELABS1 converts X/Y to SCREEN RAM addresses. Any pixel shifting is up 
to the user."
==== RESTOR ====

RESTORE AREA

| Calling Sequence: | <code z80>SYSTEM    RESTOR</code> or <code z80>SYSSUK    RESTOR
DW        (Save area)
DW        (Screen address)</code>|
| Arguments: | DE = Save area to restore from\\ HL = Absolute address of upper left-hand corner of area to restore |
| Description: | RESTOR is the inverse of [[screen handler#save|SAVE]]. The size of the area to restore is taken from the first two bytes of the save area. |
==== SAVE ====

SAVE AREA

| Calling Sequence: | <code z80>SYSTEM    SAVE</code> or <code z80>SYSSUK    SAVE
DW        (save area)
DB        (x size)
DB        (y size)
DW        (screen address)</code>|
| Arguments: | B = Y size of area to save\\ C = X size of area to save (in bytes)\\ DE = Address of save area\\ HL = Absolute address of upper left-hand corner of area to save |
| Description: | SAVE is used to preserve what is 'underneath' a moving pattern. SAVE copies the indicated area of the screen to the save area. The save area sizes are preserved in the first two bytes of the save area.\\ \\ The save area size must be greater than or equal to (x-size * y-size + 2).\\ \\ The save area may be Magic or non-Magic.|
==== SCROLL ====

SCROLL WINDOW

| Calling Sequence: | <code z80>SYSTEM    SCROLL</code> or <code z80>SYSSUK    SCROLL
DW        (line increment)
DB        (# of bytes)
DB        (# of lines)
DW        (first byte)</code>|
| Arguments: | B = Number of lines to scroll\\ C = Number of bytes on line to scroll\\ DE = Line increment\\ HL = First byte to scroll |
| Description: | This routine copies NBYTES from (first line + INC) to first line. Thus to scroll upward, HL points at the first line (which is overwritten), and the line increment would be positive. To scroll downward, HL points at the last line, and the line increment would be negative.\\ \\ The value in HL is an absolute address calculated by:\\ BASE OF SCREEN + #BYTES IN X OFFSET + (#lines offset * bytes per line) |
| Note: | This routine can only be used to scroll one line at a time. |
==== SETOUT ====

SET DISPLAY PORTS

| Calling Sequence: | <code z80>SYSTEM    SETOUT</code> or <code z80>SYSSUK    SETOUT
DB        VERBL (vertical blanking line*2)
DB        HORCB (frame color + color boundary)
DB        INMOD (interrupt mode)</code>|
| Arguments: | A = Data to output to INMOD (port $E)\\ B = Data to output to HORCB (port $9)\\ D = Data to output to VERBL (vertical blanking line, port $A) |
| Output: | None |
| Description: | Outputs data to designated [[hardware:i o ports|output ports]]. |
| Notes: | INMOD is the Bally Arcade's interrupt mode. \\ \\ The HORCB ([[hardware:color#horizontal color boundary]]) determines the imaginary line separating left/right color register values. The HORCB is positioned between any two adjacent screen RAM bytes (i.e., four pixels). So HORCB is equal to the Arcade's horizontal resolution (HORIZX) divided by 4. \\ \\ The VERBL (vertical blanking line) determines how many lines of screen RAM will display. The Arcade's maximum resolution is 102. Blanking before line 102 limits the graphics onscreen, but increases the available [[:glossary#s|scratchpad]] RAM. VERBL expects a value that is two times the designated blanking line (i.e., BLINE*2). So if you want the screen to blank on line 90, you must output 90*2 = 180 to VERBL. The screen area below VERBL will be set to the designated [[hardware:color#frame color]]. |
==== STRDIS ====

DISPLAY STRING

| Calling Sequence: | <code z80>SYSTEM    STRDIS</code> or <code z80>SYSSUK    STRDIS
DB        (x-coordinate)
DB        (y-coordinate)
DB        (options)
DW        (string)</code>|
| Arguments: | HL = String address\\ C = Standard options\\ D = Y-coordinate\\ E = X-coordinate\\ IX = Alternate Font Descriptor Address (not loaded) |
| Output: | DE = Updated to next character frame |
| Description: | The string pointed at by HL is displayed as optioned. The string is terminated by a zero byte. |
| Notes: | IX must be loaded prior to a SYSSUK call. STRDIS is not [[:glossary#r|reentrant]].\\ \\ There is an HVGLIB macro for STRDIS that displays a string with one line, but it must be used inside [[software:upi conventions#the interpreter]]:<code z80>TEXTD (string address), (x-coord), (y-coord), (options)</code> |
==== VBLANK ====

BLANK FROM VECTOR

| Calling Sequence: | <code z80>SYSTEM    VBLANK</code> or <code z80>SYSSUK    VBLANK
DW        (vector address)
DB        (x size)
DB        (y size)</code>|
| Arguments: | D = Y size\\ E = X size (in bytes)\\ IX = Vector address |
| Description: | VBLANK zeroes out an indicated area. First, the blank bit (VBBLNK) in the vector status byte is tested. If it is not set, no blanking is done. If it is set, it is reset, then the old screen address is taken from the vector and blanking is done. If FLOP is specified by the [[hardware:magic system#magic register|Magic register]] byte in the vector, a flopped blank is done. VBLANK always blanks to zero. |
| Notes: | Any monochrome image expanded to the screen occupies twice as many bytes horizontally and should be blanked accordingly.\\ \\ VBLANK ignores the Magic Register and Shift bits. The user must add 1 to the x-width to blank pixels shifted right from the saved address.\\ \\ VBLANK is //not// related to the Vertical Blank register. |
==== VECT ====

VECTOR OBJECT IN TWO DIMENSIONS

| Calling Sequence: | <code z80>SYSTEM    VECT</code> or <code z80>SYSSUK    VECT
DW        (vector block address)
DW        (limit table)</code>|
| Arguments: | HL = [[Limit Table]] address\\ IX = Vector block address (points at VBMR) |
| Output: | C = Time base used\\ Z = True, if no whole number values changed (i.e., no drawable motion) |
| Description: | VECT calculates the next position of a vectored pattern and indicates if any (whole number) motion took place. If the vector is inactive, control is returned immediately. Otherwise, [[screen handler#vectc|VECTC]] is called for X, then Y. The zero status is determined by comparing the new coordinate value with its old value. If the [[:glossary#h|high-order]] byte changed, then the object moved. Zero status is set if the object did not move, and reset if the object moved.\\ \\ Summary: If the vector is active and the time base is non-zero, then the update coordinate routine is called for the x and y portions of the vector block. |

The Limit Table is a four-byte list indicating the boundaries of a vectored pattern:

^ Byte ^ Name ^ Description ^
| 1 | X lower limit | The leftmost boundary the pattern may reach |
| 2 | X upper limit | The rightmost boundary the pattern may reach |
| 3 | Y lower limit | The topmost boundary the pattern may reach |
| 4 | Y upper limit | The bottommost edge the pattern may reach |

Keep in mind that the user must account for the dimensions and offset of the vectored pattern when calculating limits.
==== VECTC ====

VECTOR AN OBJECT COORDINATE

| Calling Sequence: | <code z80>SYSTEM    VECTC</code> or <code z80>SYSSUK    VECTC
DW        (coordinate address)
DW        (limit table)</code>|
| Arguments: | IX = Pointer to low-order byte of delta for coordinate\\ HL = [[Limit table]] for specified coordinate (if required)\\ C = Time base to use |
| Description: | This routine operates on the subset of the vector block associated with a single coordinate. This subset consists of the delta coordinate and checks mask. VECTC is provided so special vectoring schemes may be implemented, e.g., 1-dimensional or 3-dimensional vectoring.\\ \\ VECTC adds the delta to the coordinate time base times. It then performs the limit checks for the coordinate, if optioned. |
| Note: | VECTC does not interrogate or alter any bytes in the vector block outside of the defined subset. Hence the active bit isn't checked. | 
==== VWRITR ====

WRITE PATTERN RELATIVE FROM VECTOR

| Calling Sequence: | <code z80>SYSTEM    VWRITR</code> or <code z80>SYSSUK    VWRITR
DW        (vector block address)
DW        (pattern block address)</code>|
| Arguments: | HL = pattern block address\\ IX = vector block address |
| Output: | DE = Absolute (i.e., screen RAM) address calculated\\ A = Magic Register used |
| Description: | The coordinates and [[hardware:magic system#magic register|Magic register]] are loaded from the specified vector block. The relative (i.e., displacement) coordinates stored in the pattern block are added to the coordinates from the vector. The pattern size is also taken from the pattern block and writing proceeds. |
| Notes: | The value in DE should be copied into the vector block at VBOAL & VBOAH if user wishes to clear patterns with [[system routines:screen handler#vblank|VBLANK]].\\ \\ If the user wants to use Magic register EXPAND, they must specify the ON/OFF colors by placing the combined value into the expansion port (XPAND).\\ \\ Example:<code z80>LD      A,0CH       ;COLORS TO EXPAND TO (1100)
OUT     (XPAND),A   ;INTO EXPANSION PORT</code> |
==== WRIT ====

WRITE PATTERN

| Calling Sequence: | <code z80>SYSTEM    WRIT</code> or <code z80>SYSSUK    WRIT
DB        (x-coordinate)
DB        (y-coordinate)
DB        (x pattern size)
DB        (y pattern size)
DB        (Magic Register)
DW        (pattern address)</code>|
| Arguments: | HL = pattern address\\ A = [[hardware:magic system#magic register|Magic Register]]\\ B = Y pattern size\\ C = X pattern size\\ D = Y-coordinate\\ E = X-coordinate |
| Output: | DE = Absolute (i.e., screen RAM) address used\\ A = Magic Register used |
| Notes: | User must worry about ON/OFF color if expansion is used. |
==== WRITA ====

WRITE ABSOLUTE

| Calling Sequence: | <code z80>SYSTEM    WRITA</code> or <code z80>SYSSUK    WRITA
DW        (absolute address)
DB        (x pattern size)
DB        (y pattern size)
DB        (Magic Register)
DW        (Pattern block address)</code>|
| Arguments: | HL = pattern block address\\ A = [[hardware:magic system#magic register|Magic Register]]\\ B = Y pattern size\\ C = X pattern size\\ DE = Absolute screen address of upper left-hand corner of pattern write |
| Notes: | This routine writes patterns to non-Magic memory. The value in A is not output to the Magic register; it is only interrogated to decide whether to FLOP or EXPAND. |
==== WRITP ====

WRITE WITH SIZE FROM PATTERN BLOCK

| Calling Sequence: | <code z80>SYSTEM    WRITP</code> or <code z80>SYSSUK    WRITP
DB        (x-coordinate)
DB        (y-coordinate)
DB        (Magic Register)
DW        (pattern block address)</code>|
| Arguments: | HL = pattern block address\\ A = [[hardware:magic system#magic register|Magic Register]]\\ D = Y-coordinate\\ E = X-coordinate |
| Output: | DE = Screen address used\\ A = Magic Register used |
| Description: | The pattern size is taken from the pattern block. |
| Notes: | User must worry about ON/OFF color if expansion is used. |

See the [[:bunker|Space Invaders Bunker]] example for a demonstration of WRITP.
==== WRITR ====

WRITE RELATIVE

| Calling Sequence: | <code z80>SYSTEM    WRITR</code> or <code z80>SYSSUK    WRITR
DB        (x-coordinate)
DB        (y-coordinate)
DB        (Magic Register)
DW        (Pattern block address)</code>|
| Arguments: | HL = pattern block address\\ A = [[hardware:magic system#magic register|Magic Register]]\\ D = Y-coordinate\\ E = X-coordinate |
| Output: | DE = Screen address used\\ A = Magic Register used |
| Description: | The relative (i.e., displacement) coordinates stored with the pattern block are added to the coordinates passed in DE. Pattern size is taken from the pattern block. |
| Notes: | If Expander is used, user must set ON/OFF color before calling WRITR. |

----

[NM:14]