File: awedrv-prog.html

package info (click to toggle)
awesfx 0.5.2-1
links: PTS, VCS
area: main
in suites: bookworm, bullseye
size: 772 kB
sloc: ansic: 6,532; sh: 56; makefile: 47
file content (1280 lines) | stat: -rw-r--r-- 45,256 bytes
parent folder | download | duplicates (9)
<!-- X-URL: http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html -->
<BASE HREF="http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html">

<title>AWEDRV PROGRAMMING NOTES</title>
<body>

<center>
<hr>
<h1>AWEDRV PROGRAMMING NOTES</h1><p>
ver.1.07<p>
Takashi Iwai
(<a href=mailto:iwai@dragon.mm.t.u-tokyo.ac.jp>
<i>iwai@dragon.mm.t.u-tokyo.ac.jp</i></a>)
</center>
<p>

Original version:
<a href=http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html>
<i>http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html</i></a>
<p>

<hr>
<p>

<h1>0. Preface</h1>

This document describes the basic methods to access and control the AWE32
sound driver (ver.0.4.1) by Takashi Iwai.
The AWE32 sound driver provides full capability of Emu8000 chip
in the AWE32/SB32 sound card.
Please refer to AWE32 Developer's Information Package (ADIP)
distributed by CreativeLabs for details about AWE32.
<p>

<h1>1. Preparation of a message buffer</h1>

Most of macros employ a certain write buffer to access to the sound driver.
At beginning, this buffer must be defined.
The method to define, or declare this buffer is prepared in
<code>soundcard.h</code>.
<ol>
<li> Define a buffer for enough sizes (for example 2048 bytes)
<pre>
SEQ_DEFINEBUF(2048);
</pre>

<li> Define the file descriptor for <code>/dev/sequencer</code>.
<pre>
int seqfd;
</pre>

<li> Define <code>seqbuf_dump</code> function.
<pre>
void seqbuf_dump()
{
	if (_seqbufptr)
		if (write(seqfd, _seqbuf, _seqbufptr) == -1) {
			perror("write /dev/sequencer");
			exit(-1);
		}
	_seqbufptr = 0;
}
</pre>
</ol>
<p>

Most of <code>SEQ_*</code> macros write the data packet on this buffer.
The buffer is occaionally flushed when it's almost filled.
To force to send data to the driver, call <code>seqbuf_dump</code>
(or identically <code>SEQ_DUMPBUF</code>) explicitly.
<p>

<hr>
<p>

<h1>2. Opening a sound device</h1>

Then, open the sound driver device <code>/dev/sequencer</code>,
and find out the AWE32 device number from synthesizer devices in it.
Both the file descriptor and the device number must be specified
for accessing to AWE32 driver later.
Also, you should know other information of AWE32 driver, for example,
allowed voices, etc from <code>synth_info</code> structure.

<pre>
struct synth_info card_info;
int device;

void seq_init()
{
	int nrsynths;

	if ((seqfd = open("/dev/sequencer", O_WRONLY, 0)) < 0) {
		perror("open /dev/sequencer");
		exit(-1);
	}

	if (ioctl(seqfd, SNDCTL_SEQ_NRSYNTHS, &nrsynths) == -1) {
		perror("there is no soundcard");
		exit(-1);
	}
	device = -1;
	for (i = 0; i < nrsynths; i++) {
		card_info.device = i;
		if (ioctl(seqfd, SNDCTL_SYNTH_INFO, &card_info) == -1) {
			perror("cannot get info on soundcard");
			exit(-1);
		}
		if (card_info.synth_type == SYNTH_TYPE_SAMPLE
		    && card_info.synth_subtype == SAMPLE_TYPE_AWE32) {
			device = i;
			break;
		}
	}

	if (device < 0) {
		perror("No AWE synth device is found");
		exit(-1);
	}
}
</pre>
<p>

<hr>
<p>

<h1>3. Loading a sample</h1>

The awedrv has different two ways of sample loading.
One uses its own format, and another is the GUS compatible format.
In any cases, the patch data is loaded by <code>SEQ_WRPATCH</code> macro.
<pre>
SEQ_WRPATCH(patch ptr, patchlen);
</pre>
where <code>patch</code> is the pointer to the patch data,
and <code>patchlen</code> is the total length of the patch data.
<p>

<h2>3.1. AWE32 specific patches</h2>

Many of SoundFont files are designed to share the sample data
with different envelopes, or other effect parameters.
Then, awedrv accepts two separate data: the sample data, and
the voice information data.
The former contains the sample offsets and sizes,
loop position, type of sample data, a check sum value for validating,
and the sample data itself.
The latter contains the basic information to play a sample,
for example, root key note, acceptable MIDI key and velocity ranges,
envelopes, LFO's and cutoff parameters, and so on.
All the AWE patch structures are defined in <code>awe_voice.h</code>.
<p>

All the patch data has the same 16 bytes header structure at the first block,
defined as <code>awe_patch_info</code>:
<pre>
typedef struct awe_patch_info {
	short key;			/* use AWE_PATCH here */
	short device_no;		/* synthesizer number */
	unsigned short sf_id;		/* file id */
	short optarg;			/* optional argument */
	long len;			/* data length (without this header) */
	short type;			/* patch operation type */
	short reserved;			/* word alignment data */
} awe_patch_info;
</pre>
where <code>key</code> must be <code>AWE_PATCH</code> value,
and <code>device_no</code> is the above device number of AWE driver.
<code>sf_id</code> is ignored in the current version.
<code>sf_version</code> is the optional argument and depends on its
operation type.
<code>len</code> has the length of the following data
(not including this patch header itself).
<code>type</code> specifies the operation type of this patch data.
The patch data follows after this header depending its operation type.
<p>

To load the soundfont data on the driver, the following sequences are applied:
<ol>
<li> Open AWE Patch
<li> Load sample data
<li> Load voice informations
<li> Close AWE Patch
</ol>
The sections below describe each operation.
<p>

<h3>3.1.1. Open AWE Patch</h3>

This operation is necessary before loading any patch data (sample or
voice info).
If loading operations are called without opening the patch,
awedrv creates a patch information automatically as if it was opened
via this operation.
So, in this meaning, the "open" operation is not necessarilly required,
but it's recommended to call this explicitly.
<p>

