Technical information on the TI-82 ROM routines referenced by CALL and
ROM_CALL() as used for OShell-82 version 2.0 and 2.5

The majority of the information included in this document (Part I) was
retrieved from the file ZSFNLIB.TXT by Magnus Hagander and Rob Taylor, as
included in the release archive file of ZShell 4.0.

The remainder of the text file (Introduction, Part II) is written by Jason
Todd <toddlers@erinet.com>

Introduction and Part II (C) 1997 Alphasoft
===========================================================================

Introduction

This file is meant to provide a quick means of learning the TI-82's most
commonly used ROM routines.  They are all used the same way as they are on
the TI-85, so if you are familiar with the TI-85's routines, you may skip
past Part I and read Part II which contains new ROM_CALL indexes.

The functions explained in this file are defined for assembler use in the
TI-82.H file included with OShell-82.

===========================================================================

Part I - (C) 1995 Magnus Hagander and Rob Taylor

Function Index

The following functions are described in this file:

   * LD_HL_MHL
   * CP_HL_DE
   * UNPACK_HL
   * STORE_KEY
   * GET_KEY

   * TX_CHARPUT
   * D_LT_STR
   * M_CHARPUT
   * D_ZM_STR
   * D_LM_STR
   * GET_T_CUR
   * SCROLL_UP
   * TR_CHARPUT
   * CLEARLCD
   * D_HL_DECI
   * CLEARTEXT
   * D_ZT_STR
   * BUSY_OFF
   * BUSY_ON
   * FIND_PIXEL

---------------------------------------------------------------------------

LD_HL_MHL

Call method: call LD_HL_MHL
Input:       HL = pointer
Returns:     HL = (HL)   (the byte pointed to by HL)
             A  = L      (just a junk return?)

Description: This function loads HL with the value pointed to by HL. This
can be useful if you want to retreive the word pointed to by HL.
Traps: Note that the call changes the contents of A.
Example:

   ld   hl,LOOKUP         ;HL points to a lookup table defined in RAM
   ld   de,OFFSET         ;DE is how far into the table we want to be
   add  hl,de             ;HL now points to the word we want
   call LD_HL_MHL         ;HL now contains the word we looked up in the table

---------------------------------------------------------------------------

CP_HL_DE

Call method: call CP_HL_DE
Input:       HL, DE = The words to compare
Returns:     The same flags as CP. E.g. zero flag set if they are equal.

Description: This function compares the contents of HL and DE with each
other. It works just as the CP instruction, but CP does not work with words
- just bytes.
Traps: The function compare the VALUES of DE and HL, not the memory pointed
to by them (as HL is usually used for).
Example:

   ld   HL,VALUE1         ;HL contains one value
   ld   HL,VALUE2         ;DE contains second value
   call CP_HL_DE
   jr   z,Equal           ;Jump to equal if HL and DE were equal.

---------------------------------------------------------------------------

UNPACK_HL

Call method: call UNPACK_HL
Input:       HL = value to unpack from
Returns:     A  = value unpacked from HL
             HL = changed, to allow unpacking of next number

Description: This function "unpacks" one number from HL. It works from
right to left, unpacking the one-number first, then the 10-number and so
on. It is used to convert HL into characters that can be displayed using
the standard functions in decimal form. This function is used by D_HL_DECI.
Traps: Note that the function destroys the contents of HL.
Example:

   ld   de,StringPlace+4        ;Location to store string
   ld   b,5                     ;A word fits into 5 characters
ConvLoop:
   call UNPACK_HL               ;Unpack the next number
   add  a,'0'                   ;Now A is the CHARACTER for this value
   ld   (de),a                  ;Put that character into the string
   dec  de                      ;Point DE to the next byte in the string
   djnz ConvLoop                ;Convert all the 5 characters

---------------------------------------------------------------------------

STORE_KEY

Call method: call STORE_KEY
Input:       A = scancode
Returns:     (8000) = scancode
             (8006) = scancode (if scancode <>0)
             set 3,(IY+00)

Description: This function stores a keystroke into the buffer. This
keystroke can then be read by the GET_KEY function.
Traps: Overwrites any scancode that is in the buffer already.
Example:

   ld   a,$0F             ;0F is the scancode for key CLEAR
   call STORE_KEY         ;Store CLEAR into the keystroke buffer

