home *** CD-ROM | disk | FTP | other *** search
/ Esprit de Apple Corps / EDAC-2.iso / Graphics / Apps / Programs / SuperMagic / SM.Doc < prev    next >
Encoding:
Text File  |  1991-08-22  |  12.4 KB  |  633 lines
  1. << Super Magic 320 >> version 2.3B          pre-released documentation
  2.  
  3. By: Lim Thye Chean
  4.  
  5.  
  6.  
  7. 1. Introduction
  8.  
  9. Super Magic 320 is a set of assembly routines for designing demo or arcade
  10. games for the Apple IIGS personal computer. It is intended to be used by novice
  11. or average assembly programmers.
  12.  
  13. With Super Magic 320, anybody with a little assembly knowledge can easily
  14. write a GS program that is fast and beautiful.
  15.  
  16. Super Magic 320 is written in ORCA/M, and thus ORCA/M is required. APW users
  17. can also use the routines with some modifications.
  18.  
  19.  
  20.  
  21. 2. Using Super Magic 320
  22.  
  23. In your program, includes the following statements:
  24.  
  25.  
  26.          mcopy SM.Macros                - Macros file
  27.          copy  SM.Header                - Super Magic 320 header file
  28.  
  29.  
  30. in the beginning and:
  31.  
  32.  
  33.          copy  SM.Lib                   - Super Magic 320 library
  34.  
  35.  
  36. at the end.
  37.  
  38. You can now use all the Super Magic 320 library. For each or the routines that
  39. require Super Magic 320, include the statement:
  40.  
  41.  
  42.          using SM.Data
  43.  
  44.  
  45. at the beginning of the routines.
  46.  
  47. IN your program, start up Super Magic in the initializing codes of your
  48. program, and shut down Super Magic, switch to text mode in your ending
  49. routines. Refer to the routines below for instruction.
  50.  
  51. After assembling, you will have to change the filetype of your EXE file to a
  52. S16 file. If you fail to do this, the program will crashed. To change a program
  53. from EXE to S16 file, type
  54.  
  55.  
  56.          Filetype {your program name} S16
  57.  
  58.  
  59.  
  60. 3. Calling Super Magic 320 routines
  61.  
  62. All parameter in Super Magic 320, except for address, is done by variable
  63. passing. The address parameter is passed through stacks.
  64.  
  65. No variables, except for the one used by Super Magic 320 (Temp1 .. Temp9),
  66. will be destroyed after the routine is called. The content of X and Y registers
  67. will be preserved, while the accumulator's value is gone.
  68.  
  69. For example, calling a Erase Shape (ErsShp) routine required the following
  70. parameters:
  71.  
  72.  
  73.          address of background, X, Y, Length, Height
  74.  
  75.  
  76. So this is how you called it:
  77.  
  78.  
  79.          ph2   #BackAddr                - Push 16 bit background address
  80.  
  81.          lda   #100                     - Variable passing
  82.          sta   X
  83.          lda   #150
  84.          sta   Y
  85.          lda   #20
  86.          sta   Length
  87.          lda   #10
  88.          sta   Height
  89.  
  90.          jsr   ErsShp
  91.  
  92.  
  93. That's it. Definitely, if the Erase Shape routine needs to be called second
  94. time, while Length and Height remains unchanged, your codes can be:
  95.  
  96.  
  97.          ph2   #NewBackAddr
  98.  
  99.          lda   #50                      - Length and Height need not be
  100.          sta   X                          redefined, since the routine does
  101.          lda   #60                        not destroyed the variable's content
  102.          sta   Y
  103.  
  104.          jsr   ErsShp
  105.  
  106.  
  107.  
  108. 4. Predefined names and constants
  109.  
  110. The predifined variable names are all declared in the file SM.Header. Names
  111. like X, Y, Length, Height, etc are declared and should not be used by your
  112. programs.
  113.  
  114. Some constants have been defined for user convenience. For example, colour
  115. names like Yellow, Red can be used instead of the RGB values.
  116.  
  117.  
  118.  
  119. 5. Colours
  120.  
  121. There are 3 types of colour parameter used for different purposes:
  122.  
  123.  
  124. Normal Colour
  125. -------------
  126.  
  127. When the standard 320 mode palette is used, user can used names like Red,
  128. Green, Blue etc to represent the colour. For example:
  129.  
  130.  
  131.          lda   #Red
  132.          sta   Colour
  133.  
  134.  
  135. is correct. If non-standard palette is used, user will need to use $0000,
  136. $1111, $2222, etc to represent colour 0, 1, etc in the palette. For example:
  137.  
  138.  
  139.          lda   #$5555                   - Colour 5 in the palette
  140.          sta   Colour
  141.  
  142.  
  143. Gradient Colour
  144. ---------------
  145.  
  146. When Gradient Fill Palette routine is used, user can use names like GRed,
  147. GGreen, GBlue to represent the gradient colour to be filled. For example:
  148.  
  149.  
  150.          lda   #GRed
  151.          sta   GColour
  152.  
  153.  
  154. RGB Colour
  155. ----------
  156.  
  157. When colour is added to the palette, user needs to specify the RGB components
  158. of the colour. It is a 12-bit value, 4 bits for each component. Users can
  159. either use names like RRed, RGreen, RBlue to represents the RGB values, or
  160. a 12-bit value. Thus:
  161.  
  162.  
  163.          lda   #RWhite
  164.          sta   RGB
  165.  
  166.  
  167. and:
  168.  
  169.  
  170.          lda   #$FFF                    - R(ed): $F, G(reen): $F, B(lue): $F
  171.          sta   RGB
  172.  
  173.  
  174. means the same thing.
  175.  
  176.  
  177.  
  178. 6. Animation technique
  179.  
  180. If you want to do animation using Super Magic 320, you must first know a little
  181. about Super Hires. Since you are familiar with assembly, I presumed you have
  182. that knowledge.
  183.  
  184. To reduce flickers, all draw and erase actions are not done on the Super Hires
  185. screen, which resides in bank $E1/2000. Instead, you draw and erase on the
  186. shadow bank $01/2000 and copy the image to $E1/2000.
  187.  
  188. Therefore, this is what you should do:
  189.  
  190.          1.    Switch off shadowing
  191.  
  192.          2.    Draw/Erase the shapes
  193.  
  194.          3.    Switch on shadowing
  195.  
  196.          4.    For every shape drawm or erased, 'display' it on screen
  197.  
  198. Remember, for every shape being drawn or erased, it must be displayed on screen.
  199. The only exception is that, if the shape moves not more than 2 pixels wide,
  200. you can display the drawn shape with surrounding (the surrounding with display
  201. the portion that should be erased), instead of two display operations, thus
  202. speed up the animation.
  203.  
  204. Study the demo source code that came with the Super Magic 320 for example.
  205. Currently only dots and shapes can be animated. Lines are not supported.
  206.  
  207. Masking and background saving are supported in animation.
  208.  
  209. Mask is exactly the same as the shape except it is inverse of white shape, 
  210. apply the mask on the background will allow the background to be visible
  211. through the 'holes' of the shapes.
  212.  
  213. Background must be at least the same size as the shape. The background behind
  214. the shape will be saved, and redrawn when the shape is erased.
  215.  
  216.  
  217.  
  218. 7. Routines
  219.  
  220. Some routines have some restrictions for faster drawing. Error checking is not
  221. done to increase speed. All variables and X, Y registers are preserved after
  222. routines are called.
  223.  
  224. At the beginning of your program, start up Super Magic 320 (and initializes
  225. 320 mode Super Hires, etc) by calling the Startup routine. Shut down Super
  226. Magic 320 by calling ShutDown before quiting your application.
  227.  
  228. Taks note of the restrictions place on some routines. The restrictions are
  229. there to speed up the drawing, or to avoid some errors. Please be careful.
  230.  
  231.  
  232. *
  233. * Startup
  234. *
  235.  
  236.          Name: Startup
  237.  
  238.          * Note: call this routine at the beginning.
  239.  
  240.  
  241. *
  242. * Shut down tools
  243. *
  244.  
  245.          Name: ShutDown
  246.  
  247.          * Note: call this routine at the end.
  248.  
  249.  
  250. *
  251. * Text display
  252. *
  253.  
  254.          Name: Text
  255.  
  256.          * Note: call this routine at the end.
  257.  
  258.  
  259. *
  260. * Switch on shadowing
  261. *
  262.  
  263.          Name: ShadowOn
  264.  
  265.  
  266. *
  267. * Switch off shadowing
  268. *
  269.  
  270.          Name: ShadowOff
  271.  
  272.  
  273. *
  274. * Set standard colours in all palettes
  275. *
  276.  
  277.          Name: SetSClr
  278.  
  279.  
  280. *
  281. * Set all SCB to palette 0
  282. *
  283.  
  284.          Name: SetSCB0
  285.  
  286.  
  287. *
  288. * Set SCB to palette n
  289. *
  290.  
  291.          Name: SetSCB
  292.  
  293.          Input Y      : location of SCB
  294.                Palette: palette number
  295.  
  296.  
  297. *
  298. * Plot pixel
  299. *
  300.  
  301.          Name: Plot
  302.  
  303.          Input X, Y  : location of the pixel
  304.                Colour: colour of the pixel
  305.  
  306.  
  307. *
  308. * Erase pixel (to colour 0)
  309. *
  310.  
  311.          Name: Erase
  312.  
  313.          Input X, Y: location of the pixel
  314.  
  315.  
  316. *
  317. * Fast erase (background destroyed)
  318. *
  319.  
  320.          Name: Erase2
  321.  
  322.          Input X, Y: location of the pixel
  323.  
  324.  
  325. *
  326. * Display pixel
  327. *
  328.  
  329.          Name: Display
  330.  
  331.          Input X, Y: location of the pixel
  332.  
  333.  
  334. *
  335. * Horizontal line
  336. *
  337.  
  338.          Name: HorLine
  339.  
  340.          Input X1, X2, Y: start and end position of the line
  341.                Colour   : colour of the line
  342.  
  343.          * Note: X1 <= X2, X1 must be even, X2 must be odd.
  344.  
  345.  
  346. *
  347. * Vertical line
  348. *
  349.  
  350.          Name: VerLine
  351.  
  352.          Input X, Y1, Y2: start and end position of the line
  353.                Colour   : colour of the line
  354.  
  355.          * Note: Y1 <= Y2
  356.  
  357.  
  358. *
  359. * Plot shape
  360. *
  361.  
  362.          Name: PlotShp
  363.  
  364.          Input 16-bit stack: address of shape
  365.                16-bit stack: address of mask
  366.                16-bit stack: address of background
  367.                X, Y        : upper left corner of shape
  368.                Length      : length of shape
  369.                Height      : height of shape
  370.  
  371.          * Note: The length of the shape should be multiple of four, and the
  372.                  X value should be even.
  373.  
  374.  
  375. *
  376. * Fast plot shape (background not saved)
  377. *
  378.  
  379.          Name: PlotShp2
  380.  
  381.          Input 16-bit stack: address of shape
  382.                16-bit stack: address of mask
  383.                X, Y        : upper left corner of shape
  384.                Length      : length of shape
  385.                Height      : height of shape
  386.  
  387.          * Note: The length of the shape should be multiple of four, and the
  388.                  X value should be even.
  389.  
  390.  
  391. *
  392. * Erase shape
  393. *
  394.  
  395.          Name: ErsShp
  396.  
  397.          Input 16-bit stack: address of background
  398.                X, Y        : upper left corner of background
  399.                Length      : length of background
  400.                Height      : height of background
  401.  
  402.          * Note: The length of the background should be multiple of four, and
  403.                  the X value should be even.
  404.  
  405.  
  406. *
  407. * Fast erase shape (background destroyed)
  408. *
  409.  
  410.          Name: ErsShp2
  411.  
  412.          X, Y  : upper left corner of background
  413.          Length: length of background
  414.          Height: height of background
  415.  
  416.          * Note: The length of the background should be multiple of four, and
  417.                  the X value should be even.
  418.  
  419.  
  420. *
  421. * Display shape
  422. *
  423.  
  424.          Name: DsplShp
  425.  
  426.          Input X, Y  : upper left corner of shape
  427.                Length: length of shape
  428.                Height: height of shape
  429.  
  430.          * Note: The length of the shape should be multiple of four, and the
  431.                  X value should be even.
  432.  
  433.  
  434. *
  435. * Display shape with surrounding
  436. *
  437.  
  438.          Name: DsplShp2
  439.  
  440.          Input X, Y  : upper left corner of shape
  441.                Length: length of shape
  442.                Height: height of shape
  443.  
  444.          * Note: The length of the shape should be multiple of four, and the
  445.                  X value should be even.
  446.  
  447.  
  448. *
  449. * Cycle the palette to left (colour 1 to 15)
  450. *
  451.  
  452.          Name: CycLeft
  453.  
  454.          Input Palette: palette number
  455.  
  456.  
  457. *
  458. * Cycle the palette colour to the right
  459. *
  460.  
  461.          Name: CycRight
  462.  
  463.          Input Palette: palette number
  464.  
  465.  
  466. *
  467. * Partial colour cycle to the left
  468. *
  469.  
  470.          Name: PCycLeft
  471.  
  472.          Input Palette: palette number
  473.                ClrNum1: first colour in the colour range
  474.                ClrNum2: last colour in the colour range
  475.  
  476.          * Note: ClrNum1 < ClrNum2
  477.  
  478.  
  479. *
  480. * Partial colour cycle to the right
  481. *
  482.  
  483.          Name: PCycRight
  484.  
  485.          Input Palette: palette number
  486.                ClrNum1: first colour in the colour range
  487.                ClrNum2: last colour in the colour range
  488.  
  489.          * Note: ClrNum1 < ClrNum2
  490.  
  491.  
  492. *
  493. * Gradient fill palette (colour 1 to 15)
  494. *
  495.  
  496.          Name: GrdFill
  497.  
  498.          Input Palette: palette number to be gradient filled
  499.                GColour: gradient colour
  500.  
  501.  
  502. *
  503. * Set Colour
  504. *
  505.  
  506.          Name: SetClr
  507.  
  508.          Input Palette: palette number
  509.                ClrNum : colour number to be set
  510.                RGB    : RGB component of colour to be set
  511.  
  512.  
  513. *
  514. * Print message
  515. *
  516.  
  517.          Name: Print
  518.  
  519.          Input 16-bit stack: address of the message
  520.                X           : start column (0..78)
  521.                Y           : line (0..199)
  522.                Colour      : colour of the message
  523.  
  524.  
  525. *
  526. * Print message (background destroyed)
  527. *
  528.  
  529.          Name: Print2
  530.  
  531.          Input 16-bit stack: address of the message
  532.                X           : start column (0..78)
  533.                Y           : line (0..199)
  534.                Colour      : colour of the message
  535.  
  536.  
  537. *
  538. * Start music tool
  539. *
  540.  
  541.          Name: StartMsT
  542.  
  543.  
  544. *
  545. * Load one song
  546. *
  547.  
  548.          Name: LoadSong
  549.  
  550.          Input 32-bit stack: address of song
  551.  
  552.  
  553. *
  554. * Play song
  555. *
  556.  
  557.          Name: PlaySong
  558.  
  559.          Input Loop: play the song continuously
  560.  
  561.  
  562. *
  563. * Stop song
  564. *
  565.  
  566.          Name: StopSong
  567.  
  568.  
  569. *
  570. * Shut down tool
  571. *
  572.  
  573.          Name: ShutDMsT
  574.  
  575.  
  576. *
  577. * Clear screen
  578. *
  579.  
  580.          Name: ClrScrn
  581.  
  582.          Input Colour: colour of the screen
  583.  
  584.  
  585. *
  586. * Clear area
  587. *
  588.  
  589.          Name: ClrArea
  590.  
  591.          Input Y1, Y2: start and end Y position of the area
  592.                Colour: colour of the area
  593.  
  594.          * Note: Y1 <= Y2
  595.  
  596.  
  597. *
  598. * Get key
  599. *
  600.  
  601.          Name: GetKey
  602.  
  603.  
  604. *
  605. * Mouse routine (not working)
  606. *
  607.  
  608.          Name: GetMouse
  609.  
  610.          Output MouseX  : (-64 to 63)
  611.                 MouseY  : (-64 to 63)
  612.                 MouseBtn: 0 (up) or 1 (down)
  613.  
  614.  
  615. *
  616. * Delay
  617. *
  618.  
  619.          Name: Delay
  620.  
  621.          Input Time: delay time (0..$FFFF)
  622.  
  623.  
  624. *
  625. * Random number generator
  626. *
  627.  
  628.          Name: Random
  629.  
  630.          Output RndFlag: 0 or 1
  631.  
  632.          * Note:  Do not modify RndFlag.
  633.