	                
	                                 
	                     
	                              
	                 
		   FUNCTION PACK for version 1.1

(C) 1997 by Andreas Ess
~~~~~~~~~~~~~~~~~~~~~~~
Just some functions for Usgard 1.1 which will make your programming an easier
task! If you want to see any other functions in here, mail me at
 ess.andreas@computerhaus.at

--> NEW:
 * FLINE! A damn fast line algorithm by Jimmy, 4 times faster than Stephane's
 * Setting of sprite/line destination using the word DEST_ADDR of Usgard!
 * GCP


Special thanks go to:

Jimmy Mardell!
Austin Butler
Sam Davies
Jingyang Xu
Stephane Jantzen

INDEX:
 INP_WKEY       - wait for any key
 INP_ST         - input string %IX, length %C, mask %A
 INP_INIT       - input initials at %HL, length %C
 DM_A_DEC       - display %A, menustyle, dec
 D_A_DEC        - display %A, normal, dec
 DM_A_HEX       - display %A, menustyle, hex (also useful for BCD)
 D_A_HEX        - display %A, normal, hex
 PSPR_NR        - normal putsprite; put %HL at (%B,%C)
 PSPR_MSK       - mask after sprite; put %HL at (%B,%C), transparency possible
 PSPR_W         - putsprite, white transparent; put %HL at (%B,%C)
 PSPR_CLP       - clip sprite
 PSPG_CLP       - clip sprite + transparency + get background
 NASRWARP       - the normal NASR routine from SPRITLIB
 ZCP            - deZCP data (normally, a picture) at %HL to destination %DE
 DELAY          - wait...
 FLINE		- a fast line from (D,E) to (H,L)
 GCP		- deGCP data at %HL to location (PAGE1ADDR)+%BC and (PAGE2ADDR)+%BC

========================= [  Input routines:  ] =============================
- INP_WKEY ------------------------------------------------------------------
output:         AF destroyed

This function waits for any key to pressed and then to be released. Might be
useful in a title screen or whatever.

- INP_ST --------------------------------------------------------------------
input:          IX = where to put the text
		C  = maximum length
		A  = starting mode:
			bit 4 = ALPHA/alpha(set) or numeric(res)
			bit 5 = alpha(set) or ALPHA(res)
output:         IX = text
		Carry set if EXIT pressed

The input string function known from Usgard .95b. Example:

	ld	C, 8
	ld	IX, TEXT_MEM
	ld	A, %00110000b	;start with lowercase alpha!
	#fncall INP_ST

-INP_INIT -------------------------------------------------------------------
input:          HL = where to put the text
		C  = maximum length
output:         HL = text

This is a little input initials function where the user has to press the up
and down arrows to select a character, 2nd for next one.


========================= [  Output routines  ] =============================
- DM_A_DEC ------------------------------------------------------------------
input:          A  = number to display in menu style, decimal

Some people on A85 requested this one.

- D_A_DEC -------------------------------------------------------------------
input:          A = number to display in normal text style, decimal

Same as DM_A_DEC, but for normal text style.

- DM_A_HEX ------------------------------------------------------------------
input:          A = number to be displayed in hexadecimal, menustyle

This may be also useful for displaying of BCD numbers!

- D_A_HEX -------------------------------------------------------------------
input:          A = number to be displayed in hex, normal textstyle

See DM_A_HEX


========================= [  Sprite routines  ] =============================
NOTE for all sprite routines:

If you want destination (where the sprite gets drawn) to be GRAPH_MEM, just do:

	ld	HL, GRAPH_MEM
	ld	(DEST_ADDR), HL

VIDEO_MEM is standard. Of course, you can use any other area, too, for instance
a variable...

- PSPR_NR -------------------------------------------------------------------
input:          HL = sprite, B = x coordinate(0-127), C = y coordinate(0-63)
		Sprite info like this:
		.db x size, y size
		.db sprite data
trap:           set page 4: ld a, 4 \ out (5), a

