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 AudioNodeOutput_h
26#define AudioNodeOutput_h
27
28#include "AudioBus.h"
29#include "AudioNode.h"
30#include "AudioParam.h"
31#include <wtf/HashSet.h>
32#include <wtf/RefPtr.h>
33#include <wtf/Vector.h>
34
35namespace WebCore {
36
37class AudioContext;
38class AudioNodeInput;
39
40// AudioNodeOutput represents a single output for an AudioNode.
41// It may be connected to one or more AudioNodeInputs.
42
43class AudioNodeOutput {
44public:
45    // It's OK to pass 0 for numberOfChannels in which case setNumberOfChannels() must be called later on.
46    AudioNodeOutput(AudioNode*, unsigned numberOfChannels);
47
48    // Can be called from any thread.
49    AudioNode* node() const { return m_node; }
50    AudioContext* context() { return m_node->context(); }
51
52    // Causes our AudioNode to process if it hasn't already for this render quantum.
53    // It returns the bus containing the processed audio for this output, returning inPlaceBus if in-place processing was possible.
54    // Called from context's audio thread.
55    AudioBus* pull(AudioBus* inPlaceBus, size_t framesToProcess);
56
57    // bus() will contain the rendered audio after pull() is called for each rendering time quantum.
58    // Called from context's audio thread.
59    AudioBus* bus() const;
60
61    // renderingFanOutCount() is the number of AudioNodeInputs that we're connected to during rendering.
62    // Unlike fanOutCount() it will not change during the course of a render quantum.
63    unsigned renderingFanOutCount() const;
64
65    // renderingParamFanOutCount() is the number of AudioParams that we're connected to during rendering.
66    // Unlike paramFanOutCount() it will not change during the course of a render quantum.
67    unsigned renderingParamFanOutCount() const;
68
69    // Must be called with the context's graph lock.
70    void disconnectAll();
71
72    void setNumberOfChannels(unsigned);
73    unsigned numberOfChannels() const { return m_numberOfChannels; }
74    bool isChannelCountKnown() const { return numberOfChannels() > 0; }
75
76    bool isConnected() { return fanOutCount() > 0 || paramFanOutCount() > 0; }
77
78    // Disable/Enable happens when there are still JavaScript references to a node, but it has otherwise "finished" its work.
79    // For example, when a note has finished playing.  It is kept around, because it may be played again at a later time.
80    // They must be called with the context's graph lock.
81    void disable();
82    void enable();
83
84    // updateRenderingState() is called in the audio thread at the start or end of the render quantum to handle any recent changes to the graph state.
85    // It must be called with the context's graph lock.
86    void updateRenderingState();
87
88private:
89    AudioNode* m_node;
90
91    friend class AudioNodeInput;
92    friend class AudioParam;
93
94    // These are called from AudioNodeInput.
95    // They must be called with the context's graph lock.
96    void addInput(AudioNodeInput*);
97    void removeInput(AudioNodeInput*);
98    void addParam(AudioParam*);
99    void removeParam(AudioParam*);
100
101    // fanOutCount() is the number of AudioNodeInputs that we're connected to.
102    // This method should not be called in audio thread rendering code, instead renderingFanOutCount() should be used.
103    // It must be called with the context's graph lock.
104    unsigned fanOutCount();
105
106    // Similar to fanOutCount(), paramFanOutCount() is the number of AudioParams that we're connected to.
107    // This method should not be called in audio thread rendering code, instead renderingParamFanOutCount() should be used.
108    // It must be called with the context's graph lock.
109    unsigned paramFanOutCount();
110
111    // Must be called with the context's graph lock.
112    void disconnectAllInputs();
113    void disconnectAllParams();
114
115    // updateInternalBus() updates m_internalBus appropriately for the number of channels.
116    // It is called in the constructor or in the audio thread with the context's graph lock.
117    void updateInternalBus();
118
119    // Announce to any nodes we're connected to that we changed our channel count for its input.
120    // It must be called in the audio thread with the context's graph lock.
121    void propagateChannelCount();
122
123    // updateNumberOfChannels() is called in the audio thread at the start or end of the render quantum to pick up channel changes.
124    // It must be called with the context's graph lock.
125    void updateNumberOfChannels();
126
127    // m_numberOfChannels will only be changed in the audio thread.
128    // The main thread sets m_desiredNumberOfChannels which will later get picked up in the audio thread in updateNumberOfChannels().
129    unsigned m_numberOfChannels;
130    unsigned m_desiredNumberOfChannels;
131
132    // m_internalBus and m_inPlaceBus must only be changed in the audio thread with the context's graph lock (or constructor).
133    RefPtr<AudioBus> m_internalBus;
134    RefPtr<AudioBus> m_inPlaceBus;
135    // If m_isInPlace is true, use m_inPlaceBus as the valid AudioBus; If false, use the default m_internalBus.
136    bool m_isInPlace;
137
138    HashSet<AudioNodeInput*> m_inputs;
139    typedef HashSet<AudioNodeInput*>::iterator InputsIterator;
140    bool m_isEnabled;
141
142    // For the purposes of rendering, keeps track of the number of inputs and AudioParams we're connected to.
143    // These value should only be changed at the very start or end of the rendering quantum.
144    unsigned m_renderingFanOutCount;
145    unsigned m_renderingParamFanOutCount;
146
147    HashSet<RefPtr<AudioParam>> m_params;
148    typedef HashSet<RefPtr<AudioParam>>::iterator ParamsIterator;
149};
150
151} // namespace WebCore
152
153#endif // AudioNodeOutput_h
154