To open a patch, write a patch data including a header with the operation id
<code>AWE_OPEN_PATCH</code> and <code>awe_open_parm</code> structure data
following after the header,
<pre>
typedef struct _awe_open_parm {
	unsigned short type;		/* sample type */
	short reserved;
	char name[AWE_PATCH_NAME_LEN];
} awe_open_parm;
</pre>
where <code>type</code> specifies the sample type,
and <code>name</code> stores its name.
The sample type holds an enumurated value from 0 to 6 indicating
the type of patch data, and a bit flag 0x100 indicating that the sample is
"locked".
The locked samples will not be cleared even after AWE_REMOVE_LAST_SAMPLES
operation.
This means that the locked samples always remain unless all samples are
cleared by SEQ_RESET_SAMPLES via ioctl.
The sample name is a zero terminated string,
and not referred from anywhere so far in the current version.
<p>

The data length of <code>awe_patch_info</code> is equal to
<code>AWE_OPEN_PARM_SIZE</code>.
Then, write the patch data containing both <code>awe_patch_info</code>
and <code>awe_open_parm</code> as,
<pre>
SEQ_WRPATCH(patch, sizeof(*patch) + patch->len);
</pre>
<p>

<h3>3.1.2. Close AWE Patch</h3>

This operation closes the patch currently opened by AWE_OPEN_PATCH
operation.
This is useful to exchange to another soundfont file for loading at next.
<p>

To close the patch, write a patch data containing only the patch header
with the operation id <code>AWE_CLOSE_PATCH</code>.
No optional argument nor the data structure is required.
The data length of <code>awe_patch_info</code> is then equal to zero.
<p>

<h3>3.1.3. AWE Sample Information</h3>

The sample information is a variable length data which consists of
a header containing
the sample offset informations and sample wave data.
The sample header is 32 bytes header which follows after the patch header.
<pre>
typedef struct awe_sample_info {
	unsigned short sf_id;		/* file id */
	unsigned short sample;		/* sample id */
	long start, end;		/* start & end offset */
	long loopstart, loopend;	/* loop start & end offset */
	long size;			/* size (0 = ROM) */
	short checksum_flag;		/* ignored */
	unsigned short mode_flags;	/* mode flags */
	unsigned long checksum;		/* ignored */
} awe_sample_info;
</pre>
where <code>sf_id</code> is the file id used internally and normally zero,
<code>sample</code> is the sample id of this sample which is referred by
voice information records.
It's usually identical with the sampleId in soundfont files.
<code>start</code> and <code>end</code> denote the sample start and end
offset positions,
<code>loopstart</code> and <code>loopend</code> denote the loop start
and end positions,
and <code>size</code> is the data length.
The offsets and size are word length if the data is 16bit.
Otherwise for 8bit data, they are defined as byte size.
The zero <code>size</code> parameter means a ROM sample starting
from <code>start</code> offset.
When <code>size</code> has larger than zero, the sample is loaded on
DRAM, and the offsets will be shifted.
<code>checksum_flag</code> and <code>checksum</code> was obsolete
parameters, and no more supported in ver.0.4.1.
<p>

<code>mode_flags</code> is 16bit flags of the sample data.
<pre>
#define AWE_SAMPLE_8BITS	1	/* wave data is 8bits */
#define AWE_SAMPLE_UNSIGNED	2	/* wave data is unsigned */
#define AWE_SAMPLE_NO_BLANK	4	/* no blank loop is attached */
#define AWE_SAMPLE_SINGLESHOT	8	/* single-shot w/o loop */
#define AWE_SAMPLE_BIDIR_LOOP	16	/* bidirectional looping */
#define AWE_SAMPLE_STEREO_LEFT	32	/* stereo left sound */
#define AWE_SAMPLE_STEREO_RIGHT	64	/* stereo right sound */
#define AWE_SAMPLE_REVERSE_LOOP 128	/* reverse loop */
</pre>
The 8bit or unsigned data is converted inside the awedrv to 16bit signed data.
When <code>AWE_SAMPLE_NO_BLANK</code> is on, 48 words of blank loop is appended
after the sample automatically.
When <code>AWE_SAMPLE_SINGLESHOT</code> is on, the loop points are set on this blank loop.
<code>AWE_SAMPLE_BIDIR_LOOP</code> indicates that the loop is bidirectional
(pingpong), and the samples in this loop is extended as mirror image inside.
<code>AWE_SAMPLE_REVERSE_LOOP</code> means the reverse loop.
The loop sample is duplicated on mirror image inside the driver.
Other <code>STEREO</code> flags show that the voice is a stereo sound.
If the sample data doesn't contain any blank loop, <code>AWE_SAMPLE_NO_BLANK</code> flag should be set.
Also, if the sample data is a single-shot, <code>AWE_SAMPLE_SINGLESHOT</code> flag should be set.
Otherwise, you must add a blank loop after the sample, and direct the loop pointers on it by yourself.
<p>

The driver doesn't care about these stereo flags, but checks only
the key note and velocity range.  If two or more voices are suitable
on the given note and velocity pair, all they should be played simultaneously.
The multiple instruments are featured only in channel playing mode, but
in normal mode, only the first matching voice is played.
<p>

To send a wave sample data, write a patch structure containing a patch header
with the operation id <code>AWE_LOAD_DATA</code>,
the sample header <code>awe_sample_info</code>,
and the sample wave data if necessary.
Thus, the <code>len</code> parameter of the first patch header becomes<br>
(<code>AWE_SAMPLE_INFO_SIZE</code>) + <i>data byte size</i>).<br>
<p>

<h3>3.1.4. AWE Voice Information</h3>

The voice information is also an variable length data record
to specify the raw parameters of Emu8000 chip controls for each instrument.
Multiple instruments can be defined as one voice information record
if all of them are the same instrument with the same bank/preset pair.
<p>

