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 >
Wrap
Text File
|
1993-02-25
|
11KB
|
294 lines
-----------------------------------------------------------------------------
G U S U N I T
_______________
~~~~~~~~~~~~~~~
-----------------------------------------------------------------------------
Copyright (c) 1993 by TBH-Softworx
Oliver Fromme, Klingestr. 2, 3380 Goslar, Germany
Internet email: inof@asterix.rz.tu-clausthal.de
This is donated to the PUBLIC DOMAIN.
Many many thanks to Tran of Renaissance and Joshua Jensen!
This would be impossible without their tech specs.
Enjoy!
-----------------------------------------------------------------------------
Files:
~~~~~~
GUSUNIT.DOC this file
GUSUNIT.TPU the unit, compiled for Borland/turbo pascal 7.0
GUSUNIT.PAS source code of the unit
GUSUNIT.OBJ assembler object module
GU_TEST.PAS short and simple test program
What is this for?
~~~~~~~~~~~~~~~~~
GUSUNIT is a turbo pascal unit which supports the functions of the
Gravis Ultrasound board (GUS) -- well, at least some of the functions.
If you have Borland/turbo pascal 7.0, you can use the TPU file
mentioned above. If you have another version (4.0 - 6.0), you have
to recompile GUSUNIT.PAS (which uses GUSUNIT.OBJ). I haven't testet
below 6.0, but it should work down to 4.0.
Important:
~~~~~~~~~~
You need at least an AT to use this software (80286+).
Don't install SBOS! This unit does not work with SBOS installed!
First try...
~~~~~~~~~~~~
As a first try, compile and run GU_TEST.PAS. You should hear a
440 Hz sound (2 seconds duration) with a slight vibrato.
Of course, that's not a very exciting tune, but this short and simple
program makes clear how to use the unit.
GUSUNIT is much more powerful than this test program looks like.
For example, you can write a mod player, using this unit!
General procedures and functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
GUSInitialize
This should be the first statement in your main program.
At least, use it before any other procedure/function of GUSUNIT
(except GUSTest, GUSInit).
This is how GUSInitialize works:
At first it looks for the ULTRASND environment variable. If it
exists, the base address of the GUS is being read. If it doesn't
exist (or the address is invalid), it tries to detect the GUS
at 220h (the standard default address). If this fails too, it
looks at very address from 210h to 260h.
GUSPresent (boolean) is set to True, if a GUS is detected.
GUSBAse (word) is set to its base address.
GUSEnv (string) contains the ULTRASND environment variable (or an
empty string if it doesn't exist).
GUSMem (word) contains the amount of GUS memory installed in Kb,
i.e. 256, 512, 768, or 1024.
GUSInitialize sets the maximum number of voices to 16. If you you
needn't that much voices, don't worry, it's okay. If you need more
than 16 (up to 32 simultaneous), use GUSInit(16) (see below).
GUSInit (VoicesMax : byte)
You'll need this procedure in two cases:
1. You need more than 16 voices.
Let's say you need 20. Simply type:
GUSInit (20)
just after GUSInitialize.
2. You want all voices to stop (i.e. be quiet) immediately).
For example, it's a good idea to use this procedure at the
end of your program to be sure that all sounds stop.
GUSTest (PortAdr : word) : boolean
You really won't need this function, because GUSInitialize
does all the work for you. However, here is what GUSTest does:
It tries to detect a GUS at the specified base address. If there's
a GUS, it returns True and copies the base address to GUSBase.
GUSMem : word
You needn't this function, too, because it's already called
by GUSInitialize. it returns the number of Kb memory installed
on the GUS.
GUSPoke (Address : longint ; Value : shortint) ;
Writes the value into the GUS memory. These are the maximum
addresses:
256 kb memory: 0 - 262144 ($3ffff)
512 kb memory: 0 - 524288 ($7ffff)
768 kb memory: 0 - 786432 ($bffff)
1024 kb memory: 0 - 1048576 ($fffff)
Note: the value is shortint, not byte! Its range is -127 to 128.
GUSPokeW (Address : longint ; Value : integer) ;
The same as GUSPoke, but for 16 bit (word) values.
Note: The range is -32767 to 32768.
The address must be even!
GUSPeek (Address : longint) : shortint ;
Read a byte from the GUS memory. See GUSPoke.
GUSPeekW (Address : longint) : integer ;
Read a word (16 bit) from the GUS memory. See GUSPokeW.
Voice specific procedures and functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following procedures and functions affect only one voice.
The first parameter specifies the voice, it must be between
0 and MaxVoices-1. For example, if you have MaxVoices=16
(the default value), the voice number can range from 0 to 15.
VoiceBalance (Voice : byte ; Balance : byte) ;
You can change the balance at any time (panning effect).
The balance value ranges from 0 to 15, 0 being far left,
15 being far right, and 7 is approximately middle.
There are three constants defined:
Left = 0
Middle = 7
Right = 15
So you can simply type
VoiceBalance (0,Left)
and now voice 0 sounds through the left speaker only.
VoiceVolume (Voice : byte ; Volume : word)
Sets the volume (between 0 and 4095 = $fff) for that voice.
It's not a linear volume, but a logarithmic one. Best way,
you create an array with the volumes you need.
$fff = full volume
$eff = half volume
$dff = quarter volume
$cff = eighth volume
$bff = sixteenth volume etc.
Got it? The lower two hex digits can be used to fine tune the
volume. $f00 is almost as loud as $eff.
Of course, you can change the volume at any time.
VoiceFreq (Voice : byte ; Freq : word) ;
Sets the Frequency (in bytes/second). This is NOT the frequency
of the sound! For example, if you have a sampled waveform which
uses 18 bytes every oscillation, you need 7920 (18*440) bytes/second
to get a 440 Hz sound.
The frequency can be changed at any time.
VoiceMode (Voice : byte ; Mode : byte)
Sets various parameters. Mode is one or more of the following:
Bit8, Bit16 : selects 8 or 16 bit samples.
LoopOff, LoopOn: specifies whether to loop this voice.
UniDir, BiDir : unidirectional or bidirectional.
Forw, Backw : play the sample forward or backward.
For example, you can type:
VoiceMode (0,Bit8+LoopOn+UniDir+Forw)
If you omit any of the modes, the default is Bit8+LoopOff+UniDir+Forw.
VoiceSample (Voice : byte ; Start,LoopStart,LoopEnd : longint)
Specifies where the sample is located in the GUS memory.
Start is the start address of the sample (where the GUS starts
playing). It should be 32 bit aligned, i.e. bit 0 and 1 should
be 0.
LoopStart and LoopEnd define the looping range. LoopStart MUST
BE smaller than LoopEnd. Note that the actual loop ends one byte
before LoopEnd.
If you've disabled looping (see VoiceMode), just set LoopStart
the same as Start (or any other value smaller than LoopEnd).
You can use this procedure at any time -- even while the voice
is playing. This can produce some interesting effects.
VoiceStart (Voice : byte)
Starts playing the specified voice.
VoiceStop (Voice : byte)
Stops playing the specified voice.
GetVoiceLoc (Voice : byte) : longint
Get the currect byte pointer of the specified voice.
Volume ramping
~~~~~~~~~~~~~~
Volume ramping can be used in two different ways:
1. without looping, to slide the volume up or down.
2. with looping, creating those "vibrato" effects.
RampRange (Voice : byte ; Lower,Upper : word)
Specify the lower and upper volume level of the volume ramp.
These are values between $000 and $fff (see VoiceVolume), but
the lower hex digit (lower 4 bits) is ignored.
Note: Lower must be less than Upper, even when ramping down.
RampRate (Voice : byte ; Scale,Rate : byte) ;
Sets the speed of the ramping. Scale must be between 0 and 3,
Rate must be between 0 and 63 (the less, the faster).
Scale=0: every byte the volume is increased/decreased by the
Rate value.
Scale=1: every eighth byte the volume is increased/decreased
by the Rate value.
Scale=2: every sixteenth byte the volume is increased/decreased
by the Rate value.
Scale=3: every 512th byte the volume is increased/decreased
by the Rate value.
For vibrato effect, Scale=2 and Rate=8 are usually good.
For volume sliding, try Scale=1, and Rate between 2 and 20.
RampMode (Voice : byte ; Mode : byte)
Similar to VoiceMode.
LoopOff, LoopOn: specifies whether to loop the volume ramp.
UniDir, BiDir : unidirectional or bidirectional.
Up, Down : slide up or down.
For a vibrato, you should usually type:
RampMode (Voice,LoopOn+BiDir)
Up or down doesn't matter.
For a volume slide, you should type:
RampMode (Voice,LoopOff+UniDir+Up)
This will slide the volume up (from lower to upper level).
Simply replace "Up" by "Down" to slide the volume down
(from upper to lower level).
RampStart (Voice : byte)
Starts the volume ramping of the specified voice.
RampStop (Voice : byte)
Stops the volume ramping of the specified voice.
-----------------------------------------------------------------------------
That's all for this time.
Surely there's much work to do, this is just the beginning.
Here's what I'm planning for the next release:
- Support of DMA and IRQ features.
- Procedures to load samples from disk into GUS memory.
- And much more.
May the GUS be with you. Always!
- Ollie -
-----------------------------------------------------------------------------
Oliver Fromme, Klingestr. 2, 3380 Goslar, Germany
Internet email: inof@asterix.rz.tu-clausthal.de
-----------------------------------------------------------------------------