---------------------------------------------------------------------------

GET_KEY         + Doesn't seem to work the same way on the TI-82!

Call method: call GET_KEY
Input:       None
Returns:     A = scancode of last key pressed
             HL = 8000
             res 3,(IY+00)

Description: This is one of the most used ROM function. It returns the last
key that was pressed. The value returned in A is the scancode of the key.
Traps: Note that the contents of HL is changed. GET_KEY returns 0 if there
was no key pressed - it does not wait for a key.
Example:

KeyLoop:
   call GET_KEY
   jr   z,KeyLoop         ;Loop until a key is pressed, then continue

---------------------------------------------------------------------------

TX_CHARPUT

Call method: ROM_CALL(TX_CHARPUT)
Input:       A = Character to print
             Memory and bits for normal output.
Returns:     (800C) and (800D) updated with new cursor positions.

Description: This function prints a character to the screen. It also
converts the character if it is a control character.
Traps: If you set it to alter text memory, contents of your own variables
can be changed if they reside within the text memory (they usually do).
Example:

   ld       hl,$0101      ;HL contains X and Y position
   ld       ($800C),hl    ;Since HL is a word, it overlaps into 800D
   ld       A,'2'         ;Char to put
   ROM_CALL(TX_CHARPUT)   ;Put the character

---------------------------------------------------------------------------

D_LT_STR

Call method: ROM_CALL(D_LT_STR)
Input:       HL = pointer to length index string
             Memory and bits for normal output.
Returns:     (800C) and (800D) updated with new cursor position.
             HL = pointer to next byte after the string

Description: This function prints a string of characters to the screen in
normal text style (not menu style). The length of the string is determined
by the value of the first byte in the string. The cursor coordinades are
updated, and HL will point to the next byte after the string. Traps: HL is
a full pointer to the string. If you are using a string defined within your
program, you must add the programs start offset to it.
Example:

   ld   hl,STRING         ;Offset of the string, defined within "myself"
   ld   de,(PROGRAM_ADDR) ;Address of program start, defined in TI-85.H
   add  hl,de
   ROM_CALL(D_LT_STR)     ;Display the string
   ret                    ;Return from sub-routine (or to ZShell)
String:
   .db  5,"Hello"         ;String to use

---------------------------------------------------------------------------

M_CHARPUT

Call method: ROM_CALL(M_CHARPUT)
Input:       A = character to print
             Memory and bits for menu output.
Returns:     (8215) updated with new cursor position.
             DE is destroyed.

Description: This function prints the character in A on the screen in "menu
style". This is the style that is used by the TI-85 itself when in graphics
mode and in menus.
Traps: Note that DE is destroyed.
Example:

   ld   a,'A'             ;I want to print the character A.
   ld   hl,$1010          ;HL contains the coordinates
   ld   ($8215),hl        ;Since HL is a word, it overlaps into 8216
   ROM_CALL(M_CHARPUT)

---------------------------------------------------------------------------

D_ZM_STR

Call method: ROM_CALL(D_ZM_STR)
Input:       HL = pointer to null terminated string
             Memory and bits for menu output.
Returns:     (8215) updated with new cursor position.
             HL = pointer to next byte after string.

Description: This function prints a zero terminated string (ASCIIZ) on the
screen in menu style.
Traps: HL is a full pointer to the string. If you are using a string
defined within your program, you must add the programs start offset to it.
Example:

   ld   hl,STRING         ;Offset of the string, defined within "myself"
   ld   de,(PROGRAM_ADDR) ;Address of program start, defined in TI-85.H
   add  hl,de
   ROM_CALL(D_ZM_STR)     ;Display the string
   ret                    ;Return from sub-routine (or to ZShell)
String:
   .db  "Hello",0         ;String to use, with a 0 at the end

---------------------------------------------------------------------------

D_LM_STR

Call method: ROM_CALL(D_LM_STR)
Input:       HL = pointer to string
             B  = length of string
             Memory and bits for menu output.
Returns:     (8215) updated with new cursor position.
             HL = pointer to next byte after string.

