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