home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / utility / 541 / digistuf / digivec / digivec.doc < prev    next >
Encoding:
Text File  |  1991-08-15  |  6.9 KB  |  187 lines
  1.          
  2.          
  3.                  Digivec
  4.       
  5.                Copyright (C) 1991
  6.                 By David Baggett
  7.  
  8.  
  9. --------------------------------------------------------------------------------
  10.                   User Contract
  11.  
  12. This program is FREE.  You may distribute it at will, provided you
  13.     
  14.     1) do not charge any money for it,
  15.     2) distribute it WITH the documentation, and
  16.     3) do not change the program or documentation in ANY WAY.
  17.  
  18. --------------------------------------------------------------------------------
  19.  
  20.  
  21. Introduction  
  22. ------------
  23.  
  24.       "My ST was so boring before I got Digivec!"
  25.  
  26.       "Programming just isn't the same without it."
  27.  
  28.       "I just wouldn't know what to do if someone took away my Digivec!"
  29.  
  30.  
  31.    You'll agree with these happy customers once you too try the exciting new
  32. shareware utility that's taking the ST world by storm!  It's Digivec, and
  33. once you install it on your system, you won't know how you ever lived
  34. without it.
  35.  
  36.    Got your attention?  Good.  Okay, listen up.  Digivec lets you install
  37. digitized sounds to be played when various system events occur.  Like
  38. bus errors.  Illegal instruction traps.  Or line A calls.  Even...
  39. GEM critical errors (gasp!).
  40.  
  41.  
  42. General Usage
  43. -------------
  44.  
  45.    Put digivec.prg in your AUTO folder.  Then create a file called 
  46. digivec.inf with a standard ASCII text editor and put it in the root 
  47. directory of your boot partition (e.g., if your AUTO folder is C:\AUTO\, 
  48. put digivec.inf in C:\).
  49.  
  50.    In digivec.inf you specify which sounds will be installed, and what events
  51. will trigger them.  Each entry starts with a sample file name, enclosed
  52. in square brackets, followed by the sample playback speed, in Hertz, 
  53. followed by a list of system vectors which will trigger the sound.  Here's 
  54. an example digivec.inf file:
  55.  
  56. [d:\usr\sounds\buserror.snd]    11000    $8 $C
  57.  
  58. This file tells Digivec to load the sample named d:\usr\sounds\buserror.snd
  59. and to play it at 11000 Hz whenever vectors 8 (hex) and C (hex) are jumped 
  60. through (in this case, any time either a bus error or address error occur).
  61.  
  62.    Increasing the number 11000 will make the sound play faster; decreasing
  63. it will make the sound play slower.
  64.  
  65.    The digivec.inf file can contain as many of these entries as you want;
  66. the only limitation is that all the samples have to fit in memory at once.
  67.  
  68.    Note that file names MUST be enclosed in square brackets.
  69.  
  70.  
  71. Specifying an Alternate D/A Device
  72. ----------------------------------
  73.  
  74.    Digivec can be configured to play its samples through other D/A devices.  
  75. Currently, the Hippo/Navarone and ST Replay digitizers are supported.  Other 
  76. digitizers will be supported if people send me info on them.
  77.  
  78.    To use an alternate D/A device, put one of the following keywords 
  79. in curly brackets at the beginning or end of your digivec.inf file:
  80.  
  81.         hippo    replay
  82.  
  83. For example, a digivec.inf containing
  84.  
  85. {hippo}
  86. [d:\usr\sounds\buserror.snd]    11000    $8 $C
  87.  
  88. will cause Digivec to play the "buserror" sound through the Hippo/Navarone 
  89. digitizer attached to your ST's cartidge port.
  90.  
  91.  
  92. The Vectors
  93. -----------
  94.  
  95.    You can specify the system vectors either in hexadecimal (with leading $)
  96. or decimal (no leading $).  Interesting vectors for triggering sounds
  97. include (but are not limited to):
  98.  
  99.     Hex    Decimal        Description
  100.     ---    -------        -----------
  101.     $8     8        Bus Error
  102.     $C     12        Address Error
  103.     $10     16        Illegal Instruction
  104.     $14     20        Division by Zero
  105.     $20     32        Privilege Violation
  106.     $28     40        Line A Emulator
  107.     $2C     44        Line F Emulator
  108.  
  109.     $404     1028        Critical Error 
  110.     $408     1032        Process Termination
  111.     $476     1142        Drive read/write
  112.  
  113.    The first 5 vectors deal with failures caused (typically) by software
  114. bugs.  These are the things that cause the ST to put bombs on the 
  115. screen.  But it's so much more fun to have the ST say "Just what do
  116. you think you're doing, Dave?" when a bus error occurs.  (Especially
  117. if your name is Dave and you crash the machine a lot...)
  118.  
  119.    The Line A and Line F emulators are typically used to call system 
  120. functions. (Line A is used for drawing functions; Line F is used in a very 
  121. few programs for pulling off bizarre hacks and/or for floating point).  
  122. Triggering sounds with these is not terribly useful unless you're a 
  123. programmer-type and want to see just what a given application is up to.  
  124. (It's also neat to install a sound at Line A and then run NEOchrome.)
  125.  
  126.    GEM uses the critcal error vector when various things confuse it.  The 
  127. most common of these is trying to read or write with no disk in the drive.
  128.  
  129.    The process termination vector will trigger a sound whenever any program
  130. exits.  This can get extremely annoying after a while.  Trust me.  It's
  131. really fun to install this one on a machine when the owner isn't looking.
  132.  
  133.    If you miss your Atari 800, with it's "boop boop boop" disk access,
  134. you can trigger a sound with the disk read/write vector.  Another good
  135. one to surprise your friends with.
  136.  
  137.  
  138. Command Line Usage
  139. ------------------
  140.  
  141.    In previous versions of Digivec, invoking the program from the 
  142. desktop or command line was tricky.  Those problems have been fixed.
  143. To call Digivec from the desktop, rename it digivec.ttp and double
  144. click on it.  To run it from a command shell, type
  145.  
  146.     digivec
  147.    
  148. and press return.
  149.    
  150.    Note that when you run Digivec from the desktop or a command shell,
  151. it looks for digivec.inf in the current working directory.
  152.  
  153.  
  154. Technical Information
  155. ---------------------
  156.  
  157.    Digivec works by installing a new exception handler for each vector
  158. specified in digivec.inf.  Each new handler just plays the appropriate
  159. sound then jumps through the old vector.  This should not adversely affect 
  160. the system in any way, except in cases where timing is critical.  (So 
  161. don't trigger sounds with the horizontal blank interrupt!)
  162.  
  163.    Minor problems are caused by the fact that when GEM loads (after AUTO
  164. folder programs are finished), it obliterates the critical error vector and 
  165. the process termination vector and installs its own.  To get around this,
  166. Digivec waits for GEM to finish loading before it actually installs any 
  167. vectors.  The method Digivec uses to see if GEM has finished loading
  168. is a bit, ah, undocumented (I think), so I'd be interested to know if
  169. it doesn't work on certain versions of TOS.  (How's that for confidence?)
  170.  
  171.  
  172. Caveats
  173. -------
  174.  
  175.    Digivec will replace any vector in the system.  It does not check to make 
  176. sure the vectors you specify are reasonable.  This means that you could 
  177. theoretically replace some vector in the system that no one else has thought 
  178. of replacing, with nifty results.  It also means you could make your ST crash 
  179. in all kinds of hideous ways.
  180.  
  181.    The upshot is this:  Don't put digivec.prg in your AUTO folder until you're
  182. sure you know how to boot your system without Digivec getting run.  If you're
  183. a hard drive user, be sure you know how to bypass the hard drive, so that if
  184. your digivec.inf is not kosher you'll still be able to use your machine.
  185.  
  186.  
  187.