%format latex \documentstyle[din_a4]{article} \emergencystretch=100pt \title{Devpac Falcon Library} \author{Johan Karlsson \\ email: d92jk@efd.lth.se} \date {Version 4 \\ 13 October 1994} \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. \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 alot 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 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 (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. 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 screenadress. 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\\ bsr @cos value again ; d1 will now contain -1 (\$8000) œ \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,ystart,xwidth,ywidth,windowname(string terminated by 0) Out w\_handle,ap\_id,screenxmax,screenymax (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 (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) 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 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 Dspmod.S DSP MOD replay routine written by bITmASTER of BSW. Additional code by Dusan. \file Goraud.S Fast Gouraud shading polygon routines, July 1993 by Griff. \file Cache.S Cache equates by Griff. \file Fade.S Fadeit - true colour versh, coded by of Network Trash. \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}