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