home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / g / gusunit.zip / GUSUNIT.DOC < prev    next >
Text File  |  1993-02-25  |  11KB  |  294 lines
  1. -----------------------------------------------------------------------------
  2.  
  3.                                 G U S U N I T
  4.                                _______________
  5.                                ~~~~~~~~~~~~~~~
  6. -----------------------------------------------------------------------------
  7.  
  8.    Copyright (c) 1993 by TBH-Softworx
  9.                  Oliver Fromme, Klingestr. 2, 3380 Goslar, Germany
  10.                  Internet email:   inof@asterix.rz.tu-clausthal.de
  11.  
  12.    This is donated to the PUBLIC DOMAIN.
  13.  
  14.    Many many thanks to Tran of Renaissance and Joshua Jensen!
  15.    This would be impossible without their tech specs.
  16.  
  17.    Enjoy!
  18.  
  19. -----------------------------------------------------------------------------
  20.  
  21. Files:
  22. ~~~~~~
  23.    GUSUNIT.DOC    this file
  24.    GUSUNIT.TPU    the unit, compiled for Borland/turbo pascal 7.0
  25.    GUSUNIT.PAS    source code of the unit
  26.    GUSUNIT.OBJ    assembler object module
  27.    GU_TEST.PAS    short and simple test program
  28.  
  29. What is this for?
  30. ~~~~~~~~~~~~~~~~~
  31.    GUSUNIT is a turbo pascal unit which supports the functions of the
  32.    Gravis Ultrasound board (GUS) -- well, at least some of the functions.
  33.  
  34.    If you have Borland/turbo pascal 7.0, you can use the TPU file
  35.    mentioned above. If you have another version (4.0 - 6.0), you have
  36.    to recompile GUSUNIT.PAS (which uses GUSUNIT.OBJ). I haven't testet
  37.    below 6.0, but it should work down to 4.0.
  38.  
  39. Important:
  40. ~~~~~~~~~~
  41.    You need at least an AT to use this software (80286+).
  42.    Don't install SBOS! This unit does not work with SBOS installed!
  43.  
  44. First try...
  45. ~~~~~~~~~~~~
  46.    As a first try, compile and run GU_TEST.PAS. You should hear a
  47.    440 Hz sound (2 seconds duration) with a slight vibrato.
  48.  
  49.    Of course, that's not a very exciting tune, but this short and simple
  50.    program makes clear how to use the unit.
  51.    GUSUNIT is much more powerful than this test program looks like.
  52.    For example, you can write a mod player, using this unit!
  53.  
  54. General procedures and functions
  55. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56.    GUSInitialize
  57.  
  58.       This should be the first statement in your main program.
  59.       At least, use it before any other procedure/function of GUSUNIT
  60.       (except GUSTest, GUSInit).
  61.  
  62.       This is how GUSInitialize works:
  63.       At first it looks for the ULTRASND environment variable. If it
  64.       exists, the base address of the GUS is being read. If it doesn't
  65.       exist (or the address is invalid), it tries to detect the GUS
  66.       at 220h (the standard default address). If this fails too, it
  67.       looks at very address from 210h to 260h.
  68.  
  69.       GUSPresent (boolean) is set to True, if a GUS is detected.
  70.       GUSBAse (word) is set to its base address.
  71.       GUSEnv (string) contains the ULTRASND environment variable (or an
  72.                       empty string if it doesn't exist).
  73.       GUSMem (word) contains the amount of GUS memory installed in Kb,
  74.                     i.e. 256, 512, 768, or 1024.
  75.  
  76.       GUSInitialize sets the maximum number of voices to 16. If you you
  77.       needn't that much voices, don't worry, it's okay. If you need more
  78.       than 16 (up to 32 simultaneous), use GUSInit(16) (see below).
  79.  
  80.    GUSInit (VoicesMax : byte)
  81.  
  82.       You'll need this procedure in two cases:
  83.       1. You need more than 16 voices.
  84.          Let's say you need 20. Simply type:
  85.             GUSInit (20)
  86.          just after GUSInitialize.
  87.       2. You want all voices to stop (i.e. be quiet) immediately).
  88.          For example, it's a good idea to use this procedure at the
  89.          end of your program to be sure that all sounds stop.
  90.  
  91.    GUSTest (PortAdr : word) : boolean
  92.  
  93.       You really won't need this function, because GUSInitialize
  94.       does all the work for you. However, here is what GUSTest does:
  95.  
  96.       It tries to detect a GUS at the specified base address. If there's
  97.       a GUS, it returns True and copies the base address to GUSBase.
  98.  
  99.    GUSMem : word
  100.  
  101.       You needn't this function, too, because it's already called
  102.       by GUSInitialize. it returns the number of Kb memory installed
  103.       on the GUS.
  104.  
  105.    GUSPoke (Address : longint ; Value : shortint) ;
  106.  
  107.       Writes the value into the GUS memory. These are the maximum
  108.       addresses:
  109.  
  110.          256 kb memory: 0 -  262144  ($3ffff)
  111.          512 kb memory: 0 -  524288  ($7ffff)
  112.          768 kb memory: 0 -  786432  ($bffff)
  113.         1024 kb memory: 0 - 1048576  ($fffff)
  114.  
  115.       Note: the value is shortint, not byte! Its range is -127 to 128.
  116.  
  117.    GUSPokeW (Address : longint ; Value : integer) ;
  118.  
  119.       The same as GUSPoke, but for 16 bit (word) values.
  120.       Note: The range is -32767 to 32768.
  121.       The address must be even!
  122.  
  123.    GUSPeek (Address : longint) : shortint ;
  124.  
  125.       Read a byte from the GUS memory. See GUSPoke.
  126.  
  127.    GUSPeekW (Address : longint) : integer ;
  128.  
  129.       Read a word (16 bit) from the GUS memory. See GUSPokeW.
  130.  
  131.  
  132. Voice specific procedures and functions
  133. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  134.    The following procedures and functions affect only one voice.
  135.    The first parameter specifies the voice, it must be between
  136.    0 and MaxVoices-1. For example, if you have MaxVoices=16
  137.    (the default value), the voice number can range from 0 to 15.
  138.  
  139.    VoiceBalance (Voice : byte ; Balance : byte) ;
  140.  
  141.       You can change the balance at any time (panning effect).
  142.       The balance value ranges from 0 to 15, 0 being far left,
  143.       15 being far right, and 7 is approximately middle.
  144.  
  145.       There are three constants defined:
  146.          Left   = 0
  147.          Middle = 7
  148.          Right  = 15
  149.       So you can simply type
  150.          VoiceBalance (0,Left)
  151.       and now voice 0 sounds through the left speaker only.
  152.  
  153.    VoiceVolume (Voice : byte ; Volume : word)
  154.  
  155.       Sets the volume (between 0 and 4095 = $fff) for that voice.
  156.       It's not a linear volume, but a logarithmic one. Best way,
  157.       you create an array with the volumes you need.
  158.  
  159.          $fff = full volume
  160.          $eff = half volume
  161.          $dff = quarter volume
  162.          $cff = eighth volume
  163.          $bff = sixteenth volume etc.
  164.  
  165.       Got it? The lower two hex digits can be used to fine tune the
  166.       volume. $f00 is almost as loud as $eff.
  167.       Of course, you can change the volume at any time.
  168.  
  169.    VoiceFreq (Voice : byte ; Freq : word) ;
  170.  
  171.       Sets the Frequency (in bytes/second). This is NOT the frequency
  172.       of the sound! For example, if you have a sampled waveform which
  173.       uses 18 bytes every oscillation, you need 7920 (18*440) bytes/second
  174.       to get a 440 Hz sound.
  175.       The frequency can be changed at any time.
  176.  
  177.    VoiceMode (Voice : byte ; Mode : byte)
  178.  
  179.       Sets various parameters. Mode is one or more of the following:
  180.  
  181.          Bit8, Bit16    : selects 8 or 16 bit samples.
  182.          LoopOff, LoopOn: specifies whether to loop this voice.
  183.          UniDir, BiDir  : unidirectional or bidirectional.
  184.          Forw, Backw    : play the sample forward or backward.
  185.  
  186.       For example, you can type:
  187.          VoiceMode (0,Bit8+LoopOn+UniDir+Forw)
  188.       If you omit any of the modes, the default is Bit8+LoopOff+UniDir+Forw.
  189.  
  190.    VoiceSample (Voice : byte ; Start,LoopStart,LoopEnd : longint)
  191.  
  192.       Specifies where the sample is located in the GUS memory.
  193.       Start is the start address of the sample (where the GUS starts
  194.       playing). It should be 32 bit aligned, i.e. bit 0 and 1 should
  195.       be 0.
  196.       LoopStart and LoopEnd define the looping range. LoopStart MUST
  197.       BE smaller than LoopEnd. Note that the actual loop ends one byte
  198.       before LoopEnd.
  199.  
  200.       If you've disabled looping (see VoiceMode), just set LoopStart
  201.       the same as Start (or any other value smaller than LoopEnd).
  202.  
  203.       You can use this procedure at any time -- even while the voice
  204.       is playing. This can produce some interesting effects.
  205.  
  206.    VoiceStart (Voice : byte)
  207.  
  208.       Starts playing the specified voice.
  209.  
  210.    VoiceStop (Voice : byte)
  211.  
  212.       Stops playing the specified voice.
  213.  
  214.    GetVoiceLoc (Voice : byte) : longint
  215.  
  216.       Get the currect byte pointer of the specified voice.
  217.  
  218.  
  219. Volume ramping
  220. ~~~~~~~~~~~~~~
  221.    Volume ramping can be used in two different ways:
  222.    1. without looping, to slide the volume up or down.
  223.    2. with looping, creating those "vibrato" effects.
  224.  
  225.    RampRange (Voice : byte ; Lower,Upper : word)
  226.  
  227.       Specify the lower and upper volume level of the volume ramp.
  228.       These are values between $000 and $fff (see VoiceVolume), but
  229.       the lower hex digit (lower 4 bits) is ignored.
  230.  
  231.       Note: Lower must be less than Upper, even when ramping down.
  232.  
  233.    RampRate (Voice : byte ; Scale,Rate : byte) ;
  234.  
  235.       Sets the speed of the ramping. Scale must be between 0 and 3,
  236.       Rate must be between 0 and 63 (the less, the faster).
  237.  
  238.       Scale=0: every byte the volume is increased/decreased by the
  239.                Rate value.
  240.       Scale=1: every eighth byte the volume is increased/decreased
  241.                by the Rate value.
  242.       Scale=2: every sixteenth byte the volume is increased/decreased
  243.                by the Rate value.
  244.       Scale=3: every 512th byte the volume is increased/decreased
  245.                by the Rate value.
  246.  
  247.       For vibrato effect, Scale=2 and Rate=8 are usually good.
  248.       For volume sliding, try Scale=1, and Rate between 2 and 20.
  249.  
  250.    RampMode (Voice : byte ; Mode : byte)
  251.  
  252.       Similar to VoiceMode.
  253.  
  254.          LoopOff, LoopOn: specifies whether to loop the volume ramp.
  255.          UniDir, BiDir  : unidirectional or bidirectional.
  256.          Up, Down       : slide up or down.
  257.  
  258.       For a vibrato, you should usually type:
  259.          RampMode (Voice,LoopOn+BiDir)
  260.       Up or down doesn't matter.
  261.       For a volume slide, you should type:
  262.          RampMode (Voice,LoopOff+UniDir+Up)
  263.       This will slide the volume up (from lower to upper level).
  264.       Simply replace "Up" by "Down" to slide the volume down
  265.       (from upper to lower level).
  266.  
  267.    RampStart (Voice : byte)
  268.  
  269.       Starts the volume ramping of the specified voice.
  270.  
  271.    RampStop (Voice : byte)
  272.  
  273.       Stops the volume ramping of the specified voice.
  274.  
  275. -----------------------------------------------------------------------------
  276.  
  277. That's all for this time.
  278. Surely there's much work to do, this is just the beginning.
  279.  
  280. Here's what I'm planning for the next release:
  281.  
  282.  - Support of DMA and IRQ features.
  283.  - Procedures to load samples from disk into GUS memory.
  284.  - And much more.
  285.  
  286. May the GUS be with you. Always!
  287.  
  288.    - Ollie -
  289.  
  290. -----------------------------------------------------------------------------
  291. Oliver Fromme, Klingestr. 2, 3380 Goslar, Germany
  292. Internet email:   inof@asterix.rz.tu-clausthal.de
  293. -----------------------------------------------------------------------------
  294.