%format latex

\documentstyle[din_a4]{article}
\emergencystretch=100pt

\title{Devpac Falcon Library}
\author{Johan Karlsson \\ email: d92jk@efd.lth.se}
\date {Version 6 \\ 24 February, 1995}

\def\file #1.S  {\subsection{{\sc #1}}}
\def\rout @#1 #2 (#3) {{\bf @#1}\\ #2 \\ {\small (#3)\\}}
\def\routin @#1 #2 In #3 (#4) {{\bf @#1}\\ #2 \\ {\sl In #3} \\ {\small (#4)\\}}
\def\routinout @#1 #2 In #3 Out #4 (#5) {{\bf @#1}\\ #2 \\ {\sl In #3}
\\ {\sl Out #4} \\ {\small (#5)\\}}
\def\routout @#1 #2 Out #3 (#4) {{\bf @#1}\\ #2 \\ {\sl Out #3} \\ {\small (#4)\\}}
\def\macroinex @#1 macro #2 In #3 ex. #4 œ {\bf @#1 {\em macro} \rm \\ #2
\\ {\sl In #3} \\ {\small{\tt ex #4}\\}}
\def\routinex @#1 #2 In #3 (#4) ex. #5 œ {{\bf @#1}\\ #2 \\ {\sl In #3} \\ {\small
(#4)} \\ {\small{\tt ex #5}\\}}
\def\routoutex @#1 #2 Out #3 (#4) ex. #5 œ {{\bf @#1}\\ #2 \\ {\sl Out #3} \\ {\small
(#4)} \\ {\small{\tt ex #5}\\}}
\def\macroin @#1 macro #2 In #3 (#4) {\bf @#1 {\em macro} \rm \\ #2
\\ {\sl In #3} \\ {\small (#4)\\}}
\def\macro @#1 macro #2 (#3) {\bf @#1 {\em macro} \rm \\ #2 \\ {\small (#3)\\}}
\def\routinoutex @#1 #2 In #3 Out #4 (#5) ex. #6 œ {{\bf @#1}\\ #2 \\
{\sl In #3} \\ {\sl Out #4} \\ {\small (#5)} \\ {\small{\tt ex #6}\\}}
\def\ex ex. #1 œ {{\small {\tt ex #1}\\}}
\def\equ #1 EQU #2 { #1 {\em equ} #2 \\} 


\begin{document}
\twocolumn
\maketitle
\tableofcontents


\section{Introduction}

\subsection{Easy programming}

This is an assembler library for the Atari Falcon. By using this I hope
to make programming a bit faster and easier. It includes a lot of subroutines
which most assembler programmers use quite frequently as well as some
less frequently used graphic routines. I have tested all routines
and they seem to work ok, but I can't guarantee it. For everything to work
properly use Devpac 3 with ignore multiple includes active. Most things
will probably work nice with Devpac 2 too.

If you have made a routine I would appreciate if you sent it 
to me, that way I could include it in the Falcon Library for the
benefit of everyone. Please send any questions, bugreports
or contributions to me. My address is at the end of this document.

\subsection{How to use it}			
			
Following are short descriptions of all included routines. Most are
subroutines and should be called with 'bsr' or 'jsr' unless the word
macro follows the routine name in which case it is a macro. If a
routine says 'destroys a lot' then you should save all the registers
you are using except a7 which is never ruined. Some routine descriptions
even contains an example, so hopefully there will be no problems
understanding them.

The @ found before every function name is there to prevent
nameing conflicts with labels in your own program.


\section{Routine descriptions}


\file
 Cache.S

	Cache equates. You'll need devpac 3 for this one I think.
	Here they are:
\\
\equ
	 ENABLE\_CACHE		EQU 1   
\equ
	 FREEZE\_CACHE		EQU 2  
\equ	 
	 CLEAR\_INST\_CACHE\_ENTRY	EQU 4   
\equ
	 CLEAR\_INST\_CACHE	EQU 8  
\equ
	 INST\_BURST\_ENABLE	EQU 16  
\equ
	 ENABLE\_DATA\_CACHE	EQU 256 
\equ
	 FREEZE\_DATA\_CACHE	EQU 512 
\equ
	 CLEAR\_DATA\_CACHE\_ENTRY	EQU 1024 
\equ
	 CLEAR\_DATA\_CACHE	EQU 2048 
\equ
	 DATA\_BURST\_ENABLE	EQU 4096 
\equ
	 WRITE\_ALLOCATE		EQU 8192 
\ex
 ex.	move.l \#ENABLE\_CACHE+ ENABLE\_DATA\_CACHE+ WRITE\_ALLOCATE,d0 \\
      movec	d0,CACR ; turns on the caches 
œ


\file
 Cls.S
\routin
	@cls???
	 clears ??? bytes.
 In	 a0.l=start address
	 (destroys a lot)

\file
 Convpal1.S
\routinout
	@convert\_stpal
	Convert an old st colour value to a new falcon one
 In	d0.w=old st colour
 Out	d0.l=falcon colour
	(destroys d1-d3)


\file
 Cookie.S
\routinout
	@getcookie
	Finds and returns a Cookie. Supervisor only!
 In	d1.l=Cookie name
 Out	d0.l=Cookie value or -1
	(destroys a0)


\file
 Dspmod.S
\routin
	@dsp\_play
	Sets interupts and plays some soundtracker music. Modules mustn't have 
	more than 4 voices. Supervisor only.
 In	a0.l=Module adr.
	(destroys a lot)
\\
\rout
	@dsp\_stop
	Stops playing the music and restores interupts.
	Supervisor only.
	(destroys a lot)


\file
 Exit.S
\macro
	@exitifspace  macro
	 branches to exit if space has been pressed. Supervisor only!
	 (destroys nothing)

\file
 Fade.S
\routin
	@fadetrupix
	 Fades a true colour pixels from one colour to another.
	 It will fade 1/31 part each time you call this rout.
 In	 a0.l=pointer to colour to change\\
	 a1.l=pointer to target colour
	 (destroys d1-d4; adds 2 to a0-a1)


\file
 Fade2.S
\routin
	@fadetrupix2
	 Fades a true colour pixels from one colour to another.
	 It will fade 1/31 part each time you call this rout.
	 The difference between this one and FADE.S is that this one
	 fades two pixels at once and is slightly faster.
 In	 a0.l=pointer to colours to change\\
	 a1.l=pointer to target colours
	 (destroys d1-d4; adds 4 to a0-a1)

\file
 Frame.S
	This is a program frame that may be used as a start for
	new programs. Just load it and fill in the blanks (there
	is a lot of them).

\file
 Gem.S
\macroinex
	@gemdos	macro
	Calls trap \#1
 In	 \#functionnbr, \#stackcorrection
 ex.	 @gemdos~1,2 ; waits for a key œ
\\
\macroinex
	@xbios	macro
	Calls trap \#14
 In	 \#functionnbr, \#stackcorrection
 ex.	 @xbios~37,2 ; waits for vsync œ
\\
\macroinex
	@gem	macro
	Calls a trap
 In	 \#functionnbr, \#trapnbr, \#stackcorrection
 ex.	 @gem~1,1,2 ; waits for a key œ


\file
 Getpar.S	(include right after releasem.s)

	Gets all parameters sent to the program.
	Must be directly after releasem.\\
Out	a0.l=Address where the parameters are kept
\ex
 ex.	include	releasem.s ; release unused memory, this is line nr 1 of the
	program\\
   include getpar.s ; get adr. where the parameters are kept\\
	move.l a0,paradr ; save the result\\
\\
	paradr ds.l 1
œ

\file
 Goraud.S
\routinex
	@goraud
	Draw a goraud shaded polygon in true colour.
	There's no clipping so don't draw too large polygons.
	Call @initgoraud once before using this one!
\\
 In	a1.l=screen address\\
	a2.l=adr to colour table\\
	new\_crds=following table: [x,y,i]*nbr\_of\_points\\
	d6.w=nbr. of points\\
	xres equ horizontal resolution
	(destroys a lot)
 ex.	 xres equ 384 ; overscaned lowres screen\\
	 bsr @initgoraud ; call once only\\
	 move.l scradr,a1 ; screenaddress\\
	 move.l \#g\_red,a2 ; I want a red poly\\
	 moveq \#4,d6 ; four points\\
	 bsr @goraud ; draw it\\
	 new\_crds dc.w 10,10,0 ; a dark point\\
          	  dc.w 200,20,\$7fff ; a bright point\\
		  dc.w 140,140,\$7fff/2\\
		  dc.w 25,50,\$7fff/4
œ	

	The colourtable consists of 32 words, each a true colour value.
	 word nr 0 is the darkest and word nr 31 the brightest. This is
	 followed by 16 empty words.
	Supplied colours: g\_lightred, g\_green, g\_brown, g\_white
	new\_crds is a table that consist of a pair of coordinates followed
	 by a brightnes factor. The brightnes factor is a number between 0
	 and \#\$7fff.
\\\\
\rout
	@initgoraud
	 This subroutine must be called once before using @goraud.
	 (destroys a lot)

\file
 Hline1.S
\routinex
	@drawhline1
	Draws a horizontal line in 8 bitplane mode. Clipping is implemented.
	This routine only uses the six first bitplanes.
 In	a0.l=screenadr \\ d0=xmin \\ d1=xmax \\
	d2.l--d4.l =6 bitplanes \\
	xres equ  horizontal screen resolution
	(destroys d0--d7/a0--a1)
 ex.	 move.l	screen+xres*50,a0 ; ypos=50\\
	 move \#-34,d0		left xcord\\
	 move \#67,d1		right xcord\\
	 move.l \#\$0,d2		don't set bitplane 0 or 1\\
	 move.l	\#\$0000ffff,d3	set bitplane 3\\
	 move.l	\#\$ffffffff,d4	set bitplane 4 and 5\\
	 bsr @drawhline1
œ

\file
 Ice.S
\routin
	@icedecrunch
	Checks if the data is icepacked and possibly unpacks it.
 In	a0.l=Data adr.
	(destroys nothing)

\file
 Jagpad.S
\routout
	@jpd
	Reads a joypad. Supervisor only!
 Out	d3.l = c1numpad,c1midbuts,c1firebuts,c1joypad
	d6.l = c2numpad,c2midbuts,c2firebuts,c2joypad
	(destroys d0-d7/a0)

 d3/d6 contain bitwise representation in the form
 1 4 7 * 3 6 9 # 2 5 8 0 o p c b a r l d u
 where o=option, p=pause, a/b/c=fire,
 r/l/d/u=directions. and rest are the phone pad.
 d3=port 0, d6= port1.
\\\\
\file
 Loadfile.S
\routin
	@loadfile
	Loads a file and possibly unpacks it (ice 2.40).
 In	a5.l=adr. to a filename terminated by zero\\
	a6.l=dest.\\
	d7.l=filelength (this value may be larger than the file length if
	you want to load the complete file)
	(destroys a lot)
	

\file
 Releasem.S

	This routine releases all memory not needed by the program.
	Include this rout at the top of your program and the memory
	will be relesed properly.
\ex
 ex.	include	releasem.s ; release unused memory, this is line nr 1 of the
program œ


\file
 Savefile.S
\routin
	@savefile
	Saves data as a file.
 In	a5.l=adr. till nollavslutat filnamn\\
	a6.l=source\\
	d7.l=fill„ngd
	(destroys a lot)


\file
 Setfv.S
\routinout
	@setfv
	 Sets the falcon video registers. The data that is
	 written to the video registers must be a .FV (Falcon Video)
	 file. Supervisor only. The advantages of using this instead of 
	 {\bf @setvideo} is that this one will work with screen enhancers
	 like screenblaster, {\bf @setvideo} won't and by using .FV files
	 it's also possible to get higher resolutions.
 In	 a0.l=adr. to Falcon Video data
 Out	 d0.l: 0=no error  -1=error, no .FV data
	 (destroys d0--d2/a0--a2)
\\
\rout
	@savefv
	 Saves the falcon video registers to memory. Supervisor only.
	 (destroys a0--a1)
\\
\rout
	@resorefv
	 Restores the saved falcon video registers. Supervisor only.
	 (destroys d0--d2/a0--a2)

\file
 Setvideo.S
\routinex
	@setvideo
	 Save and set resolution.
 In	 d7.w=mode\\
  modeequates: vertflag, stmodes, overscan, pal, vga, col80, bps1--16
	 (xbios, destroys d0--d2/a0--a2)
 ex.	 move \#pal+bps16,d7\\
	 bsr @setvideo œ
\\
\rout
	@restorevideo
	 Restores the saved resolution.
	 (xbios, destroys d0--d2/a0--a2)
\\
\routin
	@setvadr
	 Sets the physical and logical screenaddress.
 In	 d0.l=screenadr.
	 (xbios, destroys d0--d2/a0--a2)
\\
\rout
	@savevadr
	 Saves the current screenadr.
	 (xbios, destroys d0--d2/a0--a2)
\\
\rout
	@restorevadr
	 Restores the saved screenadr.
	 (xbios, destroys d0--d2/a0--a2)


\file
 Shrtones.S
\rout
	@super
	 enter supervisor mode  (gemdos \$20, destroys d0-d1/a0-a1)
	 \\
\rout
	@user
	 returns to user mode  (gemdos \$20, destroys d0-d1/a0-a1)
	 \\
\rout
	@waitvbl
	 waits for a vertical blank  (xbios \#37, destroys d0-d2/a0-a2)
	 \\
\routout
	@waitkey
	 waits for a keypress, no echo 
 Out	 d0.b=ascii value
  (gemdos \#7, destroys a0)
  \\
\rout
	@exitifkey
	 quits if a key has been pressed
	 (gemdos \#11,\#7,\#0, destroys a0)
\\
\rout
	@quit
	 terminate process  (gemdos \#0)
\\
\routin
	@print
	 prints a string on the screen.  
 In	 a0.l=address to a null terminated ascii string
	(gemdos \#9, destroys a0)

\file
 Timer.S
\macroin
	@colour  macro
	 sets backround colour to value. Supervisor only!
 In value.l
	 (destroys nothing)

\file
 Trig.S

	All results are taken from a 1440 entries large lookup table.\\
\\
\routinout
	@sin
	 Returns the sine of an angle.
 In	 d0.w=angle in degrees with six decimal bits (the legal values are
 		0-\$59ff or 0-359.999 degrees) 
 Out	d1.w=sin(angle), a word with one
	 	sign bit and 15 decimal bits. (destroys d0/a0)
	 	\\
\routinoutex
	@cos
	 Returns the cosine of an angle.
 In	 d0.w=angle in degrees with six decimal bits (the legal values are
 0-\$59ff or 0-359.999 degrees) 
 Out d1.w=sin(angle), a word with one
	 sign bit and 15 decimal bits. (destroys d0/a0)
 ex.	move \#180*64,d0		; make it 180 degrees\\
	bsr @sin		; d1 will now contain 0\\
	move \#180*64,d0		; d0 is destroyed so we had better enter the value
	again\\
	bsr @cos ; d1 will now contain -1 (\$8000)
œ

\file
 Truespr.S
\routin
	@truespr
	 This routine draws a true colour sprite. It draws both
	 packed and unpacked sprites. Clipping isn't supported yet.
	 The sprite must be created using the Spooky Sprites sprite creator.
 In	a0.l=address to sprite file\\
	a1.l=screenadr\\
	d0.l=sprite nbr.\\
	d1.l=xpos\\
	d2.l=ypos\\
	xres equ screenwidth in pixels\\
	yres equ height of display
	(destroys d0-d7/a0-a3)


\file
 Window.S
  ({\sc Vdilib} and {\sc Aeslib} must be included at the end of the
program) \\\\
\routinout
	@createwindow
	Creates and opens a simple gem window.
	The size (xwidth,ywidth) is the workarea of the window.
 In	wtype equ \%info move full close name\\
	xstart.w, ystart.w ,xwidth.w ,ywidth.w ,windowname (string terminated by 0)
 Out w\_handle.w, ap\_id.w, screenxmax.w ,screenymax.w
	(destroys a lot)
	\\
\rout
	@recalcwindow
	 Recalculates the window size.
	 (destroys a lot)
	 \\
\routin
	@moveit
	 Moves the window. May be called at every vm\_moved(=28) event.
 In	 a0.l=adr to messagebuffer
	 (destroys a lot)
	 \\
\routin
	@drawrsrc
	 Draws the rsrc.
	 This function doesn't care about clipping, so you should probably not use it.
 In	 a0.l=adr to rsrc
	 (destroys a lot)
	 \\
\routin
	@updatersrc
	 Draws the rsrc. Use this when receiving update events(=20).
	 This function takes care of all clipping.
 In	 a0.l=adr to rsrc
	 (destroys a lot)
	 \\
\routin
	@topwindow
	 Activates the window. May be called at every vm\_topped(=21) event.
 In	 a0.l=adr to messagebuffer
	 (destroys a lot)
	 \\
\routin
	@bottomwindow
	 Bottoms the window if  it's   mine.   May   be   called   at   every
		vm\_bottomed(=33) event. 
 In a0.l=adr to messagebuffer 
	 (destroys a lot)
	 \\
\routinout
	@button
	 Returns the object number that was clicked on. This function may be called
	 at every mousebutton event.
 In	 a0.l=adr. to rsrc
	 (It automatically takes the x and y coordinates from int\_out)
 Out	 d0.w=object that was pressed or -1.
	 (destroys a lot)
	 \\
\routinout
	@loadrsrc
	 Loads a resource file and creates a window containg the object in the
	 file. You don't have to call @createwindow if you use @loadrsrc.
 In	 wtype equ \%info move full close name\\
	 windowname (string terminated by 0)\\
 	 a0.l=address to a nul terminated filename
 Out	 a0.l=address to the resource data\\
w\_handle.w, ap\_id.w, screenxmax.w, screenymax.w
	 (destroys a lot)


\file
 Winevent.S
\routinoutex
	@dowindowevents
	 For the lazy one. This function waits for events and takes care of
	 everything but the close button or if someone clicked on an object.
	 If one of these events occur the program branches to closeevent
	 or buttonevent. Those subroutines you have to make yourself.
 In	 a0.l=adr. to rsrc\\
	 w\_handle, ap\_id (These are created automatically if you use
	 @createwindow or @loadrsrc)
Out buttonevent: d0.w=number of the object pressed \\
closeevent: nothing (destroys a lot)
 ex.	;create a window;\\
	move.l rsrcadr,a0\\
	bra @dowindowevents	; it will never return so you may use 'bra' or 'jmp'\\
\\
 buttonevent		; d0.w will contain the object that was pressed\\
	cmp \#1,d0 	; was it my button?\\
 	beq mybutton	; yes!\\
	rts		; no!\\
\\
 closeevent\\
	bsr @exitwindow	; close window\\
	(rsrc\_free)	; only if you have used @loadrsrc\\
	bra @quit	; quit
œ



\section{History}

\subsection{Version 6}

A routine to draw true colour sprites created using Spooky Sprites is now
included. A correction in the FV format description. New FV vga files made
by Anthony Jacques. Code for jagpad reading included. Improved FV editor.

\subsection{Version 5.2}

GFA Basic source code for using FV files are now included.
320*240 rgb FV files added.

\subsection{Version 5.1}

There was an error in the FV Editor documentation that is removed now. The FV
editor has also been somewhat improved.

\subsection{Version 5}

A bug in the FV routines has been removed (I had missed some important
registers). You cannot use old FV files with the new routines! A FV editor is
now supplied to test or edit FV files and there is also some documentation
describing the FV file format. There has also been some corrections in the
main manual (the one you are reading now) and a postscript version has been
added.

\subsection{Version 4}

This \LaTeX\ document is now included. 
True colour fade rout optimised (about 20\% faster) and
a new two pixels at once fader that is slightly faster 
is added.
A program frame added that may be used as a start for
new programs ({\sc Frame}).
{\bf @colour} in {\sc Timer} is changed.
{\bf @print} is now available in {\sc Shrtones}.

\subsection{Version 3}
			
True colour fade routine added (found in the jagdemo).

\subsection{Version 2}
			
This one has got a file that is necessary to use {\sc Dspmod} and a file
that is necessary to use {\sc Trig} included, unfortunately I forgot
them in v1. A new function in {\sc Window}, {\bf @loadrsrc} loads a resource file
and creates a window with the loaded object in it.

\subsection{Version 1}
			
The first one. Lots of files missing.


\section{Credits}

\file Cache.S
Cache equates made by Griff.	
	
\file Dspmod.S
DSP MOD replay routine written by bITmASTER of BSW.
Additional code by Dusan.

\file Fade.S
Fadeit - true colour versh, coded by <Genie!> of Network Trash.

\file *.FV
Vga FV files made by Anthony Jacques.

\file Goraud.S
Fast Gouraud shading polygon routines, July 1993 by Griff.
	
\file Jagpad.S
Jagpad reading function made by Anthony Jacques.

\section {Address}

Most of the other stuff and putting everything together was
made by Johan Karlsson. Any contributions are very welcome, my address
is:

\begin{center}
email: d92jk@efd.lth.se
\end{center}

\begin{center}
SnailMail:\\
Magistratsv. 55 X112\\
226 44 Lund\\
SWEDEN
\end{center}

\begin{center}
Telephone: (0)46 392017
\end{center}





\end{document}