The voice information has 4 bytes after the patch header,
<pre>
typedef struct _awe_voice_rec_hdr {
	unsigned char bank;		/* midi bank number */
	unsigned char instr;		/* midi preset number */
	char nvoices;			/* number of voices */
	char write_mode;		/* write mode */
} awe_voice_rec_hdr;
</pre>
where <code>bank</code> and <code>instr</code> specify
the bank and program number of this instrument,
and <code>nvoices</code> denotes the number of voices (samples)
used in this instrument.
If any voices with the same bank and program number exist already,
the new voices are prepended before the list of older voices.
<code>nvoices</code> must be larger than zero.
Thus, <code>len</code> in patch header has the value<br>
(<code>AWE_VOICE_REC_SIZE</code> +
<code>nvoices</code> * <code>AWE_VOICE_INFO_SIZE</code>).<br>
<code>write_mode</code> specifies how the voice infos are stored on the driver.
<pre>
#define AWE_WR_APPEND		0	/* append anyway */
#define AWE_WR_EXCLUSIVE	1	/* skip if already exists */
#define AWE_WR_REPLACE		2	/* replace if already exists */
</pre>
Normally, <code>AWE_WR_APPEND</code> is used to append each data.
In usual situation, it doesn't matter which mode is selected.
If a data with the same preset/bank pair already exists on the driver
as a same patch,
the operation may differ depending on its write mode.
When <code>AWE_WR_EXCLUSIVE</code> is specified, the new data is skipped.
When <code>AWE_WR_REPLACE</code> is specified, the old data is thrown and
the new data replaces with the old one.
Otherwise, the data is always appended, and the new one is used together
with the old data, that is, both of them are reproduced as one sound.
<p>

After this 4bytes record,
<code>nvoices</code> of 92bytes of voice information
for each sample are appended.
<pre>
typedef struct _awe_voice_info {
	unsigned short sf_id;		/* file id */
	unsigned short sample;		/* sample id */
	long start, end;		/* sample offset correction */
	long loopstart, loopend;	/* loop offset correction */
	short rate_offset;		/* sample rate pitch offset */
	unsigned short mode;		/* sample mode */
	short root;			/* midi root key */
	short tune;			/* pitch tuning (in cents) */
	char low, high;			/* key note range */
	char vellow, velhigh;		/* velocity range */
	char fixkey, fixvel;		/* fixed key and velocity */
	char pan, fixpan;		/* panning, fixed panning */
	short exclusiveClass;		/* exclusive class (0 = none) */
	unsigned char amplitude;	/* sample volume (127 max) */
	unsigned char attenuation;	/* attenuation (0.375dB) */
	short scaleTuning;		/* pitch scale tuning(%), normally 100 */
	awe_voice_parm parm;		/* voice envelope parameters */
	short index;			/* internal index (set by driver) */
} awe_voice_info;
</pre>
where <code>sf_id</code> is an internal file id and normally zero,
<code>sample</code> is the referring sample id of this voice.
<code>start</code>, <code>end</code>, <code>loopstart</code>, and
<code>loopend</code> are the offset correction of this voices.
For example, a value of <code>start</code> 30 means that
this voice starts 30 points after the original start points.
<p>

<code>rate_offset</code> holds the pitch offset of this voice
according to its sample rate.
This value is an AWE specific logarithmic rate,
that each 4096 is one octave shift.
For example, a value of -2048 indicates the sample is played 6 semitones flat.
The value can be calculated by the following equation.
<pre>
rate_offset = log(Hz / 44100) / log(2) * 4096
</pre>
<p>

<code>mode</code> is 16bit flags indicating the kind of this voice.
<pre>
#define AWE_MODE_ROMSOUND		0x8000
#define AWE_MODE_STEREO			1
#define AWE_MODE_LOOPING		2
#define AWE_MODE_NORELEASE		4	/* obsolete */
#define AWE_MODE_INIT_PARM		8
</pre>
<code>AWE_MODE_STEREO</code> and <code>AWE_MODE_NORELEASE</code>
are ignored in the current version.
<code>AWE_MODE_INIT_PARM</code> means that <code>parm</code> members
are initialized at loading automatically.
<p>

<code>root</code> and <code>tune</code> contain the root key note
and fine tune of this voice.
The key is supplied by MIDI key value, from 0 to 127,
and fine tune is a cents order.
A positive fine tune value indicates the sound is played at a higher pitch,
and a negative value means a lower pitch.
<p>

<code>low</code> and <code>high</code> define
the key note range of this voice.
If the key is out of this range, the driver skips this voice,
and searches the next voice from voice list.
To accepts all keys, <code>low</code> be 0, and <code>high</code> 127.
<p>

Similarly, <code>vellow</code> and <code>velhigh</code> define
the velocity range of this voice.
As well as in key note range,
the voice is accepted only when the velocity is within this range.
<p>

<code>fixkey</code>, and <code>fixvel</code> indicate
the fixed key and velocity of this voice.
If the value is not -1, the key or velocity is fixed on this value.
<p>

<code>pan</code> has a panning position of the "dry" sound,
from 0(left) to 127(right), or -1 for not specified.
<code>fixpan</code> also contains the fixed panning position.
If valid <code>fixpan</code> is given, the panning position is fixed
to that value.
<p>

<code>exclusiveClass</code> is the exclusive class of this voice.
If the value is zero, no exclusive system activates.
Otherwise, the voices with the sample exclusive class are turned off
before playing a new voice with this class.
This feature is used for some drum instruments like hi-hat.
<p>

<code>amplitude</code> and <code>attenuation</code> define
the volume of this voice.
<code>amplitude</code> is a linear volume from 0 to 127,
and <code>amplitude</code> means the attenuation from full level
in 0.375dB order.
For example, a voice with <code>attenuation</code> 40 is reproduced
15dB lower from full scale.
<p>

<code>scaleTuning</code> is a pitch scale tuning ratio, and normally is 100.
<p>

<code>index</code> is an internal sample index, and ignored at loading.
<p>

