home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 17
/
CD_ASCQ_17_101194.iso
/
vrac
/
guslib.zip
/
GUSLIB.DOC
< prev
next >
Wrap
Text File
|
1994-08-26
|
16KB
|
440 lines
GusLib
v1.0
By Paul Kimbrel
Aug 17, 1994
Documentation
Short Description
-------------------------------------
GusLib is a public domain/royalty free programming library for the Gravis
UltraSound sound card. It's purpose is to allow programmers easy access to
the basic functions of the GUS. The library was mainly written for assembly
language use but can be easily used with C,C++,Pascal, and other languages.
It's features are:
Direct DRAM I/O functions
DMA DRAM Output
Playback routines
Register I/O functions
This library is designed primarily for output only. Some functions could
be used for input as well, though programming experience with the GUS would
be required.
Disclaimer
-------------------------------------
This program is given as is. It is subject to change with out notice or
permission. I make no claims as to it's usability or workability. I've made
all attempts to test it as much as possible, but I claim no responsibility
for any damages caused by this program. In other words, it works here, so
if doesn't work there, I can't help it.
Enough of the bad guy stuff:
I'll be happy to help with any problems and would like to know if any
flaws in the programming are found. I'm always looking to improve my
programs, so if you have any recommendations, please get a hold of me and
let me know.
As far as it's status as a program, it's public domain which means you
can do just about anything to it you want. I encourage you to dig into the
code and make your alterations to it as you wish. Copy the code, use it in
other programs, use it as a reference for other GUS applications, whatever.
This program is yours to do with as you please. Use it in your games,
applications, etc., and don't worry about royalty or credit (although, just
mentioning my name would be nice <g>). If you do use my program in any of
your applications, please drop me a note, just so I can keep track of things
(and for personal gratification).
Files
-------------------------------------
The following files are included in the GUSLIB library:
GUSLIB.ASM - Source code to GUSLIB
GUSLIB.OBJ - Object code to GUSLIB for linking
GUSLIB.LIB - Library file to GUSLIB for linking
GUSLIB.DOC - Documentation for GUSLIB
PLAYVOC.EXE - Sample program using GUSLIB (plays back .VOC files)
PLAYVOC.ASM - Sample source code using GUSLIB
Stuff that might be important (?)
-------------------------------------
Okay, I'll admit it - I hate commenting my programs - especially when I've
been working for a solid week on it. It gets to the point of "I could care
less if I know how it works just so long as it works." I'm sitting here
with an actual working model on my computer and really don't want to go
through and comment, so I'm going to let it be for now. However, you can
look for more comments in future revisions of the program (I can almost
guarantee that there will be).
If you have any questions at all about the program, you can find me
in the 80XXX echo on Fidonet (as Paul Kimbrel), you can net-mail me at
1:232/10 (again, to Paul Kimbrel), or e-mail me via the internet at
dkimbrel@heartland.bradley.edu
All answer ALL questions even if it's to say that I haven't the foggiest
idea what-so-ever. I'll be working on a better version, but this will
at least get some people (including myself) working. I hope you find
some kind of usefulness from this program.
An IMPORTANT note concerning the DMA channels! - MUST READ!!!!!
-------------------------------------
Please note that the only two channels that this program will work with
are the 8 bit channels (1 and 3). GUSLIB will allow for the 16 bit channels
(5,6 and 7), yet I've never worked with them before. As a result, I make
NO assumtions as to if they work or not. If you want to try - go for it,
just let it be known that I have tried (yet)...
Functions
-------------------------------------
To use these functions, simply fill the BX register with the function
number and all other registers with the appropriate information (depending
on the function). Next, call the procedure GUSLIB. When the function has
been executed, a return code will come back in the AX register. If AX
reads 00h, then the function was executed successfully. Otherwise, AX
contains the error code.
Function 00h - Init_Gus
-------------------------------------
Short Description: Initializes and sets up the GUS
Registers on entry:
BX = 0000h
Registers on return:
AX = Error Code - 00h - No Error
01h - Bad Environmental Variable
02h - Illegal IRQ in Environmental Variable
03h - Illegal DMA channel in Environmental Variable
04h - GUS Reset error
05h - DRAM I/O Error
Extended Description:
This function preforms several tasks. It first searches and processes the
'ULTRASND=' environmental variable. Then it checks to make sure that all the
information in the variable is correct. Third, it resets the GUS. Fourth,
it makes sure that the DRAM is okay. Finally, it sets up the library's
ISR for the IRQ and programs the computer's PIC (how's THAT for initials!).
When the ISR is setup, your program MUST run the deinitialization function
do undo what the initialization does. The best thing to do is write your
program to ALWAYS execute the deinitialation function before it exits. The
functions are made so that it won't undo the ISR if it isn't set up. In
other words, if you call the deinitalization function and there's nothing
for it to do, it'll automatically return with out doing anything, making it
easier for you to keep track of things.
Function 01h - Deinit_Gus
-------------------------------------
Short Description: Deinitializes and shuts down the GUS
Registers on entry:
BX = 0001h
Registers on return:
None
Extended Description:
This function basically undoes what function 00h does. If function 00h
isn't executed, then this function will automatically return with out doing
anything. It's best to call this function right before you exit no matter
what the situation is. This makes keeping track of the initialization
process easier (IOW - you really don't have to).
Function 02h - Poke
-------------------------------------
Short Description: Pokes data directly into the GUS's memory.
Registers on entry:
BX = 0002h
AL = Value to poke
SI:DI = Linear Address in GUS memory.
Registers on return:
None
Extended Description:
This function pokes data directly into the GUS's DRAM. SI:DI point to
the absolute linear address. Keep in mind that the GUS can only address
1 MEG of memory, so only the lower 20 bits should contain data; all other
bits should be set to 0.
NOTE: The value in AL is put into memory AS IS. There is no two's-
compliment conversion in this function. If a conversion is necessary, you
must do it to the value before you call this function.
Function 03h - Peek
-------------------------------------
Short Description: Peeks data directly from the GUS's memory.
Registers on entry:
SI:DI = Linear Address in GUS memory
Registers on return:
BX = 0003h
AL = Data at SI:DI
Extended Description:
This function peeks data directly from the GUS's memory. It's address
scheme is the same as that in function 02h.
NOTE: The value returned in AL is read AS IS. There is no two's-
compliment conversion in this function. If a conversion is necessary, you
must do it to the value after you call this function.
Function 04h - Set_Active
-------------------------------------
Short Description: Sets the number of active voices on the GUS.
Registers on entry:
BX = 0004h
AL = Number of Pages (14-32)
Registers on return:
None
Extended Description:
This function sets the number of active voices on the GUS. An explanation
of this function is beyond the scope of this documentation. Just keep in
mind that you don't using any voices beyond the number that you have set
with this function. NOTE: The fewer voices you have, the better the sound
quality will be. For more information, see the Gravis Ultrasound SDK.
Function 05h - Download_Sound
-------------------------------------
Short Description: Uses PC's DMA to send a sound sample to GUS's memory.
Registers on entry:
BX = 0005h
CL = Wait Toggle (0 = no; 1 = yes)
DI = GUS DRAM Address (upper 16 bits)
ES:SI = PC segment:offset address of sample
DX:AX = Size of sample
Registers on return:
AX = Error Code - 00h - No Error
01h - KeyBoard interrupt (if CL = 1 on entry)
02h - DMA still busy
Extended Description:
This dumps a sample that is stored in PC memory to the GUS memory via
the DMA channel. Note that the GUS DRAM Address (in DI) is only the upper
16 bits of the address. Since the entire linear address is 20 bits, you must
take your absolute address and divide it by 16 (that's 16 decimal). As you
may have noticed, your DMA address will have to on a 16 byte boundary.
The wait toggle specifies to the routine if you want to it to wait until
the DMA is done or to just return immediately.
CASE: CL = 0
The routine will return as soon as the DMA has started its transfer. No
other DMA transfers can take place until the DMA is finished. To check the
status of the DMA, execute function 6 or re-execute this function. If you
re-execute this function and get an error code of 2, then the DMA is still
busy.
CASE: CL = 1
The routine will wait until the DMA has finished its transfer before
returning. For safety purposes, the program checks the keyboard during the
wait. If a key is hit, the function will return and will send back an
error code of 1.
Function 06h - Dma_Status
-------------------------------------
Short Description: Checks on the status of the DMA download (function 5)
Registers on entry:
BX = 0006h
Registers on return:
AX = Status
Extended Description:
Returns the status of the DMA download (function 5). It returns a value
of 0 if the DMA is free and available for downloading. If it returns a value
of 1, a DMA transfer is taking place and the channel is busy.
Function 07h - Set_Volume
-------------------------------------
Short Description: Sets the volume of a specific voice.
Registers on entry:
BX = 0007h
AX = Volume (0-4095)
CL = Voice (0-active voices)
Registers on return:
None
Extended Description:
NOTE: The voice ranges from 0 to the number of active voices-1. For
example, if the number of active voices is 14, then the available voices
would be 0-13. Likewise, if the number of active voices is 32, then
the available voices would be 0-31.
Function 08h - Set_Freq
-------------------------------------
Short Description: Sets the sampling frequency of a specific voice.
Registers on entry:
BX = 0008h
AX = Frequency (1-44100)
CL = Voice
Registers on return:
None
Extended Description:
NOTE: The voice ranges from 0 to the number of active voices-1. For
example, if the number of active voices is 14, then the available voices
would be 0-13. Likewise, if the number of active voices is 32, then
the available voices would be 0-31.
Function 09h - Set_Loop
-------------------------------------
Short Description: Sets the loop back condition of the specific voice.
Registers on entry:
BX = 0009h
AL = Loop control register value (recommended value = 3)
CL = Voice
Registers on return:
None
Extended Description:
NOTE: The voice ranges from 0 to the number of active voices-1. For
example, if the number of active voices is 14, then the available voices
would be 0-13. Likewise, if the number of active voices is 32, then
the available voices would be 0-31.
NOTE: Loop control is beyond the scope of this manual. For more
information on loop control, read the Gravis Ultrasound SDK. To disable
the loop control, write the value 3 to the function. This is the
recommended action before using a voice (to clear any old values).
Function 0ah - Set_Start
-------------------------------------
Short Description: Sets the starting address (in GUS memory) of the sample.
Registers on entry:
BX = 000ah
DX:AX = Linear 20-bit address in GUS memory
CL = Voice
Registers on return:
None
Extended Description:
NOTE: The voice ranges from 0 to the number of active voices-1. For
example, if the number of active voices is 14, then the available voices
would be 0-13. Likewise, if the number of active voices is 32, then
the available voices would be 0-31.
This sets the starting location for the particular voice. GUSLIB auto-
matically adjusts the <current address> register to fit this value. When
you start playback of the voice, the playback will start at the value
in DX:AX. When the voice has stopped or has been stopped (manually), GUSLIB
will readjust the <current address> register so that it will restart at
this address each time.
Function 0bh - Set_End
-------------------------------------
Short Description: Sets the ending address (in GUS memory) of the sample.
Registers on entry:
BX = 000bh
DX:AX = Linear 20-bit address in GUS memory
CL = Voice
Registers on return:
None
Extended Description:
NOTE: The voice ranges from 0 to the number of active voices-1. For
example, if the number of active voices is 14, then the available voices
would be 0-13. Likewise, if the number of active voices is 32, then
the available voices would be 0-31.
This sets the ending address of the voice. When the playback routine
is executed, the GUS will start playback at the <start address> and will
stop when it reaches this address.
Function 0ch - Play_Voice
-------------------------------------
Short Description: Starts playback of a specific voice
Registers on entry:
BX = 000ch
AH = Control register (Use 00h for normal operation)
AL = Voice
Registers on return:
None
Extended Description:
This function starts the playback for a specific voice. To start a normal
playback (forward direction, no loop, irq's on, etc.), Simply write 00h
to the Control register (in AH). The function will filter out unwanted
information in the control register and set important information, so only
worry about those bits in which you can modify. The operation of the
control register is beyond the scope of this document; Please refer to
Gravis Ultrasound SDK for more information.
Function 0dh - Stop_Voice
-------------------------------------
Short Description: Manually stops the playback of a specific voice.
Registers on entry:
BX = 000dh
AL = Voice
Registers on return:
None
Extended Description:
This function will manually stop and reset the specified voice.
Function 0eh - Voice_Status
-------------------------------------
Short Description: Returns the playback status of a specific voice.
Registers on entry:
BX = 000eh
AL = Voice
Registers on return:
AX = Status - 00h = Voice is in playback mode
01h = Voice has stopped (not in playback mode)