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 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 <memory>
34#include <wtf/Noncopyable.h>
35#include <wtf/ThreadSafeRefCounted.h>
36#include <wtf/Vector.h>
37
38namespace WebCore {
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.
43class AudioBus : public ThreadSafeRefCounted<AudioBus> {
44 WTF_MAKE_NONCOPYABLE(AudioBus);
45public:
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 RefPtr<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 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 RefPtr<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 RefPtr<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 RefPtr<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 void copyFromRange(const AudioBus& sourceBus, unsigned startFrame, unsigned endFrame);
126
127 // Copies the samples from the source bus to this one.
128 // This is just a simple per-channel copy if the number of channels match, otherwise an up-mix or down-mix is done.
129 void copyFrom(const AudioBus& sourceBus, ChannelInterpretation = Speakers);
130
131 // Sums the samples from the source bus to this one.
132 // This is just a simple per-channel summing if the number of channels match, otherwise an up-mix or down-mix is done.
133 void sumFrom(const AudioBus& sourceBus, ChannelInterpretation = Speakers);
134
135 // Copy each channel from sourceBus into our corresponding channel.
136 // We scale by targetGain (and our own internal gain m_busGain), performing "de-zippering" to smoothly change from *lastMixGain to (targetGain*m_busGain).
137 // 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.
138 // This represents the dezippering memory.
139 void copyWithGainFrom(const AudioBus &sourceBus, float* lastMixGain, float targetGain);
140
141 // Copies the sourceBus by scaling with sample-accurate gain values.
142 void copyWithSampleAccurateGainValuesFrom(const AudioBus &sourceBus, float* gainValues, unsigned numberOfGainValues);
143
144 // Returns maximum absolute value across all channels (useful for normalization).
145 float maxAbsValue() const;
146
147 // Makes maximum absolute value == 1.0 (if possible).
148 void normalize();
149
150 static RefPtr<AudioBus> loadPlatformResource(const char* name, float sampleRate);
151
152protected:
153 AudioBus() { }
154
155 AudioBus(unsigned numberOfChannels, size_t length, bool allocate);
156
157 void speakersCopyFrom(const AudioBus&);
158 void discreteCopyFrom(const AudioBus&);
159 void speakersSumFrom(const AudioBus&);
160 void discreteSumFrom(const AudioBus&);
161 void speakersSumFrom5_1_ToMono(const AudioBus&);
162
163 size_t m_length;
164 Vector<std::unique_ptr<AudioChannel>> m_channels;
165 int m_layout;
166 float m_busGain;
167 std::unique_ptr<AudioFloatArray> m_dezipperGainValues;
168 bool m_isFirstTime;
169 float m_sampleRate; // 0.0 if unknown or N/A
170};
171
172} // WebCore
173
174#endif // AudioBus_h
175