<code>parm</code> contains the modulation/volume envelopes, LFO's and other
raw parameters of emu8000 chip.
<pre>
typedef struct _awe_voice_parm {
	unsigned short moddelay;	/* modulation delay (ENVVAL) */
	unsigned short modatkhld;	/* modulation attack & hold time (ATKHLD) */
	unsigned short moddcysus;	/* modulation decay & sustain (DCYSUS) */
	unsigned short modrelease;	/* modulation release time (DCYSUS) */
	short modkeyhold, modkeydecay;	/* envelope change per key (not used) */
	unsigned short voldelay;	/* volume delay (ENVVOL) */
	unsigned short volatkhld;	/* volume attack & hold time (ATKHLDV) */
	unsigned short voldcysus;	/* volume decay & sustain (DCYSUSV) */
	unsigned short volrelease;	/* volume release time (DCYSUSV) */
	short volkeyhold, volkeydecay;	/* envelope change per key (not used) */
	unsigned short lfo1delay;	/* LFO1 delay (LFO1VAL) */
	unsigned short lfo2delay;	/* LFO2 delay (LFO2VAL) */
	unsigned short pefe;		/* modulation pitch & cutoff (PEFE) */
	unsigned short fmmod;		/* LFO1 pitch & cutoff (FMMOD) */
	unsigned short tremfrq;		/* LFO1 volume & freq (TREMFRQ) */
	unsigned short fm2frq2;		/* LFO2 pitch & freq (FM2FRQ2) */
	unsigned char cutoff;		/* initial cutoff (upper of IFATN) */
	unsigned char filterQ;		/* initial filter Q [0-15] (upper of CCCA) */
	unsigned char chorus;		/* chorus send */
	unsigned char reverb;		/* reverb send */
	unsigned short reserved[4];	/* not used */
} awe_voice_parm;
</pre>
The values correspond to the register values of emu8000 described in
AWE32 Developer's Information Package (ADIP)
by CreativeLabs.
This record can be initialized internally in the driver
by setting <code>AWE_MODE_INIT_PARM</code> flag in voice_info record.
<p>

It would be useful to use a fixed size record if only one voice is defined
in one record.
<pre>
typedef struct _awe_voice_rec_patch {
	awe_patch_info		patch;
	awe_voice_rec_hdr	hdr;
	awe_voice_info		info;
} awe_voice_rec_patch;
</pre>
<p>

<h3>3.1.5. Load a preset map</h3>

The preset map provides a virtual voice information for a preset.
It redirects the voice information to another preset when the prescribed
preset is searched.
In the AWE MIDI player, this function is used to play XG midi files.
The XG midi format defines its specific presets, and some of them are
incompatible with GS/GM presets.
This can be solved by making virtual presets mapping to the
corresponding GS presets with different preset/bank numbers.
<p>

To load a preset map, use the operation AWE_MAP_PRESET, and the following
another patch record as its body.
<pre>
typedef struct awe_voice_map {
	int map_bank, map_instr, map_key;	/* key = -1 means all keys */
	int src_bank, src_instr, src_key;
} awe_voice_map;
</pre>
The map_bank, map_instr and map_key define the destination bank, preset
and key numbers, respectively.
The latter, src_bank, src_instr and src_key define the source preset as well.
If key number holds a value -1, it's regarded as searching all keys
in the given preset.
<p>

<h3>3.1.6. Replace a sample data</h3>

This is a new function added in the ver.0.4 driver.
It simply replaces the sample wave data with the new one.
This function is useful to switch the wave sample data
during playing another samples.
<p>

The patch record is as same as in the sample data record (3.1.2) except
the operation id <code>AWE_REPLACE_DATA</code> and the optional argument
(<code>optarg</code>).
The optional argument defines the number of channels to be used for
transfer the data.
More channels can transfer more faster the sample data, though,
of course, the available voices are restricted during transfer.
<p>

Note that the sample wave size must be equal with the replaced older data.
Otherwise, the patch will be rejected.
<p>

<h2>3.2. Unload samples</h2>

The patch data can be unloaded by writing a patch with the operation id
<code>AWE_UNLOAD_PATCH</code>.
If this operation is accepted, the driver removes
the voice informations and samples which were sent at last.
Note that no "open" operation is required for unloading.
<p>

To unload the "unlocked" samples, use <code>AWE_REMOVE_LAST_SAMPLES</code>
macro.
<pre>
AWE_REMOVE_LAST_SAMPLES(seqfd, device);
</pre>
This macro uses ioctl, the file descriptor of the sequencer device is required
as an argument.
Since the ioctl is employed, the operation is done immediately
without buffered.
<p>


<h2>3.3. Send user-defined modes</h2>

AWE driver ver.0.4.1 has a function to accept the new chorus and reverb
parameters as user-defined modes.
<p>

<h3>3.3.1. Load user-defined chorus mode</h3>

<h3>3.3.2. Load user-defined reverb mode</h3>

<h2>3.4. GUS compatible patches</h2>
From ver.0.2.0, awedrv can receive GUS style patch records.
The GUS patch structure is defined in <code>soundcard.h</code>.
Unlikely to AWE patch, one sample is associated with one voice information
in GUS patch.
<pre>
struct patch_info {
	unsigned short key;		/* Use GUS_PATCH here */
	short device_no;	/* Synthesizer number */
	short instr_no;		/* Midi pgm# */
	unsigned int mode;
	int len;	/* Size of the wave data in bytes */
	int loop_start, loop_end; /* Byte offsets from the beginning */
	unsigned int base_freq;
	unsigned int base_note;
	unsigned int high_note;
	unsigned int low_note;
	int panning;	/* 0 to 15? */
	int detuning;
	unsigned char	env_rate[ 6 ];	 /* GUS HW ramping rate */
	unsigned char	env_offset[ 6 ]; /* 255 == 100% */
	unsigned char	tremolo_sweep;
	unsigned char	tremolo_rate;
	unsigned char	tremolo_depth;
	unsigned char	vibrato_sweep;
	unsigned char	vibrato_rate;
	unsigned char	vibrato_depth;
	int		scale_frequency;
	unsigned int	scale_factor;		/* from 0 to 2048 or 0 to 2 */
        int		volume;
	int		fractions;
        int		spare[3];
	char data[1];	/* The waveform data starts here */
};
</pre>
<code>key</code> must be <code>GUS_PATCH</code> value,
and <code>device_no</code> is the device number of AWE driver.
<p>

<code>instr_no</code> defines the program number of this sample.
The bank number can be defined using the extended control
<code>AWE_SET_GUS_BANK</code> function before loading the samples.
As default, the bank is set to zero.
<p>

<code>mode</code> indicates the flags of this sample.
Backward looping, scaling and fractions are not implemented yet.