Description: This function prints a length indexed string on the screen in
menu style.
Traps: HL is a full pointer to the string. If you are using a string
defined within your program, you must add the programs start offset to it.
Example:

   ld   hl,STRING         ;Offset of the string, defined within "myself"
   ld   de,(PROGRAM_ADDR) ;Address of program start, defined in TI-85.H
   add  hl,de
   ld   b,5               ;We want to print 5 characters
   ROM_CALL(D_LT_STR)     ;Display the string
   ret                    ;Return from sub-routine (or to ZShell)
String:
   .db  "Hello"           ;String to use

---------------------------------------------------------------------------

GET_T_CUR

Call method: ROM_CALL(GET_T_CUR)
Input:       None
Returns:     HL = absolute address of text cursor (in 80DF text memory)

Description: This function returns the absolute address of the text cursor.
Traps: None, I think.
Example:

   ROM_CALL(GET_T_CUR)      ;Get the address
   ld   (hl),'A'            ;Set this byte to "A".

---------------------------------------------------------------------------

SCROLL_UP

Call method: ROM_CALL(SCROLL_UP)
Input:       (8B2F) = first row to scroll (0-7)
             (8B30) = last row to scroll (1-8)
             set 1,(IY+OD) = scroll the text memory
             res 1,(IY+0D) = don't scroll the text memory
Returns:     None

Description: This function scrolls the screen or part of it one line up,
and inserts a blank line at the end of it.
Traps: If you chose to scroll the text memory, your own variables can be
changed if they reside in the text memory, which they normally do.
Example:

   sub  a                 ;Set A=0
   ld   ($8B2F),a         ;Starting row is 0
   ld   a,5
   ld   ($8B30),a         ;Last row to scroll is 5
   ROM_CALL(SCROLL_UP)

---------------------------------------------------------------------------

TR_CHARPUT

Call method: ROM_CALL(TR_CHARPUT)
Input:       A = Character to print
             Memory and bits for normal output.
Returns:     (800C) and (800D) updated with new cursor positions.

Description: This function prints a character to the screen.
Traps: If you set it to alter text memory, contents of your own variables
can be changed if they reside within the text memory (they usually do).
Example:

   ld       hl,$0101      ;HL contains X and Y position
   ld       ($800C),hl    ;Since HL is a word, it overlaps into 800D
   ld       A,'2'         ;Char to put
   ROM_CALL(TR_CHARPUT)   ;Put the character

---------------------------------------------------------------------------

CLEARLCD

Call method: ROM_CALL(CLEARLCD)
Input:       None
Returns:     The LCD is cleared (FC00-FFFF is zeroed out).
             Text and graphics memory are left untouched.
             HL=8358
             DE=0000
             BC=0000

Description: This function clears the LCD screen. Since it does not change
the text memory, your variables are left alone.
Traps: Quite a lot of registers are changed.
Example:

   ...
   ROM_CALL(CLEARLCD)
   ...

---------------------------------------------------------------------------

D_HL_DECI

Call method: ROM_CALL(D_HL_DEC)
Input:       HL = value to print
             Memory and bits for normal output.
Returns:     (800C) and (800D) updated with new cursor positions.

Description: HL is displayed as a 5-number, right justified, blank-padded
decimal number.
Traps: None, I think.
Example:

   ld   hl,1234                ;This is the value we want to print
   ROM_CALL(D_HL_DECI)

---------------------------------------------------------------------------

CLEARTEXT

Call method: ROM_CALL(CLEARTEXT)
Input:       set 1,(IY+0D) = fill text memory (80DF) with spaces
             res 1,(IY+0D) = clear the LCD without altering the text memory
Returns:     None

Description: This function clears the text memory. If you want to be sure
you just clear the screen and not the memory, use the CLEARLCD function
instead.
Traps: If you fill the text memory with spaces, any data you have stored in
variables there will (logically) be destroyed.
Example:

   ...
   ROM_CALL(CLEARTEXT)          ;Yikes, I lost my variables...
   ...

---------------------------------------------------------------------------

D_ZT_STR

Call method: ROM_CALL(D_ZT_STR)
Input:       HM = pointer to null-terminated string
             Memory and bits for normal output.
