reflow comments in modules/{webaudio,vr}

third_party/WebKit/Source/modules/webaudio/AudioBufferSourceNode.cpp

 /*
  * Copyright (C) 2010, Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1.  Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2.  Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
@@ skipping 23 matching lines @@
 #include "platform/audio/AudioUtilities.h"
 #include "wtf/MathExtras.h"
 #include "wtf/PtrUtil.h"
 #include <algorithm>
 
 namespace blink {
 
 const double DefaultGrainDuration = 0.020;  // 20ms
 
 // Arbitrary upper limit on playback rate.
-// Higher than expected rates can be useful when playing back oversampled buffers
-// to minimize linear interpolation aliasing.
+// Higher than expected rates can be useful when playing back oversampled
+// buffers to minimize linear interpolation aliasing.
 const double MaxRate = 1024;
 
-// Number of extra frames to use when determining if a source node can be stopped.  This should be
-// at least one rendering quantum, but we add one more quantum for good measure.  This doesn't need
-// to be extra precise, just more than one rendering quantum.  See |handleStoppableSourceNode()|.
-// FIXME: Expose the rendering quantum somehow instead of hardwiring a value here.
+// Number of extra frames to use when determining if a source node can be
+// stopped.  This should be at least one rendering quantum, but we add one more
+// quantum for good measure.  This doesn't need to be extra precise, just more
+// than one rendering quantum.  See |handleStoppableSourceNode()|.
+// FIXME: Expose the rendering quantum somehow instead of hardwiring a value
+// here.
 const int kExtraStopFrames = 256;
 
 AudioBufferSourceHandler::AudioBufferSourceHandler(
     AudioNode& node,
     float sampleRate,
     AudioParamHandler& playbackRate,
     AudioParamHandler& detune)
     : AudioScheduledSourceHandler(NodeTypeAudioBufferSource, node, sampleRate),
       m_buffer(nullptr),
       m_playbackRate(playbackRate),
@@ skipping 36 matching lines @@
   }
 
   // The audio thread can't block on this lock, so we call tryLock() instead.
   MutexTryLocker tryLocker(m_processLock);
   if (tryLocker.locked()) {
     if (!buffer()) {
       outputBus->zero();
       return;
     }
 
-    // After calling setBuffer() with a buffer having a different number of channels, there can in rare cases be a slight delay
-    // before the output bus is updated to the new number of channels because of use of tryLocks() in the context's updating system.
-    // In this case, if the the buffer has just been changed and we're not quite ready yet, then just output silence.
+    // After calling setBuffer() with a buffer having a different number of
+    // channels, there can in rare cases be a slight delay before the output bus
+    // is updated to the new number of channels because of use of tryLocks() in
+    // the context's updating system.  In this case, if the the buffer has just
+    // been changed and we're not quite ready yet, then just output silence.
     if (numberOfChannels() != buffer()->numberOfChannels()) {
       outputBus->zero();
       return;
     }
 
     size_t quantumFrameOffset;
     size_t bufferFramesToProcess;
 
     updateSchedulingInfo(framesToProcess, outputBus, quantumFrameOffset,
                          bufferFramesToProcess);
 
     if (!bufferFramesToProcess) {
       outputBus->zero();
       return;
     }
 
     for (unsigned i = 0; i < outputBus->numberOfChannels(); ++i)
       m_destinationChannels[i] = outputBus->channel(i)->mutableData();
 
     // Render by reading directly from the buffer.
     if (!renderFromBuffer(outputBus, quantumFrameOffset,
                           bufferFramesToProcess)) {
       outputBus->zero();
       return;
     }
 
     outputBus->clearSilentFlag();
   } else {
-    // Too bad - the tryLock() failed.  We must be in the middle of changing buffers and were already outputting silence anyway.
+    // Too bad - the tryLock() failed.  We must be in the middle of changing
+    // buffers and were already outputting silence anyway.
     outputBus->zero();
   }
 }
 
 // Returns true if we're finished.
 bool AudioBufferSourceHandler::renderSilenceAndFinishIfNotLooping(
     AudioBus*,
     unsigned index,
     size_t framesToProcess) {
   if (!loop()) {
     // If we're not looping, then stop playing when we get to the end.
 
     if (framesToProcess > 0) {
-      // We're not looping and we've reached the end of the sample data, but we still need to provide more output,
-      // so generate silence for the remaining.
+      // We're not looping and we've reached the end of the sample data, but we
+      // still need to provide more output, so generate silence for the
+      // remaining.
       for (unsigned i = 0; i < numberOfChannels(); ++i)
         memset(m_destinationChannels[i] + index, 0,
                sizeof(float) * framesToProcess);
     }
 
     finish();
     return true;
   }
   return false;
 }
@@ skipping 49 matching lines @@
   double bufferSampleRate = buffer()->sampleRate();
 
   // Avoid converting from time to sample-frames twice by computing
   // the grain end time first before computing the sample frame.
   unsigned endFrame =
       m_isGrain ? AudioUtilities::timeToSampleFrame(
                       m_grainOffset + m_grainDuration, bufferSampleRate)
                 : bufferLength;
 
   // This is a HACK to allow for HRTF tail-time - avoids glitch at end.
-  // FIXME: implement tailTime for each AudioNode for a more general solution to this problem.
-  // https://bugs.webkit.org/show_bug.cgi?id=77224
+  // FIXME: implement tailTime for each AudioNode for a more general solution to
+  // this problem, https://bugs.webkit.org/show_bug.cgi?id=77224
   if (m_isGrain)
     endFrame += 512;
 
   // Do some sanity checking.
   if (endFrame > bufferLength)
     endFrame = bufferLength;
 
-  // If the .loop attribute is true, then values of m_loopStart == 0 && m_loopEnd == 0 implies
-  // that we should use the entire buffer as the loop, otherwise use the loop values in m_loopStart and m_loopEnd.
+  // If the .loop attribute is true, then values of
+  // m_loopStart == 0 && m_loopEnd == 0 implies that we should use the entire
+  // buffer as the loop, otherwise use the loop values in m_loopStart and
+  // m_loopEnd.
   double virtualEndFrame = endFrame;
   double virtualDeltaFrames = endFrame;
 
   if (loop() && (m_loopStart || m_loopEnd) && m_loopStart >= 0 &&
       m_loopEnd > 0 && m_loopStart < m_loopEnd) {
     // Convert from seconds to sample-frames.
     double loopStartFrame = m_loopStart * buffer()->sampleRate();
     double loopEndFrame = m_loopEnd * buffer()->sampleRate();
 
     virtualEndFrame = std::min(loopEndFrame, virtualEndFrame);
     virtualDeltaFrames = virtualEndFrame - loopStartFrame;
   }
 
-  // If we're looping and the offset (virtualReadIndex) is past the end of the loop, wrap back to
-  // the beginning of the loop. For other cases, nothing needs to be done.
+  // If we're looping and the offset (virtualReadIndex) is past the end of the
+  // loop, wrap back to the beginning of the loop. For other cases, nothing
+  // needs to be done.
   if (loop() && m_virtualReadIndex >= virtualEndFrame) {
     m_virtualReadIndex =
         (m_loopStart < 0) ? 0 : (m_loopStart * buffer()->sampleRate());
     m_virtualReadIndex =
         std::min(m_virtualReadIndex, static_cast<double>(bufferLength - 1));
   }
 
   double computedPlaybackRate = computePlaybackRate();
 
   // Sanity check that our playback rate isn't larger than the loop size.
   if (computedPlaybackRate > virtualDeltaFrames)
     return false;
 
   // Get local copy.
   double virtualReadIndex = m_virtualReadIndex;
 
-  // Render loop - reading from the source buffer to the destination using linear interpolation.
+  // Render loop - reading from the source buffer to the destination using
+  // linear interpolation.
   int framesToProcess = numberOfFrames;
 
   const float** sourceChannels = m_sourceChannels.get();
   float** destinationChannels = m_destinationChannels.get();
 
   DCHECK_GE(virtualReadIndex, 0);
   DCHECK_GE(virtualDeltaFrames, 0);
   DCHECK_GE(virtualEndFrame, 0);
 
-  // Optimize for the very common case of playing back with computedPlaybackRate == 1.
-  // We can avoid the linear interpolation.
+  // Optimize for the very common case of playing back with
+  // computedPlaybackRate == 1.  We can avoid the linear interpolation.
   if (computedPlaybackRate == 1 &&
       virtualReadIndex == floor(virtualReadIndex) &&
       virtualDeltaFrames == floor(virtualDeltaFrames) &&
       virtualEndFrame == floor(virtualEndFrame)) {
     unsigned readIndex = static_cast<unsigned>(virtualReadIndex);
     unsigned deltaFrames = static_cast<unsigned>(virtualDeltaFrames);
     endFrame = static_cast<unsigned>(virtualEndFrame);
     while (framesToProcess > 0) {
       int framesToEnd = endFrame - readIndex;
       int framesThisTime = std::min(framesToProcess, framesToEnd);
       framesThisTime = std::max(0, framesThisTime);
 
       DCHECK_LE(writeIndex + framesThisTime, destinationLength);
       DCHECK_LE(readIndex + framesThisTime, bufferLength);
 
       for (unsigned i = 0; i < numberOfChannels; ++i)
         memcpy(destinationChannels[i] + writeIndex,
                sourceChannels[i] + readIndex, sizeof(float) * framesThisTime);
 
       writeIndex += framesThisTime;
       readIndex += framesThisTime;
       framesToProcess -= framesThisTime;
 
-      // It can happen that framesThisTime is 0. DCHECK that we will actually exit the loop in
-      // this case.  framesThisTime is 0 only if readIndex >= endFrame;
+      // It can happen that framesThisTime is 0. DCHECK that we will actually
+      // exit the loop in this case.  framesThisTime is 0 only if
+      // readIndex >= endFrame;
       DCHECK(framesThisTime ? true : readIndex >= endFrame);
 
       // Wrap-around.
       if (readIndex >= endFrame) {
         readIndex -= deltaFrames;
         if (renderSilenceAndFinishIfNotLooping(bus, writeIndex,
                                                framesToProcess))
           break;
       }
     }
     virtualReadIndex = readIndex;
   } else {
     while (framesToProcess--) {
       unsigned readIndex = static_cast<unsigned>(virtualReadIndex);
       double interpolationFactor = virtualReadIndex - readIndex;
 
       // For linear interpolation we need the next sample-frame too.
       unsigned readIndex2 = readIndex + 1;
       if (readIndex2 >= bufferLength) {
         if (loop()) {
           // Make sure to wrap around at the end of the buffer.
           readIndex2 =
               static_cast<unsigned>(virtualReadIndex + 1 - virtualDeltaFrames);
         } else {
           readIndex2 = readIndex;
         }
       }
 
       // Final sanity check on buffer access.
-      // FIXME: as an optimization, try to get rid of this inner-loop check and put assertions and guards before the loop.
+      // FIXME: as an optimization, try to get rid of this inner-loop check and
+      // put assertions and guards before the loop.
       if (readIndex >= bufferLength || readIndex2 >= bufferLength)
         break;
 
       // Linear interpolation.
       for (unsigned i = 0; i < numberOfChannels; ++i) {
         float* destination = destinationChannels[i];
         const float* source = sourceChannels[i];
 
         double sample1 = source[readIndex];
         double sample2 = source[readIndex2];
         double sample = (1.0 - interpolationFactor) * sample1 +
                         interpolationFactor * sample2;
 
         destination[writeIndex] = clampTo<float>(sample);
       }
       writeIndex++;
 
       virtualReadIndex += computedPlaybackRate;
 
-      // Wrap-around, retaining sub-sample position since virtualReadIndex is floating-point.
+      // Wrap-around, retaining sub-sample position since virtualReadIndex is
+      // floating-point.
       if (virtualReadIndex >= virtualEndFrame) {
         virtualReadIndex -= virtualDeltaFrames;
         if (renderSilenceAndFinishIfNotLooping(bus, writeIndex,
                                                framesToProcess))
           break;
       }
     }
   }
 
   bus->clearSilentFlag();
 
   m_virtualReadIndex = virtualReadIndex;
 
   return true;
 }
 
 void AudioBufferSourceHandler::setBuffer(AudioBuffer* buffer,
                                          ExceptionState& exceptionState) {
   DCHECK(isMainThread());
 
   if (m_buffer) {
     exceptionState.throwDOMException(
         InvalidStateError,
         "Cannot set buffer after it has been already been set");
     return;
   }
 
-  // The context must be locked since changing the buffer can re-configure the number of channels that are output.
+  // The context must be locked since changing the buffer can re-configure the
+  // number of channels that are output.
   BaseAudioContext::AutoLocker contextLocker(context());
 
   // This synchronizes with process().
   MutexLocker processLocker(m_processLock);
 
   if (buffer) {
     // Do any necesssary re-configuration to the buffer's number of channels.
     unsigned numberOfChannels = buffer->numberOfChannels();
 
-    // This should not be possible since AudioBuffers can't be created with too many channels
-    // either.
+    // This should not be possible since AudioBuffers can't be created with too
+    // many channels either.
     if (numberOfChannels > BaseAudioContext::maxNumberOfChannels()) {
       exceptionState.throwDOMException(
           NotSupportedError, ExceptionMessages::indexOutsideRange(
                                  "number of input channels", numberOfChannels,
                                  1u, ExceptionMessages::InclusiveBound,
                                  BaseAudioContext::maxNumberOfChannels(),
                                  ExceptionMessages::InclusiveBound));
       return;
     }
 
     output(0).setNumberOfChannels(numberOfChannels);
 
     m_sourceChannels = wrapArrayUnique(new const float*[numberOfChannels]);
     m_destinationChannels = wrapArrayUnique(new float*[numberOfChannels]);
 
     for (unsigned i = 0; i < numberOfChannels; ++i)
       m_sourceChannels[i] = buffer->getChannelData(i)->data();
 
-    // If this is a grain (as set by a previous call to start()), validate the grain parameters
-    // now since it wasn't validated when start was called (because there was no buffer then).
+    // If this is a grain (as set by a previous call to start()), validate the
+    // grain parameters now since it wasn't validated when start was called
+    // (because there was no buffer then).
     if (m_isGrain)
       clampGrainParameters(buffer);
   }
 
   m_virtualReadIndex = 0;
   m_buffer = buffer;
 }
 
 unsigned AudioBufferSourceHandler::numberOfChannels() {
   return output(0).numberOfChannels();
 }
 
 void AudioBufferSourceHandler::clampGrainParameters(const AudioBuffer* buffer) {
   DCHECK(buffer);
 
-  // We have a buffer so we can clip the offset and duration to lie within the buffer.
+  // We have a buffer so we can clip the offset and duration to lie within the
+  // buffer.
   double bufferDuration = buffer->duration();
 
   m_grainOffset = clampTo(m_grainOffset, 0.0, bufferDuration);
 
-  // If the duration was not explicitly given, use the buffer duration to set the grain
-  // duration. Otherwise, we want to use the user-specified value, of course.
+  // If the duration was not explicitly given, use the buffer duration to set
+  // the grain duration. Otherwise, we want to use the user-specified value, of
+  // course.
   if (!m_isDurationGiven)
     m_grainDuration = bufferDuration - m_grainOffset;
 
   if (m_isDurationGiven && loop()) {
-    // We're looping a grain with a grain duration specified. Schedule the loop to stop after
-    // grainDuration seconds after starting, possibly running the loop multiple times if
-    // grainDuration is larger than the buffer duration. The net effect is as if the user called
-    // stop(when + grainDuration).
+    // We're looping a grain with a grain duration specified. Schedule the loop
+    // to stop after grainDuration seconds after starting, possibly running the
+    // loop multiple times if grainDuration is larger than the buffer duration.
+    // The net effect is as if the user called stop(when + grainDuration).
     m_grainDuration =
         clampTo(m_grainDuration, 0.0, std::numeric_limits<double>::infinity());
     m_endTime = m_startTime + m_grainDuration;
   } else {
     m_grainDuration =
         clampTo(m_grainDuration, 0.0, bufferDuration - m_grainOffset);
   }
 
-  // We call timeToSampleFrame here since at playbackRate == 1 we don't want to go through
-  // linear interpolation at a sub-sample position since it will degrade the quality. When
-  // aligned to the sample-frame the playback will be identical to the PCM data stored in the
-  // buffer. Since playbackRate == 1 is very common, it's worth considering quality.
+  // We call timeToSampleFrame here since at playbackRate == 1 we don't want to
+  // go through linear interpolation at a sub-sample position since it will
+  // degrade the quality. When aligned to the sample-frame the playback will be
+  // identical to the PCM data stored in the buffer. Since playbackRate == 1 is
+  // very common, it's worth considering quality.
   m_virtualReadIndex =
       AudioUtilities::timeToSampleFrame(m_grainOffset, buffer->sampleRate());
 }
 
 void AudioBufferSourceHandler::start(double when,
                                      ExceptionState& exceptionState) {
   AudioScheduledSourceHandler::start(when, exceptionState);
 }
 
 void AudioBufferSourceHandler::start(double when,
@@ skipping 46 matching lines @@
                                "duration", grainDuration, 0.0));
     return;
   }
 
   // The node is started. Add a reference to keep us alive so that audio
   // will eventually get played even if Javascript should drop all references
   // to this node. The reference will get dropped when the source has finished
   // playing.
   context()->notifySourceNodeStartedProcessing(node());
 
-  // This synchronizes with process(). updateSchedulingInfo will read some of the variables being
-  // set here.
+  // This synchronizes with process(). updateSchedulingInfo will read some of
+  // the variables being set here.
   MutexLocker processLocker(m_processLock);
 
   m_isDurationGiven = isDurationGiven;
   m_isGrain = true;
   m_grainOffset = grainOffset;
   m_grainDuration = grainDuration;
 
   // If |when| < currentTime, the source must start now according to the spec.
   // So just set startTime to currentTime in this case to start the source now.
   m_startTime = std::max(when, context()->currentTime());
@@ skipping 39 matching lines @@
   m_minPlaybackRate = std::min(finalPlaybackRate, m_minPlaybackRate);
 
   return finalPlaybackRate;
 }
 
 bool AudioBufferSourceHandler::propagatesSilence() const {
   return !isPlayingOrScheduled() || hasFinished() || !m_buffer;
 }
 
 void AudioBufferSourceHandler::handleStoppableSourceNode() {
-  // If the source node is not looping, and we have a buffer, we can determine when the source
-  // would stop playing.  This is intended to handle the (uncommon) scenario where start() has
-  // been called but is never connected to the destination (directly or indirectly).  By stopping
-  // the node, the node can be collected.  Otherwise, the node will never get collected, leaking
+  // If the source node is not looping, and we have a buffer, we can determine
+  // when the source would stop playing.  This is intended to handle the
+  // (uncommon) scenario where start() has been called but is never connected to
+  // the destination (directly or indirectly).  By stopping the node, the node
+  // can be collected.  Otherwise, the node will never get collected, leaking
   // memory.
   //
-  // If looping was ever done (m_didSetLooping = true), give up.  We can't easily determine how
-  // long we looped so we don't know the actual duration thus far, so don't try to do anything
-  // fancy.
+  // If looping was ever done (m_didSetLooping = true), give up.  We can't
+  // easily determine how long we looped so we don't know the actual duration
+  // thus far, so don't try to do anything fancy.
   if (!m_didSetLooping && buffer() && isPlayingOrScheduled() &&
       m_minPlaybackRate > 0) {
-    // Adjust the duration to include the playback rate. Only need to account for rate < 1
-    // which makes the sound last longer.  For rate >= 1, the source stops sooner, but that's
-    // ok.
+    // Adjust the duration to include the playback rate. Only need to account
+    // for rate < 1 which makes the sound last longer.  For rate >= 1, the
+    // source stops sooner, but that's ok.
     double actualDuration = buffer()->duration() / m_minPlaybackRate;
 
     double stopTime = m_startTime + actualDuration;
 
-    // See crbug.com/478301. If a source node is started via start(), the source may not start
-    // at that time but one quantum (128 frames) later.  But we compute the stop time based on
-    // the start time and the duration, so we end up stopping one quantum early.  Thus, add a
-    // little extra time; we just need to stop the source sometime after it should have stopped
-    // if it hadn't already.  We don't need to be super precise on when to stop.
+    // See crbug.com/478301. If a source node is started via start(), the source
+    // may not start at that time but one quantum (128 frames) later.  But we
+    // compute the stop time based on the start time and the duration, so we end
+    // up stopping one quantum early.  Thus, add a little extra time; we just
+    // need to stop the source sometime after it should have stopped if it
+    // hadn't already.  We don't need to be super precise on when to stop.
     double extraStopTime =
         kExtraStopFrames / static_cast<double>(context()->sampleRate());
 
     stopTime += extraStopTime;
     if (context()->currentTime() > stopTime) {
-      // The context time has passed the time when the source nodes should have stopped
-      // playing. Stop the node now and deref it. (But don't run the onEnded event because the
-      // source never actually played.)
+      // The context time has passed the time when the source nodes should have
+      // stopped playing. Stop the node now and deref it. (But don't run the
+      // onEnded event because the source never actually played.)
       finishWithoutOnEnded();
     }
   }
 }
 
 // ----------------------------------------------------------------
 AudioBufferSourceNode::AudioBufferSourceNode(BaseAudioContext& context)
     : AudioScheduledSourceNode(context),
       m_playbackRate(AudioParam::create(context,
                                         ParamTypeAudioBufferSourcePlaybackRate,
@@ skipping 113 matching lines @@
 
 void AudioBufferSourceNode::start(double when,
                                   double grainOffset,
                                   double grainDuration,
                                   ExceptionState& exceptionState) {
   audioBufferSourceHandler().start(when, grainOffset, grainDuration,
                                    exceptionState);
 }
 
 }  // namespace blink