<code>len</code> has the length of the sample data in bytes order.
Note that AWE patch holds in words order for 16bit samples, but GUS patch
is always in bytes order.
Similarly, loop position by <code>loop_start</code> and <code>loop_end</code>
is in byte offset.
<p>

<code>base_freq</code>, </code>base_note</code>, <code>high_note</code>,
and <code>low_note</code> are converted in the driver to corresponding
key note and fine tunes.
<p>

<code>panning</code> parameter is passed as the initial position
of dry sounds.
<p>

The 6 points volume envelope, tremolo, and vibrato parameters 
are converted to the AWE32 specific values in the driver.
<p>

Other parameters, <code>detuning</code>,
<code>scale_frequency</code>, <code>scale_factor</code>,
<code>volume</code>, and <code>fractions</code> are ignored.
<p>

The sample data follows after this is converted according to
the flags specified automatically.
<p>

After setting these parameters and copying the sample data from data pointer,
load this patch data on the driver.
<pre>
SEQ_WRPATCH(device, patch, sizeof(patch) + <i>data byte size</i> - 1);
</pre>
<p>

<hr>
<p>

<h1>4. Playing a voice</h1>

<h2>4.1. Playing modes</h2>

The AWE driver has several playing modes depending on its usage.
One is the normal mode, and another is the channel mode.
The former mode is as same as in the other sound driver like GUS and FM.
Each preset is assigned to one voice number.
On the contrast, the latter mode is used to make easy to handle
MIDI operations.  Each voice number is regarded as a MIDI channel, and
the voice allocation is done automatically inside the driver.
<p>

More specifically, the driver has four playing modes:
indirect, direct, multi, and multi2 modes.
The first two modes behave as the normal playing mode, and the latter
two modes as the channel playing mode.
The indirect mode is a new type which was added from ver.0.4.1e.
It assigns the actual voice for each voice number at each time
it's played, while the direct mode fixes each voice per
the corresponding voice number.
The multi2 mode is an internal mode for /dev/sequencer2 control.
Normally, this mode is not used explicitly.
<p>

The merit of indirect mode is capability of multi layered preset,
and reduction of click noises.
Many SoundFont files define presets including multiple instruments,
instruments including multiple samples, and stereo sounds.
In such a case, two or more samples must be played at the same time.
Then, in the indirect mode, the driver assigns one or more voices
when a voice number is called,
and release the assigned voices when the note-off is called
to the corresponding voice number.
A released voice is left for a while until assgined as a new voice,
so that this also reduces a click noise occuring when the voice is terminated.
The multi and multi2 modes employ this same mechanism, too.
<p>

To change the current playing mode, call <code>AWE_CHANNEL_MODE</code> macro.
<pre>
AWE_SET_CHANNEL_MODE(device, mode);
</pre>
where <code>mode</code> is one of the following predefined modes,
<pre>
#define AWE_PLAY_INDIRECT	0	/* indirect voice mode (default) */
#define AWE_PLAY_MULTI		1	/* multi note voice mode */
#define AWE_PLAY_DIRECT		2	/* direct single voice mode */
#define AWE_PLAY_MULTI2		3	/* sequencer2 mode; used internally */
</pre>
Note that the playing mode is reset at each time
the device is closed to the indirect mode.
<p>

<h2>4.1. Selecting a program</h2>

The voice program is selected by <code>SEQ_SET_PROGRAM</code> macro.
<pre>
SEQ_SET_PROGRAM(device, voice, program);
</pre>
where <code>voice</code> is the voice or channel number depending on the
current playing mode.
In the normal playing mode,
the voice number usually has a value from 0 to 29.
<code>program</code> is the program number to be played.
AWE32 has 32 individual channels, but when playing samples on DRAM,
the last two channels cannot be used due to DRAM refresh.
Thus, in awedrv, only 30 channels are available.
<p>

In channel playing mode, <code>voice</code> becomes a MIDI channel number
(usually from 0 to 15).  The voices are allocated internally by the driver.
Likewise, in all other sequencer controls, <code>voice</code> becomes the
corresponding MIDI channel number.
<p>

The drum voices are assigned to individual programs with
(<i>key number</i> + 128) by traditional reason.
The awedrv itself has a capability to deal with the drumset as one program.
In such a case, users must specify the preset number as the drumset number
and the fixed bank number 128.
You can also set the drum channels by extension control
<code>AWE_DRUM_CHANNELS</code> with a bit-blt parameter, calculated by
(1 << <i>drum number</i>), where <i>drum number</i> starts from 0.
In these channels, the voices are assumed as a drum set.
<pre>
AWE_DRUM_CHANNELS(device, channels);
</pre>
As default, only channel 10 is assumed as a drum channel,
then the <code>channels</code> value is 0x200.
Some MIDI files use also the channel 16 as a drum.
In such a case, <code>channels</code> becomes 0x8200.
<p>

The awedrv has a bank selection mechanism.
The bank selection can be done through MIDI control message #0,
so is realized by <code>SEQ_CONTROL</code> macro like
<pre>
SEQ_CONTROL(device, voice, CTL_BANK_SELECT, bank);
</pre>
where <code>bank</code> is the bank number of the sample.
For drum voices (set by <code>AWE_DRUM_CHANNELS</code>),
this number is ignored.
<p>

<h2>4.2. Setting various effects</h2>

<h3>4.2.1. Pitch control</h3>

To control the sample pitch or frequency,
the pitch wheel control is used ordinally.
The pitch change is calculated from two parameters,
pitch bender range and pitch bending degree.
The former, the pitch wheel, is controlled by
<code>SEQ_BENDER</code> macro, or obsolete <code>SEQ_PITCHBEND</code> macro.
<pre>
SEQ_BENDER(device, voice, value);
</pre>
Be careful that the parameter values are different between them.
<code>SEQ_BENDER</code> has a value from 0 to 16384,
and the center (no pitch shift) is 8192, just as same as in MIDI sequences.
On the other hand,
<code>SEQ_PITCHBEND</code> has a value from -8192 to 8192,
and the center is 0.
In both cases, the smaller than the center means lower pitch shift,
and the larger means upper pitch shift, respectively.
For example, when the bender range (see below) is 200, a value of -4096
indicates one octave flat from the normal pitch.
<p>

