**************************************************
	*     The example of direct EMU8000 control      *
	*       Version 1.0   (c) Grinus/ToM, 1996       *
	**************************************************



 INTRODUCTION

This package contains information that can be very useful to designers 
of player routines for Sound Blaster AWE32 compatible cards in native mode.

I'm sure that it will help people to get most of their AWE cards.
And it is definitely worth it. These cards offer the best quality for
reproducing the tracked music. Compared to classic GUS cards they provide
customizable reverb and chorus effects, together with a fixed highest sampling
rate of 44.1 kHz.
And I hate 'GUS-only' demos and trackers!! Can you hear me? I mean You!  ;-)

I suppose in my text that you are familiar with the "Unofficial Sound Blaster
AWE32 Programming Guide" by Vince Vu (thanks again for this unique paper).




 HOW TO RECOMPILE THE EXAMPLE

The source code is written for Borland C++ 3.1 compiler and it likely needs
a small modification for porting to another C++ clones. I'm sorry for it.
The same applies to MAKEFILE.

My project file EXAMPLE.PRJ expects the Borland C++ installed in directory 
C:\BC. If it's not your case, change the directories in IDE's options menu.




 EMU8000 REGISTERS

You can find the detailed information about registers in my header file AWE.H

After examining my sources, you'll note that I'm using my own EMU8000 register
indexing scheme. The goal is a single register index in range 0 to 5Ch.

Note that many registers are still unknown to me.  If you are so smart or
so lucky to have discovered anything new, please don't hesitate and mail me.




 AVOIDING CLICKS

This is the most important part of this text. It contains the information
and hints that you can't see in my source code files.

First of all, it is not a good aproach to assign EMU8000 channels to the
tracker channels permanently. It would not allow to release old notes smoothly
when new notes arrive. To write a good-sounding player routine, you'll have to
design a strategy for allocating free (or nearly free) EMU8000 channels
(i.e. oscillators). A well designed allocation routine is necessary to produce
the click-free sound. 
The so-called "Ultraclick removal" known to GUS users provides generally 
the same task.

You can find an example of such routine in Omega player (the part of interrupt
routine before the PlayNote function is called). The code just searches for
a channel with a released note and a current volume envelope value of zero.
If no such channel is found, the new note is not played at all. This will work
well with 4-channel modules but definitely not with 15 and more channels.

I've been using a more sophisticated algorithm in AMP player to reach that
absolutely clean sound even with many channels used.
First of all, EMU8000 channel with a sample in final silent-loop is found
(this is the case of non-looped sample played to the end).
If there is none, a channel with a minimal current volume envelope value
is picked. The channels where the note was released have an absolute priority
in that selection process.
The current oscillator positions and volumes are determined by reading the
AWE_Flt_Start and AWE_DestV_FC registers.
The channel is then cleared (by CutNote function) and used for the new note.
To allow such processing, there is necessary to keep some structures with
information about a current state of EMU8000 channels and module tracks. It was
one of reasons not to include the channel allocation code in this package.

But all this is not enough!  There is a second serious danger.
You have to avoid the clicks produced by sample interpolation algorithm
processed by EMU8000 hardware that use also three succeeding samples.
This is done by ensuring that at least three more valid samples are present
behind the active address range (i.e. the end of loop or silent-loop).
In my AMP player, I use four additional samples after the end of loop copied
from the start of loop.




 LEGAL STUFF

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL
AUTHOR BE LIABLE FOR ANY DAMAGES CAUSED BY THE USE OF THE CODE.

You have a free right to use, modify, reproduce and distribute the source code
in any way, provided that you include proper credits in your product.

And if you use it, a mail would be nice. After all, you get this for free.




 REFERENCES

1.  "SB AWE32 Developer's Information Package"
	by Creative Technology Ltd.

2.  "Unofficial Sound Blaster AWE32 Programming Guide"
	by Vince Vu a.k.a. Judge Dredd

3.  The source code of "Omega AWE32 module player v0.6"
	by Cygnus X-1

4.  "SB AWE32 - the pages of naked truth"
	by Mathias C. Hjelt

You can find the links to all of these packages on our WWW page
  http://frodo.hiof.no/~gislemm/tom/tom.html




 HOW TO CONTACT ME

Please send your comments, questions, etc. to:

 Lada Kopecky  a.k.a.  Grinus / ToM
   E-mail:  kopecky@tsoft.cz
   WWW:     http://frodo.hiof.no/~gislemm/tom/tom.html