2 * OpenAL cross platform audio library
3 * Copyright (C) 2008 by Christopher Fitzgerald.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
18 * Or go to http://www.gnu.org/copyleft/lgpl.html
29 #include "alAuxEffectSlot.h"
34 #define aluSqrt(x) ((ALfloat)sqrtf((float)(x)))
36 #define aluSqrt(x) ((ALfloat)sqrt((double)(x)))
40 #if defined(max) && !defined(__max)
43 #if defined(min) && !defined(__min)
47 typedef struct DelayLine
49 // The delay lines use lengths that are powers of 2 to allow bitmasking
50 // instead of modulus wrapping.
57 // All delay lines are allocated as a single buffer to reduce memory
58 // fragmentation and teardown code.
59 ALfloat
*SampleBuffer
;
60 // Master reverb gain.
62 // Initial reverb delay.
64 // The tap points for the initial delay. First tap goes to early
65 // reflections, the second to late reverb.
68 // Gain for early reflections.
70 // Early reflections are done with 4 delay lines.
76 // Gain for late reverb.
78 // Diffusion of late reverb.
80 // Late reverb is done with 8 delay lines.
84 // The input and last 4 delay lines are low-pass filtered.
91 // All delay line lengths are specified in seconds.
93 // The length of the initial delay line (a sum of the maximum delay before
94 // early reflections and late reverb; 0.3 + 0.1).
95 static const ALfloat MASTER_LINE_LENGTH
= 0.4000f
;
97 // The lengths of the early delay lines.
98 static const ALfloat EARLY_LINE_LENGTH
[4] =
100 0.0015f
, 0.0045f
, 0.0135f
, 0.0405f
103 // The lengths of the late delay lines.
104 static const ALfloat LATE_LINE_LENGTH
[8] =
106 0.0015f
, 0.0037f
, 0.0093f
, 0.0234f
,
107 0.0100f
, 0.0150f
, 0.0225f
, 0.0337f
110 // The last 4 late delay lines have a variable length dependent on the effect
111 // density parameter and this multiplier.
112 static const ALfloat LATE_LINE_MULTIPLIER
= 9.0f
;
114 static ALuint
NextPowerOf2(ALuint value
)
130 // Basic delay line input/output routines.
131 static __inline ALfloat
DelayLineOut(DelayLine
*Delay
, ALuint offset
)
133 return Delay
->Line
[offset
&Delay
->Mask
];
136 static __inline ALvoid
DelayLineIn(DelayLine
*Delay
, ALuint offset
, ALfloat in
)
138 Delay
->Line
[offset
&Delay
->Mask
] = in
;
141 // Delay line output routine for early reflections.
142 static __inline ALfloat
EarlyDelayLineOut(ALverbState
*State
, ALuint index
)
144 return State
->Early
.Coeff
[index
] *
145 DelayLineOut(&State
->Early
.Delay
[index
],
146 State
->Offset
- State
->Early
.Offset
[index
]);
149 // Given an input sample, this function produces a decorrelated stereo output
150 // for early reflections.
151 static __inline ALvoid
EarlyReflection(ALverbState
*State
, ALfloat in
, ALfloat
*out
)
153 ALfloat d
[4], v
, f
[4];
155 // Obtain the decayed results of each early delay line.
156 d
[0] = EarlyDelayLineOut(State
, 0);
157 d
[1] = EarlyDelayLineOut(State
, 1);
158 d
[2] = EarlyDelayLineOut(State
, 2);
159 d
[3] = EarlyDelayLineOut(State
, 3);
161 /* The following uses a lossless scattering junction from waveguide
162 * theory. It actually amounts to a householder mixing matrix, which
163 * will produce a maximally diffuse response, and means this can probably
164 * be considered a simple FDN.
172 v
= (d
[0] + d
[1] + d
[2] + d
[3]) * 0.5f
;
173 // The junction is loaded with the input here.
176 // Calculate the feed values for the delay lines.
182 // Refeed the delay lines.
183 DelayLineIn(&State
->Early
.Delay
[0], State
->Offset
, f
[0]);
184 DelayLineIn(&State
->Early
.Delay
[1], State
->Offset
, f
[1]);
185 DelayLineIn(&State
->Early
.Delay
[2], State
->Offset
, f
[2]);
186 DelayLineIn(&State
->Early
.Delay
[3], State
->Offset
, f
[3]);
188 // To decorrelate the output for stereo separation, the two outputs are
189 // obtained from the inner delay lines.
190 // Output is instant by using the inputs to them instead of taking the
191 // result of the two delay lines directly (f[0] and f[3] instead of d[1]
193 out
[0] = State
->Early
.Gain
* f
[0];
194 out
[1] = State
->Early
.Gain
* f
[3];
197 // Delay line output routine for late reverb.
198 static __inline ALfloat
LateDelayLineOut(ALverbState
*State
, ALuint index
)
200 return State
->Late
.Coeff
[index
] *
201 DelayLineOut(&State
->Late
.Delay
[index
],
202 State
->Offset
- State
->Late
.Offset
[index
]);
205 // Low-pass filter input/output routine for late reverb.
206 static __inline ALfloat
LateLowPassInOut(ALverbState
*State
, ALuint index
, ALfloat in
)
208 State
->Late
.LpSample
[index
] = in
+ ((State
->Late
.LpSample
[index
] - in
) *
209 State
->Late
.LpCoeff
[index
]);
210 return State
->Late
.LpSample
[index
];
213 // Given an input sample, this function produces a decorrelated stereo output
215 static __inline ALvoid
LateReverb(ALverbState
*State
, ALfloat in
, ALfloat
*out
)
217 ALfloat din
, d
[8], v
, dv
, f
[8];
219 // Since the input will be sent directly to the output as in the early
220 // reflections function, it needs to take into account some immediate
222 in
= LateLowPassInOut(State
, 0, in
);
224 // When diffusion is full, no input is directly passed to the variable-
225 // length delay lines (the last 4).
226 din
= (1.0f
- State
->Late
.Diffusion
) * in
;
228 // Obtain the decayed results of the fixed-length delay lines.
229 d
[0] = LateDelayLineOut(State
, 0);
230 d
[1] = LateDelayLineOut(State
, 1);
231 d
[2] = LateDelayLineOut(State
, 2);
232 d
[3] = LateDelayLineOut(State
, 3);
233 // Obtain the decayed and low-pass filtered results of the variable-
234 // length delay lines.
235 d
[4] = LateLowPassInOut(State
, 1, LateDelayLineOut(State
, 4));
236 d
[5] = LateLowPassInOut(State
, 2, LateDelayLineOut(State
, 5));
237 d
[6] = LateLowPassInOut(State
, 3, LateDelayLineOut(State
, 6));
238 d
[7] = LateLowPassInOut(State
, 4, LateDelayLineOut(State
, 7));
240 // The waveguide formula used in the early reflections function works
241 // great for high diffusion, but it is not obviously paramerized to allow
242 // a variable diffusion. With only limited time and resources, what
243 // follows is the best variation of that formula I could come up with.
244 // First, there are 8 delay lines used. The first 4 are fixed-length and
245 // generate the highest density of the diffuse response. The last 4 are
246 // variable-length, and are used to smooth out the diffuse response. The
247 // density effect parameter alters their length. The inner two delay
248 // lines of each group have their signs reversed (more about this later).
249 v
= (d
[0] - d
[1] - d
[2] + d
[3] +
250 d
[4] - d
[5] - d
[6] + d
[7]) * 0.25f
;
251 // Diffusion is applied as a reduction of the junction pressure for all
252 // branches. This presents two problems. When the diffusion factor (0
253 // to 1) reaches 0.5, the average feed value is reduced (the junction
254 // becomes lossy). Thus, at 0.5 the signal decays almost twice as fast
255 // as it should. The second problem is the introduction of some
256 // resonant frequencies (coloration). The reversed signs above are used
257 // to help combat some of the coloration by adding variations along the
259 v
*= State
->Late
.Diffusion
;
260 // Load the junction with the input. To reduce the noticeable echo of
261 // the longer delay lines (the variable-length ones) the input is loaded
262 // with the inverse of the effect diffusion. So at full diffusion, the
263 // input is not applied to the last 4 delay lines. Input signs reversed
264 // to balance the equation.
268 // As with the reversed signs above, to balance the equation the signs
269 // need to be reversed here, too.
279 // Feed the fixed-length delay lines with their own cycle (0 -> 1 -> 3 ->
281 DelayLineIn(&State
->Late
.Delay
[0], State
->Offset
, f
[2]);
282 DelayLineIn(&State
->Late
.Delay
[1], State
->Offset
, f
[0]);
283 DelayLineIn(&State
->Late
.Delay
[2], State
->Offset
, f
[3]);
284 DelayLineIn(&State
->Late
.Delay
[3], State
->Offset
, f
[1]);
285 // Feed the variable-length delay lines with their cycle (4 -> 6 -> 7 ->
287 DelayLineIn(&State
->Late
.Delay
[4], State
->Offset
, f
[5]);
288 DelayLineIn(&State
->Late
.Delay
[5], State
->Offset
, f
[7]);
289 DelayLineIn(&State
->Late
.Delay
[6], State
->Offset
, f
[4]);
290 DelayLineIn(&State
->Late
.Delay
[7], State
->Offset
, f
[6]);
292 // Output is derived from the values fed to the inner two variable-length
293 // delay lines (5 and 6).
294 out
[0] = State
->Late
.Gain
* f
[7];
295 out
[1] = State
->Late
.Gain
* f
[4];
298 // This creates the reverb state. It should be called only when the reverb
299 // effect is loaded into a slot that doesn't already have a reverb effect.
300 ALverbState
*VerbCreate(ALCcontext
*Context
)
302 ALverbState
*State
= NULL
;
303 ALuint length
[13], totalLength
, index
;
305 State
= malloc(sizeof(ALverbState
));
309 // All line lengths are powers of 2, calculated from the line timings and
310 // the addition of an extra sample (for safety).
311 length
[0] = NextPowerOf2((ALuint
)(MASTER_LINE_LENGTH
*Context
->Frequency
) + 1);
312 totalLength
= length
[0];
313 for(index
= 0;index
< 4;index
++)
315 length
[1+index
] = NextPowerOf2((ALuint
)(EARLY_LINE_LENGTH
[index
]*Context
->Frequency
) + 1);
316 totalLength
+= length
[1+index
];
318 for(index
= 0;index
< 4;index
++)
320 length
[5+index
] = NextPowerOf2((ALuint
)(LATE_LINE_LENGTH
[index
]*Context
->Frequency
) + 1);
321 totalLength
+= length
[5+index
];
323 for(index
= 4;index
< 8;index
++)
325 length
[5+index
] = NextPowerOf2((ALuint
)(LATE_LINE_LENGTH
[index
]*(1.0f
+ LATE_LINE_MULTIPLIER
)*Context
->Frequency
) + 1);
326 totalLength
+= length
[5+index
];
329 // They all share a single sample buffer.
330 State
->SampleBuffer
= malloc(totalLength
* sizeof(ALfloat
));
331 if(!State
->SampleBuffer
)
336 for(index
= 0; index
< totalLength
;index
++)
337 State
->SampleBuffer
[index
] = 0.0f
;
339 // Each one has its mask and start address calculated one time.
341 State
->Delay
.Mask
= length
[0] - 1;
342 State
->Delay
.Line
= &State
->SampleBuffer
[0];
343 totalLength
= length
[0];
348 State
->Early
.Gain
= 0.0f
;
349 // All fixed-length delay lines have their read-write offsets calculated
351 for(index
= 0;index
< 4;index
++)
353 State
->Early
.Coeff
[index
] = 0.0f
;
354 State
->Early
.Delay
[index
].Mask
= length
[1 + index
] - 1;
355 State
->Early
.Delay
[index
].Line
= &State
->SampleBuffer
[totalLength
];
356 totalLength
+= length
[1 + index
];
358 State
->Early
.Offset
[index
] = (ALuint
)(EARLY_LINE_LENGTH
[index
] * Context
->Frequency
);
361 State
->Late
.Gain
= 0.0f
;
362 State
->Late
.Diffusion
= 0.0f
;
363 for(index
= 0;index
< 8;index
++)
365 State
->Late
.Coeff
[index
] = 0.0f
;
366 State
->Late
.Delay
[index
].Mask
= length
[5 + index
] - 1;
367 State
->Late
.Delay
[index
].Line
= &State
->SampleBuffer
[totalLength
];
368 totalLength
+= length
[5 + index
];
370 State
->Late
.Offset
[index
] = 0;
373 State
->Late
.Offset
[index
] = (ALuint
)(LATE_LINE_LENGTH
[index
] * Context
->Frequency
);
374 State
->Late
.LpCoeff
[index
] = 0.0f
;
375 State
->Late
.LpSample
[index
] = 0.0f
;
379 State
->Late
.LpCoeff
[index
] = 0.0f
;
380 State
->Late
.LpSample
[index
] = 0.0f
;
388 // This destroys the reverb state. It should be called only when the effect
389 // slot has a different (or no) effect loaded over the reverb effect.
390 ALvoid
VerbDestroy(ALverbState
*State
)
394 free(State
->SampleBuffer
);
395 State
->SampleBuffer
= NULL
;
400 // This updates the reverb state. This is called any time the reverb effect
401 // is loaded into a slot.
402 ALvoid
VerbUpdate(ALCcontext
*Context
, ALeffectslot
*Slot
, ALeffect
*Effect
)
404 ALverbState
*State
= Slot
->ReverbState
;
405 ALuint index
, index2
;
406 ALfloat length
, lpcoeff
, cw
, g
;
407 ALfloat hfRatio
= Effect
->Reverb
.DecayHFRatio
;
409 // Calculate the master gain (from the slot and master reverb gain).
410 State
->Gain
= Slot
->Gain
* Effect
->Reverb
.Gain
;
412 // Calculate the initial delay taps.
413 length
= Effect
->Reverb
.ReflectionsDelay
;
414 State
->Tap
[0] = (ALuint
)(length
* Context
->Frequency
);
415 length
+= Effect
->Reverb
.LateReverbDelay
;
416 State
->Tap
[1] = (ALuint
)(length
* Context
->Frequency
);
418 // Calculate the early reflections gain. Right now this uses a gain of
419 // 0.75 to compensate for the increase in density. It should probably
420 // use a power (RMS) based measurement from the resulting distribution of
421 // early delay lines.
422 State
->Early
.Gain
= Effect
->Reverb
.ReflectionsGain
* 0.75f
;
424 // Calculate the gain (coefficient) for each early delay line.
425 for(index
= 0;index
< 4;index
++)
426 State
->Early
.Coeff
[index
] = pow(10.0f
, EARLY_LINE_LENGTH
[index
] /
427 Effect
->Reverb
.LateReverbDelay
*
430 // Calculate the late reverb gain, adjusted by density, diffusion, and
431 // decay time. To be accurate, the adjustments should probably use power
432 // measurements for each contribution, but they are not too bad as they
434 State
->Late
.Gain
= Effect
->Reverb
.LateReverbGain
*
435 (0.45f
+ (0.55f
* Effect
->Reverb
.Density
)) *
436 (1.0f
- (0.25f
* Effect
->Reverb
.Diffusion
)) *
437 (1.0f
- (0.025f
* Effect
->Reverb
.DecayTime
));
438 State
->Late
.Diffusion
= Effect
->Reverb
.Diffusion
;
440 // The EFX specification does not make it clear whether the air
441 // absorption parameter should always take effect. Both Generic Software
442 // and Generic Hardware only apply it when HF limit is flagged, so that's
443 // what is done here.
444 // If the HF limit parameter is flagged, calculate an appropriate limit
445 // based on the air absorption parameter.
446 if(Effect
->Reverb
.DecayHFLimit
&& Effect
->Reverb
.AirAbsorptionGainHF
< 1.0f
)
450 // The following is my best guess at how to limit the HF ratio by the
451 // air absorption parameter.
452 // For each of the last 4 delays, find the attenuation due to air
453 // absorption in dB (converting delay time to meters using the speed
454 // of sound). Then reversing the decay equation, solve for HF ratio.
455 // The delay length is cancelled out of the equation, so it can be
456 // calculated once for all lines.
457 limitRatio
= 1.0f
/ (log10(Effect
->Reverb
.AirAbsorptionGainHF
) *
458 SPEEDOFSOUNDMETRESPERSEC
*
459 Effect
->Reverb
.DecayTime
/ -60.0f
* 20.0f
);
460 // Need to limit the result to a minimum of 0.1, just like the HF
462 limitRatio
= __max(limitRatio
, 0.1f
);
464 // Using the limit calculated above, apply the upper bound to the
466 hfRatio
= __min(hfRatio
, limitRatio
);
469 cw
= cos(2.0f
*3.141592654f
* LOWPASSFREQCUTOFF
/ Context
->Frequency
);
471 for(index
= 0;index
< 8;index
++)
473 // Calculate the length (in seconds) of each delay line.
474 length
= LATE_LINE_LENGTH
[index
];
477 // Calculate the delay offset for the variable-length delay
479 length
*= 1.0f
+ (Effect
->Reverb
.Density
* LATE_LINE_MULTIPLIER
);
480 State
->Late
.Offset
[index
] = (ALuint
)(length
* Context
->Frequency
);
482 // Calculate the gain (coefficient) for each line.
483 State
->Late
.Coeff
[index
] = pow(10.0f
, length
/ Effect
->Reverb
.DecayTime
*
489 // Calculate the decay equation for each low-pass filter.
490 g
= pow(10.0f
, length
/ (Effect
->Reverb
.DecayTime
* hfRatio
) *
492 State
->Late
.Coeff
[index
];
495 // Calculate the gain (coefficient) for each low-pass filter.
497 if(g
< 0.9999f
) // 1-epsilon
498 lpcoeff
= (1 - g
*cw
- aluSqrt(2*g
*(1-cw
) - g
*g
*(1 - cw
*cw
))) / (1 - g
);
500 // Very low decay times will produce minimal output, so apply an
501 // upper bound to the coefficient.
502 State
->Late
.LpCoeff
[index2
] = __min(lpcoeff
, 0.98f
);
506 // This just calculates the coefficient for the late reverb input low-
507 // pass filter. It is calculated based the average (hence -30 instead
508 // of -60) length of the inner two variable-length delay lines.
509 length
= LATE_LINE_LENGTH
[5] * (1.0f
+ Effect
->Reverb
.Density
* LATE_LINE_MULTIPLIER
) +
510 LATE_LINE_LENGTH
[6] * (1.0f
+ Effect
->Reverb
.Density
* LATE_LINE_MULTIPLIER
);
512 g
= pow(10.0f
, ((length
/ (Effect
->Reverb
.DecayTime
* hfRatio
))-
513 (length
/ Effect
->Reverb
.DecayTime
)) * -30.0f
/ 20.0f
);
518 if(g
< 0.9999f
) // 1-epsilon
519 lpcoeff
= (1 - g
*cw
- aluSqrt(2*g
*(1-cw
) - g
*g
*(1 - cw
*cw
))) / (1 - g
);
521 State
->Late
.LpCoeff
[0] = __min(lpcoeff
, 0.98f
);
524 // This processes the reverb state, given the input samples and an output
526 ALvoid
VerbProcess(ALverbState
*State
, ALuint SamplesToDo
, const ALfloat
*SamplesIn
, ALfloat (*SamplesOut
)[OUTPUTCHANNELS
])
529 ALfloat in
, early
[2], late
[2], out
[2];
531 for(index
= 0;index
< SamplesToDo
;index
++)
533 // Feed the initial delay line.
534 DelayLineIn(&State
->Delay
, State
->Offset
, SamplesIn
[index
]);
536 // Calculate the early reflection from the first delay tap.
537 in
= DelayLineOut(&State
->Delay
, State
->Offset
- State
->Tap
[0]);
538 EarlyReflection(State
, in
, early
);
540 // Calculate the late reverb from the second delay tap.
541 in
= DelayLineOut(&State
->Delay
, State
->Offset
- State
->Tap
[1]);
542 LateReverb(State
, in
, late
);
544 // Mix early reflections and late reverb.
545 out
[0] = State
->Gain
* (early
[0] + late
[0]);
546 out
[1] = State
->Gain
* (early
[1] + late
[1]);
548 // Step all delays forward one sample.
551 // Output the results.
552 SamplesOut
[index
][FRONT_LEFT
] += out
[0];
553 SamplesOut
[index
][FRONT_RIGHT
] += out
[1];
554 SamplesOut
[index
][SIDE_LEFT
] += out
[0];
555 SamplesOut
[index
][SIDE_RIGHT
] += out
[1];
556 SamplesOut
[index
][BACK_LEFT
] += out
[0];
557 SamplesOut
[index
][BACK_RIGHT
] += out
[1];