third_party/WebKit/Source/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 "platform/audio/AudioChannel.h"
  33 #include "wtf/Noncopyable.h"
  34 #include "wtf/PassOwnPtr.h"
  35 #include "wtf/ThreadSafeRefCounted.h"
  36 #include "wtf/Vector.h"
  37
  38 namespace blink {
  39
  40 // An AudioBus represents a collection of one or more AudioChannels.
  41 // The data layout is "planar" as opposed to "interleaved".
  42 // An AudioBus with one channel is mono, an AudioBus with two channels is stereo, etc.
  43 class PLATFORM_EXPORT AudioBus : public ThreadSafeRefCounted<AudioBus> {
  44     WTF_MAKE_NONCOPYABLE(AudioBus);
  45 public:
  46     enum {
  47         ChannelLeft = 0,
  48         ChannelRight = 1,
  49         ChannelCenter = 2, // center and mono are the same
  50         ChannelMono = 2,
  51         ChannelLFE = 3,
  52         ChannelSurroundLeft = 4,
  53         ChannelSurroundRight = 5,
  54     };
  55
  56     enum {
  57         LayoutCanonical = 0
  58         // Can define non-standard layouts here
  59     };
  60
  61     enum ChannelInterpretation {
  62         Speakers,
  63         Discrete,
  64     };
  65
  66     // allocate indicates whether or not to initially have the AudioChannels created with managed storage.
  67     // Normal usage is to pass true here, in which case the AudioChannels will memory-manage their own storage.
  68     // If allocate is false then setChannelMemory() has to be called later on for each channel before the AudioBus is useable...
  69     static PassRefPtr<AudioBus> create(unsigned numberOfChannels, size_t length, bool allocate = true);
  70
  71     // Tells the given channel to use an externally allocated buffer.
  72     void setChannelMemory(unsigned channelIndex, float* storage, size_t length);
  73
  74     // Channels
  75     unsigned numberOfChannels() const { return m_channels.size(); }
  76
  77     AudioChannel* channel(unsigned channel) { return m_channels[channel].get(); }
  78     const AudioChannel* channel(unsigned channel) const { return const_cast<AudioBus*>(this)->m_channels[channel].get(); }
  79     AudioChannel* channelByType(unsigned type);
  80     const AudioChannel* channelByType(unsigned type) const;
  81
  82     // Number of sample-frames
  83     size_t length() const { return m_length; }
  84
  85     // resizeSmaller() can only be called with a new length <= the current length.
  86     // The data stored in the bus will remain undisturbed.
  87     void resizeSmaller(size_t newLength);
  88
  89     // Sample-rate : 0.0 if unknown or "don't care"
  90     float sampleRate() const { return m_sampleRate; }
  91     void setSampleRate(float sampleRate) { m_sampleRate = sampleRate; }
  92
  93     // Zeroes all channels.
  94     void zero();
  95
  96     // Clears the silent flag on all channels.
  97     void clearSilentFlag();
  98
  99     // Returns true if the silent bit is set on all channels.
 100     bool isSilent() const;
 101
 102     // Returns true if the channel count and frame-size match.
 103     bool topologyMatches(const AudioBus &sourceBus) const;
 104
 105     // Creates a new buffer from a range in the source buffer.
 106     // 0 may be returned if the range does not fit in the sourceBuffer
 107     static PassRefPtr<AudioBus> createBufferFromRange(const AudioBus* sourceBuffer, unsigned startFrame, unsigned endFrame);
 108
 109
 110     // Creates a new AudioBus by sample-rate converting sourceBus to the newSampleRate.
 111     // setSampleRate() must have been previously called on sourceBus.
 112     // Note: sample-rate conversion is already handled in the file-reading code for the mac port, so we don't need this.
 113     static PassRefPtr<AudioBus> createBySampleRateConverting(const AudioBus* sourceBus, bool mixToMono, double newSampleRate);
 114
 115     // Creates a new AudioBus by mixing all the channels down to mono.
 116     // If sourceBus is already mono, then the returned AudioBus will simply be a copy.
 117     static PassRefPtr<AudioBus> createByMixingToMono(const AudioBus* sourceBus);
 118
 119     // Scales all samples by the same amount.
 120     void scale(float scale);
 121
 122     void reset() { m_isFirstTime = true; } // for de-zippering
 123
 124     // Copies the samples from the source bus to this one.
 125     // This is just a simple per-channel copy if the number of channels match, otherwise an up-mix or down-mix is done.
 126     void copyFrom(const AudioBus& sourceBus, ChannelInterpretation = Speakers);
 127
 128     // Sums the samples from the source bus to this one.
 129     // This is just a simple per-channel summing if the number of channels match, otherwise an up-mix or down-mix is done.
 130     void sumFrom(const AudioBus& sourceBus, ChannelInterpretation = Speakers);
 131
 132     // Copy each channel from sourceBus into our corresponding channel.
 133     // We scale by targetGain (and our own internal gain m_busGain), performing "de-zippering" to smoothly change from *lastMixGain to (targetGain*m_busGain).
 134     // The caller is responsible for setting up lastMixGain to point to storage which is unique for every "stream" which will be applied to this bus.
 135     // This represents the dezippering memory.
 136     void copyWithGainFrom(const AudioBus &sourceBus, float* lastMixGain, float targetGain);
 137
 138     // Copies the sourceBus by scaling with sample-accurate gain values.
 139     void copyWithSampleAccurateGainValuesFrom(const AudioBus &sourceBus, float* gainValues, unsigned numberOfGainValues);
 140
 141     // Returns maximum absolute value across all channels (useful for normalization).
 142     float maxAbsValue() const;
 143
 144     // Makes maximum absolute value == 1.0 (if possible).
 145     void normalize();
 146
 147     static PassRefPtr<AudioBus> loadPlatformResource(const char* name, float sampleRate);
 148
 149 protected:
 150     AudioBus() { }
 151
 152     AudioBus(unsigned numberOfChannels, size_t length, bool allocate);
 153
 154     void speakersCopyFrom(const AudioBus&);
 155     void discreteCopyFrom(const AudioBus&);
 156     void speakersSumFrom(const AudioBus&);
 157     void discreteSumFrom(const AudioBus&);
 158     void speakersSumFrom5_1_ToMono(const AudioBus&);
 159
 160     size_t m_length;
 161     Vector<OwnPtr<AudioChannel>> m_channels;
 162     int m_layout;
 163     float m_busGain;
 164     OwnPtr<AudioFloatArray> m_dezipperGainValues;
 165     bool m_isFirstTime;
 166     float m_sampleRate; // 0.0 if unknown or N/A
 167 };
 168
 169 } // namespace blink
 170
 171 #endif // AudioBus_h