Debian Codegraph @

debian/awedrv-prog.html

raw
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>