src/third_party/WebKit/Source/modules/webaudio/AudioContext.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  * 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 #ifndef AudioContext_h
  26 #define AudioContext_h
  27
  28 #include "core/dom/ActiveDOMObject.h"
  29 #include "core/dom/DOMTypedArray.h"
  30 #include "core/events/EventListener.h"
  31 #include "modules/EventTargetModules.h"
  32 #include "modules/webaudio/AsyncAudioDecoder.h"
  33 #include "modules/webaudio/AudioDestinationNode.h"
  34 #include "platform/audio/AudioBus.h"
  35 #include "platform/heap/Handle.h"
  36 #include "wtf/HashSet.h"
  37 #include "wtf/MainThread.h"
  38 #include "wtf/OwnPtr.h"
  39 #include "wtf/PassRefPtr.h"
  40 #include "wtf/RefPtr.h"
  41 #include "wtf/ThreadSafeRefCounted.h"
  42 #include "wtf/Threading.h"
  43 #include "wtf/Vector.h"
  44 #include "wtf/text/AtomicStringHash.h"
  45
  46 namespace blink {
  47
  48 class AnalyserNode;
  49 class AudioBuffer;
  50 class AudioBufferCallback;
  51 class AudioBufferSourceNode;
  52 class AudioListener;
  53 class AudioSummingJunction;
  54 class BiquadFilterNode;
  55 class ChannelMergerNode;
  56 class ChannelSplitterNode;
  57 class ConvolverNode;
  58 class DelayNode;
  59 class Document;
  60 class DynamicsCompressorNode;
  61 class ExceptionState;
  62 class GainNode;
  63 class HTMLMediaElement;
  64 class MediaElementAudioSourceNode;
  65 class MediaStreamAudioDestinationNode;
  66 class MediaStreamAudioSourceNode;
  67 class OscillatorNode;
  68 class PannerNode;
  69 class PeriodicWave;
  70 class ScriptProcessorNode;
  71 class WaveShaperNode;
  72
  73 // AudioContext is the cornerstone of the web audio API and all AudioNodes are created from it.
  74 // For thread safety between the audio thread and the main thread, it has a rendering graph locking mechanism.
  75
  76 class AudioContext : public RefCountedGarbageCollectedWillBeGarbageCollectedFinalized<AudioContext>, public ActiveDOMObject, public EventTargetWithInlineData {
  77     DEFINE_EVENT_TARGET_REFCOUNTING_WILL_BE_REMOVED(RefCountedGarbageCollected<AudioContext>);
  78     DEFINE_WRAPPERTYPEINFO();
  79     WILL_BE_USING_GARBAGE_COLLECTED_MIXIN(AudioContext);
  80 public:
  81     // Create an AudioContext for rendering to the audio hardware.
  82     static AudioContext* create(Document&, ExceptionState&);
  83
  84     virtual ~AudioContext();
  85
  86     virtual void trace(Visitor*) override;
  87
  88     bool isInitialized() const { return m_isInitialized; }
  89     bool isOfflineContext() { return m_isOfflineContext; }
  90
  91     // Document notification
  92     virtual void stop() override final;
  93     virtual bool hasPendingActivity() const override;
  94
  95     AudioDestinationNode* destination() { return m_destinationNode.get(); }
  96     size_t currentSampleFrame() const { return m_destinationNode->currentSampleFrame(); }
  97     double currentTime() const { return m_destinationNode->currentTime(); }
  98     float sampleRate() const { return m_destinationNode->sampleRate(); }
  99
 100     AudioBuffer* createBuffer(unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionState&);
 101
 102     // Asynchronous audio file data decoding.
 103     void decodeAudioData(DOMArrayBuffer*, AudioBufferCallback*, AudioBufferCallback*, ExceptionState&);
 104
 105     AudioListener* listener() { return m_listener.get(); }
 106
 107     // The AudioNode create methods are called on the main thread (from JavaScript).
 108     AudioBufferSourceNode* createBufferSource();
 109     MediaElementAudioSourceNode* createMediaElementSource(HTMLMediaElement*, ExceptionState&);
 110     MediaStreamAudioSourceNode* createMediaStreamSource(MediaStream*, ExceptionState&);
 111     MediaStreamAudioDestinationNode* createMediaStreamDestination();
 112     GainNode* createGain();
 113     BiquadFilterNode* createBiquadFilter();
 114     WaveShaperNode* createWaveShaper();
 115     DelayNode* createDelay(ExceptionState&);
 116     DelayNode* createDelay(double maxDelayTime, ExceptionState&);
 117     PannerNode* createPanner();
 118     ConvolverNode* createConvolver();
 119     DynamicsCompressorNode* createDynamicsCompressor();
 120     AnalyserNode* createAnalyser();
 121     ScriptProcessorNode* createScriptProcessor(ExceptionState&);
 122     ScriptProcessorNode* createScriptProcessor(size_t bufferSize, ExceptionState&);
 123     ScriptProcessorNode* createScriptProcessor(size_t bufferSize, size_t numberOfInputChannels, ExceptionState&);
 124     ScriptProcessorNode* createScriptProcessor(size_t bufferSize, size_t numberOfInputChannels, size_t numberOfOutputChannels, ExceptionState&);
 125     ChannelSplitterNode* createChannelSplitter(ExceptionState&);
 126     ChannelSplitterNode* createChannelSplitter(size_t numberOfOutputs, ExceptionState&);
 127     ChannelMergerNode* createChannelMerger(ExceptionState&);
 128     ChannelMergerNode* createChannelMerger(size_t numberOfInputs, ExceptionState&);
 129     OscillatorNode* createOscillator();
 130     PeriodicWave* createPeriodicWave(DOMFloat32Array* real, DOMFloat32Array* imag, ExceptionState&);
 131
 132     // When a source node has no more processing to do (has finished playing), then it tells the context to dereference it.
 133     void notifyNodeFinishedProcessing(AudioNode*);
 134
 135     // Called at the start of each render quantum.
 136     void handlePreRenderTasks();
 137
 138     // Called at the end of each render quantum.
 139     void handlePostRenderTasks();
 140
 141     // Called periodically at the end of each render quantum to dereference finished source nodes.
 142     void derefFinishedSourceNodes();
 143
 144     void registerLiveAudioSummingJunction(AudioSummingJunction&);
 145     void registerLiveNode(AudioNode&);
 146
 147     // AudioContext can pull node(s) at the end of each render quantum even when they are not connected to any downstream nodes.
 148     // These two methods are called by the nodes who want to add/remove themselves into/from the automatic pull lists.
 149     void addAutomaticPullNode(AudioNode*);
 150     void removeAutomaticPullNode(AudioNode*);
 151
 152     // Called right before handlePostRenderTasks() to handle nodes which need to be pulled even when they are not connected to anything.
 153     void processAutomaticPullNodes(size_t framesToProcess);
 154
 155     // Keep track of AudioNode's that have their channel count mode changed. We process the changes
 156     // in the post rendering phase.
 157     void addChangedChannelCountMode(AudioNode*);
 158     void removeChangedChannelCountMode(AudioNode*);
 159     void updateChangedChannelCountMode();
 160
 161     // Keeps track of the number of connections made.
 162     void incrementConnectionCount()
 163     {
 164         ASSERT(isMainThread());
 165         m_connectionCount++;
 166     }
 167
 168     unsigned connectionCount() const { return m_connectionCount; }
 169
 170     //
 171     // Thread Safety and Graph Locking:
 172     //
 173
 174     void setAudioThread(ThreadIdentifier thread) { m_audioThread = thread; } // FIXME: check either not initialized or the same
 175     ThreadIdentifier audioThread() const { return m_audioThread; }
 176     bool isAudioThread() const;
 177
 178     void lock();
 179     bool tryLock();
 180     void unlock();
 181
 182 #if ENABLE(ASSERT)
 183     // Returns true if this thread owns the context's lock.
 184     bool isGraphOwner();
 185 #endif
 186
 187     // Returns the maximum numuber of channels we can support.
 188     static unsigned maxNumberOfChannels() { return MaxNumberOfChannels;}
 189
 190     class AutoLocker {
 191         STACK_ALLOCATED();
 192     public:
 193         explicit AutoLocker(AudioContext* context)
 194             : m_context(context)
 195         {
 196             ASSERT(context);
 197             context->lock();
 198         }
 199
 200         ~AutoLocker()
 201         {
 202             m_context->unlock();
 203         }
 204     private:
 205         Member<AudioContext> m_context;
 206     };
 207
 208     // In AudioNode::breakConnection() and deref(), a tryLock() is used for
 209     // calling actual processing, but if it fails keep track here.
 210     void addDeferredBreakConnection(AudioNode&);
 211
 212     // In the audio thread at the start of each render cycle, we'll call this.
 213     void handleDeferredAudioNodeTasks();
 214
 215     // Only accessed when the graph lock is held.
 216     void markSummingJunctionDirty(AudioSummingJunction*);
 217     // Only accessed when the graph lock is held. Must be called on the main thread.
 218     void removeMarkedSummingJunction(AudioSummingJunction*);
 219     void markAudioNodeOutputDirty(AudioNodeOutput*);
 220     void removeMarkedAudioNodeOutput(AudioNodeOutput*);
 221     void disposeOutputs(AudioNode&);
 222
 223     // EventTarget
 224     virtual const AtomicString& interfaceName() const override final;
 225     virtual ExecutionContext* executionContext() const override final;
 226
 227     DEFINE_ATTRIBUTE_EVENT_LISTENER(complete);
 228
 229     void startRendering();
 230     void fireCompletionEvent();
 231
 232     static unsigned s_hardwareContextCount;
 233
 234 protected:
 235     explicit AudioContext(Document*);
 236     AudioContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
 237
 238 private:
 239     void initialize();
 240     void uninitialize();
 241
 242     // ExecutionContext calls stop twice.
 243     // We'd like to schedule only one stop action for them.
 244     bool m_isStopScheduled;
 245     bool m_isCleared;
 246     void clear();
 247
 248     // Set to true when the destination node has been initialized and is ready to process data.
 249     bool m_isInitialized;
 250
 251     // The context itself keeps a reference to all source nodes.  The source nodes, then reference all nodes they're connected to.
 252     // In turn, these nodes reference all nodes they're connected to.  All nodes are ultimately connected to the AudioDestinationNode.
 253     // When the context dereferences a source node, it will be deactivated from the rendering graph along with all other nodes it is
 254     // uniquely connected to.  See the AudioNode::ref() and AudioNode::deref() methods for more details.
 255     void refNode(AudioNode*);
 256     void derefNode(AudioNode*);
 257
 258     // When the context goes away, there might still be some sources which haven't finished playing.
 259     // Make sure to dereference them here.
 260     void derefUnfinishedSourceNodes();
 261
 262     Member<AudioDestinationNode> m_destinationNode;
 263     Member<AudioListener> m_listener;
 264
 265     // Only accessed in the audio thread.
 266     // Oilpan: Since items are added to the vector by the audio thread (not registered to Oilpan),
 267     // we cannot use a HeapVector.
 268     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 269     Vector<AudioNode*> m_finishedNodes;
 270
 271     // List of source nodes. This is either accessed when the graph lock is
 272     // held, or on the main thread when the audio thread has finished.
 273     // Oilpan: This Vector holds connection references. We must call
 274     // AudioNode::makeConnection when we add an AudioNode to this, and must call
 275     // AudioNode::breakConnection() when we remove an AudioNode from this.
 276     Member<HeapVector<Member<AudioNode>>> m_referencedNodes;
 277
 278     class AudioNodeDisposer {
 279     public:
 280         explicit AudioNodeDisposer(AudioNode& node) : m_node(node) { }
 281         ~AudioNodeDisposer();
 282
 283     private:
 284         AudioNode& m_node;
 285     };
 286     HeapHashMap<WeakMember<AudioNode>, OwnPtr<AudioNodeDisposer> > m_liveNodes;
 287
 288     class AudioSummingJunctionDisposer {
 289     public:
 290         explicit AudioSummingJunctionDisposer(AudioSummingJunction& junction) : m_junction(junction) { }
 291         ~AudioSummingJunctionDisposer();
 292
 293     private:
 294         AudioSummingJunction& m_junction;
 295     };
 296     // The purpose of m_liveAudioSummingJunctions is to remove a dying
 297     // AudioSummingJunction from m_dirtySummingJunctions. However we put all of
 298     // AudioSummingJunction objects to m_liveAudioSummingJunctions to avoid
 299     // concurrent access to m_liveAudioSummingJunctions.
 300     HeapHashMap<WeakMember<AudioSummingJunction>, OwnPtr<AudioSummingJunctionDisposer> > m_liveAudioSummingJunctions;
 301
 302     // These two HashSet must be accessed only when the graph lock is held.
 303     // Oilpan: These HashSet should be HeapHashSet<WeakMember<AudioNodeOutput>>
 304     // ideally. But it's difficult to lock them correctly during GC.
 305     // Oilpan: Since items are added to these hash sets by the audio thread (not registered to Oilpan),
 306     // we cannot use HeapHashSets.
 307     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 308     HashSet<AudioSummingJunction*> m_dirtySummingJunctions;
 309     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 310     HashSet<AudioNodeOutput*> m_dirtyAudioNodeOutputs;
 311     void handleDirtyAudioSummingJunctions();
 312     void handleDirtyAudioNodeOutputs();
 313
 314     // For the sake of thread safety, we maintain a seperate Vector of automatic pull nodes for rendering in m_renderingAutomaticPullNodes.
 315     // It will be copied from m_automaticPullNodes by updateAutomaticPullNodes() at the very start or end of the rendering quantum.
 316     // Oilpan: Since items are added to the vector/hash set by the audio thread (not registered to Oilpan),
 317     // we cannot use a HeapVector/HeapHashSet.
 318     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 319     HashSet<AudioNode*> m_automaticPullNodes;
 320     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 321     Vector<AudioNode*> m_renderingAutomaticPullNodes;
 322     // m_automaticPullNodesNeedUpdating keeps track if m_automaticPullNodes is modified.
 323     bool m_automaticPullNodesNeedUpdating;
 324     void updateAutomaticPullNodes();
 325
 326     unsigned m_connectionCount;
 327
 328     // Graph locking.
 329     RecursiveMutex m_contextGraphMutex;
 330     volatile ThreadIdentifier m_audioThread;
 331
 332     // Only accessed in the audio thread.
 333     // Oilpan: Since items are added to these vectors by the audio thread (not registered to Oilpan),
 334     // we cannot use HeapVectors.
 335     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 336     Vector<AudioNode*> m_deferredBreakConnectionList;
 337
 338     Member<AudioBuffer> m_renderTarget;
 339
 340     bool m_isOfflineContext;
 341
 342     AsyncAudioDecoder m_audioDecoder;
 343
 344     // Collection of nodes where the channel count mode has changed. We want the channel count mode
 345     // to change in the pre- or post-rendering phase so as not to disturb the running audio thread.
 346     GC_PLUGIN_IGNORE("http://crbug.com/404527")
 347     HashSet<AudioNode*> m_deferredCountModeChange;
 348
 349     // This is considering 32 is large enough for multiple channels audio.
 350     // It is somewhat arbitrary and could be increased if necessary.
 351     enum { MaxNumberOfChannels = 32 };
 352 };
 353
 354 } // namespace blink
 355
 356 #endif // AudioContext_h