The latter control, the bender range,
is done by <code>SEQ_BENDER_RANGE</code> macro.
This function defines the bender range in (octave * 100).
For example,
a value of 400 indicates that the maximum wheel change to be four octave shift
from the normal pitch.
The default value is 200.
<pre>
SEQ_BENDER_RANGE(device, voice, value);
</pre>
<p>

Both of these controls can be changed at real time during playing the sample.
<p>

<h3>4.2.2. Volume control</h3>

The volume of each voice can be controlled by
three parameters: main volume, expression volume, and velocity.
The total volume is calculated from the product of these three values
as (main_volume * expression * velocity).
While the last velocity parameters is specified at starting the sample,
the other two parameters are given usually before playing it
though they can be changed at real time during playing the sample.
<p>

The main volume is set
via <code>SEQ_CONTROL</code> with the proper control code
(<code>CTL_MAIN_VOLUE</code> and <code>CTRL_MAIN_VOLUME</code>),
or obsolete <code>SEQ_MAIN_VOLUME</code> macro.
<pre>
SEQ_CONTROL(device, voice, CTL_MAIN_VOLUME, value);
</pre>
The value for <code>SEQ_MAIN_VOLUME</code> is identical with MIDI value,
from 0 to 127.
When the playing mode is the normal mode,
the control <code>CTL_MAIN_VOLUME</code> has a value from 0 to 20806
(= 16383 * 127 / 100).
In the channel mode, it has the same value as MIDI, from 0 to 127.
The <code>CTRL_MAIN_VOLUME</code> always has the same value as MIDI.
<p>

The expression volume is set via
<code>SEQ_CONTROL</code> with the proper control code
(<code>CTL_EXPRESSION</code> and <code>CTRL_EXPRESSION</code>),
or obsolete <code>SEQ_EXPRESSION</code> macro.
<pre>
SEQ_CONTROL(device, voice, CTL_EXPRESSION, value);
</pre>
The value for <code>SEQ_EXPRESSION</code> is identical with MIDI value,
from 0 to 127.
Similarly, when the playing mode is the normal mode,
the control code<code>CTL_EXPRESSION</code> has a value from 0 to 16256
(= 127 * 128).
In the channel mode, it has the same value as MIDI, from 0 to 127.
The <code>CTRL_EXPRESSION</code> has the same value as MIDI,
from 0 to 127.
<p>

Additionally, the awedrv has a total volume attenuation parameter.
Users can change this initial attenuation using <code>AWE_INITIAL_ATTEN</code>
control (identical with <code>AWE_INITIAL_VOLUME</code>).
<pre>
AWE_INITIAL_ATTEN(device, atten);
</pre>
This value <code>atten</code> is the attenuation volume from full scale
in 0.375 dB order.  For example, a value of 10 means that
3.75 dB lower from full scale.
The initial value is 32, 12dB below from full scale.
<p>

In the driver ver.0.4, the initial attenuation can be calculated
as an additional attenuation from predefined "zero attenuation".
The zero attenuation can be given via <code>AWE_MISC_MODE</code> control as
<pre>
AWE_MISC_MODE(device, AWE_MD_ZERO_ATTEN, atten);
</pre>
Then, the attenuation is changed via <code>AWE_SET_ATTEN</code> control.
<pre>
AWE_SET_ATTEN(device, atten);
</pre>
The definition of attenuation level is as same as the above.
Note that <code>AWE_INITIAL_ATTEN</code> sets the absolute attenuation,
while <code>AWE_SET_ATTEN</code> sets the relative attenation from
zero level.
<p>

Also, the awedrv has an mixer control of Emu8000 chip.
To change the bass and treble volume, use <code>AWE_EQUALIZER</code> macro.
<pre>
AWE_EQUALIZER(device, bass, treble);
</pre>
where both <code>bass</code> and <code>treble</code> are the integer value
from 0 (-12dB) to 11 (+12dB).
<p>

<h3>4.2.3. Panning position</h3>

The panning position is also set via control command,
<code>SEQ_CONTROL</code> with the proper control code (<code>CTL_PAN</code>),
or obsolete <code>SEQ_PANNING</code> macro.
<pre>
SEQ_CONTROL(device, voice, CTL_PAN, value);
</pre>
The value for <code>SEQ_PANNING</code> is from -128(left) to 128(right),
and different from MIDI value
unlike volume controls above.
But the value of <code>CTL_PAN</code> is identical with MIDI value,
from 0(left) to 127(right).
<p>

The panning position can be changed during playing,
but may cause a small clicking noise due to restriction of
emu8000 chip.
This is suppressed by <code>AWE_REALTIME_PAN</code> control.
<pre>
AWE_REALTIME_PAN(device, 0);
</pre>
If the argument is zero, the panning position of the voices never changes
during played.
<p>

<h3>4.2.4. Chorus and reverb effects</h3>

The AWE32 has chorus and reverb effects for each voice.
In awedrv, these effects are controlled via <code>SEQ_CONTROL</code>
with two control commands,
<code>CTL_CHORUS_DEPTH</code> and <code>CTL_EXT_EFF_DEPTH</code>,
for chorus and reverb, respectively.
<pre>
SEQ_CONTROL(device, voice, CTL_CHORUS_DEPTH, value);
SEQ_CONTROL(device, voice, CTL_EXT_EFF_DEPTH, value);
</pre>
In both cases, the value range is from 0 to 127,
where 127 means 100% of output is send to the corresponding effect processor.
These values cannot be changed during playing the sample.
<p>

Also, AWE32 has eight modes for both chorus and reverb effects.
They can be changed by extended control by
<code>AWE_CHORUS_MODE</code> and <code>AWE_REVERB_MODE</code>, respectively.
<pre>
AWE_CHORUS_MODE(device, mode);
AWE_REVERB_MODE(device, mode);
</pre>
In both cases, the range of the parameter value is from 0 to 7.
The corresponding mode to each value is defined in <code>awe_voice.h</code>,
that is,
Chorus 1 - 4, Feedback, Flanger, Short Delay, and Short Delay 2 for chorus modes,
and
Room 1 - 3, Hall 1/2, Plate, Delay, Panning Delay for reverb modes.
See AWE32 FAQ by CreativeLabs for meaning of each mode.
<p>

<h3>4.2.5. Other effects</h3>

