home *** CD-ROM | disk | FTP | other *** search
/ Global Amiga Experience / globalamigaexperience.iso / compressed / development / blitz2demod.lha / BBDemo / BlitzBlank / Programmers.doc < prev    next >
Text File  |  1993-10-07  |  8KB  |  292 lines
  1. Programming modules for BlitzBlank
  2. ==================================
  3.  
  4. General rules:
  5. --------------
  6.  
  7. - modules can be written in any language (examples are in BlitzBasic 2).
  8. - don`t turn the multitasking off!!
  9. - don`t use too much CPU-time, if possible.
  10. - you must be AGA/OS 3.0 compatible, test it on AGA-machines.
  11. - if you want to be compatible to graphic-cards, then use OS-graphic-
  12.   routines (in BlitzBasic also: WLine etc...).
  13. - use the given task-priority (set with SetTaskPriority()).
  14. - be screenmode- and depth-flexible.
  15. - use the screenmode/depth provided from BlitzBlank if possible.
  16. - assume that you are running under OS 2.04 or higher.
  17. - take advantage of AGA or OS 3.0 if present (AGA-colors,
  18.   InterLeaved-BitMaps for faster blitting, etc.).
  19. - save your modules` prefs in BlitzBlank`s general configfile.
  20. - if you`ve written a module, please don`t release it on your own.
  21.   Send it to me. I will then bundle it with the next BlitzBlank
  22.   release.
  23. - please allow me to make minimal changes in your code if this would
  24.   be necessary.
  25.  
  26.  
  27. The name of your module:
  28. ------------------------
  29.  
  30. The name MUST begin with "BB.", so that BlitzBlank can find it.
  31.  
  32.  
  33. How your module is called from BlitzBlank:
  34. ------------------------------------------
  35.  
  36. Your module must incorporate these three functions:
  37.  
  38.         - Blank
  39.         - Config
  40.         - Info
  41.  
  42. Your module is called from the CLI with the following parameters:
  43.  
  44. Command Width Height Mode Monitor Depth Reserved Pri Path [Path Path Path...]
  45.  
  46.  
  47. Command: The actual function your module has to execute.
  48.          Three commands are used right now:
  49.  
  50.         - BLANK :  Do your action (blanktime has come)
  51.         - CONFIG:  Display your config-window (user clicked on Config)
  52.         - INFO  :  Display a window with your name, copyright and
  53.                    miscellaneous information (user clicked on Info)
  54.  
  55.          Check this argument first to see what your module has to do.
  56.  
  57. Width: The user-choosen width of the display
  58.  
  59. Height: The user-choosen height of the display
  60.  
  61. Mode: The user-choosen lower 16 bits of the screenmodeID.
  62.  
  63. Monitor: The user-choosen higher 16 bits of the screenmodeID.
  64.  
  65. Note 1: You get the modeID by calculating: mode+$10000*monitor
  66. Note 2: Mode and monitor are NOT the correct values of the screenmode and
  67.         monitor, they just represent the modeID! Always use the
  68.         complete modeID to open a screen.
  69.  
  70. Depth: The user-choosen depth of the screen.
  71.  
  72. Note: Width, height, mode, monitor and depth are only interesting for
  73.       you, if you don`t clone the actual frontscreen.
  74.       Tiles is an example for the case of cloning, Lines for the case
  75.       of opening a desired screen.
  76.  
  77. Reserved: This is reserved for future use and contains "x" right now.
  78.  
  79. Pri: The task-priority for your module.
  80.  
  81. Path: This is the path where the BlitzBlank-config-file can be found.
  82.       Be careful: The path can have spaces so get all following arguments
  83.       to get the full path
  84.  
  85.  
  86. Example 1:
  87. ~~~~~~~~~~
  88. BlitzBlank starts your module with the following parameters:
  89.  
  90. Modulename BLANK 676 476 36868 9 4 x -2 sys:wbstartup/
  91.  
  92. That means:
  93. You should do your blankaction on a screen with a resolution of 676x476
  94. and 16 colors on a screen with the modeID $99004 (36868=$9004).
  95. Your task-priority must be set to -2.
  96. The configfile can be found in "sys:wbstartup/"
  97.  
  98. Example 2:
  99. ~~~~~~~~~~
  100. BlitzBlank starts your module with the following parameters:
  101.  
  102. Modulename CONFIG 676 476 36868 9 4 x -2 sys:wbstartup/
  103.  
  104. That means:
  105. You should open your config-window and get/save your config-data
  106. from the config-file in "sys:wbstartup/".
  107.  
  108. Example 3:
  109. ~~~~~~~~~~
  110. BlitzBlank starts your module with the following parameters:
  111.  
  112. Modulename INFO
  113.  
  114. That means:
  115. You should display a window with your name and copyright.
  116. (This can be easily done with EasyRequestArgs())
  117.  
  118.  
  119. Blanking:
  120. ---------
  121.  
  122. If BlitzBlank starts your module asking it to blank, you should do the
  123. following:
  124.  
  125. - Create a messageport with CreateMsgPort() by the name of
  126.   "BB.BlankModule".
  127. - Add this port to the public list with AddPort().
  128. - Set your taskpriority with SetTaskPri(FindTask(0),Pri) to `Pri`.
  129. - Evaluate the other arguments.
  130. - Read your config-data (if you have some).
  131.   See the section Configuring.
  132. - Open your screen using OpenScreenTagList().
  133. - Blank the mouse if you wish.
  134.   See the section Methods of mouseblanking.
  135. - Do your screen-action.
  136. - While doing your blanking, check your port frequently if there
  137.   is a message with GetMsg(Port).
  138. - If there was a message, stop all action and close your screen.
  139. - Free spritedata, if you have blanked the mouse.
  140. - Remove port from the public list with RemPort().
  141. - Delete your messageport with DeleteMsgPort().
  142.  
  143.  
  144. Configuring:
  145. ------------
  146.  
  147. If you have config-data (like the number of objects etc), you must save
  148. this data in BlitzBlank`s configfile "BB.Modules.config".
  149. It can be found in the path that BlitzBlank tells you as last parameter.
  150. This configfile is shared by BlitzBlank and all modules.
  151. In the examples above the configfile would have been
  152. "sys:wbstartup/BB.Modules.config".
  153.  
  154. Example how the configfile could look:
  155. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  156. *** Fade ***
  157. 10
  158. *** Tiles ***
  159. 2
  160. 3
  161. *** Spot ***
  162. 3
  163. *** Lines ***
  164. 200
  165. *** Stars ***
  166. 50
  167. 1
  168. 1
  169. 0
  170. *** BlitzBlank ***
  171. 676
  172. 467
  173. 36868
  174. 9
  175. 3
  176. *** Pyro ***
  177. 50
  178. 0
  179.  
  180. There must always be a header "*** Modulename ***" followed by the
  181. module`s data.
  182.  
  183. If you want to read your module`s data then browse through the configfile
  184. until you reach your header and then read your data.
  185.  
  186. If you want to write your data, then use the following procedure:
  187.  
  188. - Open a temporary file (eg. "BB.Modules.temp").
  189. - Write all data from the other modules in this file.
  190. - Then you delete the original config-file, rename the temp-file to
  191.   "BB.Modules.config" and append your own modules' config data.
  192.  
  193. Assuming that your module was the "Lines"-module from the example above,
  194. the new config-file should look like this after a change:
  195.  
  196. *** Fade ***
  197. 10
  198. *** Tiles ***
  199. 2
  200. 3
  201. *** Spot ***
  202. 3
  203. *** Stars ***
  204. 50
  205. 1
  206. 1
  207. 0
  208. *** BlitzBlank ***
  209. 676
  210. 467
  211. 36868
  212. 9
  213. 3
  214. *** Pyro ***
  215. 50
  216. 0
  217. *** Lines ***
  218. 150
  219.  
  220. Doing it this way, you can make sure that your data in the config-file
  221. is 100% accurate after writing to it.
  222. Keep in mind that the user may accidentally delete the config-file keep
  223. default-values of all data or change it illegally himself.
  224.  
  225. New modules may use the "readconfig" and "writeconfig" subroutines
  226. of my supplied modules, if you are programming in BlitzBasic 2.
  227.  
  228. If you have nothing to configure, then please inform the user about this
  229. with an EasyRequest if your module is started with "CONFIG".
  230.  
  231.  
  232. Methods of mouseblanking:
  233. -------------------------
  234.  
  235. I currently use 2 methods of mouseblanking in my modules. I hope, they are
  236. both legal.
  237. I DO NOT turn sprite-DMA off, because of the side effects that can happen
  238. (can be read in the RKMs). Both methods use a structure "spritedata" of 6
  239. words which MUST be in CHIP-RAM (allocate with AllocMem()).
  240.  
  241. If you use one screen:
  242. ~~~~~~~~~~~~~~~~~~~~~~
  243. Open your screen, bring it to front, then do:
  244.  
  245. WaitTOF() (or VWait for Blitz-users)
  246. ChangeSprite (0,spr,*sprdata)
  247.  
  248. spr = empty SimpleSprite-structure
  249. *sprdata = Pointer to the spritedata in CHIP-RAM
  250.  
  251. Using this method, the mouse is automatically unblanked if it is moved, or
  252. if another screen is brought to front.
  253.  
  254. If you use more than one screen (doublebuffering for example):
  255. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  256. Open a small 1x1 window on the WB, which is automatically activated
  257. (WFLG_ACTIVATE). Then do:
  258.  
  259. WaitTOF() (or VWait for Blitz-users)
  260. SetPointer(*mywindow,*sprdata,0,0,0,0)
  261.  
  262. *mywindow = Pointer to the mini-window
  263. *sprdata = Pointer to the spritedata in CHIP-RAM
  264.  
  265. Using this method, the mouse is blanked until the mini-window is
  266. deactivated.
  267. Don`t forget to do this before leaving your module:
  268.  
  269. ClearPointer( *mywindow)
  270. CloseWindow( *mywindow)
  271.  
  272. For both methods:
  273. ~~~~~~~~~~~~~~~~~
  274. Don`t forget to free the memory of the spritedata.
  275.  
  276.  
  277. Testing:
  278. --------
  279.  
  280. While testing your module, you can use the provided "Signal"-program to
  281. tell your module to halt, when you have started your module via the CLI and
  282. not via BlitzBlank.
  283.  
  284.  
  285. Problems:
  286. ---------
  287.  
  288. Feel free to look at the source of the included modules.
  289.  
  290. If you have problems writing a module, feel free to contact me and I`ll
  291. give you all the help I can.
  292.