home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / utilities / scrsavers / hangfire / Docs / Writing < prev   
Encoding:
Text File  |  1991-12-09  |  4.8 KB  |  140 lines
  1. How to write Hang Fire © modules.
  2.  
  3. Its actually very easy; easy enough in fact to be able to work out what
  4. to do from simply looking at the existing modules.
  5.  
  6. The two main things to note are the layout of the program and the calls
  7. and variables you can use from the main program.
  8.  
  9. If we look at the program we can see the correct way to lay out a
  10. module, but the wrong way to actauuly make it work nicley.
  11.  
  12. REM ><Current$Dir>.Simple
  13. REM
  14. REM Hang Fire Module "Simple" - To show how to write a module
  15.  
  16. DEF FNSimple_Install(ScratchArea)
  17. =0
  18.  
  19. DEF FNSimple_Option(Opt,OptArea)
  20. =0
  21.  
  22. DEF FNSimple_Start
  23. =0
  24.  
  25. DEF FNSimple_Poll
  26. GCOL RND(63)
  27. CIRCLE FILL RND(1280),RND(1024),RND(64)
  28. =0
  29.  
  30. DEF FNSimple_Finish
  31. =0
  32.  
  33. DEF FNSimple_Deinstall
  34. =0
  35.  
  36. To get your code called properly all you have to do is save your module
  37. in the Modules Directory and have the same calls as above but instaed
  38. of prefixing them with 'simple' you prefix them with the same name as
  39. you module (useing the same case.)
  40.  
  41. The Install code gets called when your module gets loaded--this is if
  42. it was the saved module option when Hang Fire startsup, or when someone
  43. changes to it by clicking on its name in the scoller window in the
  44. options window.
  45. The parameter that gets passed to you is ScratchArea. Now there is
  46. no way you can DIM memory or arrays at the moment since they do
  47. not get deleted when you code is deinstalled. This means if you
  48. did, memory would soon fill up and the programwould fall over.
  49. My solution (and one that may change in the future although
  50. in such a way as to not affect the modules already written) is
  51. to give the module a chunk of memory that it can use for anything
  52. it likes. This can be Machine code, Lookup tables, Sprites,
  53. Data or whatever.
  54. The only constrint you have is that it is only 32K long (which
  55. has been plenty big enough for all the code so far.)
  56.  
  57. The Option code get called when a user chooses a option specific for
  58. your module (which is never at the moment--see the ThingsToDo file)
  59.  
  60. The Start code gets called whenever a screen save starts and your the
  61. current save module. Usually you clear the screen to black and init
  62. any varibles you need in this code.
  63.  
  64. The Poll code gets called every update of the screen save (ie this
  65. is the code that gets repeatedly called for each 'frame' of the
  66. save.) This is where you put all your main graphics code.
  67.  
  68. The Finish code gets called when a screen save finishes, ie when
  69. someone moves the mouse or presses a key. You donthave to do anything
  70. to restore the screen in this, Hang Fire does all that for you.
  71.  
  72. The Deinstall code gets called when your module is deinstalled (simple
  73. really...)
  74.  
  75.  
  76. Now Hang Fire has a few built-in 'commands' and variables.
  77. These are to help you write modules, and to help them work in
  78. all screen modes (which is very important.)
  79.  
  80. The 'command' are basic procedures to make writing modules simpler
  81. (andsmalle, since you dont have to include the same code in all
  82. your modules.)
  83.  
  84. There are tow commands for clearing the screen to black (something
  85. that is common to many modules.)
  86.  
  87. PROCClearScreen
  88.  
  89. This simply clears the screen to black (ala CLS or CLG.) Use this
  90. instead of your own code as it will clear the screento black in any
  91. mode.
  92.  
  93. The other one is
  94.  
  95. PROCFadeScreen(<var>)
  96.  
  97. This also clears the screen to black but uses a number of random
  98. effects (or 'fades or 'wipes') to do so. You should use this
  99. if you just want the screen black and it dosn't have to do it
  100. immediatly (it can take several seconds.)
  101.  
  102. You should pass it one of two variables:
  103.  RandomFade
  104. or
  105.  FadeSequential
  106.  
  107. The first chooses a random fade and the second goes through all the
  108. fades one by one.
  109.  
  110.  
  111. Many modules will want to use colour in their effects, but the
  112. code has to work in all screen modes so you have to use
  113. ColourTrans calls to do stuff. Now I have put in a procedure
  114. that simplifies this. Just call
  115.  
  116. PROCSetColour(r,g,b)
  117.  
  118. where the r g & b are values for the amount of red green and blue
  119. (from 0 - 255 : 0 being off and 255 being full on)
  120.  
  121.  
  122. There are also variables you can use (but not change.)
  123.  
  124. HF_ScreenMaxX : The maximum X size of the screen in OS units
  125. HF_ScreenMaxY : The maximum Y size of the screen in OS units
  126. HF_ScreenMinX : The minimum X            ''                  (usually 0)
  127. HF_ScreenMinY : The    ''   Y            ''                      ''
  128. HF_XEigFactor : The X Eig factor of the screen (its easier to use HF_XSize)
  129. HF_YEigFactor : The Y          ''                      ''         HF_YSize)
  130. HF_XSize      : The size of a pixel in the X direction in OS units
  131. HF_YSize      : The          ''            Y          ''
  132. HF_Wait       : Whether you shouldhavewaits in your code or not.
  133.         Many screen effects are a bit smoother when you call
  134.         WAIT but they may go a lot faster if you do not. The
  135.         decision should be up to the user. You should put
  136.         IF HF_Wait THEN WAIT
  137.         in your code atany place you might want to call WAIT
  138.         normally.
  139.  
  140.