src/third_party/WebKit/Source/platform/audio/HRTFPanner.cpp

   1 /*
   2  * Copyright (C) 2010, Google Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1.  Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2.  Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  15  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  16  * DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  17  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  18  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  19  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  20  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  22  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23  */
  24
  25 #include "config.h"
  26
  27 #if ENABLE(WEB_AUDIO)
  28
  29 #include "platform/audio/HRTFPanner.h"
  30
  31 #include <algorithm>
  32 #include "platform/audio/AudioBus.h"
  33 #include "platform/audio/HRTFDatabase.h"
  34 #include "wtf/MathExtras.h"
  35 #include "wtf/RefPtr.h"
  36
  37 using namespace std;
  38
  39 namespace blink {
  40
  41 // The value of 2 milliseconds is larger than the largest delay which exists in any HRTFKernel from the default HRTFDatabase (0.0136 seconds).
  42 // We ASSERT the delay values used in process() with this value.
  43 const double MaxDelayTimeSeconds = 0.002;
  44
  45 const int UninitializedAzimuth = -1;
  46 const unsigned RenderingQuantum = 128;
  47
  48 HRTFPanner::HRTFPanner(float sampleRate, HRTFDatabaseLoader* databaseLoader)
  49     : Panner(PanningModelHRTF)
  50     , m_databaseLoader(databaseLoader)
  51     , m_sampleRate(sampleRate)
  52     , m_crossfadeSelection(CrossfadeSelection1)
  53     , m_azimuthIndex1(UninitializedAzimuth)
  54     , m_elevation1(0)
  55     , m_azimuthIndex2(UninitializedAzimuth)
  56     , m_elevation2(0)
  57     , m_crossfadeX(0)
  58     , m_crossfadeIncr(0)
  59     , m_convolverL1(fftSizeForSampleRate(sampleRate))
  60     , m_convolverR1(fftSizeForSampleRate(sampleRate))
  61     , m_convolverL2(fftSizeForSampleRate(sampleRate))
  62     , m_convolverR2(fftSizeForSampleRate(sampleRate))
  63     , m_delayLineL(MaxDelayTimeSeconds, sampleRate)
  64     , m_delayLineR(MaxDelayTimeSeconds, sampleRate)
  65     , m_tempL1(RenderingQuantum)
  66     , m_tempR1(RenderingQuantum)
  67     , m_tempL2(RenderingQuantum)
  68     , m_tempR2(RenderingQuantum)
  69 {
  70     ASSERT(databaseLoader);
  71 }
  72
  73 HRTFPanner::~HRTFPanner()
  74 {
  75 }
  76
  77 size_t HRTFPanner::fftSizeForSampleRate(float sampleRate)
  78 {
  79     // The HRTF impulse responses (loaded as audio resources) are 512 sample-frames @44.1KHz.
  80     // Currently, we truncate the impulse responses to half this size, but an FFT-size of twice impulse response size is needed (for convolution).
  81     // So for sample rates around 44.1KHz an FFT size of 512 is good. We double the FFT-size only for sample rates at least double this.
  82     ASSERT(sampleRate >= 44100 && sampleRate <= 96000.0);
  83     return (sampleRate < 88200.0) ? 512 : 1024;
  84 }
  85
  86 void HRTFPanner::reset()
  87 {
  88     m_convolverL1.reset();
  89     m_convolverR1.reset();
  90     m_convolverL2.reset();
  91     m_convolverR2.reset();
  92     m_delayLineL.reset();
  93     m_delayLineR.reset();
  94 }
  95
  96 int HRTFPanner::calculateDesiredAzimuthIndexAndBlend(double azimuth, double& azimuthBlend)
  97 {
  98     // Convert the azimuth angle from the range -180 -> +180 into the range 0 -> 360.
  99     // The azimuth index may then be calculated from this positive value.
 100     if (azimuth < 0)
 101         azimuth += 360.0;
 102
 103     HRTFDatabase* database = m_databaseLoader->database();
 104     ASSERT(database);
 105
 106     int numberOfAzimuths = database->numberOfAzimuths();
 107     const double angleBetweenAzimuths = 360.0 / numberOfAzimuths;
 108
 109     // Calculate the azimuth index and the blend (0 -> 1) for interpolation.
 110     double desiredAzimuthIndexFloat = azimuth / angleBetweenAzimuths;
 111     int desiredAzimuthIndex = static_cast<int>(desiredAzimuthIndexFloat);
 112     azimuthBlend = desiredAzimuthIndexFloat - static_cast<double>(desiredAzimuthIndex);
 113
 114     // We don't immediately start using this azimuth index, but instead approach this index from the last index we rendered at.
 115     // This minimizes the clicks and graininess for moving sources which occur otherwise.
 116     desiredAzimuthIndex = max(0, desiredAzimuthIndex);
 117     desiredAzimuthIndex = min(numberOfAzimuths - 1, desiredAzimuthIndex);
 118     return desiredAzimuthIndex;
 119 }
 120
 121 void HRTFPanner::pan(double desiredAzimuth, double elevation, const AudioBus* inputBus, AudioBus* outputBus, size_t framesToProcess)
 122 {
 123     unsigned numInputChannels = inputBus ? inputBus->numberOfChannels() : 0;
 124
 125     bool isInputGood = inputBus &&  numInputChannels >= 1 && numInputChannels <= 2;
 126     ASSERT(isInputGood);
 127
 128     bool isOutputGood = outputBus && outputBus->numberOfChannels() == 2 && framesToProcess <= outputBus->length();
 129     ASSERT(isOutputGood);
 130
 131     if (!isInputGood || !isOutputGood) {
 132         if (outputBus)
 133             outputBus->zero();
 134         return;
 135     }
 136
 137     HRTFDatabase* database = m_databaseLoader->database();
 138     ASSERT(database);
 139     if (!database) {
 140         outputBus->zero();
 141         return;
 142     }
 143
 144     // IRCAM HRTF azimuths values from the loaded database is reversed from the panner's notion of azimuth.
 145     double azimuth = -desiredAzimuth;
 146
 147     bool isAzimuthGood = azimuth >= -180.0 && azimuth <= 180.0;
 148     ASSERT(isAzimuthGood);
 149     if (!isAzimuthGood) {
 150         outputBus->zero();
 151         return;
 152     }
 153
 154     // Normally, we'll just be dealing with mono sources.
 155     // If we have a stereo input, implement stereo panning with left source processed by left HRTF, and right source by right HRTF.
 156     const AudioChannel* inputChannelL = inputBus->channelByType(AudioBus::ChannelLeft);
 157     const AudioChannel* inputChannelR = numInputChannels > 1 ? inputBus->channelByType(AudioBus::ChannelRight) : 0;
 158
 159     // Get source and destination pointers.
 160     const float* sourceL = inputChannelL->data();
 161     const float* sourceR = numInputChannels > 1 ? inputChannelR->data() : sourceL;
 162     float* destinationL = outputBus->channelByType(AudioBus::ChannelLeft)->mutableData();
 163     float* destinationR = outputBus->channelByType(AudioBus::ChannelRight)->mutableData();
 164
 165     double azimuthBlend;
 166     int desiredAzimuthIndex = calculateDesiredAzimuthIndexAndBlend(azimuth, azimuthBlend);
 167
 168     // Initially snap azimuth and elevation values to first values encountered.
 169     if (m_azimuthIndex1 == UninitializedAzimuth) {
 170         m_azimuthIndex1 = desiredAzimuthIndex;
 171         m_elevation1 = elevation;
 172     }
 173     if (m_azimuthIndex2 == UninitializedAzimuth) {
 174         m_azimuthIndex2 = desiredAzimuthIndex;
 175         m_elevation2 = elevation;
 176     }
 177
 178     // Cross-fade / transition over a period of around 45 milliseconds.
 179     // This is an empirical value tuned to be a reasonable trade-off between
 180     // smoothness and speed.
 181     const double fadeFrames = sampleRate() <= 48000 ? 2048 : 4096;
 182
 183     // Check for azimuth and elevation changes, initiating a cross-fade if needed.
 184     if (!m_crossfadeX && m_crossfadeSelection == CrossfadeSelection1) {
 185         if (desiredAzimuthIndex != m_azimuthIndex1 || elevation != m_elevation1) {
 186             // Cross-fade from 1 -> 2
 187             m_crossfadeIncr = 1 / fadeFrames;
 188             m_azimuthIndex2 = desiredAzimuthIndex;
 189             m_elevation2 = elevation;
 190         }
 191     }
 192     if (m_crossfadeX == 1 && m_crossfadeSelection == CrossfadeSelection2) {
 193         if (desiredAzimuthIndex != m_azimuthIndex2 || elevation != m_elevation2) {
 194             // Cross-fade from 2 -> 1
 195             m_crossfadeIncr = -1 / fadeFrames;
 196             m_azimuthIndex1 = desiredAzimuthIndex;
 197             m_elevation1 = elevation;
 198         }
 199     }
 200
 201     // This algorithm currently requires that we process in power-of-two size chunks at least RenderingQuantum.
 202     ASSERT(1UL << static_cast<int>(log2(framesToProcess)) == framesToProcess);
 203     ASSERT(framesToProcess >= RenderingQuantum);
 204
 205     const unsigned framesPerSegment = RenderingQuantum;
 206     const unsigned numberOfSegments = framesToProcess / framesPerSegment;
 207
 208     for (unsigned segment = 0; segment < numberOfSegments; ++segment) {
 209         // Get the HRTFKernels and interpolated delays.
 210         HRTFKernel* kernelL1;
 211         HRTFKernel* kernelR1;
 212         HRTFKernel* kernelL2;
 213         HRTFKernel* kernelR2;
 214         double frameDelayL1;
 215         double frameDelayR1;
 216         double frameDelayL2;
 217         double frameDelayR2;
 218         database->getKernelsFromAzimuthElevation(azimuthBlend, m_azimuthIndex1, m_elevation1, kernelL1, kernelR1, frameDelayL1, frameDelayR1);
 219         database->getKernelsFromAzimuthElevation(azimuthBlend, m_azimuthIndex2, m_elevation2, kernelL2, kernelR2, frameDelayL2, frameDelayR2);
 220
 221         bool areKernelsGood = kernelL1 && kernelR1 && kernelL2 && kernelR2;
 222         ASSERT(areKernelsGood);
 223         if (!areKernelsGood) {
 224             outputBus->zero();
 225             return;
 226         }
 227
 228         ASSERT(frameDelayL1 / sampleRate() < MaxDelayTimeSeconds && frameDelayR1 / sampleRate() < MaxDelayTimeSeconds);
 229         ASSERT(frameDelayL2 / sampleRate() < MaxDelayTimeSeconds && frameDelayR2 / sampleRate() < MaxDelayTimeSeconds);
 230
 231         // Crossfade inter-aural delays based on transitions.
 232         double frameDelayL = (1 - m_crossfadeX) * frameDelayL1 + m_crossfadeX * frameDelayL2;
 233         double frameDelayR = (1 - m_crossfadeX) * frameDelayR1 + m_crossfadeX * frameDelayR2;
 234
 235         // Calculate the source and destination pointers for the current segment.
 236         unsigned offset = segment * framesPerSegment;
 237         const float* segmentSourceL = sourceL + offset;
 238         const float* segmentSourceR = sourceR + offset;
 239         float* segmentDestinationL = destinationL + offset;
 240         float* segmentDestinationR = destinationR + offset;
 241
 242         // First run through delay lines for inter-aural time difference.
 243         m_delayLineL.setDelayFrames(frameDelayL);
 244         m_delayLineR.setDelayFrames(frameDelayR);
 245         m_delayLineL.process(segmentSourceL, segmentDestinationL, framesPerSegment);
 246         m_delayLineR.process(segmentSourceR, segmentDestinationR, framesPerSegment);
 247
 248         bool needsCrossfading = m_crossfadeIncr;
 249
 250         // Have the convolvers render directly to the final destination if we're not cross-fading.
 251         float* convolutionDestinationL1 = needsCrossfading ? m_tempL1.data() : segmentDestinationL;
 252         float* convolutionDestinationR1 = needsCrossfading ? m_tempR1.data() : segmentDestinationR;
 253         float* convolutionDestinationL2 = needsCrossfading ? m_tempL2.data() : segmentDestinationL;
 254         float* convolutionDestinationR2 = needsCrossfading ? m_tempR2.data() : segmentDestinationR;
 255
 256         // Now do the convolutions.
 257         // Note that we avoid doing convolutions on both sets of convolvers if we're not currently cross-fading.
 258
 259         if (m_crossfadeSelection == CrossfadeSelection1 || needsCrossfading) {
 260             m_convolverL1.process(kernelL1->fftFrame(), segmentDestinationL, convolutionDestinationL1, framesPerSegment);
 261             m_convolverR1.process(kernelR1->fftFrame(), segmentDestinationR, convolutionDestinationR1, framesPerSegment);
 262         }
 263
 264         if (m_crossfadeSelection == CrossfadeSelection2 || needsCrossfading) {
 265             m_convolverL2.process(kernelL2->fftFrame(), segmentDestinationL, convolutionDestinationL2, framesPerSegment);
 266             m_convolverR2.process(kernelR2->fftFrame(), segmentDestinationR, convolutionDestinationR2, framesPerSegment);
 267         }
 268
 269         if (needsCrossfading) {
 270             // Apply linear cross-fade.
 271             float x = m_crossfadeX;
 272             float incr = m_crossfadeIncr;
 273             for (unsigned i = 0; i < framesPerSegment; ++i) {
 274                 segmentDestinationL[i] = (1 - x) * convolutionDestinationL1[i] + x * convolutionDestinationL2[i];
 275                 segmentDestinationR[i] = (1 - x) * convolutionDestinationR1[i] + x * convolutionDestinationR2[i];
 276                 x += incr;
 277             }
 278             // Update cross-fade value from local.
 279             m_crossfadeX = x;
 280
 281             if (m_crossfadeIncr > 0 && fabs(m_crossfadeX - 1) < m_crossfadeIncr) {
 282                 // We've fully made the crossfade transition from 1 -> 2.
 283                 m_crossfadeSelection = CrossfadeSelection2;
 284                 m_crossfadeX = 1;
 285                 m_crossfadeIncr = 0;
 286             } else if (m_crossfadeIncr < 0 && fabs(m_crossfadeX) < -m_crossfadeIncr) {
 287                 // We've fully made the crossfade transition from 2 -> 1.
 288                 m_crossfadeSelection = CrossfadeSelection1;
 289                 m_crossfadeX = 0;
 290                 m_crossfadeIncr = 0;
 291             }
 292         }
 293     }
 294 }
 295
 296 double HRTFPanner::tailTime() const
 297 {
 298     // Because HRTFPanner is implemented with a DelayKernel and a FFTConvolver, the tailTime of the HRTFPanner
 299     // is the sum of the tailTime of the DelayKernel and the tailTime of the FFTConvolver, which is MaxDelayTimeSeconds
 300     // and fftSize() / 2, respectively.
 301     return MaxDelayTimeSeconds + (fftSize() / 2) / static_cast<double>(sampleRate());
 302 }
 303
 304 double HRTFPanner::latencyTime() const
 305 {
 306     // The latency of a FFTConvolver is also fftSize() / 2, and is in addition to its tailTime of the
 307     // same value.
 308     return (fftSize() / 2) / static_cast<double>(sampleRate());
 309 }
 310
 311 } // namespace blink
 312
 313 #endif // ENABLE(WEB_AUDIO)