home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / screen / m / vdusaver1 / SaverDoc next >
Encoding:
Text File  |  1992-01-13  |  19.4 KB  |  449 lines
  1.                   Documentation for VDU Saver Module V2.04
  2.                   ----------------------------------------
  3.  
  4. ********************** Incredibly boring Copyright Notice *********************
  5. *                                                                             *
  6. *       All program code is the exclusive copyright of Richard K. Lloyd.      *
  7. *     The program (source and binary) and documentation for VDU Saver are     *
  8. *                           freely distributable                              *
  9. *                                                                             *
  10. *******************************************************************************
  11.  
  12.                             Version V2.02 onwards
  13.                             ---------------------
  14. Due to the sterling work of people like Philip Colmer of Acorn, I have decided
  15. to make the source code of the VDU Saver publicly available. It's not a
  16. fantastic example of ARM code programming by any means, but it provides some
  17. useful tips (such as how to call lots of OS routines from inside interrupts
  18. with the minimum of fuss). Please, please, please report any bugs or improve-
  19. ments to the address at the bottom of this document - I will *not* support
  20. 'hacked' versions that I don't know about.
  21.  
  22. Installing VDU Saver (Now requires RISC OS)
  23. -------------------------------------------
  24.  
  25. Because VDU Saver is a relocatable module, you can install it by typing
  26. *VDUSaver, assuming that you have sufficient RMA available and the filetype
  27. is set to Module. To activate it once it is installed, type *VDUSaver [params].
  28. This * command is explained in greater detail later in this document.
  29.  
  30. So what does VDU Saver do ?
  31. ---------------------------
  32.  
  33. Acorn standard 14" monitors have a tendency to 'snap' occasionally (actually,
  34. the blame lies with Philips, but that's another story). Why this happens is
  35. beyond my limited electronic know-how (I'm of the 'bash-it-and-see' school of
  36. thinking), but I personally blame bright colours on the screen for prolonged
  37. periods of time (not a game, honest !).
  38.  
  39. This is where VDU Saver comes in. It is a relocatable module that sits in
  40. the background waiting for a specified period of non-activity. When this
  41. occurs, the current palette is saved and all logical colours in the current
  42. MODE are set to black, the mouse pointer is saved and the border is set to
  43. black.
  44.  
  45. A 'Smiley' face bounces around the screen to indicate that the screen has been
  46. blacked. This looks more impressive in the 320*256 MODEs (e.g. MODE 1) because
  47. the face appears circular rather than elliptical !
  48.  
  49. Instead of a 'Smiley' face, the current time in 24-hour clock format can be
  50. displayed instead. See the *Configure SaverType command and the Technical
  51. Details section.
  52.  
  53. VDU Saver now works in all screen MODEs including the 256-colour and teletext
  54. MODEs. In 256-colour MODEs, the border colour will 'throb' in varying
  55. intensities of the RGB colour specified when the *VDUSaver command was issued.
  56.  
  57. You can, if you wish, control the speed of the Smiley face or time, its colour
  58. and whether or not the screen is restored on VDU output.
  59.  
  60. The palette, border and mouse pointer are all restored on any key event (yes,
  61. that includes SHIFT, Alt etc...), mouse movement, mouse button press or
  62. (optionally) VDU output.
  63.  
  64. *Help VDUSaver will give you plenty of on-line help - in fact all of the
  65. following command descriptions are available via *Help.
  66.  
  67. The *VDUSaver command
  68. ---------------------
  69.  
  70. Syntax: *VDUSaver [<Minutes>] [<Speed>] [<Type>] [<VDUTrap>]
  71.                   [<Red>] [<Green>] [<Blue>]
  72.  
  73. The (optional) parameters have the following meaning:
  74.  
  75. <Minutes>   Minutes (1-63) of inactivity before activation.
  76.             A value of 0 will completely disable VDUSaver.
  77.             If omitted, then the *Configure SaverDelay value is used.
  78.  
  79. <Speed>     Speed of Smiley face (1 = slowest, 3 = fastest).
  80.             A value of 0 will plot the Smiley face randomly.
  81.             If omitted, then the *Configure SaverSpeed value is used.
  82.  
  83. <Type>      What type of mouse shape will be plotted.
  84.             0 will always plot the (now infamous) Smiley face.
  85.             1 will plot the current time in 24-hour format.
  86.             If omitted, then the *Configure SaverType value is used.
  87.  
  88. <VDUTrap>   Signifies if VDU output will restore the screen.
  89.             0 will ignore VDU output, 1 will restore the screen on VDU output.
  90.             If omitted, then the *Configure SaverTrap value is used.
  91.             V1.03 onwards now recognises MODE changes as a screen restoration
  92.             by the OS, even when VDUTrap = 0.
  93.  
  94. <R> <G> <B> Quantities of RGB in the Smiley face.
  95.             0 0 0 gives black (invisible) and 3 3 3 gives white.
  96.             If any omitted, then the *Configure SaverRGB values are used.
  97.  
  98. The *VDUStatus Command      *NEW TO V2.03*
  99. ----------------------
  100.  
  101. Syntax: *VDUStatus
  102.  
  103. Because *Status only reveals the VDU Saver CMOS RAM (i.e. permanent) settings,
  104. I decided to supplement this with a command that shows BOTH the currently
  105. active settings supplied with *VDUSaver and the *Configure ones. The current
  106. settings obviously cannot be shown until an activating *VDUSaver command is
  107. issued, so "Inactive" is displayed in the Current column until such a command
  108. occurs.
  109.  
  110. The *Configure SaverDelay Command
  111. ---------------------------------
  112.  
  113. Syntax: *Configure SaverDelay <Minutes>
  114.  
  115. This command alters the permanent SaverDelay value (saved to CMOS RAM byte 35).
  116. <Minutes> should be an integer value between 1 and 63. A value of 0 is NOT
  117. permitted and if your CMOS RAM is set to that value, VDUSaver will force it
  118. to a more sensible value of 15 (minutes).
  119.  
  120. The *Configure SaverSpeed Command
  121. ---------------------------------
  122.  
  123. Syntax: *Configure SaverSpeed <Speed>
  124.  
  125. This command alters the permanent SaverSpeed value (saved to CMOS RAM byte 36).
  126. <Speed> should be an integer value between 0 and 3.
  127.  
  128. The *Configure SaverType Command
  129. --------------------------------
  130.  
  131. Syntax: *Configure SaverType <Type>
  132.  
  133. This command alters the permanent SaverType value (saved to CMOS RAM byte 35).
  134. <Type> should be either 0 or 1.
  135.  
  136. The *Configure SaverTrap Command
  137. --------------------------------
  138.  
  139. Syntax: *Configure SaverTrap <VDUTrap>
  140.  
  141. This command alters the permanent SaverTrap value (saved to CMOS RAM byte 35).
  142. <VDUTrap> should be either 0 or 1.
  143.  
  144. The *Configure SaverRGB Command
  145. -------------------------------
  146.  
  147. Syntax: *Configure SaverRGB <Red> <Green> <Blue>
  148.  
  149. This command alters the permanent SaverRGB values (saved to CMOS RAM byte 36).
  150. <Red>, <Green>, <Blue> should be integer values between 0 and 3.
  151.  
  152. Some Tips whilst using VDU Saver
  153. --------------------------------
  154.  
  155. 1. I've just noticed that moving the pointer over various areas of the icon bar
  156.    causes the VDU Saver to stop working. Further investigation has shown that
  157.    that VDU output occurs ! Hence, people may prefer to set VDUTrap to 0 if
  158.    they spend most of their time in the Desktop.
  159.  
  160. 2. When SaverType is 1, the mouse shape is defined once a minute when the
  161.    screen is blanked - this causes a 'glitch' if SaverSpeed is non-zero due to
  162.    the lengthy time OS_Word 21 (param 0) takes to execute. Hence, I recommend
  163.    a setting of SaverSpeed 0 (randomly plot) when SaverType is set to 1.
  164.  
  165. 3. For those of you who have dead batteries or faulty clocks (mine falls into
  166.    the latter), DON'T PANIC ! The program has been written so that it only
  167.    reads the current time ONCE each time the screen is blanked. Minute updates
  168.    are achieved by using an internal counter - this may eventually lead to
  169.    slight inaccuracies over a long period of time.
  170.  
  171. Technical Details of VDU Saver
  172. ------------------------------
  173.  
  174. Initially, I tried to use OS_CallAfter and OS_RemoveTickerEvent, but these
  175. seemed to carry on regardless (maybe they don't work in SVC Mode 3 ?). I
  176. ended up using a simple decrementing counter inside a Vsync event routine.
  177.  
  178. I now blank the screen in two possible ways, depending on the MODE :
  179.  
  180. 1. Non-Teletext/256-colour MODEs
  181.    -----------------------------
  182.  
  183.    The number of logical colours is found using the NColour (3) value supplied
  184.    to OS_ReadVduVariables. It is assumed that it will be a maximum of 15 in
  185.    this case. The palette is read and stored in a (logical colours+2)*4-byte
  186.    area. The extra 8 bytes are for the border colour and mouse logical colour
  187.    1 in case you're wondering. In the same loop, each colour is set to black
  188.    after its original colour is safely stored. I now use OS_RemoveCursors and
  189.    OS_RestoreCursors to make sure the cursor doesn't remain.
  190.  
  191. 2. Teletext (currently only MODE 7) and 256-colour MODEs
  192.    -----------------------------------------------------
  193.  
  194.    This is the case when bit 1 of ModeFlags (0) is set to indicate teletext or
  195.    when NColour (3) is set to 63. Less work has to be done here, because the
  196.    ONLY KNOWN WAY to blank/restore the screen in these MODEs is to use the
  197.    following bit of code (of course, I do the ARM equivalent...) :
  198.    
  199.    SYS "OS_UpdateMEMC",&300,&700 TO oldval          : blanks the screen
  200.    SYS "OS_UpdateMEMC",oldval,&700                  : restores it.
  201.    Thanks to Tolli's Blanker (available on SID) for this information.
  202.  
  203.    Annoyingly, the mouse also gets blanked - hence there is no 'Smiley' face
  204.    or time in these MODEs. The only palette saves/restores that still have to
  205.    be done are the border colour and the background colour (0), the latter of
  206.    which I forgot to do in V1.03 ! For V2.01 onwards, I've added a 'throbbing'
  207.    border colour to at least indicate that something is going on. This cycles
  208.    up and down the palette according to the SaverRGB values specified.
  209.  
  210. The 'Smiley' face is simply mouse pointer shape 2 (the system usually uses
  211. shape 1) re-programmed and using colour 1 set to the SaverRGB values * &50.
  212.  
  213. The following vectors are trapped to avoid mouse shape change during blanking:
  214. * OS_Byte vector to check for *FX 106,<value>.
  215.   The value is stored (but NOT executed to prevent shape change) and then used,
  216.   when the screen is restored, to restore the new pointer shape number.
  217. * OS_Word vector to check for OS_Word 12 (write palette) for physical colour
  218.   25 (mouse). Again, this is saved and restored later on.
  219.  
  220. Oh, by the way, there's no call to read the current mouse shape (its pixel
  221. pattern in other words), so shape 2 is overwritten I'm afraid.
  222.  
  223. *NEW TO V2.03*
  224. Also missing is a call to find the current mouse rectangle bounds, so I have to
  225. set them to ( 0 , 0 ) - ( X , Y ) where:
  226. X = ( XWindLimit << XEigFactor ) and         } As read by
  227. Y = ( ( YWindLimit - 12 ) << YEigFactor )    } OS_ReadVduVariables
  228.  
  229. When the screen is blanked, the WrchV (restore screen on any VDU output) and
  230. EventV (restore on Event 10 - Mouse Button pressed - or 11 - Key pressed)
  231. vectors reactivate the screen. OS_Mouse is also checked to see if the mouse
  232. position has changed. If it has, the screen is restored.
  233.  
  234. The Service Call &46 (Mode Change) is now recognised so as to permit a MODE
  235. change to be a valid screen restoration (by the OS rather than VDU Saver).
  236. This is independent of the VDUTrap setting or screen MODE.
  237.  
  238. The new 24-hour clock feature isn't as easy as it sounds because I've specially
  239. defined the digits 0 to 9 and the string "TIME" as mouse shape data. I call
  240. OS_Word 14 (param 1) to get the current time in BCD. I do some shifting and
  241. use the value of the digits to get the offset into the data, which is poked
  242. into the mouse shape definition.
  243.  
  244. V2.00 onwards now uses CMOS RAM in the following way:
  245.  
  246. +---------+-------+-------+-------+-------+-------+-------+-------+-------+
  247. | Bits:   |   7   |   6   |   5   |   4   |   3   |   2   |   1   |   0   |
  248. +---------+-------+-------+-------+-------+-------+-------+-------+-------+
  249. | Byte 35 |<Trap->|<Type->|<---------------  SaverDelay  ---------------->|
  250. +---------+-------+-------+-------+-------+-------+-------+-------+-------+
  251. | Byte 36 |<--- Blue ---->|<--- Green --->|<---- Red ---->|<-SaverSpeed-->|
  252. +---------+-------+-------+-------+-------+-------+-------+-------+-------+
  253.  
  254. CPU utilisation    *UPDATED FOR RISC OS*
  255. ---------------
  256.  
  257. Someone enquired about the amount of CPU time used when the VDU Saver was
  258. active. Here's some (crude, but effective) benchmarks done on my A310 running
  259. BASIC 1.04 and RISC OS 2.00 :
  260.  
  261.                                       VDUTrap?  Inactive Active  Diff    Slower
  262. 10 MODE 0:TIME=0
  263. 20 FOR A%=1 TO 4000000:NEXT          Irrelevant  58.99s  59.06s  00.07s  00.12%
  264. 30 PRINT TIME/100
  265.  
  266. 10 MODE 0:TIME=0                        Yes      51.32s  61.40s  10.08s  19.64%
  267. 20 FOR A%=1 TO 300000:PRINT"*";:NEXT    No       51.32s  51.38s  00.06s  00.12%
  268. 30 PRINT TIME/100
  269.  
  270. As you can see, there is a hefty CPU grab (nearly one-fifth) if continuous
  271. VDU output occurs when the VDU Saver is active and the VDUTrap is switched on.
  272. This would seem to indicate that claiming WriteCV (but not doing much) appears
  273. to be a no-no if you want fast VDU output - blame Acorn, not me !
  274.  
  275. In normal situations, however, the CPU grab will be well under 1%, so there is
  276. no need to panic at the alarming 19.64% figure (yes, I was shocked at this
  277. too)...
  278.  
  279. The code in V2.00 onwards has been extensively re-organised to use the minimum
  280. amount of CPU time when the module is loaded and either active or inactive.
  281. Previous versions would actually use up CPU time as soon as the module was
  282. loaded ! In particular, V2.00 onwards does not claim any vectors or enable
  283. events until a *VDUSaver command is issued.
  284.  
  285. Revision History of VDU Saver
  286. -----------------------------
  287.  
  288. Version 2.04
  289. ------------
  290.  
  291. * Y-coord fix to bug introduced in 2.03.
  292.  
  293. * Changed key scanning code to use Event 2.
  294.  
  295. Version 2.03
  296. ------------
  297.  
  298. * A new *VDUStatus command has been added so that users can check what values
  299.   they've just supplied to the latest *VDUSaver command.
  300.  
  301. * To tie in with the new command, a soft reset now performs the equivalent
  302.   of a *VDUSaver 0 command so that *VDUStatus will report the correct status
  303.   (Inactive) rather than the last active values.
  304.  
  305. * Used OS_ReadVduVariables to find the MODE-independent mouse rectangle, so
  306.   those people with hi-res B&W monitors should (hopefully...anyone care to
  307.   test this ?) have a proper rectangle.
  308.  
  309. * Due to above change, support for Arthur 1.20 has now been dropped. RISC OS
  310.   has been generally available for more than 6 months now, so there's no
  311.   excuse (and you can now readily order the new PRM's too - I've got mine).
  312.  
  313. Version 2.02
  314. ------------
  315.  
  316. * Prevented the mouse shape number (2) used by VDU Saver from changing during
  317.   screen blanking (but still changes to requested shape number on screen
  318.   restoration). Ditto for mouse colour 1 (for OS_Word 12 calls only).
  319.   
  320. * The check for 0 delay value in CMOS RAM was not working correctly. Although
  321.   the value of 15 (minutes) would be used (and shown in *Status), a faulty
  322.   MOVEQS instruction meant that the actual CMOS RAM would not be forced to the
  323.   value of 15. This has been fixed.
  324.  
  325. * Slightly changed the random number seeding routine.
  326.  
  327. Version 2.01
  328. ------------
  329.  
  330. * Philip Colmer (of Acorn no less) spotted a bug:
  331.   V2.00 would incorrectly restore the palette in 256-colour MODEs. In fact,
  332.   everything started turning green (mouldy old programming perhaps ?)...
  333.   Investigation revealed that I'd moved two statements further down in the
  334.   code, but the first of them, MOV R2,#0, should have remained where it was.
  335.   *BUG FIXED WITH VAPONA FLY SPRAY*
  336.  
  337. * Philip also put forward the suggestion that the user should see something
  338.   happening in the 256-colour MODEs e.g. the border colour should change.
  339.   I implemented his suggestion - I hope nobody objects too much. He also
  340.   hinted at the possibility of VDU Saver appearing on SID...fingers crossed.
  341.   *VERSION 2.01 IS NOW AVAILABLE ON SID*
  342.  
  343. Version 2.00
  344. ------------
  345.  
  346. * Due to the extra mouse pointer definitions, V2.00 is now 7K long. Some
  347.   people may consider this big for a screen saver, but think of that pretty
  348.   time plotted on the screen and you might forgive me...
  349.  
  350. * Re-organised the code to use less CPU time generally, especially when
  351.   the module has been loaded but not activated.
  352.  
  353. * Fixed the bug whereby colour 0 (background) wasn't restored properly in
  354.   256-colour MODEs.
  355.  
  356. * Fully (ho hum - I lied here) tested and working in RISC OS (yes, I now have
  357.   it !).
  358.  
  359. * Modified the MEMC poke to make it 'safer'.
  360.  
  361. * Now allow either the current time or the Smiley face to be plotted...
  362.   you have a choice at last !
  363.  
  364. * Added *Configure SaverType to go with the new mouse shape choice.
  365.  
  366. * Reduced the maximum SaverDelay to 63 minutes because Bit 6 of Byte 35 is
  367.   now used for the SaverType. Also made doubly sure that the version I
  368.   release specifies the delay in minutes (rather than seconds, which I use
  369.   for test purposes and accidentally forgot to change to minutes in V1.03 !).
  370.  
  371. Version 1.03
  372. ------------
  373.  
  374. * Make a special check for Teletext MODEs, so that the screen saving is
  375.   performed in the same way as 256-colour MODEs.
  376.  
  377. * 256-colour MODEs now toggle the Video/Cursor DMA Enable flag in MEMC's
  378.   control register to blank the screen. In plain English, VDU Saver now
  379.   works in 256-colour MODEs but without the dubious benefit of a Smiley
  380.   face (because the mouse is unfortunately blanked in these MODEs as well).
  381.  
  382. * MODE changes are now recognised as a screen restoration without the
  383.   intervention of VDU Saver. This takes care of the case when VDUTrap = 0
  384.   and the MODE is changed in a program whilst the screen is blanked. Earlier
  385.   versions would have, after the appropriate delay, restored the OLD palette
  386.   (prior to the MODE change) to the NEW MODE.
  387.  
  388. * OK, a little bugette here folks. A friend ran VDU Saver on RISC OS and
  389.   claimed erratic behaviour with the screen restoring at random intervals..!?!
  390.   Due to laziness on my part, I had assumed that all events are disabled
  391.   unless enabled by user programs (it's the case in Arthur 1.20). My theory is
  392.   that RISC OS (probably the Desktop) enables events which Arthur 1.20 didn't
  393.   use to. To remedy this problem, I've specifically checked for events 4,10
  394.   and 11 in my event routine, so this behaviour should have been eliminated
  395.   *CONFIRMED - OK IN RISC OS*.
  396.  
  397. Version 1.02
  398. ------------
  399.  
  400. * A soft reset no longer causes the *VDUSaver command to fail to activate.
  401.  
  402. * Uses 2 bytes of CMOS RAM (35 and 36) to permanently store VDUSaver settings.
  403.  
  404. * Allows finer control over the Smiley face in terms of colour, speed and
  405.   plotting method.
  406.  
  407. * The text cursor is now switched off and restored correctly during blanking.
  408.  
  409. * Screen restoration on VDU output is now optional, because some users may have
  410.   a clock running that uses the VDU drivers (especially Twin and graphicky
  411.   Desktop clocks).
  412.  
  413. Version 1.01
  414. ------------
  415.  
  416. * Shows a bouncing 'Smiley' face when the screen is blacked.
  417.  
  418. * Restores the screen on mouse movement as well as mouse button presses.
  419.  
  420. Version 1.00
  421. ------------
  422.  
  423. * Written as a relocatable module that traps vectors.
  424.  
  425. * Properly switches off and restores the mouse pointer and border colour.
  426.  
  427. Future Improvements to VDU Saver V2.04
  428. --------------------------------------
  429.  
  430. * Although OS_Word 12 is trapped to check for mouse colour 1 being changed,
  431.   I later discovered that the *Pointer 1 command actually bypasses this call
  432.   (it uses VDU 19 instead) when changing the mouse colour ! I guess I'll have
  433.   to add yet more code to cope with this...
  434.  
  435. * At some point, I might make it install itself on the icon bar and act proper
  436.   like wot all programs should do. There again, I might not...nope, I haven't
  437.   bothered yet.
  438.  
  439. Where to find me to report bugs or improvements to the VDU Saver
  440. ----------------------------------------------------------------
  441.  
  442. Snail Mail           JANET e-mail
  443. ----------           ------------
  444. Richard K. Lloyd,    rkl@uk.ac.liv.cs.and
  445. 1, Banks Road,
  446. Lower Heswall,
  447. Wirral,
  448. Merseyside. 
  449.