home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / MM1 / GRAPHICS / kwsaver20.lzh / programmer.lzh / kwsaver.programmers.notes < prev   
Text File  |  1994-06-21  |  7KB  |  149 lines
  1.                           KWSaver Programmers' Notes
  2.                           ==========================
  3.  
  4. UPDATED FOR VERSION 2.0 (06/21/94)
  5.  
  6.     This file contains information on writing your own screen-savers for use 
  7. with KWSaver.  No information contained in this file is guaranteed for future 
  8. versions (although it probably will still be valid).  The version used when 
  9. writing this file was Version 2.0.  As always, use this program (and all 
  10. related files) at your own risk.
  11.  
  12.     Also, it is assumed you have read the "Technical Notes" section in the 
  13. kwsaver.readme file, which contains some important information not mentioned 
  14. here.
  15.  
  16.  
  17. Three Types of Screen-Savers:
  18. =============================
  19.  
  20.     There are three types (ways of writing) screen-savers for KWSaver.  Type 1 
  21. screen-savers are the simplest.  What makes them Type 1?  The fact that they 
  22. require no signal handler function.  I.E. they die when a signal (any signal) 
  23. is sent to them.  So, Type 2 screen-savers obviously require a signal handler 
  24. to prevent their death at the hands of a signal.  Type 3 screen-savers also 
  25. require a signal handler, and also rely on the memory data module named 
  26. "kwsaver_data" (Version 2.0).  Type 3 screen-savers need code to link-to, and 
  27. unlink-from the module.
  28.  
  29.     When is a signal sent to a screen-saver?  When KWSaver wants the 
  30. screen-saver to go away due to the user returning to his mouse/keyboard.  
  31. KWSaver will send the signal 4444 (decimal) when this occurs.  For Type 1 
  32. savers, this means instant death.  But why would Type 2 and 3 savers want to 
  33. prevent this death anyway?
  34.  
  35.     Type 2 and 3 savers "stare death in the eye" because they need to do some 
  36. cleanup processing before dying (exiting).  Usually, this cleanup work is 
  37. killing some K-Windows graphics buffers the saver used for animation while it 
  38. was running.  Type 3 savers need to unlink from the memory data module, 
  39. kwsaver_data.  If there was no signal handler, the saver would die instantly, 
  40. but any K-Windows buffers it may have used would remain, needlessly hogging up 
  41. memory.  And for a Type 3 saver, if it dies without unlinking from the 
  42. kwsaver_data module, the module will remain in memory until manually unlinked 
  43. by an unusually perceptive user!  (And the kwsaver_data module is quite a 
  44. memory-hog.)  So, when the saver receives a signal, it should deallocate 
  45. (kill) any K-Windows buffers it has been using, unlink from the kwsaver_data 
  46. module (if it's a Type 3 saver), and then exit.
  47.  
  48.  
  49. RULES FOR WRITING SCREEN-SAVERS THAT WORK:
  50. ==========================================
  51.  
  52. 1) Thou shalt use the current screen, and none other.  Do not allocate any 
  53. other screen, and do not attempt to Select() another screen.
  54.  
  55. 2) Thou shalt NOT deallocate (DWEnd) the current screen.  (KWSaver will take 
  56. care of this for you upon exit.)
  57.  
  58. 3) Thou shalt NOT change palettes.  (Actually, you can if you want, but since 
  59. savers do not run on the currently selected screen, the palette changes will 
  60. have absolutely no visual effect.)
  61.  
  62. 4) Thou shalt die when a signal is sent.  (Specifically for Type 2 and 3 
  63. savers... Be sure to make your saver responsive enough to a received signal.  
  64. When the user comes back, s/he does not want to wait a half-hour for the 
  65. screen-saver to die because the programmer wanted to list the credits, company 
  66. logo, etc.!)
  67.  
  68. 5) Thou shalt NOT require any command-line arguments... since there's no 
  69. command-line!
  70.  
  71. 6) If thy screen-saver is of Type 3, thou shalt unlink from the 
  72. "kwsaver_data" module before exiting.  (Hmmm... I wonder how many times I 
  73. should repeat this to make sure people know it's important!)
  74.  
  75.  
  76. Included Sample Files:
  77. ======================
  78.  
  79.     Well, that's pretty much all the information you really need to get 
  80. started.  If you follow the rules, things should work out pretty nicely.  
  81. There are a few sample files with source code included in this archive to help 
  82. you out.  'kwsaver_lines.c' is a simple Type 1 saver.  If you are a novice 
  83. OS-9 C programmer, you may want to check this out.  If you are familiar with 
  84. signal handlers, and feel you're ready to tackle Type 2, check out 
  85. 'kwsaver_mm1s.c' to see how a graphical logo is moved around the screen.  
  86. (The last program also requires a header file, 'kwsaver_mm1s.h' to compile.)
  87.  
  88.     Type 3 screen-savers add yet another level of complexity, and you really 
  89. do need to know what you're doing before you attempt one of these puppies.  I 
  90. have included the source-code to a sample Type 3 saver program named 
  91. 'kwsaver_rain.c' for those interested.  I would suggest directly copying the 
  92. the module linking/unlinking code directly from that source to any Type 3 
  93. saver you may try to write, since that can be a slightly confusing part of 
  94. writing a Type 3 saver.  Below, please find the file specification of the 
  95. "kwsaver_data" module.
  96.  
  97.     Anyone who develops a screen-saver, please send me a copy.  I'd love to 
  98. see it!
  99.  
  100.     Finally, this program has taken up a decent amount of time to write 
  101. (mainly trying to find ways to side-step K-Windows bugs).  No, I'm not asking 
  102. for any money; rather I'm stating that I'm not receiving money for this 
  103. program.  Therefore, I hearby decree, no one may sell (for profit, excluding 
  104. minimal copying, shipping, and media charges) screen-savers where the intended 
  105. audience is KWSaver users.  Nor can KWSaver be sold.  In other words, no one 
  106. may take the work I've done for free and use it to profit themselves or 
  107. others.  You may upload your screen-savers whereever you like for others to 
  108. enjoy -- that is strongly encouraged!
  109.  
  110.  
  111. - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = -
  112.  
  113.  
  114.          DEFINITION OF THE CONTENTS OF THE "KWSAVER_DATA" DATA MODULE
  115.          ------------------------------------------------------------
  116.  
  117. * 'Offset' is given in BYTES, while 'INT Offset' is given in integers (4-byte 
  118. integers).  The sample source file "kwsaver_rain.c" uses the convenient 'INT 
  119. Offset' notation within its code as an example.
  120.  
  121. Offset  INT Offset  Description
  122. ======  ==========  ==========================================================
  123.    0         0      Version number of KWSaver (in ascii).  The format is VVRR,
  124.                       where VV is version and RR is release.  For example,
  125.                       Version 2.0 of KWSaver would place the string '0200' in
  126.                       the first 4 bytes of the data module.
  127.  
  128.    4         1      Actual size (in bytes) of screen data saved.
  129.  
  130.    8         2      Bytes per scanline.  (Length of each horizontal line.)
  131.  
  132.   12         3      Total scanlines.  (Total Y-pixel coordinates.)
  133.  
  134.   16         4      Maximum X pixel coordinate.
  135.  
  136.   20         5      Bits per pixel.
  137.                       * Note that the number of pixels per byte can be
  138.                         computed from this with the formula:
  139.                         pixels_per_byte = 8/bits_per_pixel;
  140.  
  141.   24         6      Maximum colors available.  (16 for 16-color screen,
  142.                       256 for 256-color screen.)
  143.  
  144.   28         7      This is where the raw screen-data is saved.  The length
  145.                       of this data is given above in "Actual size of screen
  146.                       data saved".  Nothing follows the raw screen-data.
  147.  
  148.  
  149.