home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / falcon / falclib.lzh / DOC / DOC.TXT < prev    next >
Encoding:
Text File  |  1994-08-19  |  10.0 KB  |  433 lines
  1.  
  2.         Devpac Falcon Library
  3.         
  4.             Manual
  5.             
  6.             
  7. Following are short descriptions of all included routines. Most are
  8. subroutines and should be called with 'bsr' or 'jsr' unless the word
  9. macro follows the routine name in which case it is a macro. If a
  10. routine says 'destroys a lot' then you should save all the registers
  11. you are using except a7 which is never ruined. Some routine descriptions
  12. even contains an example, so hopefully there will be no problems
  13. understanding them.
  14.  
  15.  
  16. *
  17. * CACHE.S
  18. *
  19. *    Cache equates. You'll need devpac 3 for this one I think.
  20. *    Here they are:
  21. *
  22. *     ENABLE_CACHE        EQU 1   ; Enable instruction cache
  23. *     FREEZE_CACHE        EQU 2   ; Freeze instruction cache
  24. *     CLEAR_INST_CACHE_ENTRY    EQU 4   ; Clear instruction cache entry
  25. *     CLEAR_INST_CACHE    EQU 8   ; Clear instruction cache
  26. *     INST_BURST_ENABLE    EQU 16  ; Instruction burst enable
  27. *     ENABLE_DATA_CACHE    EQU 256 ; Enable data cache
  28. *     FREEZE_DATA_CACHE    EQU 512 ; Freeze data cache
  29. *     CLEAR_DATA_CACHE_ENTRY    EQU 1024 ; Clear data cache entry
  30. *     CLEAR_DATA_CACHE    EQU 2048 ; Clear data cache
  31. *     DATA_BURST_ENABLE    EQU 4096 ; Instruction burst enable
  32. *     WRITE_ALLOCATE        EQU 8192 ; Write allocate 
  33. *
  34. * ex.    move.l    #ENABLE_CACHE+ENABLE_DATA_CACHE+WRITE_ALLOCATE,d0
  35. *    movec    d0,CACR        ; turns on the caches
  36. *
  37.  
  38. *
  39. * CLS.S
  40. *
  41. *    @cls???
  42. *     clears ??? bytes.
  43. * In     a0.l=start address
  44. *     (destroys a lot)
  45. *
  46. *    ??? supported:    184320 (384*240*16bp)
  47. *            92160  (384*240*8bp)
  48. *            32000  (st modes)
  49. * ex.     bsr @cls92160
  50. *
  51.  
  52. *
  53. * CONVPAL1.S
  54. *
  55. *    @convert_stpal
  56. *
  57. *    Convert an old st colour value to a new falcon one
  58. *
  59. * In    d0.w=old st colour
  60. * Out    d0.l=falcon colour
  61. *    (destroys d1-d3)
  62. *
  63.  
  64. *
  65. * COOKIE.S
  66. *
  67. *    @getcookie
  68. *
  69. *    Finds and returns a Cookie. Supervisor only!
  70. *
  71. * In    d1.l=Cookie name
  72. * Out    d0.l=Cookie value or -1
  73. *    (destroys a0)
  74. *
  75.  
  76. *
  77. * DSPMOD.S
  78. *
  79. *    @dsp_play
  80. *
  81. *    Sets interupts and plays some music. Supervisor only.
  82. *    May return to user mode after the procedure.
  83. *
  84. * In    a0.l=Module adr.
  85. *    (destroys a lot)
  86. *
  87. *    @dsp_stop
  88. *
  89. *    Stops playing the music and resets interupts.
  90. *    Supervisor only.
  91. *    (destroys a lot)
  92. *
  93.  
  94. *
  95. * EXIT.S
  96. *
  97. *    @exitifspace  macro
  98. *     branches to exit if space has been pressed. Supervisor only!
  99. *     (destroys nothing)
  100. *
  101.  
  102. *
  103. * GEM.S
  104. *
  105. *    @gemdos    macro
  106. * In     #functionnbr, #stackcorrection
  107. * ex.     @gemdos 1,2    ;waits for a key
  108. *
  109. *    @xbios    macro
  110. * In     #functionnbr, #stackcorrection
  111. * ex.     @xbios 37,2    ;waits for vsync
  112. *
  113. *    @gem    macro
  114. * In     #functionnbr, #trapnbr, #stackcorrection
  115. * ex.     @gem 1,1,2    ;waits for a key
  116. *
  117.  
  118. *
  119. * GETPAR.S    (include right after releasem.s)
  120. *
  121. *    Gets all parameters sent to the program.
  122. *    Must be directly after releasem.
  123. *
  124. * Out    a0.l=Address where the parameters are kept
  125. *
  126. * ex.    include    releasem.s    release unused memory, this is line nr 1 of the program
  127. *    include    getpar.s    get adr. where the parameters are kept
  128. *    move.l a0,paradr    save the result
  129. *
  130. *    paradr ds.l 1
  131. *
  132.  
  133. *
  134. * GORAUD.S
  135. *
  136. *    @goraud
  137. *
  138. *    Draw a goraud shaded polygon in true colour.
  139. *    There's no clipping so don't draw too large polygons.
  140. *    Call @initgoraud once before using this one!
  141. *
  142. * In    a1.l=screenadr
  143. *    a2.l=adr to colourtable
  144. *    new_crds=following table: [x,y,i]*nbr_of_points
  145. *    d6.w=nbr. of points
  146. *    xres equ horizontal resolution
  147. *    (destroys a lot)
  148. *
  149. *    The colourtable consists of 32 words, each a true colour value.
  150. *     word nr 0 is the darkest and word nr 31 the brightest. This is
  151. *     followed by 16 empty words.
  152. *    Supplied colours: g_lightred, g_green, g_brown, g_white
  153. *    new_crds is a table that consist of a pair of coordinates followed
  154. *     by a brightnes factor. The brightnes factor is a number between 0
  155. *     and #$7fff.
  156. *
  157. * ex.     xres equ 384        overscaned lowres screen
  158. *     bsr @initgoraud    call once only
  159. *
  160. *     move.l scradr,a1    screenaddress
  161. *     move.l #g_red,a2    I want a red poly
  162. *     moveq #4,d6        four points
  163. *     bsr @goraud        draw it
  164. *
  165. *     new_crds dc.w 10,10,0        a dark point
  166. *                dc.w 200,20,$7fff    a bright point
  167. *          dc.w 140,140,$7fff/2
  168. *          dc.w 25,50,$7fff/4
  169. *    
  170. *
  171. *    @initgoraud
  172. *     This subroutine must be called once before using @goraud.
  173. *
  174.  
  175. *
  176. * HLINE1.S
  177. *
  178. *    @drawhline1
  179. *
  180. *    Draws a horizontal line in 8 bitplane mode. Clipping is implemented.
  181. *    This routine only uses the six first bitplanes.
  182. *
  183. * In    a0.l=screenadr d0=xmin d1=xmax
  184. *    d2.l - d4.l =6 bitplanes
  185. *    xres equ  horizontal screen resolution
  186. *    (destroys d0-d7/a0-a1)
  187. *
  188. * ex.     move.l    screen+xres*50,a0    ypos=50
  189. *     move #-34,d0        left xcord
  190. *     move #67,d1        right xcord
  191. *     move.l #$0,d2        don't set bitplane 0 or 1
  192. *     move.l    #$0000ffff,d3    set bitplane 3
  193. *     move.l    #$ffffffff,d4    set bitplane 4 and 5
  194. *     bsr @drawhline1
  195. *
  196.  
  197. *
  198. * ICE.S
  199. *
  200. *    @icedecrunch
  201. *
  202. *    Checks if the data is icepacked and possibly unpacks it.
  203. *
  204. * In    a0.l=Data adr.
  205. *
  206.  
  207. *
  208. * LOADFILE.S
  209. *
  210. *    @loadfile
  211. *
  212. *    Loads a file and possibly unpacks it (ice 2.40).
  213. *
  214. * In    a5.l=adr. to a filename terminated by zero
  215. *    a6.l=dest.
  216. *    d7.l=filelength
  217. *    (destroys a lot)
  218. *    
  219.  
  220. *
  221. * RELEASEM.S
  222. *
  223. *    This routine releases all memory not needed by the program.
  224. *    Include this rout at the top of your program and the memory
  225. *    will be relesed properly.
  226. *
  227. * ex.    include    releasem.s    release unused memory, this is line nr 1 of the program
  228. *
  229.  
  230. *
  231. * SAVEFILE.S
  232. *
  233. *    @savefile
  234. *
  235. *    Saves data as a file.
  236. *
  237. * In    a5.l=adr. till nollavslutat filnamn
  238. *    a6.l=source
  239. *    d7.l=fillängd
  240. *    (destroys a lot)
  241. *
  242.  
  243. *
  244. * SETFV.S
  245. *
  246. *    @setfv
  247. *     Sets the falcon video registers. The data that is
  248. *     written to the video registers must be a .FV (Falcon Video)
  249. *     file. Supervisor only.
  250. * In     a0.l=adr. to Falcon Video data
  251. * Out     d0.l: 0=no error  -1=error, no .FV data
  252. *     (destroys d0-d2/a0-a2)
  253. *
  254. *    @savefv
  255. *     Saves the falcon video registers to memory. Supervisor only.
  256. *     (destroys a0-a1)
  257. *
  258. *    @resorefv
  259. *     Restores the saved falcon video registers. Supervisor only.
  260. *     (destroys d0-d2/a0-a2)
  261. *
  262.  
  263. *
  264. * SETVIDEO.S
  265. *
  266. *    @setvideo
  267. *     Save and set resolution.
  268. * In     d7.w=mode
  269. *  modeequates: vertflag, stmodes, overscan, pal, vga, col80, bps1-16
  270. *     (xbios, destroys d0-d2/a0-a2)
  271. * ex.     move #pal+bps16,d7
  272. *     bsr @setvideo
  273. *
  274. *    @restorevideo
  275. *     Restores the saved resolution.
  276. *     (xbios, destroys d0-d2/a0-a2)
  277. *
  278. *    @setvadr
  279. *     Sets the physical and logical screenadress.
  280. * In     d0.l=screenadr.
  281. *     (xbios, destroys d0-d2/a0-a2)
  282. *
  283. *    @savevadr
  284. *     Saves the current screenadr.
  285. *     (xbios, destroys d0-d2/a0-a2)
  286. *
  287. *    @restorevadr
  288. *     Restores the saved screenadr.
  289. *     (xbios, destroys d0-d2/a0-a2)
  290. *
  291.  
  292. *
  293. * SHRTONES.S
  294. *
  295. *    @super
  296. *     enter supervisor mode  (gemdos($20), destroys d0-d1/a0-a1)
  297. *
  298. *    @user
  299. *     returns to user mode  (gemdos($20), destroys d0-d1/a0-a1)
  300. *
  301. *    @waitvbl
  302. *     waits for a vertical blank  (xbios(#37), destroys d0-d2/a0-a2)
  303. *
  304. *    @waitkey
  305. *     waits for a keypress, no echo  (gemdos(#7), destroys a0)
  306. * Out     d0.b=ascii value
  307. *
  308. *    @exitifkey
  309. *     quits if a key has been pressed
  310. *     (gemdos(#11,#7,#0), destroys a0)
  311. *
  312. *    @quit
  313. *     terminate process  (gemdos(#0))
  314. *
  315.  
  316. *
  317. * TIMER.S
  318. *
  319. *    @colour[#value.l]  macro
  320. *     sets backround colour to value. Supervisor only!
  321. *     (destroys nothing)
  322. *
  323.  
  324. *
  325. * TRIG.S
  326. *
  327. *    All results are taken from a 1440 entries large lookup table.
  328. *
  329. *    @sin
  330. *     Returns the sine of an angle.
  331. * In     d0.w=angle in degrees with six decimal bits (the legal values are 0-$59ff or 0-359.999 degrees)
  332. * Out     d1.w=sin(angle), a word with one sign bit and 15 decimal bits.
  333. *     (destroys d0/a0)
  334. *
  335. *    @cos
  336. *     Returns the cosine of an angle.
  337. * In     d0.w=angle in degrees with six decimal bits (the legal values are 0-$59ff or 0-359.999 degrees)
  338. * Out     d1.w=sin(angle), a word with one sign bit and 15 decimal bits.
  339. *     (destroys d0/a0)
  340. *
  341. * ex.    move #180*64,d0        ; make it 180 degrees
  342. *    bsr @sin        ; d1 will now contain 0
  343. *    move #180*64,d0        ; d0 is destroyed so we had better enter the value again
  344. *    bsr @cos        ; d1 will now contain -1 ($8000)
  345. *
  346.  
  347. *
  348. * WINDOW.S
  349. *  (vdilib.i & aeslib.i must be included at the end of the program)
  350. *
  351. *    @createwindow
  352. *
  353. *    Creates and opens a simple gem window.
  354. *
  355. * In    wtype equ %info move full close name
  356. *    xstart,ystart,xwidth,ywidth,windowname(string terminated by 0)
  357. * Out    w_handle,ap_id
  358. *    (destroys a lot)
  359. *
  360. *    @recalcwindow
  361. *     Recalculates the window size.
  362. *     (destroys a lot)
  363. *
  364. *    @moveit
  365. *     Moves the window. May be called at every vm_moved(=28) event.
  366. * In     a0.l=adr to messagebuffer
  367. *     (destroys a lot)
  368. *
  369. *    @drawrsrc
  370. *     Draws the rsrc.
  371. *     This function doesn't care about clipping, so you should probably not use it.
  372. * In     a0.l=adr to rsrc
  373. *     (destroys a lot)
  374. *
  375. *    @updatersrc
  376. *     Draws the rsrc. Use this when receiving update events(=20).
  377. *     This function takes care of all clipping.
  378. * In     a0.l=adr to rsrc
  379. *     (destroys a lot)
  380. *
  381. *    @topwindow
  382. *     Activates the window. May be called at every vm_topped(=21) event.
  383. * In     a0.l=adr to messagebuffer
  384. *     (destroys a lot)
  385. *
  386. *    @bottomwindow
  387. *     Bottoms the window if it's mine. May be called at every vm_bottomed(=33) event.
  388. * In     a0.l=adr to messagebuffer 
  389. *     (destroys a lot)
  390. *
  391. *    @button
  392. *     Returns the object number that was clicked on. This function may be called
  393. *     at every mousebutton event.
  394. * In     a0.l=adr. to rsrc
  395. *     (It automatically takes the x and y coordinates from int_out)
  396. * Out     d0.w=object that was pressed or -1.
  397. *     (destroys a lot)
  398. *
  399.  
  400. *
  401. * WINEVENT.S
  402. *
  403. *    @dowindowevents
  404. *     For the lazy one. This function waits for events and takes care of
  405. *     everything but the close button or if someone clicked on an object.
  406. *     If one of these events occur the program branches to closeevent
  407. *     or buttonevent. Those subroutines you have to make yourself.
  408. * In     a0.l=adr. to rsrc
  409. *     w_handle, ap_id  (These are created automatically if you use @createwindow)
  410. * Out     buttonevent: d0.w=number of the object pressed
  411. *     closeevent: nothing
  412. *     (destroys a lot)
  413. *
  414. * ex.    ;create a window;
  415. *    lea rsrc,a0
  416. *    bra @dowindowevents    ; it will never return so you may use 'bra' or 'jmp'
  417. *    
  418. * buttonevent        ; d0.w will contain the object that was pressed
  419. *    cmp #1,d0     ; was it my button?
  420. *     beq mybutton    ; yes!
  421. *    rts        ; no!
  422. *
  423. * closeevent
  424. *    bsr @exitwindow    ; close window
  425. *    bra @quit    ; quit
  426. *
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.