| 1 |
<!-- X-URL: http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html --> |
| 2 |
<BASE HREF="http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html"> |
| 3 |
|
| 4 |
<title>AWEDRV PROGRAMMING NOTES</title> |
| 5 |
<body> |
| 6 |
|
| 7 |
<center> |
| 8 |
<hr> |
| 9 |
<h1>AWEDRV PROGRAMMING NOTES</h1><p> |
| 10 |
ver.1.07<p> |
| 11 |
Takashi Iwai |
| 12 |
(<a href=mailto:[email protected]> |
| 13 |
<i>[email protected]</i></a>) |
| 14 |
</center> |
| 15 |
<p> |
| 16 |
|
| 17 |
Original version: |
| 18 |
<a href=http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html> |
| 19 |
<i>http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/awedrv/awedrv-prog.html</i></a> |
| 20 |
<p> |
| 21 |
|
| 22 |
<hr> |
| 23 |
<p> |
| 24 |
|
| 25 |
<h1>0. Preface</h1> |
| 26 |
|
| 27 |
This document describes the basic methods to access and control the AWE32 |
| 28 |
sound driver (ver.0.4.1) by Takashi Iwai. |
| 29 |
The AWE32 sound driver provides full capability of Emu8000 chip |
| 30 |
in the AWE32/SB32 sound card. |
| 31 |
Please refer to AWE32 Developer's Information Package (ADIP) |
| 32 |
distributed by CreativeLabs for details about AWE32. |
| 33 |
<p> |
| 34 |
|
| 35 |
<h1>1. Preparation of a message buffer</h1> |
| 36 |
|
| 37 |
Most of macros employ a certain write buffer to access to the sound driver. |
| 38 |
At beginning, this buffer must be defined. |
| 39 |
The method to define, or declare this buffer is prepared in |
| 40 |
<code>soundcard.h</code>. |
| 41 |
<ol> |
| 42 |
<li> Define a buffer for enough sizes (for example 2048 bytes) |
| 43 |
<pre> |
| 44 |
SEQ_DEFINEBUF(2048); |
| 45 |
</pre> |
| 46 |
|
| 47 |
<li> Define the file descriptor for <code>/dev/sequencer</code>. |
| 48 |
<pre> |
| 49 |
int seqfd; |
| 50 |
</pre> |
| 51 |
|
| 52 |
<li> Define <code>seqbuf_dump</code> function. |
| 53 |
<pre> |
| 54 |
void seqbuf_dump() |
| 55 |
{ |
| 56 |
if (_seqbufptr) |
| 57 |
if (write(seqfd, _seqbuf, _seqbufptr) == -1) { |
| 58 |
perror("write /dev/sequencer"); |
| 59 |
exit(-1); |
| 60 |
} |
| 61 |
_seqbufptr = 0; |
| 62 |
} |
| 63 |
</pre> |
| 64 |
</ol> |
| 65 |
<p> |
| 66 |
|
| 67 |
Most of <code>SEQ_*</code> macros write the data packet on this buffer. |
| 68 |
The buffer is occaionally flushed when it's almost filled. |
| 69 |
To force to send data to the driver, call <code>seqbuf_dump</code> |
| 70 |
(or identically <code>SEQ_DUMPBUF</code>) explicitly. |
| 71 |
<p> |
| 72 |
|
| 73 |
<hr> |
| 74 |
<p> |
| 75 |
|
| 76 |
<h1>2. Opening a sound device</h1> |
| 77 |
|
| 78 |
Then, open the sound driver device <code>/dev/sequencer</code>, |
| 79 |
and find out the AWE32 device number from synthesizer devices in it. |
| 80 |
Both the file descriptor and the device number must be specified |
| 81 |
for accessing to AWE32 driver later. |
| 82 |
Also, you should know other information of AWE32 driver, for example, |
| 83 |
allowed voices, etc from <code>synth_info</code> structure. |
| 84 |
|
| 85 |
<pre> |
| 86 |
struct synth_info card_info; |
| 87 |
int device; |
| 88 |
|
| 89 |
void seq_init() |
| 90 |
{ |
| 91 |
int nrsynths; |
| 92 |
|
| 93 |
if ((seqfd = open("/dev/sequencer", O_WRONLY, 0)) < 0) { |
| 94 |
perror("open /dev/sequencer"); |
| 95 |
exit(-1); |
| 96 |
} |
| 97 |
|
| 98 |
if (ioctl(seqfd, SNDCTL_SEQ_NRSYNTHS, &nrsynths) == -1) { |
| 99 |
perror("there is no soundcard"); |
| 100 |
exit(-1); |
| 101 |
} |
| 102 |
device = -1; |
| 103 |
for (i = 0; i < nrsynths; i++) { |
| 104 |
card_info.device = i; |
| 105 |
if (ioctl(seqfd, SNDCTL_SYNTH_INFO, &card_info) == -1) { |
| 106 |
perror("cannot get info on soundcard"); |
| 107 |
exit(-1); |
| 108 |
} |
| 109 |
if (card_info.synth_type == SYNTH_TYPE_SAMPLE |
| 110 |
&& card_info.synth_subtype == SAMPLE_TYPE_AWE32) { |
| 111 |
device = i; |
| 112 |
break; |
| 113 |
} |
| 114 |
} |
| 115 |
|
| 116 |
if (device < 0) { |
| 117 |
perror("No AWE synth device is found"); |
| 118 |
exit(-1); |
| 119 |
} |
| 120 |
} |
| 121 |
</pre> |
| 122 |
<p> |
| 123 |
|
| 124 |
<hr> |
| 125 |
<p> |
| 126 |
|
| 127 |
<h1>3. Loading a sample</h1> |
| 128 |
|
| 129 |
The awedrv has different two ways of sample loading. |
| 130 |
One uses its own format, and another is the GUS compatible format. |
| 131 |
In any cases, the patch data is loaded by <code>SEQ_WRPATCH</code> macro. |
| 132 |
<pre> |
| 133 |
SEQ_WRPATCH(patch ptr, patchlen); |
| 134 |
</pre> |
| 135 |
where <code>patch</code> is the pointer to the patch data, |
| 136 |
and <code>patchlen</code> is the total length of the patch data. |
| 137 |
<p> |
| 138 |
|
| 139 |
<h2>3.1. AWE32 specific patches</h2> |
| 140 |
|
| 141 |
Many of SoundFont files are designed to share the sample data |
| 142 |
with different envelopes, or other effect parameters. |
| 143 |
Then, awedrv accepts two separate data: the sample data, and |
| 144 |
the voice information data. |
| 145 |
The former contains the sample offsets and sizes, |
| 146 |
loop position, type of sample data, a check sum value for validating, |
| 147 |
and the sample data itself. |
| 148 |
The latter contains the basic information to play a sample, |
| 149 |
for example, root key note, acceptable MIDI key and velocity ranges, |
| 150 |
envelopes, LFO's and cutoff parameters, and so on. |
| 151 |
All the AWE patch structures are defined in <code>awe_voice.h</code>. |
| 152 |
<p> |
| 153 |
|
| 154 |
All the patch data has the same 16 bytes header structure at the first block, |
| 155 |
defined as <code>awe_patch_info</code>: |
| 156 |
<pre> |
| 157 |
typedef struct awe_patch_info { |
| 158 |
short key; /* use AWE_PATCH here */ |
| 159 |
short device_no; /* synthesizer number */ |
| 160 |
unsigned short sf_id; /* file id */ |
| 161 |
short optarg; /* optional argument */ |
| 162 |
long len; /* data length (without this header) */ |
| 163 |
short type; /* patch operation type */ |
| 164 |
short reserved; /* word alignment data */ |
| 165 |
} awe_patch_info; |
| 166 |
</pre> |
| 167 |
where <code>key</code> must be <code>AWE_PATCH</code> value, |
| 168 |
and <code>device_no</code> is the above device number of AWE driver. |
| 169 |
<code>sf_id</code> is ignored in the current version. |
| 170 |
<code>sf_version</code> is the optional argument and depends on its |
| 171 |
operation type. |
| 172 |
<code>len</code> has the length of the following data |
| 173 |
(not including this patch header itself). |
| 174 |
<code>type</code> specifies the operation type of this patch data. |
| 175 |
The patch data follows after this header depending its operation type. |
| 176 |
<p> |
| 177 |
|
| 178 |
To load the soundfont data on the driver, the following sequences are applied: |
| 179 |
<ol> |
| 180 |
<li> Open AWE Patch |
| 181 |
<li> Load sample data |
| 182 |
<li> Load voice informations |
| 183 |
<li> Close AWE Patch |
| 184 |
</ol> |
| 185 |
The sections below describe each operation. |
| 186 |
<p> |
| 187 |
|
| 188 |
<h3>3.1.1. Open AWE Patch</h3> |
| 189 |
|
| 190 |
This operation is necessary before loading any patch data (sample or |
| 191 |
voice info). |
| 192 |
If loading operations are called without opening the patch, |
| 193 |
awedrv creates a patch information automatically as if it was opened |
| 194 |
via this operation. |
| 195 |
So, in this meaning, the "open" operation is not necessarilly required, |
| 196 |
but it's recommended to call this explicitly. |
| 197 |
<p> |
| 198 |
|
| 199 |
To open a patch, write a patch data including a header with the operation id |
| 200 |
<code>AWE_OPEN_PATCH</code> and <code>awe_open_parm</code> structure data |
| 201 |
following after the header, |
| 202 |
<pre> |
| 203 |
typedef struct _awe_open_parm { |
| 204 |
unsigned short type; /* sample type */ |
| 205 |
short reserved; |
| 206 |
char name[AWE_PATCH_NAME_LEN]; |
| 207 |
} awe_open_parm; |
| 208 |
</pre> |
| 209 |
where <code>type</code> specifies the sample type, |
| 210 |
and <code>name</code> stores its name. |
| 211 |
The sample type holds an enumurated value from 0 to 6 indicating |
| 212 |
the type of patch data, and a bit flag 0x100 indicating that the sample is |
| 213 |
"locked". |
| 214 |
The locked samples will not be cleared even after AWE_REMOVE_LAST_SAMPLES |
| 215 |
operation. |
| 216 |
This means that the locked samples always remain unless all samples are |
| 217 |
cleared by SEQ_RESET_SAMPLES via ioctl. |
| 218 |
The sample name is a zero terminated string, |
| 219 |
and not referred from anywhere so far in the current version. |
| 220 |
<p> |
| 221 |
|
| 222 |
The data length of <code>awe_patch_info</code> is equal to |
| 223 |
<code>AWE_OPEN_PARM_SIZE</code>. |
| 224 |
Then, write the patch data containing both <code>awe_patch_info</code> |
| 225 |
and <code>awe_open_parm</code> as, |
| 226 |
<pre> |
| 227 |
SEQ_WRPATCH(patch, sizeof(*patch) + patch->len); |
| 228 |
</pre> |
| 229 |
<p> |
| 230 |
|
| 231 |
<h3>3.1.2. Close AWE Patch</h3> |
| 232 |
|
| 233 |
This operation closes the patch currently opened by AWE_OPEN_PATCH |
| 234 |
operation. |
| 235 |
This is useful to exchange to another soundfont file for loading at next. |
| 236 |
<p> |
| 237 |
|
| 238 |
To close the patch, write a patch data containing only the patch header |
| 239 |
with the operation id <code>AWE_CLOSE_PATCH</code>. |
| 240 |
No optional argument nor the data structure is required. |
| 241 |
The data length of <code>awe_patch_info</code> is then equal to zero. |
| 242 |
<p> |
| 243 |
|
| 244 |
<h3>3.1.3. AWE Sample Information</h3> |
| 245 |
|
| 246 |
The sample information is a variable length data which consists of |
| 247 |
a header containing |
| 248 |
the sample offset informations and sample wave data. |
| 249 |
The sample header is 32 bytes header which follows after the patch header. |
| 250 |
<pre> |
| 251 |
typedef struct awe_sample_info { |
| 252 |
unsigned short sf_id; /* file id */ |
| 253 |
unsigned short sample; /* sample id */ |
| 254 |
long start, end; /* start & end offset */ |
| 255 |
long loopstart, loopend; /* loop start & end offset */ |
| 256 |
long size; /* size (0 = ROM) */ |
| 257 |
short checksum_flag; /* ignored */ |
| 258 |
unsigned short mode_flags; /* mode flags */ |
| 259 |
unsigned long checksum; /* ignored */ |
| 260 |
} awe_sample_info; |
| 261 |
</pre> |
| 262 |
where <code>sf_id</code> is the file id used internally and normally zero, |
| 263 |
<code>sample</code> is the sample id of this sample which is referred by |
| 264 |
voice information records. |
| 265 |
It's usually identical with the sampleId in soundfont files. |
| 266 |
<code>start</code> and <code>end</code> denote the sample start and end |
| 267 |
offset positions, |
| 268 |
<code>loopstart</code> and <code>loopend</code> denote the loop start |
| 269 |
and end positions, |
| 270 |
and <code>size</code> is the data length. |
| 271 |
The offsets and size are word length if the data is 16bit. |
| 272 |
Otherwise for 8bit data, they are defined as byte size. |
| 273 |
The zero <code>size</code> parameter means a ROM sample starting |
| 274 |
from <code>start</code> offset. |
| 275 |
When <code>size</code> has larger than zero, the sample is loaded on |
| 276 |
DRAM, and the offsets will be shifted. |
| 277 |
<code>checksum_flag</code> and <code>checksum</code> was obsolete |
| 278 |
parameters, and no more supported in ver.0.4.1. |
| 279 |
<p> |
| 280 |
|
| 281 |
<code>mode_flags</code> is 16bit flags of the sample data. |
| 282 |
<pre> |
| 283 |
#define AWE_SAMPLE_8BITS 1 /* wave data is 8bits */ |
| 284 |
#define AWE_SAMPLE_UNSIGNED 2 /* wave data is unsigned */ |
| 285 |
#define AWE_SAMPLE_NO_BLANK 4 /* no blank loop is attached */ |
| 286 |
#define AWE_SAMPLE_SINGLESHOT 8 /* single-shot w/o loop */ |
| 287 |
#define AWE_SAMPLE_BIDIR_LOOP 16 /* bidirectional looping */ |
| 288 |
#define AWE_SAMPLE_STEREO_LEFT 32 /* stereo left sound */ |
| 289 |
#define AWE_SAMPLE_STEREO_RIGHT 64 /* stereo right sound */ |
| 290 |
#define AWE_SAMPLE_REVERSE_LOOP 128 /* reverse loop */ |
| 291 |
</pre> |
| 292 |
The 8bit or unsigned data is converted inside the awedrv to 16bit signed data. |
| 293 |
When <code>AWE_SAMPLE_NO_BLANK</code> is on, 48 words of blank loop is appended |
| 294 |
after the sample automatically. |
| 295 |
When <code>AWE_SAMPLE_SINGLESHOT</code> is on, the loop points are set on this blank loop. |
| 296 |
<code>AWE_SAMPLE_BIDIR_LOOP</code> indicates that the loop is bidirectional |
| 297 |
(pingpong), and the samples in this loop is extended as mirror image inside. |
| 298 |
<code>AWE_SAMPLE_REVERSE_LOOP</code> means the reverse loop. |
| 299 |
The loop sample is duplicated on mirror image inside the driver. |
| 300 |
Other <code>STEREO</code> flags show that the voice is a stereo sound. |
| 301 |
If the sample data doesn't contain any blank loop, <code>AWE_SAMPLE_NO_BLANK</code> flag should be set. |
| 302 |
Also, if the sample data is a single-shot, <code>AWE_SAMPLE_SINGLESHOT</code> flag should be set. |
| 303 |
Otherwise, you must add a blank loop after the sample, and direct the loop pointers on it by yourself. |
| 304 |
<p> |
| 305 |
|
| 306 |
The driver doesn't care about these stereo flags, but checks only |
| 307 |
the key note and velocity range. If two or more voices are suitable |
| 308 |
on the given note and velocity pair, all they should be played simultaneously. |
| 309 |
The multiple instruments are featured only in channel playing mode, but |
| 310 |
in normal mode, only the first matching voice is played. |
| 311 |
<p> |
| 312 |
|
| 313 |
To send a wave sample data, write a patch structure containing a patch header |
| 314 |
with the operation id <code>AWE_LOAD_DATA</code>, |
| 315 |
the sample header <code>awe_sample_info</code>, |
| 316 |
and the sample wave data if necessary. |
| 317 |
Thus, the <code>len</code> parameter of the first patch header becomes<br> |
| 318 |
(<code>AWE_SAMPLE_INFO_SIZE</code>) + <i>data byte size</i>).<br> |
| 319 |
<p> |
| 320 |
|
| 321 |
<h3>3.1.4. AWE Voice Information</h3> |
| 322 |
|
| 323 |
The voice information is also an variable length data record |
| 324 |
to specify the raw parameters of Emu8000 chip controls for each instrument. |
| 325 |
Multiple instruments can be defined as one voice information record |
| 326 |
if all of them are the same instrument with the same bank/preset pair. |
| 327 |
<p> |
| 328 |
|
| 329 |
The voice information has 4 bytes after the patch header, |
| 330 |
<pre> |
| 331 |
typedef struct _awe_voice_rec_hdr { |
| 332 |
unsigned char bank; /* midi bank number */ |
| 333 |
unsigned char instr; /* midi preset number */ |
| 334 |
char nvoices; /* number of voices */ |
| 335 |
char write_mode; /* write mode */ |
| 336 |
} awe_voice_rec_hdr; |
| 337 |
</pre> |
| 338 |
where <code>bank</code> and <code>instr</code> specify |
| 339 |
the bank and program number of this instrument, |
| 340 |
and <code>nvoices</code> denotes the number of voices (samples) |
| 341 |
used in this instrument. |
| 342 |
If any voices with the same bank and program number exist already, |
| 343 |
the new voices are prepended before the list of older voices. |
| 344 |
<code>nvoices</code> must be larger than zero. |
| 345 |
Thus, <code>len</code> in patch header has the value<br> |
| 346 |
(<code>AWE_VOICE_REC_SIZE</code> + |
| 347 |
<code>nvoices</code> * <code>AWE_VOICE_INFO_SIZE</code>).<br> |
| 348 |
<code>write_mode</code> specifies how the voice infos are stored on the driver. |
| 349 |
<pre> |
| 350 |
#define AWE_WR_APPEND 0 /* append anyway */ |
| 351 |
#define AWE_WR_EXCLUSIVE 1 /* skip if already exists */ |
| 352 |
#define AWE_WR_REPLACE 2 /* replace if already exists */ |
| 353 |
</pre> |
| 354 |
Normally, <code>AWE_WR_APPEND</code> is used to append each data. |
| 355 |
In usual situation, it doesn't matter which mode is selected. |
| 356 |
If a data with the same preset/bank pair already exists on the driver |
| 357 |
as a same patch, |
| 358 |
the operation may differ depending on its write mode. |
| 359 |
When <code>AWE_WR_EXCLUSIVE</code> is specified, the new data is skipped. |
| 360 |
When <code>AWE_WR_REPLACE</code> is specified, the old data is thrown and |
| 361 |
the new data replaces with the old one. |
| 362 |
Otherwise, the data is always appended, and the new one is used together |
| 363 |
with the old data, that is, both of them are reproduced as one sound. |
| 364 |
<p> |
| 365 |
|
| 366 |
After this 4bytes record, |
| 367 |
<code>nvoices</code> of 92bytes of voice information |
| 368 |
for each sample are appended. |
| 369 |
<pre> |
| 370 |
typedef struct _awe_voice_info { |
| 371 |
unsigned short sf_id; /* file id */ |
| 372 |
unsigned short sample; /* sample id */ |
| 373 |
long start, end; /* sample offset correction */ |
| 374 |
long loopstart, loopend; /* loop offset correction */ |
| 375 |
short rate_offset; /* sample rate pitch offset */ |
| 376 |
unsigned short mode; /* sample mode */ |
| 377 |
short root; /* midi root key */ |
| 378 |
short tune; /* pitch tuning (in cents) */ |
| 379 |
char low, high; /* key note range */ |
| 380 |
char vellow, velhigh; /* velocity range */ |
| 381 |
char fixkey, fixvel; /* fixed key and velocity */ |
| 382 |
char pan, fixpan; /* panning, fixed panning */ |
| 383 |
short exclusiveClass; /* exclusive class (0 = none) */ |
| 384 |
unsigned char amplitude; /* sample volume (127 max) */ |
| 385 |
unsigned char attenuation; /* attenuation (0.375dB) */ |
| 386 |
short scaleTuning; /* pitch scale tuning(%), normally 100 */ |
| 387 |
awe_voice_parm parm; /* voice envelope parameters */ |
| 388 |
short index; /* internal index (set by driver) */ |
| 389 |
} awe_voice_info; |
| 390 |
</pre> |
| 391 |
where <code>sf_id</code> is an internal file id and normally zero, |
| 392 |
<code>sample</code> is the referring sample id of this voice. |
| 393 |
<code>start</code>, <code>end</code>, <code>loopstart</code>, and |
| 394 |
<code>loopend</code> are the offset correction of this voices. |
| 395 |
For example, a value of <code>start</code> 30 means that |
| 396 |
this voice starts 30 points after the original start points. |
| 397 |
<p> |
| 398 |
|
| 399 |
<code>rate_offset</code> holds the pitch offset of this voice |
| 400 |
according to its sample rate. |
| 401 |
This value is an AWE specific logarithmic rate, |
| 402 |
that each 4096 is one octave shift. |
| 403 |
For example, a value of -2048 indicates the sample is played 6 semitones flat. |
| 404 |
The value can be calculated by the following equation. |
| 405 |
<pre> |
| 406 |
rate_offset = log(Hz / 44100) / log(2) * 4096 |
| 407 |
</pre> |
| 408 |
<p> |
| 409 |
|
| 410 |
<code>mode</code> is 16bit flags indicating the kind of this voice. |
| 411 |
<pre> |
| 412 |
#define AWE_MODE_ROMSOUND 0x8000 |
| 413 |
#define AWE_MODE_STEREO 1 |
| 414 |
#define AWE_MODE_LOOPING 2 |
| 415 |
#define AWE_MODE_NORELEASE 4 /* obsolete */ |
| 416 |
#define AWE_MODE_INIT_PARM 8 |
| 417 |
</pre> |
| 418 |
<code>AWE_MODE_STEREO</code> and <code>AWE_MODE_NORELEASE</code> |
| 419 |
are ignored in the current version. |
| 420 |
<code>AWE_MODE_INIT_PARM</code> means that <code>parm</code> members |
| 421 |
are initialized at loading automatically. |
| 422 |
<p> |
| 423 |
|
| 424 |
<code>root</code> and <code>tune</code> contain the root key note |
| 425 |
and fine tune of this voice. |
| 426 |
The key is supplied by MIDI key value, from 0 to 127, |
| 427 |
and fine tune is a cents order. |
| 428 |
A positive fine tune value indicates the sound is played at a higher pitch, |
| 429 |
and a negative value means a lower pitch. |
| 430 |
<p> |
| 431 |
|
| 432 |
<code>low</code> and <code>high</code> define |
| 433 |
the key note range of this voice. |
| 434 |
If the key is out of this range, the driver skips this voice, |
| 435 |
and searches the next voice from voice list. |
| 436 |
To accepts all keys, <code>low</code> be 0, and <code>high</code> 127. |
| 437 |
<p> |
| 438 |
|
| 439 |
Similarly, <code>vellow</code> and <code>velhigh</code> define |
| 440 |
the velocity range of this voice. |
| 441 |
As well as in key note range, |
| 442 |
the voice is accepted only when the velocity is within this range. |
| 443 |
<p> |
| 444 |
|
| 445 |
<code>fixkey</code>, and <code>fixvel</code> indicate |
| 446 |
the fixed key and velocity of this voice. |
| 447 |
If the value is not -1, the key or velocity is fixed on this value. |
| 448 |
<p> |
| 449 |
|
| 450 |
<code>pan</code> has a panning position of the "dry" sound, |
| 451 |
from 0(left) to 127(right), or -1 for not specified. |
| 452 |
<code>fixpan</code> also contains the fixed panning position. |
| 453 |
If valid <code>fixpan</code> is given, the panning position is fixed |
| 454 |
to that value. |
| 455 |
<p> |
| 456 |
|
| 457 |
<code>exclusiveClass</code> is the exclusive class of this voice. |
| 458 |
If the value is zero, no exclusive system activates. |
| 459 |
Otherwise, the voices with the sample exclusive class are turned off |
| 460 |
before playing a new voice with this class. |
| 461 |
This feature is used for some drum instruments like hi-hat. |
| 462 |
<p> |
| 463 |
|
| 464 |
<code>amplitude</code> and <code>attenuation</code> define |
| 465 |
the volume of this voice. |
| 466 |
<code>amplitude</code> is a linear volume from 0 to 127, |
| 467 |
and <code>amplitude</code> means the attenuation from full level |
| 468 |
in 0.375dB order. |
| 469 |
For example, a voice with <code>attenuation</code> 40 is reproduced |
| 470 |
15dB lower from full scale. |
| 471 |
<p> |
| 472 |
|
| 473 |
<code>scaleTuning</code> is a pitch scale tuning ratio, and normally is 100. |
| 474 |
<p> |
| 475 |
|
| 476 |
<code>index</code> is an internal sample index, and ignored at loading. |
| 477 |
<p> |
| 478 |
|
| 479 |
<code>parm</code> contains the modulation/volume envelopes, LFO's and other |
| 480 |
raw parameters of emu8000 chip. |
| 481 |
<pre> |
| 482 |
typedef struct _awe_voice_parm { |
| 483 |
unsigned short moddelay; /* modulation delay (ENVVAL) */ |
| 484 |
unsigned short modatkhld; /* modulation attack & hold time (ATKHLD) */ |
| 485 |
unsigned short moddcysus; /* modulation decay & sustain (DCYSUS) */ |
| 486 |
unsigned short modrelease; /* modulation release time (DCYSUS) */ |
| 487 |
short modkeyhold, modkeydecay; /* envelope change per key (not used) */ |
| 488 |
unsigned short voldelay; /* volume delay (ENVVOL) */ |
| 489 |
unsigned short volatkhld; /* volume attack & hold time (ATKHLDV) */ |
| 490 |
unsigned short voldcysus; /* volume decay & sustain (DCYSUSV) */ |
| 491 |
unsigned short volrelease; /* volume release time (DCYSUSV) */ |
| 492 |
short volkeyhold, volkeydecay; /* envelope change per key (not used) */ |
| 493 |
unsigned short lfo1delay; /* LFO1 delay (LFO1VAL) */ |
| 494 |
unsigned short lfo2delay; /* LFO2 delay (LFO2VAL) */ |
| 495 |
unsigned short pefe; /* modulation pitch & cutoff (PEFE) */ |
| 496 |
unsigned short fmmod; /* LFO1 pitch & cutoff (FMMOD) */ |
| 497 |
unsigned short tremfrq; /* LFO1 volume & freq (TREMFRQ) */ |
| 498 |
unsigned short fm2frq2; /* LFO2 pitch & freq (FM2FRQ2) */ |
| 499 |
unsigned char cutoff; /* initial cutoff (upper of IFATN) */ |
| 500 |
unsigned char filterQ; /* initial filter Q [0-15] (upper of CCCA) */ |
| 501 |
unsigned char chorus; /* chorus send */ |
| 502 |
unsigned char reverb; /* reverb send */ |
| 503 |
unsigned short reserved[4]; /* not used */ |
| 504 |
} awe_voice_parm; |
| 505 |
</pre> |
| 506 |
The values correspond to the register values of emu8000 described in |
| 507 |
AWE32 Developer's Information Package (ADIP) |
| 508 |
by CreativeLabs. |
| 509 |
This record can be initialized internally in the driver |
| 510 |
by setting <code>AWE_MODE_INIT_PARM</code> flag in voice_info record. |
| 511 |
<p> |
| 512 |
|
| 513 |
It would be useful to use a fixed size record if only one voice is defined |
| 514 |
in one record. |
| 515 |
<pre> |
| 516 |
typedef struct _awe_voice_rec_patch { |
| 517 |
awe_patch_info patch; |
| 518 |
awe_voice_rec_hdr hdr; |
| 519 |
awe_voice_info info; |
| 520 |
} awe_voice_rec_patch; |
| 521 |
</pre> |
| 522 |
<p> |
| 523 |
|
| 524 |
<h3>3.1.5. Load a preset map</h3> |
| 525 |
|
| 526 |
The preset map provides a virtual voice information for a preset. |
| 527 |
It redirects the voice information to another preset when the prescribed |
| 528 |
preset is searched. |
| 529 |
In the AWE MIDI player, this function is used to play XG midi files. |
| 530 |
The XG midi format defines its specific presets, and some of them are |
| 531 |
incompatible with GS/GM presets. |
| 532 |
This can be solved by making virtual presets mapping to the |
| 533 |
corresponding GS presets with different preset/bank numbers. |
| 534 |
<p> |
| 535 |
|
| 536 |
To load a preset map, use the operation AWE_MAP_PRESET, and the following |
| 537 |
another patch record as its body. |
| 538 |
<pre> |
| 539 |
typedef struct awe_voice_map { |
| 540 |
int map_bank, map_instr, map_key; /* key = -1 means all keys */ |
| 541 |
int src_bank, src_instr, src_key; |
| 542 |
} awe_voice_map; |
| 543 |
</pre> |
| 544 |
The map_bank, map_instr and map_key define the destination bank, preset |
| 545 |
and key numbers, respectively. |
| 546 |
The latter, src_bank, src_instr and src_key define the source preset as well. |
| 547 |
If key number holds a value -1, it's regarded as searching all keys |
| 548 |
in the given preset. |
| 549 |
<p> |
| 550 |
|
| 551 |
<h3>3.1.6. Replace a sample data</h3> |
| 552 |
|
| 553 |
This is a new function added in the ver.0.4 driver. |
| 554 |
It simply replaces the sample wave data with the new one. |
| 555 |
This function is useful to switch the wave sample data |
| 556 |
during playing another samples. |
| 557 |
<p> |
| 558 |
|
| 559 |
The patch record is as same as in the sample data record (3.1.2) except |
| 560 |
the operation id <code>AWE_REPLACE_DATA</code> and the optional argument |
| 561 |
(<code>optarg</code>). |
| 562 |
The optional argument defines the number of channels to be used for |
| 563 |
transfer the data. |
| 564 |
More channels can transfer more faster the sample data, though, |
| 565 |
of course, the available voices are restricted during transfer. |
| 566 |
<p> |
| 567 |
|
| 568 |
Note that the sample wave size must be equal with the replaced older data. |
| 569 |
Otherwise, the patch will be rejected. |
| 570 |
<p> |
| 571 |
|
| 572 |
<h2>3.2. Unload samples</h2> |
| 573 |
|
| 574 |
The patch data can be unloaded by writing a patch with the operation id |
| 575 |
<code>AWE_UNLOAD_PATCH</code>. |
| 576 |
If this operation is accepted, the driver removes |
| 577 |
the voice informations and samples which were sent at last. |
| 578 |
Note that no "open" operation is required for unloading. |
| 579 |
<p> |
| 580 |
|
| 581 |
To unload the "unlocked" samples, use <code>AWE_REMOVE_LAST_SAMPLES</code> |
| 582 |
macro. |
| 583 |
<pre> |
| 584 |
AWE_REMOVE_LAST_SAMPLES(seqfd, device); |
| 585 |
</pre> |
| 586 |
This macro uses ioctl, the file descriptor of the sequencer device is required |
| 587 |
as an argument. |
| 588 |
Since the ioctl is employed, the operation is done immediately |
| 589 |
without buffered. |
| 590 |
<p> |
| 591 |
|
| 592 |
|
| 593 |
<h2>3.3. Send user-defined modes</h2> |
| 594 |
|
| 595 |
AWE driver ver.0.4.1 has a function to accept the new chorus and reverb |
| 596 |
parameters as user-defined modes. |
| 597 |
<p> |
| 598 |
|
| 599 |
<h3>3.3.1. Load user-defined chorus mode</h3> |
| 600 |
|
| 601 |
<h3>3.3.2. Load user-defined reverb mode</h3> |
| 602 |
|
| 603 |
<h2>3.4. GUS compatible patches</h2> |
| 604 |
From ver.0.2.0, awedrv can receive GUS style patch records. |
| 605 |
The GUS patch structure is defined in <code>soundcard.h</code>. |
| 606 |
Unlikely to AWE patch, one sample is associated with one voice information |
| 607 |
in GUS patch. |
| 608 |
<pre> |
| 609 |
struct patch_info { |
| 610 |
unsigned short key; /* Use GUS_PATCH here */ |
| 611 |
short device_no; /* Synthesizer number */ |
| 612 |
short instr_no; /* Midi pgm# */ |
| 613 |
unsigned int mode; |
| 614 |
int len; /* Size of the wave data in bytes */ |
| 615 |
int loop_start, loop_end; /* Byte offsets from the beginning */ |
| 616 |
unsigned int base_freq; |
| 617 |
unsigned int base_note; |
| 618 |
unsigned int high_note; |
| 619 |
unsigned int low_note; |
| 620 |
int panning; /* 0 to 15? */ |
| 621 |
int detuning; |
| 622 |
unsigned char env_rate[ 6 ]; /* GUS HW ramping rate */ |
| 623 |
unsigned char env_offset[ 6 ]; /* 255 == 100% */ |
| 624 |
unsigned char tremolo_sweep; |
| 625 |
unsigned char tremolo_rate; |
| 626 |
unsigned char tremolo_depth; |
| 627 |
unsigned char vibrato_sweep; |
| 628 |
unsigned char vibrato_rate; |
| 629 |
unsigned char vibrato_depth; |
| 630 |
int scale_frequency; |
| 631 |
unsigned int scale_factor; /* from 0 to 2048 or 0 to 2 */ |
| 632 |
int volume; |
| 633 |
int fractions; |
| 634 |
int spare[3]; |
| 635 |
char data[1]; /* The waveform data starts here */ |
| 636 |
}; |
| 637 |
</pre> |
| 638 |
<code>key</code> must be <code>GUS_PATCH</code> value, |
| 639 |
and <code>device_no</code> is the device number of AWE driver. |
| 640 |
<p> |
| 641 |
|
| 642 |
<code>instr_no</code> defines the program number of this sample. |
| 643 |
The bank number can be defined using the extended control |
| 644 |
<code>AWE_SET_GUS_BANK</code> function before loading the samples. |
| 645 |
As default, the bank is set to zero. |
| 646 |
<p> |
| 647 |
|
| 648 |
<code>mode</code> indicates the flags of this sample. |
| 649 |
Backward looping, scaling and fractions are not implemented yet. |
| 650 |
|
| 651 |
<code>len</code> has the length of the sample data in bytes order. |
| 652 |
Note that AWE patch holds in words order for 16bit samples, but GUS patch |
| 653 |
is always in bytes order. |
| 654 |
Similarly, loop position by <code>loop_start</code> and <code>loop_end</code> |
| 655 |
is in byte offset. |
| 656 |
<p> |
| 657 |
|
| 658 |
<code>base_freq</code>, </code>base_note</code>, <code>high_note</code>, |
| 659 |
and <code>low_note</code> are converted in the driver to corresponding |
| 660 |
key note and fine tunes. |
| 661 |
<p> |
| 662 |
|
| 663 |
<code>panning</code> parameter is passed as the initial position |
| 664 |
of dry sounds. |
| 665 |
<p> |
| 666 |
|
| 667 |
The 6 points volume envelope, tremolo, and vibrato parameters |
| 668 |
are converted to the AWE32 specific values in the driver. |
| 669 |
<p> |
| 670 |
|
| 671 |
Other parameters, <code>detuning</code>, |
| 672 |
<code>scale_frequency</code>, <code>scale_factor</code>, |
| 673 |
<code>volume</code>, and <code>fractions</code> are ignored. |
| 674 |
<p> |
| 675 |
|
| 676 |
The sample data follows after this is converted according to |
| 677 |
the flags specified automatically. |
| 678 |
<p> |
| 679 |
|
| 680 |
After setting these parameters and copying the sample data from data pointer, |
| 681 |
load this patch data on the driver. |
| 682 |
<pre> |
| 683 |
SEQ_WRPATCH(device, patch, sizeof(patch) + <i>data byte size</i> - 1); |
| 684 |
</pre> |
| 685 |
<p> |
| 686 |
|
| 687 |
<hr> |
| 688 |
<p> |
| 689 |
|
| 690 |
<h1>4. Playing a voice</h1> |
| 691 |
|
| 692 |
<h2>4.1. Playing modes</h2> |
| 693 |
|
| 694 |
The AWE driver has several playing modes depending on its usage. |
| 695 |
One is the normal mode, and another is the channel mode. |
| 696 |
The former mode is as same as in the other sound driver like GUS and FM. |
| 697 |
Each preset is assigned to one voice number. |
| 698 |
On the contrast, the latter mode is used to make easy to handle |
| 699 |
MIDI operations. Each voice number is regarded as a MIDI channel, and |
| 700 |
the voice allocation is done automatically inside the driver. |
| 701 |
<p> |
| 702 |
|
| 703 |
More specifically, the driver has four playing modes: |
| 704 |
indirect, direct, multi, and multi2 modes. |
| 705 |
The first two modes behave as the normal playing mode, and the latter |
| 706 |
two modes as the channel playing mode. |
| 707 |
The indirect mode is a new type which was added from ver.0.4.1e. |
| 708 |
It assigns the actual voice for each voice number at each time |
| 709 |
it's played, while the direct mode fixes each voice per |
| 710 |
the corresponding voice number. |
| 711 |
The multi2 mode is an internal mode for /dev/sequencer2 control. |
| 712 |
Normally, this mode is not used explicitly. |
| 713 |
<p> |
| 714 |
|
| 715 |
The merit of indirect mode is capability of multi layered preset, |
| 716 |
and reduction of click noises. |
| 717 |
Many SoundFont files define presets including multiple instruments, |
| 718 |
instruments including multiple samples, and stereo sounds. |
| 719 |
In such a case, two or more samples must be played at the same time. |
| 720 |
Then, in the indirect mode, the driver assigns one or more voices |
| 721 |
when a voice number is called, |
| 722 |
and release the assigned voices when the note-off is called |
| 723 |
to the corresponding voice number. |
| 724 |
A released voice is left for a while until assgined as a new voice, |
| 725 |
so that this also reduces a click noise occuring when the voice is terminated. |
| 726 |
The multi and multi2 modes employ this same mechanism, too. |
| 727 |
<p> |
| 728 |
|
| 729 |
To change the current playing mode, call <code>AWE_CHANNEL_MODE</code> macro. |
| 730 |
<pre> |
| 731 |
AWE_SET_CHANNEL_MODE(device, mode); |
| 732 |
</pre> |
| 733 |
where <code>mode</code> is one of the following predefined modes, |
| 734 |
<pre> |
| 735 |
#define AWE_PLAY_INDIRECT 0 /* indirect voice mode (default) */ |
| 736 |
#define AWE_PLAY_MULTI 1 /* multi note voice mode */ |
| 737 |
#define AWE_PLAY_DIRECT 2 /* direct single voice mode */ |
| 738 |
#define AWE_PLAY_MULTI2 3 /* sequencer2 mode; used internally */ |
| 739 |
</pre> |
| 740 |
Note that the playing mode is reset at each time |
| 741 |
the device is closed to the indirect mode. |
| 742 |
<p> |
| 743 |
|
| 744 |
<h2>4.1. Selecting a program</h2> |
| 745 |
|
| 746 |
The voice program is selected by <code>SEQ_SET_PROGRAM</code> macro. |
| 747 |
<pre> |
| 748 |
SEQ_SET_PROGRAM(device, voice, program); |
| 749 |
</pre> |
| 750 |
where <code>voice</code> is the voice or channel number depending on the |
| 751 |
current playing mode. |
| 752 |
In the normal playing mode, |
| 753 |
the voice number usually has a value from 0 to 29. |
| 754 |
<code>program</code> is the program number to be played. |
| 755 |
AWE32 has 32 individual channels, but when playing samples on DRAM, |
| 756 |
the last two channels cannot be used due to DRAM refresh. |
| 757 |
Thus, in awedrv, only 30 channels are available. |
| 758 |
<p> |
| 759 |
|
| 760 |
In channel playing mode, <code>voice</code> becomes a MIDI channel number |
| 761 |
(usually from 0 to 15). The voices are allocated internally by the driver. |
| 762 |
Likewise, in all other sequencer controls, <code>voice</code> becomes the |
| 763 |
corresponding MIDI channel number. |
| 764 |
<p> |
| 765 |
|
| 766 |
The drum voices are assigned to individual programs with |
| 767 |
(<i>key number</i> + 128) by traditional reason. |
| 768 |
The awedrv itself has a capability to deal with the drumset as one program. |
| 769 |
In such a case, users must specify the preset number as the drumset number |
| 770 |
and the fixed bank number 128. |
| 771 |
You can also set the drum channels by extension control |
| 772 |
<code>AWE_DRUM_CHANNELS</code> with a bit-blt parameter, calculated by |
| 773 |
(1 << <i>drum number</i>), where <i>drum number</i> starts from 0. |
| 774 |
In these channels, the voices are assumed as a drum set. |
| 775 |
<pre> |
| 776 |
AWE_DRUM_CHANNELS(device, channels); |
| 777 |
</pre> |
| 778 |
As default, only channel 10 is assumed as a drum channel, |
| 779 |
then the <code>channels</code> value is 0x200. |
| 780 |
Some MIDI files use also the channel 16 as a drum. |
| 781 |
In such a case, <code>channels</code> becomes 0x8200. |
| 782 |
<p> |
| 783 |
|
| 784 |
The awedrv has a bank selection mechanism. |
| 785 |
The bank selection can be done through MIDI control message #0, |
| 786 |
so is realized by <code>SEQ_CONTROL</code> macro like |
| 787 |
<pre> |
| 788 |
SEQ_CONTROL(device, voice, CTL_BANK_SELECT, bank); |
| 789 |
</pre> |
| 790 |
where <code>bank</code> is the bank number of the sample. |
| 791 |
For drum voices (set by <code>AWE_DRUM_CHANNELS</code>), |
| 792 |
this number is ignored. |
| 793 |
<p> |
| 794 |
|
| 795 |
<h2>4.2. Setting various effects</h2> |
| 796 |
|
| 797 |
<h3>4.2.1. Pitch control</h3> |
| 798 |
|
| 799 |
To control the sample pitch or frequency, |
| 800 |
the pitch wheel control is used ordinally. |
| 801 |
The pitch change is calculated from two parameters, |
| 802 |
pitch bender range and pitch bending degree. |
| 803 |
The former, the pitch wheel, is controlled by |
| 804 |
<code>SEQ_BENDER</code> macro, or obsolete <code>SEQ_PITCHBEND</code> macro. |
| 805 |
<pre> |
| 806 |
SEQ_BENDER(device, voice, value); |
| 807 |
</pre> |
| 808 |
Be careful that the parameter values are different between them. |
| 809 |
<code>SEQ_BENDER</code> has a value from 0 to 16384, |
| 810 |
and the center (no pitch shift) is 8192, just as same as in MIDI sequences. |
| 811 |
On the other hand, |
| 812 |
<code>SEQ_PITCHBEND</code> has a value from -8192 to 8192, |
| 813 |
and the center is 0. |
| 814 |
In both cases, the smaller than the center means lower pitch shift, |
| 815 |
and the larger means upper pitch shift, respectively. |
| 816 |
For example, when the bender range (see below) is 200, a value of -4096 |
| 817 |
indicates one octave flat from the normal pitch. |
| 818 |
<p> |
| 819 |
|
| 820 |
The latter control, the bender range, |
| 821 |
is done by <code>SEQ_BENDER_RANGE</code> macro. |
| 822 |
This function defines the bender range in (octave * 100). |
| 823 |
For example, |
| 824 |
a value of 400 indicates that the maximum wheel change to be four octave shift |
| 825 |
from the normal pitch. |
| 826 |
The default value is 200. |
| 827 |
<pre> |
| 828 |
SEQ_BENDER_RANGE(device, voice, value); |
| 829 |
</pre> |
| 830 |
<p> |
| 831 |
|
| 832 |
Both of these controls can be changed at real time during playing the sample. |
| 833 |
<p> |
| 834 |
|
| 835 |
<h3>4.2.2. Volume control</h3> |
| 836 |
|
| 837 |
The volume of each voice can be controlled by |
| 838 |
three parameters: main volume, expression volume, and velocity. |
| 839 |
The total volume is calculated from the product of these three values |
| 840 |
as (main_volume * expression * velocity). |
| 841 |
While the last velocity parameters is specified at starting the sample, |
| 842 |
the other two parameters are given usually before playing it |
| 843 |
though they can be changed at real time during playing the sample. |
| 844 |
<p> |
| 845 |
|
| 846 |
The main volume is set |
| 847 |
via <code>SEQ_CONTROL</code> with the proper control code |
| 848 |
(<code>CTL_MAIN_VOLUE</code> and <code>CTRL_MAIN_VOLUME</code>), |
| 849 |
or obsolete <code>SEQ_MAIN_VOLUME</code> macro. |
| 850 |
<pre> |
| 851 |
SEQ_CONTROL(device, voice, CTL_MAIN_VOLUME, value); |
| 852 |
</pre> |
| 853 |
The value for <code>SEQ_MAIN_VOLUME</code> is identical with MIDI value, |
| 854 |
from 0 to 127. |
| 855 |
When the playing mode is the normal mode, |
| 856 |
the control <code>CTL_MAIN_VOLUME</code> has a value from 0 to 20806 |
| 857 |
(= 16383 * 127 / 100). |
| 858 |
In the channel mode, it has the same value as MIDI, from 0 to 127. |
| 859 |
The <code>CTRL_MAIN_VOLUME</code> always has the same value as MIDI. |
| 860 |
<p> |
| 861 |
|
| 862 |
The expression volume is set via |
| 863 |
<code>SEQ_CONTROL</code> with the proper control code |
| 864 |
(<code>CTL_EXPRESSION</code> and <code>CTRL_EXPRESSION</code>), |
| 865 |
or obsolete <code>SEQ_EXPRESSION</code> macro. |
| 866 |
<pre> |
| 867 |
SEQ_CONTROL(device, voice, CTL_EXPRESSION, value); |
| 868 |
</pre> |
| 869 |
The value for <code>SEQ_EXPRESSION</code> is identical with MIDI value, |
| 870 |
from 0 to 127. |
| 871 |
Similarly, when the playing mode is the normal mode, |
| 872 |
the control code<code>CTL_EXPRESSION</code> has a value from 0 to 16256 |
| 873 |
(= 127 * 128). |
| 874 |
In the channel mode, it has the same value as MIDI, from 0 to 127. |
| 875 |
The <code>CTRL_EXPRESSION</code> has the same value as MIDI, |
| 876 |
from 0 to 127. |
| 877 |
<p> |
| 878 |
|
| 879 |
Additionally, the awedrv has a total volume attenuation parameter. |
| 880 |
Users can change this initial attenuation using <code>AWE_INITIAL_ATTEN</code> |
| 881 |
control (identical with <code>AWE_INITIAL_VOLUME</code>). |
| 882 |
<pre> |
| 883 |
AWE_INITIAL_ATTEN(device, atten); |
| 884 |
</pre> |
| 885 |
This value <code>atten</code> is the attenuation volume from full scale |
| 886 |
in 0.375 dB order. For example, a value of 10 means that |
| 887 |
3.75 dB lower from full scale. |
| 888 |
The initial value is 32, 12dB below from full scale. |
| 889 |
<p> |
| 890 |
|
| 891 |
In the driver ver.0.4, the initial attenuation can be calculated |
| 892 |
as an additional attenuation from predefined "zero attenuation". |
| 893 |
The zero attenuation can be given via <code>AWE_MISC_MODE</code> control as |
| 894 |
<pre> |
| 895 |
AWE_MISC_MODE(device, AWE_MD_ZERO_ATTEN, atten); |
| 896 |
</pre> |
| 897 |
Then, the attenuation is changed via <code>AWE_SET_ATTEN</code> control. |
| 898 |
<pre> |
| 899 |
AWE_SET_ATTEN(device, atten); |
| 900 |
</pre> |
| 901 |
The definition of attenuation level is as same as the above. |
| 902 |
Note that <code>AWE_INITIAL_ATTEN</code> sets the absolute attenuation, |
| 903 |
while <code>AWE_SET_ATTEN</code> sets the relative attenation from |
| 904 |
zero level. |
| 905 |
<p> |
| 906 |
|
| 907 |
Also, the awedrv has an mixer control of Emu8000 chip. |
| 908 |
To change the bass and treble volume, use <code>AWE_EQUALIZER</code> macro. |
| 909 |
<pre> |
| 910 |
AWE_EQUALIZER(device, bass, treble); |
| 911 |
</pre> |
| 912 |
where both <code>bass</code> and <code>treble</code> are the integer value |
| 913 |
from 0 (-12dB) to 11 (+12dB). |
| 914 |
<p> |
| 915 |
|
| 916 |
<h3>4.2.3. Panning position</h3> |
| 917 |
|
| 918 |
The panning position is also set via control command, |
| 919 |
<code>SEQ_CONTROL</code> with the proper control code (<code>CTL_PAN</code>), |
| 920 |
or obsolete <code>SEQ_PANNING</code> macro. |
| 921 |
<pre> |
| 922 |
SEQ_CONTROL(device, voice, CTL_PAN, value); |
| 923 |
</pre> |
| 924 |
The value for <code>SEQ_PANNING</code> is from -128(left) to 128(right), |
| 925 |
and different from MIDI value |
| 926 |
unlike volume controls above. |
| 927 |
But the value of <code>CTL_PAN</code> is identical with MIDI value, |
| 928 |
from 0(left) to 127(right). |
| 929 |
<p> |
| 930 |
|
| 931 |
The panning position can be changed during playing, |
| 932 |
but may cause a small clicking noise due to restriction of |
| 933 |
emu8000 chip. |
| 934 |
This is suppressed by <code>AWE_REALTIME_PAN</code> control. |
| 935 |
<pre> |
| 936 |
AWE_REALTIME_PAN(device, 0); |
| 937 |
</pre> |
| 938 |
If the argument is zero, the panning position of the voices never changes |
| 939 |
during played. |
| 940 |
<p> |
| 941 |
|
| 942 |
<h3>4.2.4. Chorus and reverb effects</h3> |
| 943 |
|
| 944 |
The AWE32 has chorus and reverb effects for each voice. |
| 945 |
In awedrv, these effects are controlled via <code>SEQ_CONTROL</code> |
| 946 |
with two control commands, |
| 947 |
<code>CTL_CHORUS_DEPTH</code> and <code>CTL_EXT_EFF_DEPTH</code>, |
| 948 |
for chorus and reverb, respectively. |
| 949 |
<pre> |
| 950 |
SEQ_CONTROL(device, voice, CTL_CHORUS_DEPTH, value); |
| 951 |
SEQ_CONTROL(device, voice, CTL_EXT_EFF_DEPTH, value); |
| 952 |
</pre> |
| 953 |
In both cases, the value range is from 0 to 127, |
| 954 |
where 127 means 100% of output is send to the corresponding effect processor. |
| 955 |
These values cannot be changed during playing the sample. |
| 956 |
<p> |
| 957 |
|
| 958 |
Also, AWE32 has eight modes for both chorus and reverb effects. |
| 959 |
They can be changed by extended control by |
| 960 |
<code>AWE_CHORUS_MODE</code> and <code>AWE_REVERB_MODE</code>, respectively. |
| 961 |
<pre> |
| 962 |
AWE_CHORUS_MODE(device, mode); |
| 963 |
AWE_REVERB_MODE(device, mode); |
| 964 |
</pre> |
| 965 |
In both cases, the range of the parameter value is from 0 to 7. |
| 966 |
The corresponding mode to each value is defined in <code>awe_voice.h</code>, |
| 967 |
that is, |
| 968 |
Chorus 1 - 4, Feedback, Flanger, Short Delay, and Short Delay 2 for chorus modes, |
| 969 |
and |
| 970 |
Room 1 - 3, Hall 1/2, Plate, Delay, Panning Delay for reverb modes. |
| 971 |
See AWE32 FAQ by CreativeLabs for meaning of each mode. |
| 972 |
<p> |
| 973 |
|
| 974 |
<h3>4.2.5. Other effects</h3> |
| 975 |
|
| 976 |
The awedrv has several extended controls |
| 977 |
to write raw register values for emu8000 parameters. |
| 978 |
Through this function, users can control any function of AWE32 sound effects, |
| 979 |
although the parameter value itself is not generic. |
| 980 |
<p> |
| 981 |
|
| 982 |
The extended controls are passed through |
| 983 |
<code>AWE_SEND_EFFECT</code> macro with |
| 984 |
specified commands and values. |
| 985 |
<pre> |
| 986 |
AWE_SEND_EFFECT(device, voice, command, value); |
| 987 |
</pre> |
| 988 |
The commands are defined in <code>awe_voice.h</code>, that is, |
| 989 |
<pre> |
| 990 |
/* 0*/ AWE_FX_ENV1_DELAY, /* WORD: ENVVAL */ |
| 991 |
/* 1*/ AWE_FX_ENV1_ATTACK, /* BYTE: up ATKHLD */ |
| 992 |
/* 2*/ AWE_FX_ENV1_HOLD, /* BYTE: lw ATKHLD */ |
| 993 |
/* 3*/ AWE_FX_ENV1_DECAY, /* BYTE: lw DCYSUS */ |
| 994 |
/* 4*/ AWE_FX_ENV1_RELEASE, /* BYTE: lw DCYSUS */ |
| 995 |
/* 5*/ AWE_FX_ENV1_SUSTAIN, /* BYTE: up DCYSUS */ |
| 996 |
/* 6*/ AWE_FX_ENV1_PITCH, /* BYTE: up PEFE */ |
| 997 |
/* 7*/ AWE_FX_ENV1_CUTOFF, /* BYTE: lw PEFE */ |
| 998 |
|
| 999 |
/* 8*/ AWE_FX_ENV2_DELAY, /* WORD: ENVVOL */ |
| 1000 |
/* 9*/ AWE_FX_ENV2_ATTACK, /* BYTE: up ATKHLDV */ |
| 1001 |
/*10*/ AWE_FX_ENV2_HOLD, /* BYTE: lw ATKHLDV */ |
| 1002 |
/*11*/ AWE_FX_ENV2_DECAY, /* BYTE: lw DCYSUSV */ |
| 1003 |
/*12*/ AWE_FX_ENV2_RELEASE, /* BYTE: lw DCYSUSV */ |
| 1004 |
/*13*/ AWE_FX_ENV2_SUSTAIN, /* BYTE: up DCYSUSV */ |
| 1005 |
|
| 1006 |
/*14*/ AWE_FX_LFO1_DELAY, /* WORD: LFO1VAL */ |
| 1007 |
/*15*/ AWE_FX_LFO1_FREQ, /* BYTE: lo TREMFRQ */ |
| 1008 |
/*16*/ AWE_FX_LFO1_VOLUME, /* BYTE: up TREMFRQ */ |
| 1009 |
/*17*/ AWE_FX_LFO1_PITCH, /* BYTE: up FMMOD */ |
| 1010 |
/*18*/ AWE_FX_LFO1_CUTOFF, /* BYTE: lo FMMOD */ |
| 1011 |
|
| 1012 |
/*19*/ AWE_FX_LFO2_DELAY, /* WORD: LFO2VAL */ |
| 1013 |
/*20*/ AWE_FX_LFO2_FREQ, /* BYTE: lo FM2FRQ2 */ |
| 1014 |
/*21*/ AWE_FX_LFO2_PITCH, /* BYTE: up FM2FRQ2 */ |
| 1015 |
|
| 1016 |
/*22*/ AWE_FX_INIT_PITCH, /* SHORT: pitch offset */ |
| 1017 |
/*23*/ AWE_FX_CHORUS, /* BYTE: chorus effects send (0-255) */ |
| 1018 |
/*24*/ AWE_FX_REVERB, /* BYTE: reverb effects send (0-255) */ |
| 1019 |
/*25*/ AWE_FX_CUTOFF, /* BYTE: up IFATN */ |
| 1020 |
/*26*/ AWE_FX_FILTERQ, /* BYTE: up CCCA */ |
| 1021 |
|
| 1022 |
/*27*/ AWE_FX_SAMPLE_START, /* SHORT: offset */ |
| 1023 |
/*28*/ AWE_FX_LOOP_START, /* SHORT: offset */ |
| 1024 |
/*29*/ AWE_FX_LOOP_END, /* SHORT: offset */ |
| 1025 |
/*30*/ AWE_FX_COARSE_SAMPLE_START, /* SHORT: upper word offset */ |
| 1026 |
/*31*/ AWE_FX_COARSE_LOOP_START, /* SHORT: upper word offset */ |
| 1027 |
/*32*/ AWE_FX_COARSE_LOOP_END, /* SHORT: upper word offset */ |
| 1028 |
/*33*/ AWE_FX_ATTEN, /* BYTE: lo IFATN */ |
| 1029 |
</pre> |
| 1030 |
The commands 0 - 7 define parameters of the modulation envelope, |
| 1031 |
8 - 13 of the volume envelope, |
| 1032 |
14 - 18 of LFO1, |
| 1033 |
19 - 21 of LFO2, |
| 1034 |
22 - 26 of other effect parameters for total voice, |
| 1035 |
and the later provides sample start position, and loop offset. |
| 1036 |
See ADIP for the parameter values of envelopes and LFO's. |
| 1037 |
<p> |
| 1038 |
|
| 1039 |
<code>AWE_ADD_EFFECT</code> is used to adjust the effect from |
| 1040 |
predefined value in the voice patch data. |
| 1041 |
The relative value is given as an argument, |
| 1042 |
while the absolute value is given in <code>AWE_SEND_EFFECT</code> control. |
| 1043 |
<pre> |
| 1044 |
AWE_ADD_EFFECT(device, voice, command, value); |
| 1045 |
</pre> |
| 1046 |
<p> |
| 1047 |
|
| 1048 |
On the channel mode, these effects are kept |
| 1049 |
unless <code>AWE_UNSET_EFFECT</code> macro is used. |
| 1050 |
<pre> |
| 1051 |
AWE_UNSET_EFFECT(device, voice, layer, command); |
| 1052 |
</pre> |
| 1053 |
On the normal mode, the effects are always cleared after the voice is off. |
| 1054 |
To suppress this, set <code>AWE_MD_KEEP_EFFECT</code> by |
| 1055 |
<code>AWE_MISC_MODE</code> control. |
| 1056 |
<pre> |
| 1057 |
AWE_MISC_MODE(device, AWE_MD_KEEP_EFFECT, 1); |
| 1058 |
</pre> |
| 1059 |
<p> |
| 1060 |
|
| 1061 |
Also, on the channel mode, each instrument "layer" can be controlled via |
| 1062 |
<code>AWE_SEND_LAYER_EFFECT</code> and <code>AWE_ADD_LAYER_EFFECT</code> |
| 1063 |
macros. |
| 1064 |
It affects the effects only on one layer (= one voice) |
| 1065 |
specified in the argument. |
| 1066 |
<pre> |
| 1067 |
AWE_SEND_EFFECT_LAYER(device, voice, layer, command, value); |
| 1068 |
</pre> |
| 1069 |
<p> |
| 1070 |
|
| 1071 |
GUS compatible extended controls are partly implemented. |
| 1072 |
<code>GUS_VOICE_POS</code> is interpreted inside as an extension control |
| 1073 |
27(<code>AWE_FX_SAMPLE_START</code>) and |
| 1074 |
30(<code>AWE_FX_COARSE_SAMPLE_START</code>). |
| 1075 |
<p> |
| 1076 |
|
| 1077 |
<h2>4.3. Starting a note</h2> |
| 1078 |
|
| 1079 |
There are two ways to start a voice. |
| 1080 |
The standard method is to call <code>SEQ_START_NOTE</code> macro. |
| 1081 |
<pre> |
| 1082 |
SEQ_START_NOTE(device, voice, note, velocity); |
| 1083 |
</pre> |
| 1084 |
where <code>note</code> and <code>velocity</code> are the MIDI key and velocity |
| 1085 |
to be played, respectively. |
| 1086 |
A sample including the specified note in its key range |
| 1087 |
is searched from all samples with given bank and program numbers. |
| 1088 |
Then, the volume and pitch parameters are computed here |
| 1089 |
from specified note and velocity. |
| 1090 |
If this sample is an exclusive voice like drum hi-hat sounds, |
| 1091 |
turn off other voices with the same exclusive key, that is |
| 1092 |
the other hi-hat sounds which is being played. |
| 1093 |
After that, start this voice. |
| 1094 |
<p> |
| 1095 |
|
| 1096 |
In the normal playing mode, |
| 1097 |
the note 255 has a special meaning. |
| 1098 |
When this function is called with the note 255, |
| 1099 |
only volume is changed according its velocity, |
| 1100 |
and never affects the envelope change, and so on. |
| 1101 |
This can be used for dynamic volume control |
| 1102 |
without using other <code>SEQ_CONTROL</code> functions. |
| 1103 |
Note that this feature is ignored in the channel playing mode. |
| 1104 |
<p> |
| 1105 |
|
| 1106 |
If the velocity is specified as zero, then one channel is allocated, |
| 1107 |
but the sound is not started. It starts when volume change control |
| 1108 |
is received later. |
| 1109 |
<p> |
| 1110 |
|
| 1111 |
The another way for start is to call a GUS specific control |
| 1112 |
<pre> |
| 1113 |
GUS_VOICEON(device, voice, mode); |
| 1114 |
</pre> |
| 1115 |
where <code>mode</code> is a voice mode, but ignored in awedrv. |
| 1116 |
This simply starts a sound on the channel, so voice parameters |
| 1117 |
like program, pitch and volume must be set before calling this function. |
| 1118 |
<p> |
| 1119 |
|
| 1120 |
<hr> |
| 1121 |
<p> |
| 1122 |
|
| 1123 |
<h1>5. Modulating a voice</h1> |
| 1124 |
|
| 1125 |
<h2>5.1. Changing volume</h2> |
| 1126 |
|
| 1127 |
Many methods are provided to change the volume of the sample. |
| 1128 |
One is to use <code>SEQ_KEY_PRESSURE</code> macro, |
| 1129 |
or <code>AWE_KEY_PRESSURE</code> macro, depending on its playing mode. |
| 1130 |
In the channel playing mode, the former macro |
| 1131 |
<code>SEQ_KEY_PRESSURE</code> is ignored |
| 1132 |
due to compatibility problems. |
| 1133 |
Thus, in the channel mode, |
| 1134 |
use the latter <code>AWE_KEY_PRESSURE</code> macro instead. |
| 1135 |
The parameter value is as same as MIDI pressure value, from 0 to 127. |
| 1136 |
<pre> |
| 1137 |
AWE_KEY_PRESSURE(device, voice, note, velocity); |
| 1138 |
</pre> |
| 1139 |
<p> |
| 1140 |
|
| 1141 |
The second way is updating main or expression volume on each channel |
| 1142 |
by <code>SEQ_CONTROL</code> or other macros (see 4.2.2). |
| 1143 |
Also, using <code>SEQ_START_NOTE</code> with a special note 255 is |
| 1144 |
available for changing volume as explained above. |
| 1145 |
<p> |
| 1146 |
|
| 1147 |
<h2>5.2. Changing pitch</h2> |
| 1148 |
|
| 1149 |
You can change pitch of the sound by using the pitch wheel, |
| 1150 |
or by <code>AWE_SEND_EFFECT</code> with |
| 1151 |
<code>AWE_FX_INIT_PITCH</code> command |
| 1152 |
(see 4.2.1). |
| 1153 |
<p> |
| 1154 |
|
| 1155 |
<h2>5.3. Changing panning position</h2> |
| 1156 |
|
| 1157 |
The panning position is able to be changed at real time, |
| 1158 |
but it may cause a noise as explained above (see 4.2.3). |
| 1159 |
<p> |
| 1160 |
|
| 1161 |
<h2>5.4. Changing chorus and reverb</h2> |
| 1162 |
|
| 1163 |
The chorus and reverb effects can NOT be changed at real time. |
| 1164 |
However, the chorus and reverb modes are possible to be changed. |
| 1165 |
<p> |
| 1166 |
|
| 1167 |
<h2>5.5. Changing other effects</h2> |
| 1168 |
|
| 1169 |
The LFO1 depth can be changed via <code>AWE_CHN_PRESSURE</code> and |
| 1170 |
<code>CTL_MODWHEEL</code> MIDI control. |
| 1171 |
The former affets all the voices on the channel, while the latter affects |
| 1172 |
only one voice (in the channel mode). |
| 1173 |
<pre> |
| 1174 |
AWE_CHN_PRESSURE(device, channel, value); |
| 1175 |
SEQ_CONTROL(device, voice, CTL_MODWHEEL, value); |
| 1176 |
</pre> |
| 1177 |
The value is MIDI value from 0 to 127. |
| 1178 |
<p> |
| 1179 |
|
| 1180 |
The LFO parameters (frequency, volume, pitch shift, and cutoff shift), and |
| 1181 |
LFO2 parameters (frequency, and pitch shift) |
| 1182 |
can be changed at real time via <code>AWE_SEND_EFFECT</code> control. |
| 1183 |
Also, total cutoff frequency can be changed. |
| 1184 |
The values are passed through the extended controls (see 4.2.5). |
| 1185 |
<p> |
| 1186 |
|
| 1187 |
<hr> |
| 1188 |
<p> |
| 1189 |
|
| 1190 |
<h1>6. Timer control</h1> |
| 1191 |
|
| 1192 |
The awedrv itself doesn't provide any timer control functions. |
| 1193 |
Use the standard timer macros, <code>SEQ_START_TIMER</code>, |
| 1194 |
<code>SEQ_WAIT_TIME</code> or <code>SEQ_DELTA_TIME</code>, |
| 1195 |
and <code>SEQ_STOP_TIMER</code>. |
| 1196 |
<p> |
| 1197 |
|
| 1198 |
<hr> |
| 1199 |
<p> |
| 1200 |
|
| 1201 |
<h1>7. Ending a voice</h1> |
| 1202 |
|
| 1203 |
To end a sound, call <code>SEQ_STOP_NOTE</code> macro. |
| 1204 |
This releases the sound from the sustain level to silence |
| 1205 |
according to the volume envelope. |
| 1206 |
The note and velocity parameters are ignored. |
| 1207 |
<pre> |
| 1208 |
SEQ_STOP_NOTE(device, voice, note, velocity); |
| 1209 |
</pre> |
| 1210 |
<p> |
| 1211 |
|
| 1212 |
Or, you can terminate the voice completely by extended control, |
| 1213 |
<code>AWE_TERMINATE_CHANNEL</code>. |
| 1214 |
This stops the sound without any releasing echo. |
| 1215 |
<pre> |
| 1216 |
AWE_TERMINATE_CHANNEL(device, voice); |
| 1217 |
</pre> |
| 1218 |
To terminate all voices, the extended control |
| 1219 |
<code>AWE_TERMINATE_ALL</code> is available. |
| 1220 |
<pre> |
| 1221 |
AWE_TERMINATE_ALL(device); |
| 1222 |
</pre> |
| 1223 |
To turn off the all channels similary as SEQ_STOP_NOTE |
| 1224 |
(with sustain effects), |
| 1225 |
use <code>AWE_NOTEOFF_ALL</code>. |
| 1226 |
<pre> |
| 1227 |
AWE_RELEASE_ALL(device); |
| 1228 |
</pre> |
| 1229 |
Also, to force to turn off the all channels without sustain effects, |
| 1230 |
use <code>AWE_NOTEOFF_ALL</code>. |
| 1231 |
<pre> |
| 1232 |
AWE_NOTEOFF_ALL(device); |
| 1233 |
</pre> |
| 1234 |
<p> |
| 1235 |
|
| 1236 |
<hr> |
| 1237 |
<p> |
| 1238 |
|
| 1239 |
<h1>8. Other features</h1> |
| 1240 |
|
| 1241 |
<h2>8.1. Debug options</h2> |
| 1242 |
The debug message is toggled on/off by the extended control |
| 1243 |
<code>AWE_DEBUG_MODE</code>. |
| 1244 |
<pre> |
| 1245 |
AWE_DEBUG_MODE(device, mode); |
| 1246 |
</pre> |
| 1247 |
The value zero means to turn off debugging messages, |
| 1248 |
and values larger then zero means to output debugging messages |
| 1249 |
on syslog, usually <code>/var/adm/syslog</code> or </code>/var/adm/message</code> |
| 1250 |
(depending on the setting of <code>/etc/syslog.conf</code>). |
| 1251 |
<p> |
| 1252 |
|
| 1253 |
<h2>8.2. Initialize Emu8000 chip</h2> |
| 1254 |
The emu8000 chip can be initialized explicitly by the extended control |
| 1255 |
<code>AWE_INITIALIZE_CHIP</code>. |
| 1256 |
This only re-initializes the AWE32, and doesn't affect other driver-internal |
| 1257 |
parameters or effects. |
| 1258 |
<pre> |
| 1259 |
AWE_INITIALIZE_CHIP(seqfd, device); |
| 1260 |
</pre> |
| 1261 |
This function uses ioctl, so the file descriptor of sequencer device |
| 1262 |
is required. |
| 1263 |
<p> |
| 1264 |
|
| 1265 |
<h2>8.3. Set miscellaneous operation modes</h2> |
| 1266 |
Many operation modes can be set via <code>AWE_MISC_MODE</code> control. |
| 1267 |
<pre> |
| 1268 |
AWE_MISC_MODE(device, type, value); |
| 1269 |
</pre> |
| 1270 |
See <code>awe_voice.h</code> for each definition. |
| 1271 |
<p> |
| 1272 |
|
| 1273 |
<p><hr> |
| 1274 |
Takashi Iwai<br> |
| 1275 |
<a href=mailto:[email protected]> |
| 1276 |
<i>[email protected]</i></a><br> |
| 1277 |
<a href=http://bahamut.mm.t.u-tokyo.ac.jp/~iwai> |
| 1278 |
<i>http://bahamut.mm.t.u-tokyo.ac.jp/~iwai</i></a> |
| 1279 |
|
| 1280 |
</body> |