Source/WebCore/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 "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 MediaStreamAudioDestinationNode;
  53 class MediaStreamAudioSourceNode;
  54 class HTMLMediaElement;
  55 class ChannelMergerNode;
  56 class ChannelSplitterNode;
  57 class GainNode;
  58 class PannerNode;
  59 class AudioListener;
  60 class AudioSummingJunction;
  61 class BiquadFilterNode;
  62 class DelayNode;
  63 class Document;
  64 class ConvolverNode;
  65 class DynamicsCompressorNode;
  66 class AnalyserNode;
  67 class WaveShaperNode;
  68 class ScriptProcessorNode;
  69 class OscillatorNode;
  70 class WaveTable;
  71
  72 // AudioContext is the cornerstone of the web audio API and all AudioNodes are created from it.
  73 // For thread safety between the audio thread and the main thread, it has a rendering graph locking mechanism.
  74
  75 class AudioContext : public ActiveDOMObject, public ThreadSafeRefCounted<AudioContext>, public EventTarget {
  76 public:
  77     // Create an AudioContext for rendering to the audio hardware.
  78     static PassRefPtr<AudioContext> create(Document*, ExceptionCode&);
  79
  80     // Create an AudioContext for offline (non-realtime) rendering.
  81     static PassRefPtr<AudioContext> createOfflineContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionCode&);
  82
  83     virtual ~AudioContext();
  84
  85     bool isInitialized() const;
  86
  87     bool isOfflineContext() { return m_isOfflineContext; }
  88
  89     // Returns true when initialize() was called AND all asynchronous initialization has completed.
  90     bool isRunnable() const;
  91
  92     // Document notification
  93     virtual void stop();
  94 #if ENABLE(TIZEN_WEB_AUDIO)
  95     void pause();
  96 #endif
  97     Document* document() const; // ASSERTs if document no longer exists.
  98     bool hasDocument();
  99
 100     AudioDestinationNode* destination() { return m_destinationNode.get(); }
 101     size_t currentSampleFrame() const { return m_destinationNode->currentSampleFrame(); }
 102     double currentTime() const { return m_destinationNode->currentTime(); }
 103     float sampleRate() const { return m_destinationNode->sampleRate(); }
 104     unsigned long activeSourceCount() const { return static_cast<unsigned long>(m_activeSourceCount); }
 105 #if ENABLE(TIZEN_WEB_AUDIO)
 106     unsigned long activeScriptProcessorCount() const { return static_cast<unsigned long>(m_activeScriptProcessorCount); }
 107 #endif
 108     void incrementActiveSourceCount();
 109     void decrementActiveSourceCount();
 110 #if ENABLE(TIZEN_WEB_AUDIO)
 111     void incrementActiveScriptProcessorCount();
 112     void decrementActiveScriptProcessorCount();
 113 #endif
 114     PassRefPtr<AudioBuffer> createBuffer(unsigned numberOfChannels, size_t numberOfFrames, float sampleRate, ExceptionCode&);
 115     PassRefPtr<AudioBuffer> createBuffer(ArrayBuffer*, bool mixToMono, ExceptionCode&);
 116
 117     // Asynchronous audio file data decoding.
 118     void decodeAudioData(ArrayBuffer*, PassRefPtr<AudioBufferCallback>, PassRefPtr<AudioBufferCallback>, ExceptionCode& ec);
 119
 120     AudioListener* listener() { return m_listener.get(); }
 121
 122     // The AudioNode create methods are called on the main thread (from JavaScript).
 123     PassRefPtr<AudioBufferSourceNode> createBufferSource();
 124 #if ENABLE(VIDEO)
 125     PassRefPtr<MediaElementAudioSourceNode> createMediaElementSource(HTMLMediaElement*, ExceptionCode&);
 126 #endif
 127 #if ENABLE(MEDIA_STREAM)
 128     PassRefPtr<MediaStreamAudioSourceNode> createMediaStreamSource(MediaStream*, ExceptionCode&);
 129     PassRefPtr<MediaStreamAudioDestinationNode> createMediaStreamDestination();
 130 #endif
 131     PassRefPtr<GainNode> createGain();
 132     PassRefPtr<BiquadFilterNode> createBiquadFilter();
 133     PassRefPtr<WaveShaperNode> createWaveShaper();
 134     PassRefPtr<DelayNode> createDelay(ExceptionCode&);
 135     PassRefPtr<DelayNode> createDelay(double maxDelayTime, ExceptionCode&);
 136     PassRefPtr<PannerNode> createPanner();
 137     PassRefPtr<ConvolverNode> createConvolver();
 138     PassRefPtr<DynamicsCompressorNode> createDynamicsCompressor();
 139     PassRefPtr<AnalyserNode> createAnalyser();
 140     PassRefPtr<ScriptProcessorNode> createScriptProcessor(size_t bufferSize, ExceptionCode&);
 141     PassRefPtr<ScriptProcessorNode> createScriptProcessor(size_t bufferSize, size_t numberOfInputChannels, ExceptionCode&);
 142     PassRefPtr<ScriptProcessorNode> createScriptProcessor(size_t bufferSize, size_t numberOfInputChannels, size_t numberOfOutputChannels, ExceptionCode&);
 143     PassRefPtr<ChannelSplitterNode> createChannelSplitter(ExceptionCode&);
 144     PassRefPtr<ChannelSplitterNode> createChannelSplitter(size_t numberOfOutputs, ExceptionCode&);
 145     PassRefPtr<ChannelMergerNode> createChannelMerger(ExceptionCode&);
 146     PassRefPtr<ChannelMergerNode> createChannelMerger(size_t numberOfInputs, ExceptionCode&);
 147     PassRefPtr<OscillatorNode> createOscillator();
 148     PassRefPtr<WaveTable> createWaveTable(Float32Array* real, Float32Array* imag, ExceptionCode&);
 149
 150     // When a source node has no more processing to do (has finished playing), then it tells the context to dereference it.
 151     void notifyNodeFinishedProcessing(AudioNode*);
 152
 153     // Called at the start of each render quantum.
 154     void handlePreRenderTasks();
 155
 156     // Called at the end of each render quantum.
 157     void handlePostRenderTasks();
 158
 159     // Called periodically at the end of each render quantum to dereference finished source nodes.
 160     void derefFinishedSourceNodes();
 161
 162     // We schedule deletion of all marked nodes at the end of each realtime render quantum.
 163     void markForDeletion(AudioNode*);
 164     void deleteMarkedNodes();
 165
 166     // AudioContext can pull node(s) at the end of each render quantum even when they are not connected to any downstream nodes.
 167     // These two methods are called by the nodes who want to add/remove themselves into/from the automatic pull lists.
 168     void addAutomaticPullNode(AudioNode*);
 169     void removeAutomaticPullNode(AudioNode*);
 170
 171     // Called right before handlePostRenderTasks() to handle nodes which need to be pulled even when they are not connected to anything.
 172     void processAutomaticPullNodes(size_t framesToProcess);
 173
 174     // Keeps track of the number of connections made.
 175     void incrementConnectionCount()
 176     {
 177         ASSERT(isMainThread());
 178         m_connectionCount++;
 179     }
 180
 181     unsigned connectionCount() const { return m_connectionCount; }
 182
 183     //
 184     // Thread Safety and Graph Locking:
 185     //
 186
 187     void setAudioThread(ThreadIdentifier thread) { m_audioThread = thread; } // FIXME: check either not initialized or the same
 188     ThreadIdentifier audioThread() const { return m_audioThread; }
 189     bool isAudioThread() const;
 190
 191     // Returns true only after the audio thread has been started and then shutdown.
 192     bool isAudioThreadFinished() { return m_isAudioThreadFinished; }
 193
 194     // mustReleaseLock is set to true if we acquired the lock in this method call and caller must unlock(), false if it was previously acquired.
 195     void lock(bool& mustReleaseLock);
 196
 197     // Returns true if we own the lock.
 198     // mustReleaseLock is set to true if we acquired the lock in this method call and caller must unlock(), false if it was previously acquired.
 199     bool tryLock(bool& mustReleaseLock);
 200
 201     void unlock();
 202
 203     // Returns true if this thread owns the context's lock.
 204     bool isGraphOwner() const;
 205
 206     // Returns the maximum numuber of channels we can support.
 207     static unsigned maxNumberOfChannels() { return MaxNumberOfChannels;}
 208
 209     class AutoLocker {
 210     public:
 211         AutoLocker(AudioContext* context)
 212             : m_context(context)
 213         {
 214             ASSERT(context);
 215             context->lock(m_mustReleaseLock);
 216         }
 217
 218         ~AutoLocker()
 219         {
 220             if (m_mustReleaseLock)
 221                 m_context->unlock();
 222         }
 223     private:
 224         AudioContext* m_context;
 225         bool m_mustReleaseLock;
 226     };
 227
 228     // In AudioNode::deref() a tryLock() is used for calling finishDeref(), but if it fails keep track here.
 229     void addDeferredFinishDeref(AudioNode*);
 230
 231     // In the audio thread at the start of each render cycle, we'll call handleDeferredFinishDerefs().
 232     void handleDeferredFinishDerefs();
 233
 234     // Only accessed when the graph lock is held.
 235     void markSummingJunctionDirty(AudioSummingJunction*);
 236     void markAudioNodeOutputDirty(AudioNodeOutput*);
 237
 238     // Must be called on main thread.
 239     void removeMarkedSummingJunction(AudioSummingJunction*);
 240
 241     // EventTarget
 242     virtual const AtomicString& interfaceName() const;
 243     virtual ScriptExecutionContext* scriptExecutionContext() const;
 244     virtual EventTargetData* eventTargetData() { return &m_eventTargetData; }
 245     virtual EventTargetData* ensureEventTargetData() { return &m_eventTargetData; }
 246
 247     DEFINE_ATTRIBUTE_EVENT_LISTENER(complete);
 248
 249     // Reconcile ref/deref which are defined both in ThreadSafeRefCounted and EventTarget.
 250     using ThreadSafeRefCounted<AudioContext>::ref;
 251     using ThreadSafeRefCounted<AudioContext>::deref;
 252
 253     void startRendering();
 254     void fireCompletionEvent();
 255
 256     static unsigned s_hardwareContextCount;
 257
 258 protected:
 259     explicit AudioContext(Document*);
 260     AudioContext(Document*, unsigned numberOfChannels, size_t numberOfFrames, float sampleRate);
 261
 262     static bool isSampleRateRangeGood(float sampleRate);
 263
 264 private:
 265     void constructCommon();
 266
 267     void lazyInitialize();
 268     void uninitialize();
 269
 270     // ScriptExecutionContext calls stop twice.
 271     // We'd like to schedule only one stop action for them.
 272     bool m_isStopScheduled;
 273     static void uninitializeDispatch(void* userData);
 274 #if ENABLE(TIZEN_WEB_AUDIO)
 275     static void pauseDispatch(void* userData);
 276 #endif
 277     void clear();
 278
 279     void scheduleNodeDeletion();
 280     static void deleteMarkedNodesDispatch(void* userData);
 281
 282     bool m_isInitialized;
 283     bool m_isAudioThreadFinished;
 284
 285     // The context itself keeps a reference to all source nodes.  The source nodes, then reference all nodes they're connected to.
 286     // In turn, these nodes reference all nodes they're connected to.  All nodes are ultimately connected to the AudioDestinationNode.
 287     // When the context dereferences a source node, it will be deactivated from the rendering graph along with all other nodes it is
 288     // uniquely connected to.  See the AudioNode::ref() and AudioNode::deref() methods for more details.
 289     void refNode(AudioNode*);
 290     void derefNode(AudioNode*);
 291
 292     // When the context goes away, there might still be some sources which haven't finished playing.
 293     // Make sure to dereference them here.
 294     void derefUnfinishedSourceNodes();
 295
 296     RefPtr<AudioDestinationNode> m_destinationNode;
 297     RefPtr<AudioListener> m_listener;
 298
 299     // Only accessed in the audio thread.
 300     Vector<AudioNode*> m_finishedNodes;
 301
 302     // We don't use RefPtr<AudioNode> here because AudioNode has a more complex ref() / deref() implementation
 303     // with an optional argument for refType.  We need to use the special refType: RefTypeConnection
 304     // Either accessed when the graph lock is held, or on the main thread when the audio thread has finished.
 305     Vector<AudioNode*> m_referencedNodes;
 306
 307     // Accumulate nodes which need to be deleted here.
 308     // This is copied to m_nodesToDelete at the end of a render cycle in handlePostRenderTasks(), where we're assured of a stable graph
 309     // state which will have no references to any of the nodes in m_nodesToDelete once the context lock is released
 310     // (when handlePostRenderTasks() has completed).
 311     Vector<AudioNode*> m_nodesMarkedForDeletion;
 312
 313     // They will be scheduled for deletion (on the main thread) at the end of a render cycle (in realtime thread).
 314     Vector<AudioNode*> m_nodesToDelete;
 315     bool m_isDeletionScheduled;
 316
 317     // Only accessed when the graph lock is held.
 318     HashSet<AudioSummingJunction*> m_dirtySummingJunctions;
 319     HashSet<AudioNodeOutput*> m_dirtyAudioNodeOutputs;
 320     void handleDirtyAudioSummingJunctions();
 321     void handleDirtyAudioNodeOutputs();
 322
 323     // For the sake of thread safety, we maintain a seperate Vector of automatic pull nodes for rendering in m_renderingAutomaticPullNodes.
 324     // It will be copied from m_automaticPullNodes by updateAutomaticPullNodes() at the very start or end of the rendering quantum.
 325     HashSet<AudioNode*> m_automaticPullNodes;
 326     Vector<AudioNode*> m_renderingAutomaticPullNodes;
 327     // m_automaticPullNodesNeedUpdating keeps track if m_automaticPullNodes is modified.
 328     bool m_automaticPullNodesNeedUpdating;
 329     void updateAutomaticPullNodes();
 330
 331     unsigned m_connectionCount;
 332
 333     // Graph locking.
 334     Mutex m_contextGraphMutex;
 335     volatile ThreadIdentifier m_audioThread;
 336     volatile ThreadIdentifier m_graphOwnerThread; // if the lock is held then this is the thread which owns it, otherwise == UndefinedThreadIdentifier
 337
 338     // Only accessed in the audio thread.
 339     Vector<AudioNode*> m_deferredFinishDerefList;
 340
 341     // HRTF Database loader
 342     RefPtr<HRTFDatabaseLoader> m_hrtfDatabaseLoader;
 343
 344     // EventTarget
 345     virtual void refEventTarget() { ref(); }
 346     virtual void derefEventTarget() { deref(); }
 347     EventTargetData m_eventTargetData;
 348
 349     RefPtr<AudioBuffer> m_renderTarget;
 350
 351     bool m_isOfflineContext;
 352
 353     AsyncAudioDecoder m_audioDecoder;
 354
 355     // This is considering 32 is large enough for multiple channels audio.
 356     // It is somewhat arbitrary and could be increased if necessary.
 357     enum { MaxNumberOfChannels = 32 };
 358
 359     // Number of AudioBufferSourceNodes that are active (playing).
 360     int m_activeSourceCount;
 361 #if ENABLE(TIZEN_WEB_AUDIO)
 362     int m_activeScriptProcessorCount;
 363 #endif
 364 };
 365
 366 } // WebCore
 367
 368 #endif // AudioContext_h