Source/WebCore/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 "ActiveDOMObject.h"
  29 #include "AsyncAudioDecoder.h"
  30 #include "AudioBus.h"
  31 #include "AudioDestinationNode.h"
  32 #include "EventListener.h"
  33 #include "EventTarget.h"
  34 #include "HRTFDatabaseLoader.h"
  35 #include <wtf/HashSet.h>
  36 #include <wtf/MainThread.h>
  37 #include <wtf/OwnPtr.h>
  38 #include <wtf/PassRefPtr.h>
  39 #include <wtf/RefCounted.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 WebCore {
  47
  48 class AudioBuffer;
  49 class AudioBufferCallback;
  50 class AudioBufferSourceNode;
  51 class MediaElementAudioSourceNode;
  52 class HTMLMediaElement;
  53 class AudioChannelMerger;
  54 class AudioChannelSplitter;
  55 class AudioGainNode;
  56 class AudioPannerNode;
  57 class AudioListener;
  58 class BiquadFilterNode;
  59 class DelayNode;
  60 class Document;
  61 class LowPass2FilterNode;
  62 class HighPass2FilterNode;
  63 class ConvolverNode;
  64 class DynamicsCompressorNode;
  65 class RealtimeAnalyserNode;
  66 class WaveShaperNode;
  67 class JavaScriptAudioNode;
  68
  69 // AudioContext is the cornerstone of the web audio API and all AudioNodes are created from it.
  70 // For thread safety between the audio thread and the main thread, it has a rendering graph locking mechanism.
  71
  72 class AudioContext : public ActiveDOMObject, public ThreadSafeRefCounted<AudioContext>, public EventTarget {
  73 public:
  74     // Create an AudioContext for rendering to the audio hardware.
  75     static PassRefPtr<AudioContext> create(Document*);
  76
  77     // Create an AudioContext for offline (non-realtime) rendering.
  78     static PassRefPtr<AudioContext> createOfflineContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionCode&);
  79
  80     virtual ~AudioContext();
  81
  82     bool isInitialized() const;
  83
  84     bool isOfflineContext() { return m_isOfflineContext; }
  85
  86     // Returns true when initialize() was called AND all asynchronous initialization has completed.
  87     bool isRunnable() const;
  88
  89     // Document notification
  90     virtual void stop();
  91
  92     Document* document() const; // ASSERTs if document no longer exists.
  93     bool hasDocument();
  94
  95     AudioDestinationNode* destination() { return m_destinationNode.get(); }
  96     double currentTime() { return m_destinationNode->currentTime(); }
  97     float sampleRate() { return m_destinationNode->sampleRate(); }
  98
  99     PassRefPtr<AudioBuffer> createBuffer(unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
 100     PassRefPtr<AudioBuffer> createBuffer(ArrayBuffer* arrayBuffer, bool mixToMono);
 101
 102     // Asynchronous audio file data decoding.
 103     void decodeAudioData(ArrayBuffer*, PassRefPtr<AudioBufferCallback>, PassRefPtr<AudioBufferCallback>, ExceptionCode& ec);
 104
 105     // Keep track of this buffer so we can release memory after the context is shut down...
 106     void refBuffer(PassRefPtr<AudioBuffer> buffer);
 107
 108     AudioListener* listener() { return m_listener.get(); }
 109
 110     // The AudioNode create methods are called on the main thread (from JavaScript).
 111     PassRefPtr<AudioBufferSourceNode> createBufferSource();
 112 #if ENABLE(VIDEO)
 113     PassRefPtr<MediaElementAudioSourceNode> createMediaElementSource(HTMLMediaElement*, ExceptionCode&);
 114 #endif
 115     PassRefPtr<AudioGainNode> createGainNode();
 116     PassRefPtr<BiquadFilterNode> createBiquadFilter();
 117     PassRefPtr<WaveShaperNode> createWaveShaper();
 118     PassRefPtr<DelayNode> createDelayNode();
 119     PassRefPtr<LowPass2FilterNode> createLowPass2Filter();
 120     PassRefPtr<HighPass2FilterNode> createHighPass2Filter();
 121     PassRefPtr<AudioPannerNode> createPanner();
 122     PassRefPtr<ConvolverNode> createConvolver();
 123     PassRefPtr<DynamicsCompressorNode> createDynamicsCompressor();
 124     PassRefPtr<RealtimeAnalyserNode> createAnalyser();
 125     PassRefPtr<JavaScriptAudioNode> createJavaScriptNode(size_t bufferSize);
 126     PassRefPtr<AudioChannelSplitter> createChannelSplitter();
 127     PassRefPtr<AudioChannelMerger> createChannelMerger();
 128
 129     AudioBus* temporaryMonoBus() { return m_temporaryMonoBus.get(); }
 130     AudioBus* temporaryStereoBus() { return m_temporaryStereoBus.get(); }
 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     // We schedule deletion of all marked nodes at the end of each realtime render quantum.
 145     void markForDeletion(AudioNode*);
 146     void deleteMarkedNodes();
 147
 148     // Keeps track of the number of connections made.
 149     void incrementConnectionCount()
 150     {
 151         ASSERT(isMainThread());
 152         m_connectionCount++;
 153     }
 154
 155     unsigned connectionCount() const { return m_connectionCount; }
 156
 157     //
 158     // Thread Safety and Graph Locking:
 159     //
 160
 161     void setAudioThread(ThreadIdentifier thread) { m_audioThread = thread; } // FIXME: check either not initialized or the same
 162     ThreadIdentifier audioThread() const { return m_audioThread; }
 163     bool isAudioThread() const;
 164
 165     // Returns true only after the audio thread has been started and then shutdown.
 166     bool isAudioThreadFinished() { return m_isAudioThreadFinished; }
 167
 168     // mustReleaseLock is set to true if we acquired the lock in this method call and caller must unlock(), false if it was previously acquired.
 169     void lock(bool& mustReleaseLock);
 170
 171     // Returns true if we own the lock.
 172     // mustReleaseLock is set to true if we acquired the lock in this method call and caller must unlock(), false if it was previously acquired.
 173     bool tryLock(bool& mustReleaseLock);
 174
 175     void unlock();
 176
 177     // Returns true if this thread owns the context's lock.
 178     bool isGraphOwner() const;
 179
 180     class AutoLocker {
 181     public:
 182         AutoLocker(AudioContext* context)
 183             : m_context(context)
 184         {
 185             ASSERT(context);
 186             context->lock(m_mustReleaseLock);
 187         }
 188
 189         ~AutoLocker()
 190         {
 191             if (m_mustReleaseLock)
 192                 m_context->unlock();
 193         }
 194     private:
 195         AudioContext* m_context;
 196         bool m_mustReleaseLock;
 197     };
 198
 199     // In AudioNode::deref() a tryLock() is used for calling finishDeref(), but if it fails keep track here.
 200     void addDeferredFinishDeref(AudioNode*, AudioNode::RefType);
 201
 202     // In the audio thread at the start of each render cycle, we'll call handleDeferredFinishDerefs().
 203     void handleDeferredFinishDerefs();
 204
 205     // Only accessed when the graph lock is held.
 206     void markAudioNodeInputDirty(AudioNodeInput*);
 207     void markAudioNodeOutputDirty(AudioNodeOutput*);
 208
 209     // EventTarget
 210     virtual const AtomicString& interfaceName() const;
 211     virtual ScriptExecutionContext* scriptExecutionContext() const;
 212     virtual EventTargetData* eventTargetData() { return &m_eventTargetData; }
 213     virtual EventTargetData* ensureEventTargetData() { return &m_eventTargetData; }
 214
 215     DEFINE_ATTRIBUTE_EVENT_LISTENER(complete);
 216
 217     // Reconcile ref/deref which are defined both in ThreadSafeRefCounted and EventTarget.
 218     using ThreadSafeRefCounted<AudioContext>::ref;
 219     using ThreadSafeRefCounted<AudioContext>::deref;
 220
 221     void startRendering();
 222     void fireCompletionEvent();
 223
 224     static unsigned s_hardwareContextCount;
 225
 226 private:
 227     AudioContext(Document*);
 228     AudioContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
 229     void constructCommon();
 230
 231     void lazyInitialize();
 232     void uninitialize();
 233     static void uninitializeDispatch(void* userData);
 234
 235     void scheduleNodeDeletion();
 236     static void deleteMarkedNodesDispatch(void* userData);
 237
 238     bool m_isInitialized;
 239     bool m_isAudioThreadFinished;
 240     bool m_isAudioThreadShutdown;
 241
 242     Document* m_document;
 243
 244     // The context itself keeps a reference to all source nodes.  The source nodes, then reference all nodes they're connected to.
 245     // In turn, these nodes reference all nodes they're connected to.  All nodes are ultimately connected to the AudioDestinationNode.
 246     // When the context dereferences a source node, it will be deactivated from the rendering graph along with all other nodes it is
 247     // uniquely connected to.  See the AudioNode::ref() and AudioNode::deref() methods for more details.
 248     void refNode(AudioNode*);
 249     void derefNode(AudioNode*);
 250
 251     // When the context goes away, there might still be some sources which haven't finished playing.
 252     // Make sure to dereference them here.
 253     void derefUnfinishedSourceNodes();
 254
 255     RefPtr<AudioDestinationNode> m_destinationNode;
 256     RefPtr<AudioListener> m_listener;
 257
 258     // Only accessed in the main thread.
 259     Vector<RefPtr<AudioBuffer> > m_allocatedBuffers;
 260
 261     // Only accessed in the audio thread.
 262     Vector<AudioNode*> m_finishedNodes;
 263
 264     // We don't use RefPtr<AudioNode> here because AudioNode has a more complex ref() / deref() implementation
 265     // with an optional argument for refType.  We need to use the special refType: RefTypeConnection
 266     // Either accessed when the graph lock is held, or on the main thread when the audio thread has finished.
 267     Vector<AudioNode*> m_referencedNodes;
 268
 269     // Accumulate nodes which need to be deleted here.
 270     // They will be scheduled for deletion (on the main thread) at the end of a render cycle (in realtime thread).
 271     Vector<AudioNode*> m_nodesToDelete;
 272     bool m_isDeletionScheduled;
 273
 274     // Only accessed when the graph lock is held.
 275     HashSet<AudioNodeInput*> m_dirtyAudioNodeInputs;
 276     HashSet<AudioNodeOutput*> m_dirtyAudioNodeOutputs;
 277     void handleDirtyAudioNodeInputs();
 278     void handleDirtyAudioNodeOutputs();
 279
 280     OwnPtr<AudioBus> m_temporaryMonoBus;
 281     OwnPtr<AudioBus> m_temporaryStereoBus;
 282
 283     unsigned m_connectionCount;
 284
 285     // Graph locking.
 286     Mutex m_contextGraphMutex;
 287     volatile ThreadIdentifier m_audioThread;
 288     volatile ThreadIdentifier m_graphOwnerThread; // if the lock is held then this is the thread which owns it, otherwise == UndefinedThreadIdentifier
 289
 290     // Deferred de-referencing.
 291     struct RefInfo {
 292         RefInfo(AudioNode* node, AudioNode::RefType refType)
 293             : m_node(node)
 294             , m_refType(refType)
 295         {
 296         }
 297         AudioNode* m_node;
 298         AudioNode::RefType m_refType;
 299     };
 300
 301     // Only accessed in the audio thread.
 302     Vector<RefInfo> m_deferredFinishDerefList;
 303
 304     // HRTF Database loader
 305     RefPtr<HRTFDatabaseLoader> m_hrtfDatabaseLoader;
 306
 307     // EventTarget
 308     virtual void refEventTarget() { ref(); }
 309     virtual void derefEventTarget() { deref(); }
 310     EventTargetData m_eventTargetData;
 311
 312     RefPtr<AudioBuffer> m_renderTarget;
 313
 314     bool m_isOfflineContext;
 315
 316     AsyncAudioDecoder m_audioDecoder;
 317 };
 318
 319 } // WebCore
 320
 321 #endif // AudioContext_h