1 /*----------------------------------------------------------------------------
2  *
3  * File:
4  * eas_sndlib.h
5  *
6  * Contents and purpose:
7  * Declarations for the sound library
8  *
9  * Copyright Sonic Network Inc. 2005
10 
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  *      http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  *
23  *----------------------------------------------------------------------------
24  * Revision Control:
25  *   $Revision: 550 $
26  *   $Date: 2007-02-02 09:37:03 -0800 (Fri, 02 Feb 2007) $
27  *----------------------------------------------------------------------------
28 */
29 
30 #ifndef _EAS_SNDLIB_H
31 #define _EAS_SNDLIB_H
32 
33 #include "eas_types.h"
34 #include "eas_synthcfg.h"
35 
36 #ifdef _WT_SYNTH
37 #include "eas_wtengine.h"
38 #endif
39 
40 /*----------------------------------------------------------------------------
41  * This is bit of a hack to allow us to keep the same structure
42  * declarations for the DLS parser. Normally, the data is located
43  * in read-only memory, but for DLS, we store the data in RW
44  * memory.
45  *----------------------------------------------------------------------------
46 */
47 #ifndef SCNST
48 #define SCNST const
49 #endif
50 
51 /*----------------------------------------------------------------------------
52  * sample size
53  *----------------------------------------------------------------------------
54 */
55 #ifdef _16_BIT_SAMPLES
56 typedef EAS_I16 EAS_SAMPLE;
57 #else
58 typedef EAS_I8 EAS_SAMPLE;
59 #endif
60 
61 /*----------------------------------------------------------------------------
62  * EAS Library ID - quick check for valid library and version
63  *----------------------------------------------------------------------------
64 */
65 #define _EAS_LIBRARY_VERSION        0x01534145
66 
67 #define NUM_PROGRAMS_IN_BANK        128
68 #define INVALID_REGION_INDEX        0xffff
69 
70 /* this bit in region index indicates that region is for secondary synth */
71 #define FLAG_RGN_IDX_FM_SYNTH       0x8000
72 #define FLAG_RGN_IDX_DLS_SYNTH      0x4000
73 #define REGION_INDEX_MASK           0x3fff
74 
75 /*----------------------------------------------------------------------------
76  * Generic region data structure
77  *
78  * This must be the first element in each region structure
79  *----------------------------------------------------------------------------
80 */
81 typedef struct s_region_tag
82 {
83     EAS_U16     keyGroupAndFlags;
84     EAS_U8      rangeLow;
85     EAS_U8      rangeHigh;
86 } S_REGION;
87 
88 /*
89  * Bit fields for m_nKeyGroupAndFlags
90  * Bits 0-2 are mode bits in FM synth
91  * Bits 8-11 are the key group
92  */
93 #define REGION_FLAG_IS_LOOPED                   0x01
94 #define REGION_FLAG_USE_WAVE_GENERATOR          0x02
95 #define REGION_FLAG_USE_ADPCM                   0x04
96 #define REGION_FLAG_ONE_SHOT                    0x08
97 #define REGION_FLAG_SQUARE_WAVE                 0x10
98 #define REGION_FLAG_OFF_CHIP                    0x20
99 #define REGION_FLAG_NON_SELF_EXCLUSIVE          0x40
100 #define REGION_FLAG_LAST_REGION                 0x8000
101 
102 /*----------------------------------------------------------------------------
103  * Envelope data structure
104  *----------------------------------------------------------------------------
105 */
106 typedef struct s_envelope_tag
107 {
108     EAS_I16     attackTime;
109     EAS_I16     decayTime;
110     EAS_I16     sustainLevel;
111     EAS_I16     releaseTime;
112 } S_ENVELOPE;
113 
114 /*----------------------------------------------------------------------------
115  * DLS envelope data structure
116  *----------------------------------------------------------------------------
117 */
118 typedef struct s_dls_envelope_tag
119 {
120     EAS_I16         delayTime;
121     EAS_I16         attackTime;
122     EAS_I16         holdTime;
123     EAS_I16         decayTime;
124     EAS_I16         sustainLevel;
125     EAS_I16         releaseTime;
126     EAS_I16         velToAttack;
127     EAS_I16         keyNumToDecay;
128     EAS_I16         keyNumToHold;
129 } S_DLS_ENVELOPE;
130 
131 /*----------------------------------------------------------------------------
132  * LFO data structure
133  *----------------------------------------------------------------------------
134 */
135 typedef struct s_lfo_params_tag
136 {
137     EAS_I16     lfoFreq;
138     EAS_I16     lfoDelay;
139 } S_LFO_PARAMS;
140 
141 /*----------------------------------------------------------------------------
142  * Articulation data structure
143  *----------------------------------------------------------------------------
144 */
145 typedef struct s_articulation_tag
146 {
147     S_ENVELOPE  eg1;
148     S_ENVELOPE  eg2;
149     EAS_I16     lfoToPitch;
150     EAS_I16     lfoDelay;
151     EAS_I16     lfoFreq;
152     EAS_I16     eg2ToPitch;
153     EAS_I16     eg2ToFc;
154     EAS_I16     filterCutoff;
155     EAS_I8      lfoToGain;
156     EAS_U8      filterQ;
157     EAS_I8      pan;
158 } S_ARTICULATION;
159 
160 /*----------------------------------------------------------------------------
161  * DLS articulation data structure
162  *----------------------------------------------------------------------------
163 */
164 
165 typedef struct s_dls_articulation_tag
166 {
167     S_LFO_PARAMS    modLFO;
168     S_LFO_PARAMS    vibLFO;
169 
170     S_DLS_ENVELOPE  eg1;
171     S_DLS_ENVELOPE  eg2;
172 
173     EAS_I16         eg1ShutdownTime;
174 
175     EAS_I16         filterCutoff;
176     EAS_I16         modLFOToFc;
177     EAS_I16         modLFOCC1ToFc;
178     EAS_I16         modLFOChanPressToFc;
179     EAS_I16         eg2ToFc;
180     EAS_I16         velToFc;
181     EAS_I16         keyNumToFc;
182 
183     EAS_I16         modLFOToGain;
184     EAS_I16         modLFOCC1ToGain;
185     EAS_I16         modLFOChanPressToGain;
186 
187     EAS_I16         tuning;
188     EAS_I16         keyNumToPitch;
189     EAS_I16         vibLFOToPitch;
190     EAS_I16         vibLFOCC1ToPitch;
191     EAS_I16         vibLFOChanPressToPitch;
192     EAS_I16         modLFOToPitch;
193     EAS_I16         modLFOCC1ToPitch;
194     EAS_I16         modLFOChanPressToPitch;
195     EAS_I16         eg2ToPitch;
196 
197     /* pad to 4-byte boundary */
198     EAS_U16         pad;
199 
200     EAS_I8          pan;
201     EAS_U8          filterQandFlags;
202 
203 #ifdef _REVERB
204     EAS_I16         reverbSend;
205     EAS_I16         cc91ToReverbSend;
206 #endif
207 
208 #ifdef _CHORUS
209     EAS_I16         chorusSend;
210     EAS_I16         cc93ToChorusSend;
211 #endif
212 } S_DLS_ARTICULATION;
213 
214 /* flags in filterQandFlags
215  * NOTE: Q is stored in bottom 5 bits
216  */
217 #define FLAG_DLS_VELOCITY_SENSITIVE     0x80
218 #define FILTER_Q_MASK                   0x1f
219 
220 /*----------------------------------------------------------------------------
221  * Wavetable region data structure
222  *----------------------------------------------------------------------------
223 */
224 typedef struct s_wt_region_tag
225 {
226     S_REGION    region;
227     EAS_I16     tuning;
228     EAS_I16     gain;
229     EAS_U32     loopStart;
230     EAS_U32     loopEnd;
231     EAS_U16     waveIndex;
232     EAS_U16     artIndex;
233 } S_WT_REGION;
234 
235 /*----------------------------------------------------------------------------
236  * DLS region data structure
237  *----------------------------------------------------------------------------
238 */
239 typedef struct s_dls_region_tag
240 {
241     S_WT_REGION     wtRegion;
242     EAS_U8          velLow;
243     EAS_U8          velHigh;
244 } S_DLS_REGION;
245 
246 /*----------------------------------------------------------------------------
247  * FM synthesizer data structures
248  *----------------------------------------------------------------------------
249 */
250 typedef struct s_fm_oper_tag
251 {
252     EAS_I16     tuning;
253     EAS_U8      attackDecay;
254     EAS_U8      velocityRelease;
255     EAS_U8      egKeyScale;
256     EAS_U8      sustain;
257     EAS_U8      gain;
258     EAS_U8      flags;
259 } S_FM_OPER;
260 
261 /* defines for S_FM_OPER.m_nFlags */
262 #define FM_OPER_FLAG_MONOTONE           0x01
263 #define FM_OPER_FLAG_NO_VIBRATO         0x02
264 #define FM_OPER_FLAG_NOISE              0x04
265 #define FM_OPER_FLAG_LINEAR_VELOCITY    0x08
266 
267 /* NOTE: The first two structure elements are common with S_WT_REGION
268  * and we will rely on that in the voice management code and must
269  * remain there unless the voice management code is revisited.
270  */
271 typedef struct s_fm_region_tag
272 {
273     S_REGION        region;
274     EAS_U8          vibTrem;
275     EAS_U8          lfoFreqDelay;
276     EAS_U8          feedback;
277     EAS_I8          pan;
278     S_FM_OPER       oper[4];
279 } S_FM_REGION;
280 
281 /*----------------------------------------------------------------------------
282  * Common data structures
283  *----------------------------------------------------------------------------
284 */
285 
286 /*----------------------------------------------------------------------------
287  * Program data structure
288  * Used for individual programs not stored as a complete bank.
289  *----------------------------------------------------------------------------
290 */
291 typedef struct s_program_tag
292 {
293     EAS_U32 locale;
294     EAS_U16 regionIndex;
295 } S_PROGRAM;
296 
297 /*----------------------------------------------------------------------------
298  * Bank data structure
299  *
300  * A bank always consists of 128 programs. If a bank is less than 128
301  * programs, it should be stored as a spare matrix in the pPrograms
302  * array.
303  *
304  * bankNum:     MSB/LSB of MIDI bank select controller
305  * regionIndex: Index of first region in program
306  *----------------------------------------------------------------------------
307 */
308 typedef struct s_bank_tag
309 {
310     EAS_U16 locale;
311     EAS_U16 regionIndex[NUM_PROGRAMS_IN_BANK];
312 } S_BANK;
313 
314 
315 /* defines for libFormat field
316  * bits 0-17 are the sample rate
317  * bit 18 is true if wavetable is present
318  * bit 19 is true if FM is present
319  * bit 20 is true if filter is enabled
320  * bit 21 is sample depth (0 = 8-bits, 1 = 16-bits)
321  * bits 22-31 are reserved
322  */
323 #define LIBFORMAT_SAMPLE_RATE_MASK      0x0003ffff
324 #define LIB_FORMAT_TYPE_MASK            0x000c0000
325 #define LIB_FORMAT_WAVETABLE            0x00000000
326 #define LIB_FORMAT_FM                   0x00040000
327 #define LIB_FORMAT_HYBRID               0x00080000
328 #define LIB_FORMAT_FILTER_ENABLED       0x00100000
329 #define LIB_FORMAT_16_BIT_SAMPLES       0x00200000
330 
331 #ifdef DLS_SYNTHESIZER
332 /*----------------------------------------------------------------------------
333  * DLS data structure
334  *
335  * pDLSPrograms         pointer to array of DLS programs
336  * pDLSRegions          pointer to array of DLS regions
337  * pDLSArticulations    pointer to array of DLS articulations
338  * pSampleLen           pointer to array of sample lengths
339  * ppSamples            pointer to array of sample pointers
340  * numDLSPrograms       number of DLS programs
341  * numDLSRegions        number of DLS regions
342  * numDLSArticulations  number of DLS articulations
343  * numDLSSamples        number of DLS samples
344  *----------------------------------------------------------------------------
345 */
346 typedef struct s_eas_dls_tag
347 {
348     S_PROGRAM           *pDLSPrograms;
349     S_DLS_REGION        *pDLSRegions;
350     S_DLS_ARTICULATION  *pDLSArticulations;
351     EAS_U32             *pDLSSampleLen;
352     EAS_U32             *pDLSSampleOffsets;
353     EAS_SAMPLE          *pDLSSamples;
354     EAS_U16             numDLSPrograms;
355     EAS_U16             numDLSRegions;
356     EAS_U16             numDLSArticulations;
357     EAS_U16             numDLSSamples;
358     EAS_U8              refCount;
359 } S_DLS;
360 #endif
361 
362 /*----------------------------------------------------------------------------
363  * Sound library data structure
364  *
365  * pBanks           pointer to array of banks
366  * pPrograms        pointer to array of programs
367  * pWTRegions       pointer to array of wavetable regions
368  * pFMRegions       pointer to array of FM regions
369  * pArticulations   pointer to array of articulations
370  * pSampleLen       pointer to array of sample lengths
371  * ppSamples        pointer to array of sample pointers
372  * numBanks         number of banks
373  * numPrograms      number of individual program
374  * numRegions       number of regions
375  * numArticulations number of articulations
376  * numSamples       number of samples
377  *----------------------------------------------------------------------------
378 */
379 typedef struct s_eas_sndlib_tag
380 {
381     SCNST EAS_U32               identifier;
382     SCNST EAS_U32               libAttr;
383 
384     SCNST S_BANK                *pBanks;
385     SCNST S_PROGRAM             *pPrograms;
386 
387     SCNST S_WT_REGION           *pWTRegions;
388     SCNST S_ARTICULATION        *pArticulations;
389     SCNST EAS_U32               *pSampleLen;
390     SCNST EAS_U32               *pSampleOffsets;
391     SCNST EAS_SAMPLE            *pSamples;
392 
393     SCNST S_FM_REGION           *pFMRegions;
394 
395     SCNST EAS_U16               numBanks;
396     SCNST EAS_U16               numPrograms;
397 
398     SCNST EAS_U16               numWTRegions;
399     SCNST EAS_U16               numArticulations;
400     SCNST EAS_U16               numSamples;
401 
402     SCNST EAS_U16               numFMRegions;
403 } S_EAS;
404 
405 #endif
406 
407