The awedrv has several extended controls
to write raw register values for emu8000 parameters.
Through this function, users can control any function of AWE32 sound effects,
although the parameter value itself is not generic.
<p>

The extended controls are passed through
<code>AWE_SEND_EFFECT</code> macro with
specified commands and values.
<pre>
AWE_SEND_EFFECT(device, voice, command, value);
</pre>
The commands are defined in <code>awe_voice.h</code>, that is,
<pre>
/* 0*/	AWE_FX_ENV1_DELAY,	/* WORD: ENVVAL */
/* 1*/	AWE_FX_ENV1_ATTACK,	/* BYTE: up ATKHLD */
/* 2*/	AWE_FX_ENV1_HOLD,	/* BYTE: lw ATKHLD */
/* 3*/	AWE_FX_ENV1_DECAY,	/* BYTE: lw DCYSUS */
/* 4*/	AWE_FX_ENV1_RELEASE,	/* BYTE: lw DCYSUS */
/* 5*/	AWE_FX_ENV1_SUSTAIN,	/* BYTE: up DCYSUS */
/* 6*/	AWE_FX_ENV1_PITCH,	/* BYTE: up PEFE */
/* 7*/	AWE_FX_ENV1_CUTOFF,	/* BYTE: lw PEFE */

/* 8*/	AWE_FX_ENV2_DELAY,	/* WORD: ENVVOL */
/* 9*/	AWE_FX_ENV2_ATTACK,	/* BYTE: up ATKHLDV */
/*10*/	AWE_FX_ENV2_HOLD,	/* BYTE: lw ATKHLDV */
/*11*/	AWE_FX_ENV2_DECAY,	/* BYTE: lw DCYSUSV */
/*12*/	AWE_FX_ENV2_RELEASE,	/* BYTE: lw DCYSUSV */
/*13*/	AWE_FX_ENV2_SUSTAIN,	/* BYTE: up DCYSUSV */
	
/*14*/	AWE_FX_LFO1_DELAY,	/* WORD: LFO1VAL */
/*15*/	AWE_FX_LFO1_FREQ,	/* BYTE: lo TREMFRQ */
/*16*/	AWE_FX_LFO1_VOLUME,	/* BYTE: up TREMFRQ */
/*17*/	AWE_FX_LFO1_PITCH,	/* BYTE: up FMMOD */
/*18*/	AWE_FX_LFO1_CUTOFF,	/* BYTE: lo FMMOD */

/*19*/	AWE_FX_LFO2_DELAY,	/* WORD: LFO2VAL */
/*20*/	AWE_FX_LFO2_FREQ,	/* BYTE: lo FM2FRQ2 */
/*21*/	AWE_FX_LFO2_PITCH,	/* BYTE: up FM2FRQ2 */

/*22*/	AWE_FX_INIT_PITCH,	/* SHORT: pitch offset */
/*23*/	AWE_FX_CHORUS,		/* BYTE: chorus effects send (0-255) */
/*24*/	AWE_FX_REVERB,		/* BYTE: reverb effects send (0-255) */
/*25*/	AWE_FX_CUTOFF,		/* BYTE: up IFATN */
/*26*/	AWE_FX_FILTERQ,		/* BYTE: up CCCA */

/*27*/	AWE_FX_SAMPLE_START,	/* SHORT: offset */
/*28*/	AWE_FX_LOOP_START,	/* SHORT: offset */
/*29*/	AWE_FX_LOOP_END,	/* SHORT: offset */
/*30*/	AWE_FX_COARSE_SAMPLE_START,	/* SHORT: upper word offset */
/*31*/	AWE_FX_COARSE_LOOP_START,	/* SHORT: upper word offset */
/*32*/	AWE_FX_COARSE_LOOP_END,		/* SHORT: upper word offset */
/*33*/	AWE_FX_ATTEN,		/* BYTE: lo IFATN */
</pre>
The commands 0 - 7 define parameters of the modulation envelope,
8 - 13 of the volume envelope,
14 - 18 of LFO1,
19 - 21 of LFO2,
22 - 26 of other effect parameters for total voice,
and the later provides sample start position, and loop offset.
See ADIP for the parameter values of envelopes and LFO's.
<p>

<code>AWE_ADD_EFFECT</code> is used to adjust the effect from
predefined value in the voice patch data.
The relative value is given as an argument,
while the absolute value is given in <code>AWE_SEND_EFFECT</code> control.
<pre>
AWE_ADD_EFFECT(device, voice, command, value);
</pre>
<p>

On the channel mode, these effects are kept
unless <code>AWE_UNSET_EFFECT</code> macro is used.
<pre>
AWE_UNSET_EFFECT(device, voice, layer, command);
</pre>
On the normal mode, the effects are always cleared after the voice is off.
To suppress this, set <code>AWE_MD_KEEP_EFFECT</code> by
<code>AWE_MISC_MODE</code> control.
<pre>
AWE_MISC_MODE(device, AWE_MD_KEEP_EFFECT, 1);
</pre>
<p>

Also, on the channel mode, each instrument "layer" can be controlled via
<code>AWE_SEND_LAYER_EFFECT</code> and <code>AWE_ADD_LAYER_EFFECT</code>
macros.
It affects the effects only on one layer (= one voice)
specified in the argument.
<pre>
AWE_SEND_EFFECT_LAYER(device, voice, layer, command, value);
</pre>
<p>

GUS compatible extended controls are partly implemented.
<code>GUS_VOICE_POS</code> is interpreted inside as an extension control
27(<code>AWE_FX_SAMPLE_START</code>) and
30(<code>AWE_FX_COARSE_SAMPLE_START</code>).
<p>

<h2>4.3. Starting a note</h2>

There are two ways to start a voice.
The standard method is to call <code>SEQ_START_NOTE</code> macro.
<pre>
SEQ_START_NOTE(device, voice, note, velocity);
</pre>
where <code>note</code> and <code>velocity</code> are the MIDI key and velocity
to be played, respectively.
A sample including the specified note in its key range
is searched from all samples with given bank and program numbers.
Then, the volume and pitch parameters are computed here
from specified note and velocity.
If this sample is an exclusive voice like drum hi-hat sounds,
turn off other voices with the same exclusive key, that is
the other hi-hat sounds which is being played.
After that, start this voice.
<p>

