2011-06-08 Chris Rogers <crogers@google.com>
[WebKit-https.git] / Source / WebCore / webaudio / AudioNode.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 AudioNode_h
26 #define AudioNode_h
27
28 #include <wtf/OwnPtr.h>
29 #include <wtf/PassOwnPtr.h>
30 #include <wtf/RefPtr.h>
31 #include <wtf/Vector.h>
32
33 #define DEBUG_AUDIONODE_REFERENCES 0
34
35 namespace WebCore {
36
37 class AudioContext;
38 class AudioNodeInput;
39 class AudioNodeOutput;
40
41 // An AudioNode is the basic building block for handling audio within an AudioContext.
42 // It may be an audio source, an intermediate processing module, or an audio destination.
43 // Each AudioNode can have inputs and/or outputs. An AudioSourceNode has no inputs and a single output.
44 // An AudioDestinationNode has one input and no outputs and represents the final destination to the audio hardware.
45 // Most processing nodes such as filters will have one input and one output, although multiple inputs and outputs are possible.
46
47 class AudioNode {
48 public:
49     enum { ProcessingSizeInFrames = 128 };
50
51     AudioNode(AudioContext*, double sampleRate);
52     virtual ~AudioNode();
53
54     AudioContext* context() { return m_context.get(); }
55
56     enum NodeType {
57         NodeTypeUnknown,
58         NodeTypeDestination,
59         NodeTypeAudioBufferSource,
60         NodeTypeJavaScript,
61         NodeTypeBiquadFilter,
62         NodeTypeLowPass2Filter,
63         NodeTypeHighPass2Filter,
64         NodeTypePanner,
65         NodeTypeConvolver,
66         NodeTypeDelay,
67         NodeTypeGain,
68         NodeTypeChannelSplitter,
69         NodeTypeChannelMerger,
70         NodeTypeAnalyser,
71         NodeTypeDynamicsCompressor,
72         NodeTypeEnd
73     };
74
75     NodeType type() const { return m_type; }
76     void setType(NodeType);
77
78     // We handle our own ref-counting because of the threading issues and subtle nature of
79     // how AudioNodes can continue processing (playing one-shot sound) after there are no more
80     // JavaScript references to the object.
81     enum RefType { RefTypeNormal, RefTypeConnection, RefTypeDisabled };
82
83     // Can be called from main thread or context's audio thread.
84     void ref(RefType refType = RefTypeNormal);
85     void deref(RefType refType = RefTypeNormal);
86
87     // Can be called from main thread or context's audio thread.  It must be called while the context's graph lock is held.
88     void finishDeref(RefType refType);
89
90     // The AudioNodeInput(s) (if any) will already have their input data available when process() is called.
91     // Subclasses will take this input data and put the results in the AudioBus(s) of its AudioNodeOutput(s) (if any).
92     // Called from context's audio thread.
93     virtual void process(size_t framesToProcess) = 0;
94
95     // Resets DSP processing state (clears delay lines, filter memory, etc.)
96     // Called from context's audio thread.
97     virtual void reset() = 0;
98
99     // No significant resources should be allocated until initialize() is called.
100     // Processing may not occur until a node is initialized.
101     virtual void initialize();
102     virtual void uninitialize();
103
104     bool isInitialized() const { return m_isInitialized; }
105     void lazyInitialize();
106
107     unsigned numberOfInputs() const { return m_inputs.size(); }
108     unsigned numberOfOutputs() const { return m_outputs.size(); }
109
110     AudioNodeInput* input(unsigned);
111     AudioNodeOutput* output(unsigned);
112
113     // connect() / disconnect() return true on success.
114     // Called from main thread by corresponding JavaScript methods.
115     bool connect(AudioNode* destination, unsigned outputIndex = 0, unsigned inputIndex = 0);
116     bool disconnect(unsigned outputIndex = 0);
117
118     double sampleRate() const { return m_sampleRate; }
119
120     // processIfNecessary() is called by our output(s) when the rendering graph needs this AudioNode to process.
121     // This method ensures that the AudioNode will only process once per rendering time quantum even if it's called repeatedly.
122     // This handles the case of "fanout" where an output is connected to multiple AudioNode inputs.
123     // Called from context's audio thread.
124     void processIfNecessary(size_t framesToProcess);
125
126     // Called when a new connection has been made to one of our inputs or the connection number of channels has changed.
127     // This potentially gives us enough information to perform a lazy initialization or, if necessary, a re-initialization.
128     // Called from main thread.
129     virtual void checkNumberOfChannelsForInput(AudioNodeInput*) { }
130
131 #if DEBUG_AUDIONODE_REFERENCES
132     static void printNodeCounts();
133 #endif
134
135     bool isMarkedForDeletion() const { return m_isMarkedForDeletion; }
136
137 protected:
138     // Inputs and outputs must be created before the AudioNode is initialized.
139     void addInput(PassOwnPtr<AudioNodeInput>);
140     void addOutput(PassOwnPtr<AudioNodeOutput>);
141     
142     // Called by processIfNecessary() to cause all parts of the rendering graph connected to us to process.
143     // Each rendering quantum, the audio data for each of the AudioNode's inputs will be available after this method is called.
144     // Called from context's audio thread.
145     virtual void pullInputs(size_t framesToProcess);
146
147 private:
148     volatile bool m_isInitialized;
149     NodeType m_type;
150     RefPtr<AudioContext> m_context;
151     double m_sampleRate;
152     Vector<OwnPtr<AudioNodeInput> > m_inputs;
153     Vector<OwnPtr<AudioNodeOutput> > m_outputs;
154
155     double m_lastProcessingTime;
156
157     // Ref-counting
158     volatile int m_normalRefCount;
159     volatile int m_connectionRefCount;
160     volatile int m_disabledRefCount;
161     
162     bool m_isMarkedForDeletion;
163     bool m_isDisabled;
164     
165 #if DEBUG_AUDIONODE_REFERENCES
166     static bool s_isNodeCountInitialized;
167     static int s_nodeCount[NodeTypeEnd];
168 #endif
169 };
170
171 } // namespace WebCore
172
173 #endif // AudioNode_h