This text file was written in November, 1993.
────────────────────────────────────────
GusPlay v1.5 and UltraDox v1.? interface for
Borland/Turbo Pascal, version 6.0 and up
────────────────────────────────────
── Juggler/BTL ──
───────
Quick Start
───────────
If you are anything like me you will want to try the program before you
bother to read the dox.. so just run MAKE.BAT and then GUSTEST to see how
it looks.. not very impressive, but it'll do. (make.bat uses tasm and tpc,
if they aren't in your path you'll hafta do it manually)
Intro
─────
Hmm.. how to begin..? Well... This code is the result of about a week of
entertaining coding and hacking, done by me after I discovered the source to
GusPlay 1.5 on ftp.uwp.edu .. my favorite .MOD player on my favorite FTP
site. Oh Joy! :-)
This is written so I can put GUS support in a game I'm writing.. (coming
soon to an FTP site near you) ..and because it is so much fun to write code
and have it work almost immediately.
Anyway, this isn't perfect (yet), and that is probably at least in part my
fault. If I discover any horrid bugs I'll probably upload an update. Only
a small portion of the code is written by me, just enuff to get both GusPlay
and Josh's low level code to work together, and to allow me to play sound
effects without trashing the .MOD playback. If you like it, write a GUS
program/game/demo and send me a copy :-)
BTW: Joshua Jensen (CyberStrike) has left Renaissance. BUT..he was still
with them when Ultradox was written, and it was distributed as a
Renaissance product, so I'm gonna keep on calling it the Renaissance
code (or just Ultradox).
BTW2: If you run into any weird errors, take a peek at the assembly file
and make sure all my PUSHs and POPs match correctly. I may have
slipt up somewhere (my most common error).
Technical stuff
───────────────
Much of this code is self-explanitory ('cause of comments) and I think I even
managed to think up understandable proc/func names. There are just a few
things you should know before you start to use the unit, the most important
having to do with the memory management. (primitive!)
GUS memory:
┌──0:0000───┐ This little schematic shows how my code treats the
│Sound FX │ UltraSound's memory. At the bottom I put misc. sound
│Sound FX │ _GMP^ effects, and "protect" them by saving the top of the
│Instruments│ memory they use in a variable. (GP.GUSMemProt^)
│Instruments│ This marks where to begin to load module instruments,
│Instruments│ _GM^ and another variable (GP.GUSMem^) marks the beginning
│Free.... │ of the unused GUS memory.
└──F:FFFF───┘
Why did I organize it this way? Well, for my game. :-) I want to have the
same sound effects available all the time, but different songs playing on
different levels/waves. Therefore it makes sense to put all my sound effects
at the bottom, where I can easily keep them from being overwritten by the
module loading routines. This means that if you disagree with my
philosophy, and absolutley MUST load your module first, you will have to do
this:
GP.GUSMemProt^ := 0 ;
LoadModule('k00ld00d.mod') ;
GP.GUSMemProt^ := GP.GUSMem^ ;
And then be *very* careful when you want to change songs. Of course, this
makes changing samples much safer and easier.. but there is always a trade
off. One other reason for "forcing" people to load their sound effects first
is that if you try to load your samples while the module is playing you will
often get really screwed up results. Why? Because the playback routine
alters the GUS registers many times per second. If somebody teaches me to
do DMA, this could be fixed. A CLI and a STI would also do it, but then the
playback "stutters" or stops, and you won't have gained anything.
Since you have ready access to the two memory markers, you can move them
around, and easily divide the GUS memory into, say, two 128k buffers, just
by resetting GP.GUSMemProt^ right after loading your sound effects.
*** The only routines that use this memory allocation scheme are my ***
*** GP_Prot* routines and the module loading/killing routines. ***
The GP_ProtSampPlay routine automatically selects one of the 12 free voices
when you call it, and rotates the voice pointer (GP.Vars^[NextVoice]). This
means each voice will play as long as you let it (if you try to play 13
samples at once, the first one will be killed by the thirteenth). It seems
to confuse the .MOD player if you change the number of active voices, and I
don't mean after compiling (That's SURE to mess things up). :)
Oh yeah.. one other bit of trivia: The module loading routines use DOS
memory to save the patterns, not the TP heap. To keep from getting errors
put {$M Stack,Min-heap,Max-heap} at the top of your program. Make sure your
heap doesn't use up all of the available DOS memory. One solution is to
forget about the Pascal heap entirely, and just use DOS memory. Hmm.. maybe
I'll include memalloc.pas in this package.. (DOS memory allocation stuff)
The GusPlay playback routine uses the timer interrupt. If you alter the
timer's speed after starting playback you will mess things up, and if you
alter it before playback, then GusPlay will reset it to the usual rate (I
think). So just stay away from the timer. :-) GusPlay calls the old
interrupt handler at regulaur intervals, so it doesn't mess up the clock and
you can use routines like Delay() or hook int 1Ch in your programs as usual.
GusPlay also gives you a nice millisecond counter, set to zero when you start
playback. (GP_Timer^)
I tried to keep this code as low-level and simple as possible, without losing
functionality, so you should study how the UltraSound works before trying to
use the more mysterious routines. Especially the Renaissance code.
This chapter could keep getting bigger and bigger, but I really don't think
there is much that needs explaining. Read the info about the GUS hardware
in the SDK, and Ultradox if you can't figure out how it all works.
Things to do..?
───────────────
- Some volume ramping routines. I'd have to write these myself. (Heaven
forbid!) I've already got the bit definitions in there..
- DMA up/downloads would be nice.
- A routine to play midi files would ALSO be nice. 'Specially if it runs
off the timer and is as friendly/stable as GusPlay.
- Write instructions for EACH and EVERY procedure and variable in the
unit.. (this one is a bit unrealistic. ;-)
- Learn to write modules!
What the heck is BTL?
─────────────────────
BTL is me and two friends, here in Iceland who share an interest in demos,
programming, and girls (not in that order). BTL stands for Better Than Life,
and we hope our programs will someday be BTL :-). Shamelessly lifted from
the cover of my second favorite book, Better Than Life by Grant Naylor
(sequal to Red Dwarf). Read it!
Greets: Anybody I've chatted with on IRC, 'specially the #teens regulaurs.
My friends that aren't trapped in cyberspace.
The Villa BBS gang.
Anybody who wrote a demo I've liked.
I want to thank Joshua Jensen, Tran and Robert Adolfsson for making this
possible. Not to mention Advance Gravis! :-)
Copyright & Your rights
───────────────────────
GP15.PAS and PASGPLAY.ASM are (C) Copyright 1993 by Bjarni R. Einarsson.
This code is "my property" (the parts that aren't Robert's or Josh's, that
is), but you are free to use and alter it in any programs you write, as long
as you fulfill the terms set by Robert Adolfsson, on the GusPlay routines.
I am pretty sure that the Renaissance stuff is public domain. Read the
gusplay.txt file included in this archive for more info.
If you want to see exactly what is mine, unpack gusp15.zip and take a peek
at the original source to GusPlay v1.5. The changes are pretty minor.
The only terms I set are that you mention my name in the credits, docs or
both that go with your program. You should also mention Robert and Joshua,
since they did all the technical stuff. :-) I like E-mail, and snail mail
is even more exciting, so please drop me a line and tell me what you are
doing with this program.
Snail: Bjarni R. Einarsson Internet: bre@os.is
Barmahlid 56
105 Reykjavik IRC nick: Juggler
ICELAND IRC bot: BoTL
─────────────────────────────────────────────────────────────────────────────
!TheGUSwillconquerall!Haveanicedayandenjoytheprogram!Sendmemanyverybigchecks!
