home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / MM1 / GRAPHICS / kwsaver.lzh / kwsaver.programmers.notes < prev    next >
Text File  |  1994-05-05  |  4KB  |  86 lines
  1.                           KWSaver Programmers' Notes
  2.                           ==========================
  3.  
  4.     This file contains information on writing your own screen-savers for use 
  5. with KWSaver.  No information contained in this file is guaranteed for future 
  6. versions (although it probably will still be valid).  The version used when 
  7. writing this file was Version 1.0.  As always, use this program (and all 
  8. related files) at your own risk.
  9.  
  10.     Also, it is assumed you have read the "Technical Notes" section in the 
  11. kwsaver.readme file, which contains some important information not mentioned 
  12. here.
  13.  
  14.  
  15. Two Types of Screen-Savers:
  16. ===========================
  17.  
  18.     There are two types (ways of writing) screen-savers for KWSaver.  Type 1 
  19. screen-savers are the simplest.  What makes the type 1?  The fact that they 
  20. require no signal handler function.  I.E. they die when a signal (any signal) 
  21. is sent to them.  So, type 2 screen-savers obviously require a signal 
  22. handler to prevent their death at the hands of a signal.
  23.  
  24.     When is a signal sent to a screen-saver?  When KWSaver wants the 
  25. screen-saver to go away due to the user returning to his mouse/keyboard.  
  26. KWSaver will send the signal 4444 (decimal) when this occurs.  For Type 1 
  27. savers, this means instant death.  But why would Type 2 savers want to prevent 
  28. this death anyway?
  29.  
  30.     Type 2 savers "stare death in the eye" because they need to do some 
  31. cleanup processing before dying (exiting).  Usually, this cleanup work is 
  32. killing some K-Windows graphics buffers the saver used for animation while it 
  33. was running.  If there was no signal handler, the saver would die instantly, 
  34. but any K-Windows buffers it may have used would remain, needlessly hogging up 
  35. memory.  So, when the saver receives a signal, it should deallocate (kill) any 
  36. K-Windows buffers it has been using, and then exit.
  37.  
  38.  
  39. RULES FOR WRITING SCREEN-SAVERS THAT WORK:
  40. ==========================================
  41.  
  42. 1) Thou shalt use the current screen, and none other.  Do not allocate any 
  43. other screen, and do not attempt to Select() another screen.
  44.  
  45. 2) Thou shalt NOT deallocate (DWEnd) the current screen.  (KWSaver will take 
  46. care of this for you upon exit.)
  47.  
  48. 3) Thou shalt NOT change palettes.  (Actually, you can if you want, but since 
  49. savers do not run on the currently selected screen, the palette changes will 
  50. have absolutely no visual effect.)
  51.  
  52. 4) Thou shalt die when a signal is sent.  (Specifically for Type 2 savers... 
  53. Be sure to make your saver responsive enough to a received signal.  When the 
  54. user comes back, s/he does not want to wait a half-hour for the screen-saver 
  55. to die because the programmer wanted to list the credits, company logo, etc.)
  56.  
  57. 5) Thou shalt NOT require any command-line arguments... since there's no 
  58. command-line!
  59.  
  60.  
  61. Included Sample Files:
  62. ======================
  63.  
  64.     Well, that's pretty much all the information you really need to get 
  65. started.  If you follow the rules, things should work out pretty nicely.  
  66. There are a few sample files with source code included in this archive to help 
  67. you out.  'kwsaver_lines.c' is a simple Type 1 saver.  If you are a novice 
  68. OS-9 C programmer, you may want to check this out.  If you are familiar with 
  69. signal handlers, and feel you're ready to tackle Type 2, check out 
  70. 'kwsaver_mm1s.c' to see how a graphical logo is moved around the screen.  
  71. (The last program also requires a header file, 'kwsaver_mm1s.h' to compile.)
  72.  
  73.     Anyone who develops a screen-saver, please send me a copy.  I'd love to 
  74. see it!
  75.  
  76.     Finally, this program has taken up a decent amount of time to write 
  77. (mainly trying to find ways to side-step K-Windows bugs).  No, I'm not asking 
  78. for any money; rather I'm stating that I'm not receiving money for this 
  79. program.  Therefore, I hearby decree, no one may sell (for profit, excluding 
  80. minimal copying, shipping, and media charges) screen-savers where the intended 
  81. audience is KWSaver users.  Nor can KWSaver be sold.  In other words, no one 
  82. may take the work I've done for free and use it to profit themselves or 
  83. others.  You may upload your screen-savers whereever you like for others to 
  84. enjoy -- that is strongly encouraged.
  85.  
  86.