home *** CD-ROM | disk | FTP | other *** search
/ Esprit de Apple Corps / EDAC-1.iso / MOD.Utilities / DOCVu / DOCVu.Dox < prev   
Text File  |  1994-06-20  |  15KB  |  357 lines
  1.     _
  2.    / \OCVu
  3.   / ^ \
  4.  / / > >   -The Ensoniq like you've never seen it before-
  5.  \/ / /
  6.    / /
  7.   <_/
  8.  
  9.  
  10. DOCVu v2.0
  11. ==========
  12.  
  13. DOCVu is -FREEWARE- distribute freely, but do not sell...
  14.  
  15.  - CDA based.
  16.  - 32 SHR-based oscilloscopes, 100% configurable layout, selectable scan rate
  17.  - 32 SHR-based volume level sensitive vu-meters
  18.  - Full Ensoniq DOC data, including DOC pause function
  19.  - Ensoniq DOC RAM peeker
  20.  - Instant and Average CPU load
  21.  - Left/Right channel volume output levels
  22.  - Optional digitizing oscilloscope
  23.  - Fully compatible with all GS/OS desktop and shell based programs
  24.  - Runs unsynchronized in real-time, for best results with accelerators
  25.  
  26.  
  27. Installation
  28. ============
  29. DOCVu.CDA:  place into */System/Desk.Accs
  30. DOCVu.Dox:  read, remember, then delete...
  31.  
  32.  
  33. Operation
  34. =========
  35. Initially invoking DOCVu from the CDA menu will cause it to load its
  36. data files from the disk, this is only required once, subsequent calls
  37. to DOCVu will not require disk access.  Should DOCVu have problems loading
  38. or obtaining memory then it will display an error message indicating the
  39. problem, and then exit back to the CDA menu.
  40. If you have problems check the following:
  41.  
  42.     1> DOCVu requires about 95K of memory and will not run if it cannot
  43.         allocate the needed space.
  44.     2> DOCVu is not compatible with ProDOS 8 and will not run under it.
  45.  
  46. As soon as the DOCVu screen comes up, it will put you in "normal mode".  The
  47. following options are available:
  48.  
  49. <All keypresses are case irrelevant...>
  50.  
  51. 'esc' - this key will exit DOCVu and return you to the CDA menu.
  52.  
  53. '/' or '?' - these are a couple of the most important keys, they bring
  54.     up the online help screen.  It pretty much sums up this whole
  55.     doc file, so use it, it's cool :>
  56.  
  57. 'left/right arrow keys' - the oscillators now have selectable scan rates.
  58.     In the top, right corner there will be a sliding indicator which
  59.     will indicate the current scanning rate.  A higher number scan rate
  60.     will increase the scanning period and will give you a larger view
  61.     of the wave, however on the whole the wave will take longer to
  62.     complete and will appear to update more slowly.  The available rates
  63.     are 8, 10, and 16.  Some rates such as 16 will be unsuitable for high
  64.     CPU loads, such as when using a mod player.
  65.  
  66. 'b' - pressing the 'b' key will activate the busy flag suppression.  This
  67.     will insure that the busy flag is clear when DOCVu is active.  The
  68.     method that DOCVu uses to accomplish this task is nothing short of
  69.     illegal, so use it at your own risk...  The top right corner of the
  70.     screen will show the status of this feature.  There are two lights next
  71.     to the word "BSY":  the left one indicates if the busy flag was clear
  72.     on entry into DOCVu <black means it was clear, red means it wasn't>,
  73.     and the right one indicates if the suppression is active.  These
  74.     lights do not toggle, either one or both may be lit.
  75.  
  76. 'c' - pressing the 'c' key will put you into a "configuration mode".  The
  77.     oscillators will black out to reveal the current DOC oscillator
  78.     mapped to that position.  The "red" number will represent the current
  79.     cursor position while the green numbers represent all the other current
  80.     oscillators mapped.  In this mode -ONLY- the following keypresses
  81.     will have any effect:
  82.  
  83.         <esc> - this key will back you out of the configuration mode into
  84.         normal operating mode.
  85.  
  86.         <p> - pause, this acts like the normal pause explained below.
  87.  
  88.     <arrow keys> - use the arrow keys to position the config cursor
  89.         to the appropriate location you wish to re-map.
  90.  
  91.         <number keys 0-9> - typing the number keys will modify the 
  92.         oscillator number currently displayed.
  93.  
  94.     <return> - the return key is used to "lock" in the new oscillator
  95.         to the current map position.  Only valid oscillator
  96.         numbers will be allowed, valid numbers range from 0 to 31.
  97.  
  98.         The procedure for modifying the map is as follows:
  99.  
  100.     1> Use the arrow keys to position the "red" cursor to the location
  101.         you want to modify.
  102.     2> Input the new oscillator number (0-31) by using the number keys.
  103.     3> Press <return> to lock in the new number.  If you do not do this
  104.             the old oscillator number will be returned.
  105.         4> Press <esc> to exit configuration mode, or repeat the above
  106.         procedure.
  107.  
  108.         The CDA will always boot up in its default mode, which displays
  109.     all 32 of the oscs, however once you re-map the oscs, it will
  110.     remain in that configuration until you reboot again.
  111.  
  112. 'd' - pressing the 'd' key will invoke the digitizing oscillator, you will
  113.     see the left-hand 'DE' logo open to reveal a digitizing osc.  This
  114.     oscillator will respond only to sound input into the DOC.  It's
  115.     nothing super-special, but it is a nifty feature to test mic/recorder
  116.     volume input.  Pressing the 'd' key a second time will cover it
  117.     back up.
  118.  
  119. 'i' - pressing the 'i' key will turn on a mode which causes the border to
  120.     change colors when the sound interrupt occurs.  This is useful for
  121.     programmers who need to have the interrupt occur at a specific time
  122.     frame.  It will provide a visual means of determining where the
  123.     interrupt occurs relative to the 60Hz screen refresh.  Pressing 'i'
  124.     a second time will turn it off.
  125.  
  126. 'p' - this key is to pause the DOC <and everything else>, it will work in
  127.     any mode.  When you press this key the computer will come to a
  128.     grinding halt.  This is useful for programmers like myself who
  129.     cannot read the DOC information as quickly as its being updated.
  130.     It allows you to freeze the DOC internals so you can examine them
  131.     more closely. Pressing any key afterwards will continue normal
  132.     operation.
  133.  
  134. 'r' - pressing the 'r' key will activate RAM-VU mode, the RAM-VU screen
  135.     will fade in at the bottom.  You will see four rows of numbers
  136.     divided into two groups.  The four digit numbers to the far left
  137.     are the address in DOC RAM <in hex>, and the 16 two digit numbers
  138.     to its right correspond to the data stored at that address <also
  139.     in hex>.  The current cursor position will be determined by the
  140.     "red" address.  While in RAM-VU mode -ONLY- the following
  141.     keypresses will have any effect:
  142.  
  143.         <esc> - this key will back you out of the RAM-VU mode into
  144.         normal operating mode, the bottom eight oscillators
  145.         will fade back in.
  146.  
  147.         <p> - pause, this acts like the normal pause explained above.
  148.  
  149.     <up/down arrow> - these two arrow keys will move the current
  150.         "red" cursor position between the address locations.
  151.  
  152.     <left/right arrow> - these two arrow keys will decrement or
  153.         increment the current address location.
  154.  
  155.         <number keys 0-9> - these keys are used to enter the new DOC
  156.         <letter keys a-f>   RAM address to be viewed.  The number must
  157.                 be entered in hex format.
  158.  
  159.     <return> - the return key is used to "lock" in the new address
  160.         to the current location.  Any 4 digit hex number will be
  161.         valid.  Numbers greater than $FFF0 will cause RAM-VU to
  162.             wrap around to address $0000 when displaying data.
  163.  
  164.         The procedure for modifying the addresses is as follows:
  165.  
  166.     1> Use the arrow keys to position the "red" cursor to the location
  167.         you want to modify.
  168.     2> Input the new address in hex by using the number and letter keys.
  169.     3> Press <return> to lock in the new address.  If you do not do this
  170.             the old address will be returned.
  171.  
  172.         The CDA will always boot up in its default mode, which sets
  173.     all address locations to $0000, however once you enter new
  174.     addresses it will remain in that configuration until you
  175.     reboot again.
  176.  
  177. 'v' - this key will remove the main 32 oscillator array and replace it with
  178.     32 volume level sensitive vu-meters.  The new vu-meter block will
  179.     have a series of numbers along the top, which will display the
  180.     current DOC oscillator mapped to that vu-meter.  The way in which
  181.     the oscillators are mapped to the vu-meters is in direct correspondance
  182.     with how they are mapped to the oscillators using the configuration
  183.     mode.  The top row of oscs will be mapped to the far left and the
  184.     bottom row to the far right.
  185.  
  186.     Below these numbers are the vu-meters, they will respond to the
  187.     -real- volume output that you hear, which is not to be confused
  188.     with the DOC volume registers.  Directly below the vu-meters
  189.     will be a light, if the light is lit that means the corresponding
  190.     DOC oscillator is currently running.  If it is not lit then the DOC
  191.     oscillator is halted.
  192.  
  193.     Finally, below these lights are another row of numbers.  These numbers
  194.     represent the DOC volume registers.  Within this mode the only
  195.     thing you can do is exit <'esc' key> or pause <'p' key>.
  196.  
  197. 'ctrl-r' - every once in a while, but most likely when debugging new
  198.     programs, DOCVu's screen data can become garbled.  Since DOCVu
  199.     stores its data in a compressed format this can lead to bizzare
  200.     effects such as turning the screen all green-blue or something.
  201.     If this ever happens, then press this key sequence and DOCVu will
  202.     reload all of its data off of the disk again and everything will
  203.     return to normal.
  204.  
  205.  
  206. Display
  207. =======
  208. In the top right of the screen there is a box which looks like this:
  209.  
  210.  Average CPU load..................         ........Busy Flag set on entry
  211.                                   :         :
  212.  Instantaneous CPU load.......    :         :  .....Busy Flag suppression
  213.                              :    :         :  :
  214.                ______________:____:_________:__:____
  215.               |              :_   :_        :  :    |
  216.               |  |\  /      |  | |  |  BSY  [] []   |
  217.               |  | ><-       \/   \/      SCAN      |
  218.               |  |/  \       00% CPU   8 =[]== 16   |
  219.               |______________:_____________:________|
  220.                              :             :
  221.  Average CPU load............:             :................Osc Scan Rate
  222.    (percentage)
  223.  
  224. The left-hand CPU meter indicates the instantaneous load that the sound
  225. interrupt places on the CPU.  The right-hand meter is the avarage CPU load
  226. over a period of 1/3rd of a second.  The % CPU reading is the exact
  227. percentage number associated with the right-hand meter.  The sliding switch
  228. represents the current osc scan rate, and has three settings: 8, 10, and 16.
  229. The two busy flag lights show the status of the busy flag suppression.
  230.  
  231. The top left has a similar box which has the three registers: OSC INT
  232. <oscillator interrupt>, OSC ENABLE <oscillator enable>, and
  233. A/D CONVRT <Analog/Digital Converter>.
  234.  
  235. Below these are two horizontal VU meters which represent the total channel
  236. output volume for the left and right channels.
  237.  
  238. Below that is the array of oscs, the area around each osc looks like this:
  239.  
  240.                    [sample-size] [DOC RAM loc]
  241.                    FREQ            [frequency]
  242. Oscillator............./\  [osc mode]  /\....................Interrupt
  243.   enabled             /__\____________/__\                    enabled
  244.                     _|                    |_
  245.                    |_|                    |_|
  246. Left channel.......|_| ***Oscilloscope*** |_|...............Right channel
  247.    in use          |_|                    |_|                  in use
  248.                      |____________________|
  249.  
  250. Sample Size - will show the size of the sample in DOC memory, valid sizes are
  251.     256 bytes, 512 bytes, 1K, 2K, 4K, 8K, 16K, and 32K.
  252.  
  253. DOC Ram Location - this is a hex number representing the location of the
  254.         sample in DOC Ram.
  255.  
  256. Frequency - this is a hex number representing the speed at which the oscillator
  257.         is reading the wavetable from DOC Ram.
  258.  
  259. Oscillator Mode - this indicates which mode the oscillator is in, the different
  260.     modes are FREE, SHOT, SYNC, and SWAP.
  261.  
  262. Oscillator Enabled - a yellow light will indicate if the oscillator is 
  263.     currently running.
  264.  
  265. Interrupt Enabled - a red light will indicate if the oscillator is interrupt
  266.         enabled.
  267.  
  268. Left/Right channel - green lights will indicate the channel that the oscillator
  269.     is currently sending to.
  270.  
  271. The oscillator display will become brighter as the -real- volume output
  272. by the oscillator increases.  Thus, those oscillators which are not enabled
  273. or are not producing volume will appear black.
  274.  
  275.  
  276. Notes and Author Blurb
  277. ======================
  278. Many thanks to everyone who suggested ideas and continued to show interest
  279. in DOCVu's completion.  Most of the new features were requested, however I
  280. did add in a couple more of my own ideas.  This new version should solve most
  281. of the previous bugs and quirks of DOCVu 1.0.
  282.  
  283. The CPU load meter is probably one of the more practical additions to DOCVu.
  284. Now programmers have the ability to directly judge sequencer performance
  285. while its playing.  One small thing I've noticed is that for most sequencers,
  286. including SoundSmith and the various mod players, the CPU speed of the system
  287. seems to have little effect on performance.  I'm fairly sure this is a
  288. direct result of the I/O bottleneck on the DOC.  Naturally you will probably
  289. see a difference in the screen update speed of DOCVu, however the sound IRQ
  290. load will probably remain relatively unchanged.
  291.  
  292. This version does have some remaining bugs which I know of, but as yet do not
  293. have enough info on to fix.  One of these is the problem with the digitizing
  294. osc not responding to the sound card input.  I know why this happens, however
  295. I am still gathering information on how to fix it.
  296.  
  297. For those of you who are wondering about this busy flag thing, it was put
  298. in to fix one specific problem.  The problem had to do with using Shellplay
  299. inside GNO.  Shellplay checks the busy flag before it loads a new song and
  300. for some mysterious reason <still unknown> whenever you enter the CDA menu
  301. from GNO the busy flag is set to 3.  Therefore, if you happen to be watching
  302. DOCVu when Shellplay tries to switch songs it would stop until you exit the
  303. CDA menu.  Since according to ToolBox Vol.1 <Desk Manager> "CDAs have all
  304. system resources available to them", DOCVu adjusts the busy flag to fix the
  305. problem <only when busy flag suppression is on>.  I haven't had any
  306. problems using this yet, however if anyone does let me know.
  307.  
  308. The resource fork of DOCVu has been adjusted to take care of the AppleShare
  309. problem.  I do not have access to an AppleShare network myself, so if this
  310. does not correct the problem then let me know.
  311.  
  312. I added in a Pause function this time, I cannot fathom why I left it out
  313. in the last version.  Since most people, such as me, cannot read something that
  314. changes at 60Hz, I put something in so you can now stop and take a look at
  315. whats happening.
  316.  
  317. People were complaining that I did not include the volume registers on the
  318. original version.  Well take a look at the 'v' key, now you got volume with
  319. a vengence.
  320.  
  321.  
  322. Credits
  323. =======
  324. DOCVu 2.0 <c> 1993-1994 all rights reserved...
  325.  
  326. Coding: Brian Ballweber
  327. Graphics: Brian Ballweber, Jeremy Chadwick
  328.  
  329. Special thanks to Dave Huang for his technical help and ideas.
  330. Many thanks to Alvin Tan for his Ensoniq knowledge, and helping to hunt
  331.     down that damn interrupt bug.
  332. Special thanks extended to Steve Gunn, Ian Schmidt, Frank Lim, and
  333.     James Brookes for ideas and betatesting.
  334. Big Hellos to Dana C, Hal B, Ian B, Rich W, JB of NinjaForce,
  335.     and only the friendly guys on #appleiigs via IRC.
  336.  
  337.  
  338. Finally, please forward comments, criticism, and especially ideas to:
  339.  
  340. Internet:
  341.         ballweb@csos.orst.edu
  342.            or
  343.         yoshi@csos.orst.edu
  344.  
  345. Snail Mail:
  346.         Brian Ballweber
  347.         2941 NE Conser
  348.         Corvallis, OR 97330
  349.            or
  350.         Jeremy Chadwick
  351.         33811 Twin Maple Lane
  352.         Corvallis, OR 97333
  353.  
  354. "DE: life sux.."
  355. ~x~4/^\5_=,}:
  356. NO CARRIER
  357.