Source/WebCore/platform/audio/AudioBus.h

   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  *
   8  * 1.  Redistributions of source code must retain the above copyright
   9  *     notice, this list of conditions and the following disclaimer.
  10  * 2.  Redistributions in binary form must reproduce the above copyright
  11  *     notice, this list of conditions and the following disclaimer in the
  12  *     documentation and/or other materials provided with the distribution.
  13  * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
  14  *     its contributors may be used to endorse or promote products derived
  15  *     from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
  18  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  20  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 #ifndef AudioBus_h
  30 #define AudioBus_h
  31
  32 #include "AudioChannel.h"
  33 #include <wtf/Noncopyable.h>
  34 #include <wtf/PassOwnPtr.h>
  35 #include <wtf/Vector.h>
  36
  37 namespace WebCore {
  38
  39 // An AudioBus represents a collection of one or more AudioChannels.
  40 // The data layout is "planar" as opposed to "interleaved".
  41 // An AudioBus with one channel is mono, an AudioBus with two channels is stereo, etc.
  42 class AudioBus  : public Noncopyable {
  43 public:
  44     enum {
  45         ChannelLeft = 0,
  46         ChannelRight = 1,
  47         ChannelCenter = 2, // center and mono are the same
  48         ChannelMono = 2,
  49         ChannelLFE = 3,
  50         ChannelSurroundLeft = 4,
  51         ChannelSurroundRight = 5,
  52     };
  53
  54     enum {
  55         LayoutCanonical = 0
  56         // Can define non-standard layouts here
  57     };
  58
  59     // allocate indicates whether or not to initially have the AudioChannels created with managed storage.
  60     // Normal usage is to pass true here, in which case the AudioChannels will memory-manage their own storage.
  61     // If allocate is false then setChannelMemory() has to be called later on for each channel before the AudioBus is useable...
  62     AudioBus(unsigned numberOfChannels, size_t length, bool allocate = true);
  63
  64     // Tells the given channel to use an externally allocated buffer.
  65     void setChannelMemory(unsigned channelIndex, float* storage, size_t length);
  66
  67     // Channels
  68     unsigned numberOfChannels() const { return m_channels.size(); }
  69
  70     AudioChannel* channel(unsigned channel) { return m_channels[channel].get(); }
  71     const AudioChannel* channel(unsigned channel) const { return const_cast<AudioBus*>(this)->m_channels[channel].get(); }
  72     AudioChannel* channelByType(unsigned type);
  73
  74     // Number of sample-frames
  75     size_t length() const { return m_length; }
  76
  77     // Sample-rate : 0.0 if unknown or "don't care"
  78     double sampleRate() const { return m_sampleRate; }
  79     void setSampleRate(double sampleRate) { m_sampleRate = sampleRate; }
  80
  81     // Zeroes all channels.
  82     void zero();
  83
  84     // Returns true if the channel count and frame-size match.
  85     bool topologyMatches(const AudioBus &sourceBus) const;
  86
  87     // Creates a new buffer from a range in the source buffer.
  88     // 0 may be returned if the range does not fit in the sourceBuffer
  89     static PassOwnPtr<AudioBus> createBufferFromRange(AudioBus* sourceBuffer, unsigned startFrame, unsigned endFrame);
  90
  91     // Scales all samples by the same amount.
  92     void scale(double scale);
  93
  94     // Master gain for this bus - used with sumWithGainFrom() below
  95     void setGain(double gain) { m_busGain = gain; }
  96     double gain() { return m_busGain; }
  97
  98     void reset() { m_isFirstTime = true; } // for de-zippering
  99
 100     // Assuming sourceBus has the same topology, copies sample data from each channel of sourceBus to our corresponding channel.
 101     void copyFrom(const AudioBus &sourceBus);
 102
 103     // Sums the sourceBus into our bus with unity gain.
 104     // Our own internal gain m_busGain is ignored.
 105     void sumFrom(const AudioBus &sourceBus);
 106
 107     // Copy or sum each channel from sourceBus into our corresponding channel.
 108     // We scale by targetGain (and our own internal gain m_busGain), performing "de-zippering" to smoothly change from *lastMixGain to (targetGain*m_busGain).
 109     // The caller is responsible for setting up lastMixGain to point to storage which is unique for every "stream" which will be summed to this bus.
 110     // This represents the dezippering memory.
 111     void copyWithGainFrom(const AudioBus &sourceBus, double* lastMixGain, double targetGain);
 112     void sumWithGainFrom(const AudioBus &sourceBus, double* lastMixGain, double targetGain);
 113
 114     // Returns maximum absolute value across all channels (useful for normalization).
 115     float maxAbsValue() const;
 116
 117     // Makes maximum absolute value == 1.0 (if possible).
 118     void normalize();
 119
 120     static PassOwnPtr<AudioBus> loadPlatformResource(const char* name, double sampleRate);
 121
 122 protected:
 123     AudioBus() { };
 124
 125     void processWithGainFrom(const AudioBus &sourceBus, double* lastMixGain, double targetGain, bool sumToBus);
 126     void processWithGainFromMonoStereo(const AudioBus &sourceBus, double* lastMixGain, double targetGain, bool sumToBus);
 127
 128     size_t m_length;
 129
 130     Vector<OwnPtr<AudioChannel> > m_channels;
 131
 132     int m_layout;
 133
 134     double m_busGain;
 135     bool m_isFirstTime;
 136     double m_sampleRate; // 0.0 if unknown or N/A
 137 };
 138
 139 } // WebCore
 140
 141 #endif // AudioBus_h