Returns:     (800C) and (800D) updated with new cursor positions.

Description: This function prints a zero-terminated string on the screen in
normal style.
Traps: HL is a full pointer to the string. If you are using a string
defined within your program, you must add the programs start offset to it.
Example:

   ld   hl,STRING         ;Offset of the string, defined within "myself"
   ld   de,(PROGRAM_ADDR) ;Address of program start, defined in TI-85.H
   add  hl,de
   ROM_CALL(D_ZT_STR)     ;Display the string
   ret                    ;Return from sub-routine (or to ZShell)
String:
   .db  "Hello",0         ;String to use with a 0 behind

---------------------------------------------------------------------------

BUSY_OFF

Call method: ROM_CALL(BUSY_OFF)
Input:       Nothing
Returns:     res 0,(IY+12)

Description: The busy indicator (upper right corner of the screen) is
turned off.
Traps: None, I think.
Example:

   ...
   ROM_CALL(BUSY_OFF)
   ...

---------------------------------------------------------------------------

BUSY_ON

Call method: ROM_CALL(BUSY_ON)
Input:       None
Returns:     set 0,(IY+12)

Description: The busy indicator (upper right corner of the screen) is
turned on.
Traps: None, I think.
Example:

   ...
   ROM_CALL(BUSY_ON)
   ...

---------------------------------------------------------------------------

FIND_PIXEL

Call method: ROM_CALL(FIND_PIXEL)
Input:       B = X coordinate
             C = Y coordinate
Returns:     HL = offset in video buffer
             A = Value of bit to change

Description: This function returns the offset and bit-value of a given
pixel on the graphics screen. It is useful if you want to set, reset or
read a single pixel. If you want to update a larger area of the screen, you
should use direct memory access. Check this page for example of routines
that use this function.
Traps: HL and A are (naturally) destroyed. This function must be executed
when memory page is set to 4. To do this, use the following code:

   ld   a,4
   out  (5),a

Example:

   ld   b,10
   ld   c,50                ;Put pixel at (10,50)
   ROM_CALL(FIND_PIXEL)
   or   (hl)
   ld   (hl),a

Memory and bit sets for normal text operations

The following memory addresses and bits are used in the functions that deal
with normal text strings (not menu style):

             (800C) = Row to put character in
             (800D) = Column to put character in
             set 3,(IY+05) = Display white on black
             res 3,(IY+05) = Display black on white (normal)
             set 1,(IY+0D) = Alter text memory
             res 1,(IY+0D) = Don't alter text memory

Memory and bit sets for menu text operations

The following menu addresses and bits are used in the functions that deal
with menu text strings:

             (8215) = x coordinate
             (8216) = y coordinate
             res 1,(IY+05) = Print only 6 rows of the character
             set 1,(IY+05) = Print entire 7 rows of the character
             res 3,(IY+05) = Print character over current screen
             set 3,(IY+05) = XOR character with current screen

===========================================================================

Part II - (C) 1997 Jason Todd

In OShell-82 version 1.0 and 1.1, I included two important routines which are
also present in the TI-83 supported assembly language.

---------------------------------------------------------------------------

_GETKEY

Call method: ROM_CALL(_GETKEY)
Input:       None
Returns:     A contains the code of the key pressed

Description: This function waits in low-power mode for a key then returns its
value.  APD can occur after about 5 minutes if no key is pressed.  If 00 is
returned, then ON has been pressed and the ON INTERRUPT flag has been set.
Then you must reset the flag with RES 4,(IY+09) in order to restore _getkey's
correct functionality.

Traps: WARNING - While this call interprets the [2nd] and [ALPHA] keypresses,
it also interprets [2nd] [ON] which means the calculator can be turned off
from this routine.  But, when it is turned back on the calculator will either
lock up or reset, either way it is lethal to your assembly language program.

---------------------------------------------------------------------------

_GRBUFCPY_V

Call method: ROM_CALL(_GRBUFCPY_V)
Input:       Nothing
Returns:     Nothing

Description: The graph memory ($88B8) is displayed on the LCD
Traps: Whatever was on the LCD first gets overwritten (not really a trap...)

---------------------------------------------------------------------------