In the normal playing mode,
the note 255 has a special meaning.
When this function is called with the note 255,
only volume is changed according its velocity,
and never affects the envelope change, and so on.
This can be used for dynamic volume control
without using other <code>SEQ_CONTROL</code> functions.
Note that this feature is ignored in the channel playing mode.
<p>

If the velocity is specified as zero, then one channel is allocated,
but the sound is not started.  It starts when volume change control
is received later.
<p>

The another way for start is to call a GUS specific control
<pre>
GUS_VOICEON(device, voice, mode);
</pre>
where <code>mode</code> is a voice mode, but ignored in awedrv.
This simply starts a sound on the channel, so voice parameters
like program, pitch and volume must be set before calling this function.
<p>

<hr>
<p>

<h1>5. Modulating a voice</h1>

<h2>5.1. Changing volume</h2>

Many methods are provided to change the volume of the sample.
One is to use <code>SEQ_KEY_PRESSURE</code> macro,
or <code>AWE_KEY_PRESSURE</code> macro, depending on its playing mode.
In the channel playing mode, the former macro
<code>SEQ_KEY_PRESSURE</code> is ignored
due to compatibility problems.
Thus, in the channel mode,
use the latter <code>AWE_KEY_PRESSURE</code> macro instead.
The parameter value is as same as MIDI pressure value, from 0 to 127.
<pre>
AWE_KEY_PRESSURE(device, voice, note, velocity);
</pre>
<p>

The second way is updating main or expression volume on each channel
by <code>SEQ_CONTROL</code> or other macros (see 4.2.2).
Also, using <code>SEQ_START_NOTE</code> with a special note 255 is
available for changing volume as explained above.
<p>

<h2>5.2. Changing pitch</h2>

You can change pitch of the sound by using the pitch wheel,
or by <code>AWE_SEND_EFFECT</code> with
<code>AWE_FX_INIT_PITCH</code> command
(see 4.2.1).
<p>

<h2>5.3. Changing panning position</h2>

The panning position is able to be changed at real time,
but it may cause a noise as explained above (see 4.2.3).
<p>

<h2>5.4. Changing chorus and reverb</h2>

The chorus and reverb effects can NOT be changed at real time.
However, the chorus and reverb modes are possible to be changed.
<p>

<h2>5.5. Changing other effects</h2>

The LFO1 depth can be changed via <code>AWE_CHN_PRESSURE</code> and
<code>CTL_MODWHEEL</code> MIDI control.
The former affets all the voices on the channel, while the latter affects
only one voice (in the channel mode).
<pre>
AWE_CHN_PRESSURE(device, channel, value);
SEQ_CONTROL(device, voice, CTL_MODWHEEL, value);
</pre>
The value is MIDI value from 0 to 127.
<p>

The LFO parameters (frequency, volume, pitch shift, and cutoff shift), and
LFO2 parameters (frequency, and pitch shift)
can be changed at real time via <code>AWE_SEND_EFFECT</code> control.
Also, total cutoff frequency can be changed.
The values are passed through the extended controls (see 4.2.5).
<p>

<hr>
<p>

<h1>6. Timer control</h1>

The awedrv itself doesn't provide any timer control functions.
Use the standard timer macros, <code>SEQ_START_TIMER</code>,
<code>SEQ_WAIT_TIME</code> or <code>SEQ_DELTA_TIME</code>,
and <code>SEQ_STOP_TIMER</code>.
<p>

<hr>
<p>

<h1>7. Ending a voice</h1>

To end a sound, call <code>SEQ_STOP_NOTE</code> macro.
This releases the sound from the sustain level to silence
according to the volume envelope.
The note and velocity parameters are ignored.
<pre>
SEQ_STOP_NOTE(device, voice, note, velocity);
</pre>
<p>

Or, you can terminate the voice completely by extended control,
<code>AWE_TERMINATE_CHANNEL</code>.
This stops the sound without any releasing echo.
<pre>
AWE_TERMINATE_CHANNEL(device, voice);
</pre>
To terminate all voices, the extended control
<code>AWE_TERMINATE_ALL</code> is available.
<pre>
AWE_TERMINATE_ALL(device);
</pre>
To turn off the all channels similary as SEQ_STOP_NOTE
(with sustain effects),
use <code>AWE_NOTEOFF_ALL</code>.
<pre>
AWE_RELEASE_ALL(device);
</pre>
Also, to force to turn off the all channels without sustain effects,
use <code>AWE_NOTEOFF_ALL</code>.
<pre>
AWE_NOTEOFF_ALL(device);
</pre>
<p>

<hr>
<p>

<h1>8. Other features</h1>

<h2>8.1. Debug options</h2>
The debug message is toggled on/off by the extended control
<code>AWE_DEBUG_MODE</code>.
<pre>
AWE_DEBUG_MODE(device, mode);
</pre>
The value zero means to turn off debugging messages,
and values larger then zero means to output debugging messages
on syslog, usually <code>/var/adm/syslog</code> or </code>/var/adm/message</code>
(depending on the setting of <code>/etc/syslog.conf</code>).
<p>

<h2>8.2. Initialize Emu8000 chip</h2>
The emu8000 chip can be initialized explicitly by the extended control
<code>AWE_INITIALIZE_CHIP</code>.
This only re-initializes the AWE32, and doesn't affect other driver-internal
parameters or effects.
<pre>
AWE_INITIALIZE_CHIP(seqfd, device);
</pre>
This function uses ioctl, so the file descriptor of sequencer device
is required.
<p>

<h2>8.3. Set miscellaneous operation modes</h2>
Many operation modes can be set via <code>AWE_MISC_MODE</code> control.
<pre>
AWE_MISC_MODE(device, type, value);
</pre>
See <code>awe_voice.h</code> for each definition.
<p>

<p><hr>
Takashi Iwai<br>
<a href=mailto:iwai@dragon.mm.t.u-tokyo.ac.jp>
<i>iwai@dragon.mm.t.u-tokyo.ac.jp</i></a><br>
<a href=http://bahamut.mm.t.u-tokyo.ac.jp/~iwai>
<i>http://bahamut.mm.t.u-tokyo.ac.jp/~iwai</i></a>

</body>