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