This is the standard putsprite, which also can be found in Jimmy's ZShell school
at HTTP://WWW.ALGONET.SE/~MJA! It doesn't support transparency.

- PSPR_MSK ------------------------------------------------------------------
input:          HL = sprite, B = x coordinate(0-127), C = y coordinate(0-63)
		Sprite info stored like this:
		.db sprite data (8 bytes) - 0 bit = black, 1 bit = white
		.db mask data (8 bytes)   - 0 bit = dont draw, 1 bit = draw
output:         AF, IX and HL destroyed
trap:           set page 4: ld a, 4 \ out (5), a

This is a modified putsprite routine, I fixed the size to 8 and added masking
(seen for instance in Sqrxz).

- PSPR_W --------------------------------------------------------------------
input:          HL = sprite, B = x coordinate(0-127), C = y coordinate(0-63)
		Sprite info like this:
		.db x size, y size
		.db sprite data
trap:           set page 4: ld a, 4 \ out (5), a

This is the standard putsprite, with added white transparency (i.e. only black
pixels are displayed), slightly faster than normal one.

- PSPR_CLP ------------------------------------------------------------------
input:          HL = sprite, B = x coordinate(0-127), C = y coordinate(0-63)
		-> CLIPPING PERFORMED! <-
		Sprite info stored like this:
		.db sprite data (8 bytes) - 0 bit = black, 1 bit = white
output:         AF destroyed
trap:           set page 4: ld a, 4 \ out (5), a

This routine is directly from Sqrxz 1.01 for Usgard. Thanks to Jimmy!


- PSPG_CLP ------------------------------------------------------------------
input:          HL = sprite, B = x coordinate(0-127), C = y coordinate(0-63)
		DE = pointer where background should be stored
		-> CLIPPING PERFORMED! <-
		Sprite info stored like this:
		.db sprite data (8 bytes) - 0 bit = black, 1 bit = white
		.db mask data (8 bytes)   - 0 bit = dont draw, 1 bit = draw
output:         AF destroyed
trap:           set page 4: ld a, 4 \ out (5), a

This routine is directly from Sqrxz 1.01 for Usgard. Thanks to Jimmy!

- NASRWARP ------------------------------------------------------------------
input:         HL = pointer to sprite
	       BC = X,Y coordinates
	       A = 0 -> erases sprite.  Anything else draws it.
output:        Registers destroyed
SPRITE FORMAT:
label:
.db a,b,c      a = smallest integer < or > X/8
	       b = a*8-x+1
	       c = Y
.db %11111111,%11111111,%11111111
.db %01010101,$01010101,%01010101
.db %00100100,%00100100,%00100100
.db %0001....

This routine by Jingyang Xu should only be used if there's need for bigger
sprites than 8x8, because PutSprite is two times faster. However, if you need
big sprites, this is your choice!

========================= [  Other  routines  ] =============================
- ZCP -----------------------------------------------------------------------
input:          HL = pointer to compressed data
		DE = where to store uncompressed data
output:         registers destroyed

Well, this is a handy, quite fast, 67 bytes small, etc. ZCP routine for your
programs. Thanks to Stephane for the original idea & routine.


- DELAY ---------------------------------------------------------------------
input:          BC = time to wait in 1/200 s
registers:      BC = 0, A = 0

This waits for a specified time.

- FLINE ---------------------------------------------------------------------
input:		(D,E) line's starting point
		(H,L) line's ending point
registers:	AF destroyed

FLINE can be used to draw lines very efficient, 4 times faster than the line
algorithm found on HTTP://WWW.TICALC.ORG

- GCP -----------------------------------------------------------------------
input:		HL = data to be decompressed to (PAGE1ADDR), (PAGE2ADDR)
		BC = starting offset within (PAGE1ADDR) and (PAGE2ADDR)
registers:	AF, BC, DE, HL, IX destroyed
traps:		grayscale must be active!!!

GCP is used to (de)compress 4 grayscale pictures. The compressor is available
at HTTP://WWW.TICALC.ORG or on my homepage, HTTP://ANDI.GANYMED.ORG

