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