Cinder  0.8.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
Node.h
Go to the documentation of this file.
1 /*
2  Copyright (c) 2014, The Cinder Project
3 
4  This code is intended to be used with the Cinder C++ library, http://libcinder.org
5 
6  Redistribution and use in source and binary forms, with or without modification, are permitted provided that
7  the following conditions are met:
8 
9  * Redistributions of source code must retain the above copyright notice, this list of conditions and
10  the following disclaimer.
11  * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
12  the following disclaimer in the documentation and/or other materials provided with the distribution.
13 
14  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
15  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
16  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
17  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
18  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
20  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
21  POSSIBILITY OF SUCH DAMAGE.
22  */
23 
24 #pragma once
25 
26 #include "cinder/audio/Buffer.h"
27 #include "cinder/audio/Exception.h"
28 
29 #include <boost/noncopyable.hpp>
30 #include <boost/logic/tribool.hpp>
31 
32 #include <memory>
33 #include <atomic>
34 #include <set>
35 
36 namespace cinder { namespace audio {
37 
38 typedef std::shared_ptr<class Context> ContextRef;
39 typedef std::shared_ptr<class Node> NodeRef;
40 
59 class Node : public std::enable_shared_from_this<Node>, public boost::noncopyable {
60  public:
63  enum class ChannelMode {
65  SPECIFIED,
70  };
71 
72  struct Format {
73  Format() : mChannels( 0 ), mChannelMode( ChannelMode::MATCHES_INPUT ), mAutoEnable( boost::logic::indeterminate ) {}
74 
76  Format& channels( size_t ch ) { mChannels = ch; return *this; }
78  Format& channelMode( ChannelMode mode ) { mChannelMode = mode; return *this; }
80  Format& autoEnable( bool autoEnable = true ) { mAutoEnable = autoEnable; return *this; }
81 
82  size_t getChannels() const { return mChannels; }
83  ChannelMode getChannelMode() const { return mChannelMode; }
84  boost::tribool getAutoEnable() const { return mAutoEnable; }
85 
86  void setChannels( size_t ch ) { mChannels = ch; }
87  void setChannelMode( ChannelMode mode ) { mChannelMode = mode; }
88  void setAutoEnable( bool autoEnable ) { mAutoEnable = autoEnable; }
89 
90  private:
91  size_t mChannels;
92  ChannelMode mChannelMode;
93  boost::tribool mAutoEnable;
94  };
95 
96  Node( const Format &format );
97  virtual ~Node();
98 
100  void enable();
102  void disable();
104  void setEnabled( bool b = true );
106  bool isEnabled() const { return mEnabled; }
107 
109  virtual void connect( const NodeRef &output );
111  virtual void disconnect( const NodeRef &output );
113  virtual void disconnectAll();
115  virtual void disconnectAllOutputs();
117  virtual void disconnectAllInputs();
118 
120  size_t getNumConnectedInputs() const;
122  size_t getNumConnectedOutputs() const;
124  bool isConnectedToInput( const NodeRef &input ) const;
126  bool isConnectedToOutput( const NodeRef &output ) const;
128  ContextRef getContext() const { return mContext.lock(); }
130  size_t getNumChannels() const { return mNumChannels; }
132  ChannelMode getChannelMode() const { return mChannelMode; }
134  size_t getMaxNumInputChannels() const;
136  size_t getSampleRate() const;
138  size_t getFramesPerBlock() const;
140  bool isAutoEnabled() const { return mAutoEnabled; }
142  void setAutoEnabled( bool b = true ) { mAutoEnabled = b; }
144  bool isInitialized() const { return mInitialized; }
146  bool getProcessesInPlace() const { return mProcessInPlace; }
148  bool canConnectToInput( const NodeRef &input );
150  bool checkCycle( const NodeRef &sourceNode, const NodeRef &destNode ) const;
151 
153  const std::set<NodeRef>& getInputs() const { return mInputs; }
155  std::vector<NodeRef> getOutputs() const;
156 
158  virtual std::string getName();
160  void setName( const std::string &name ) { mName = name; }
161 
163  Buffer* getInternalBuffer() { return &mInternalBuffer; }
165  const Buffer* getInternalBuffer() const { return &mInternalBuffer; }
167  void pullInputs( Buffer *inPlaceBuffer );
168 
169  protected:
170 
172  virtual void initialize() {}
174  virtual void uninitialize() {}
176  virtual void enableProcessing() {}
178  virtual void disableProcessing() {}
180  virtual void process( Buffer *buffer ) {}
181 
182  virtual void sumInputs();
183 
185  virtual bool supportsInputNumChannels( size_t numChannels ) const { return mNumChannels == numChannels; }
187  virtual bool supportsCycles() const { return false; }
189  virtual bool supportsProcessInPlace() const { return true; }
190 
192  virtual void connectInput( const NodeRef &input );
193  virtual void disconnectInput( const NodeRef &input );
194  virtual void disconnectOutput( const NodeRef &output );
195  virtual void configureConnections();
196 
199  bool inputChannelsAreUnequal() const;
200 
202  void setNumChannels( size_t numChannels );
205 
206  void initializeImpl();
207  void uninitializeImpl();
208 
209  BufferDynamic* getSummingBuffer() { return &mSummingBuffer; }
210  const BufferDynamic* getSummingBuffer() const { return &mSummingBuffer; }
211 
212  private:
213  // The owning Context calls this.
214  void setContext( const ContextRef &context ) { mContext = context; }
215 
216  std::weak_ptr<Context> mContext;
217  std::atomic<bool> mEnabled;
218  bool mInitialized;
219  bool mAutoEnabled;
220  bool mProcessInPlace;
221  ChannelMode mChannelMode;
222  size_t mNumChannels;
223  uint64_t mLastProcessedFrame;
224  std::string mName;
225  BufferDynamic mInternalBuffer, mSummingBuffer;
226 
227  std::set<std::shared_ptr<Node> > mInputs;
228  std::vector<std::weak_ptr<Node> > mOutputs;
229 
230  friend class Context;
231  friend class Param;
232 };
233 
235 inline const NodeRef& operator>>( const NodeRef &input, const NodeRef &output )
236 {
237  input->connect( output );
238  return output;
239 }
240 
242 class NodeAutoPullable : public Node {
243  public:
244  virtual ~NodeAutoPullable();
245 
246  virtual void connect( const NodeRef &output ) override;
247  virtual void connectInput( const NodeRef &input ) override;
248  virtual void disconnectInput( const NodeRef &input ) override;
250  virtual void disconnectAllOutputs() override;
251 
252  protected:
253  NodeAutoPullable( const Format &format );
254  void updatePullMethod();
255 
257 };
258 
262  ScopedEnableNode( const NodeRef &node );
264  ScopedEnableNode( const NodeRef &node, bool enable );
266  private:
267  NodeRef mNode;
268  bool mWasEnabled;
269 };
270 
271 class NodeCycleExc : public AudioExc {
272  public:
273  NodeCycleExc( const NodeRef &sourceNode, const NodeRef &destNode );
274 };
275 
276 } } // namespace cinder::audio
size_t getFramesPerBlock() const
Returns the number of frames processed in one block by this Node, which is governed by the Context's ...
Definition: Node.cpp:281
size_t getSampleRate() const
Returns the samplerate of this Node, which is governed by the Context's OutputNode.
Definition: Node.cpp:276
void setNumChannels(size_t numChannels)
Only Node subclasses can specify num channels directly - users specify via Format at construction tim...
Definition: Node.cpp:248
NodeAutoPullable(const Format &format)
Definition: Node.cpp:475
void setAutoEnabled(bool b=true)
Sets whether this Node is automatically enabled / disabled when connected.
Definition: Node.h:142
GLenum mode
Definition: GLee.h:3042
virtual void uninitialize()
Called once the contents of initialize are no longer relevant, i.e. connections have changed...
Definition: Node.h:174
This Node matches it's channels with it's input.
virtual void disconnect(const NodeRef &output)
Disconnects this Node from output.
Definition: Node.cpp:79
GLenum GLenum GLenum input
Definition: GLee.h:8931
void setAutoEnable(bool autoEnable)
Definition: Node.h:88
ChannelMode
Definition: Node.h:63
virtual std::string getName()
Returns a string representing the name of this Node type. Default returns a demangled, compiler-specific class name.
Definition: Node.cpp:466
Definition: Node.h:271
void pullInputs(Buffer *inPlaceBuffer)
Usually called internally by the Node, in special cases sub-classes may need to call this on other No...
Definition: Node.cpp:369
Number of channels has been specified by user or is non-settable.
void enable(GLenum state)
Enables the OpenGL State state. Equivalent to calling to glEnable( state );.
Definition: dx.h:198
std::vector< NodeRef > getOutputs() const
Returns a copy of the NodeRef's referenced by the this Node as outputs. The copy is necessary because...
Definition: Node.cpp:153
~ScopedEnableNode()
Definition: Node.cpp:546
void setChannelMode(ChannelMode mode)
Definition: Node.h:87
size_t getMaxNumInputChannels() const
Returns the maximum number of channels any input has.
Definition: Node.cpp:267
size_t getChannels() const
Definition: Node.h:82
GLsizei const GLchar ** string
Definition: GLee.h:2427
void notifyConnectionsDidChange()
Definition: Node.cpp:450
virtual bool supportsProcessInPlace() const
Default implementation returns true, subclasses should return false if they must process out-of-place...
Definition: Node.h:189
bool isAutoEnabled() const
Returns whether this Node is automatically enabled / disabled when connected.
Definition: Node.h:140
virtual void connect(const NodeRef &output) override
Connects this Node to output.
Definition: Node.cpp:484
ScopedEnableNode(const NodeRef &node)
Constructs an object that will store node's enabled state and restore it at the end of the current sc...
Definition: Node.cpp:529
virtual void connectInput(const NodeRef &input) override
Definition: Node.cpp:490
size_t getNumConnectedOutputs() const
Returns the number of outputs this Node is connected to.
Definition: Node.cpp:199
General Audio exception.
Definition: Exception.h:34
void updatePullMethod()
Definition: Node.cpp:512
virtual void process(Buffer *buffer)
Override to perform audio processing on buffer.
Definition: Node.h:180
Manages the creation, connections, and lifecycle of audio::Node's.
Definition: Context.h:44
BufferDynamic * getSummingBuffer()
Definition: Node.h:209
virtual void disconnectAllInputs()
Disconnects all of this Node's inputs.
Definition: Node.cpp:110
ChannelMode getChannelMode() const
Returns the channel mode.
Definition: Node.h:132
const ChannelRouterNodeRef & operator>>(const NodeRef &input, const ChannelRouterNode::RouteConnector &route)
Enable routing connection syntax:
Definition: ChannelRouterNode.cpp:55
void setChannels(size_t ch)
Definition: Node.h:86
boost::tribool getAutoEnable() const
Definition: Node.h:84
BufferDynamicT< Buffer > BufferDynamic
Definition: Buffer.h:289
bool isConnectedToOutput(const NodeRef &output) const
Returns true if output is connected to this Node as an output, false otherwise.
Definition: Node.cpp:209
bool inputChannelsAreUnequal() const
Definition: Node.cpp:286
bool isInitialized() const
Returns whether this Node is in an initialized state and is capable of processing audio...
Definition: Node.h:144
virtual ~NodeAutoPullable()
Definition: Node.cpp:480
virtual void connectInput(const NodeRef &input)
Definition: Node.cpp:121
bool mIsPulledByContext
Definition: Node.h:256
Format & channels(size_t ch)
Sets the number of channels for the Node.
Definition: Node.h:76
virtual void enableProcessing()
Callled when this Node should enable processing. Initiated from Node::enable().
Definition: Node.h:176
virtual void disconnectAllOutputs()
Disconnects this Node from all outputs.
Definition: Node.cpp:101
void initializeImpl()
Definition: Node.cpp:220
virtual bool supportsCycles() const
Default implementation returns false, return true if it makes sense for the Node to be processed in a...
Definition: Node.h:187
bool isEnabled() const
Returns whether this Node is enabled for processing or not.
Definition: Node.h:106
void setEnabled(bool b=true)
Sets whether this Node is enabled for processing or not.
Definition: Node.cpp:186
virtual bool supportsInputNumChannels(size_t numChannels) const
Default implementation returns true if numChannels matches our format.
Definition: Node.h:185
RAII-style utility class to set a Node's enabled state and have it restored at the end of the current...
Definition: Node.h:260
virtual void disconnectInput(const NodeRef &input)
Definition: Node.cpp:129
std::shared_ptr< class Context > ContextRef
Definition: Node.h:38
Format & channelMode(ChannelMode mode)
Controls how channels will be matched between connected Node's, if necessary.
Definition: Node.h:78
bool getProcessesInPlace() const
Returns whether this Node will process audio with an in-place Buffer.
Definition: Node.h:146
virtual void disconnectOutput(const NodeRef &output)
Definition: Node.cpp:141
void uninitializeImpl()
Definition: Node.cpp:236
virtual void connect(const NodeRef &output)
Connects this Node to output.
Definition: Node.cpp:61
GLuint buffer
Definition: GLee.h:2065
bool canConnectToInput(const NodeRef &input)
Returns whether it is possible to connect to input, example reasons of failure would be this == Node...
Definition: Node.cpp:455
virtual void configureConnections()
Definition: Node.cpp:302
const BufferDynamic * getSummingBuffer() const
Definition: Node.h:210
Definition: Node.h:72
ContextRef getContext() const
Returns the Context associated with this Node.
Definition: Node.h:128
a Node that can be pulled without being connected to any outputs.
Definition: Node.h:242
const std::set< NodeRef > & getInputs() const
Returns an immutable reference to the inputs container.
Definition: Node.h:153
GLboolean GLboolean GLboolean b
Definition: GLee.h:2964
virtual void disconnectAll()
Disconnects this Node from all inputs and outputs.
Definition: Node.cpp:95
Fundamental building block for creating an audio processing graph.
Definition: Node.h:59
bool checkCycle(const NodeRef &sourceNode, const NodeRef &destNode) const
Returns true if there is an unmanageable cycle betweeen sourceNode and destNode. If any Node's in the...
Definition: Node.cpp:434
virtual void initialize()
Called before audio buffers need to be used. There is always a valid Context at this point...
Definition: Node.h:172
GLuint const GLchar * name
Definition: GLee.h:2259
NodeCycleExc(const NodeRef &sourceNode, const NodeRef &destNode)
Definition: Node.cpp:556
void setupProcessWithSumming()
Definition: Node.cpp:423
virtual void disconnectInput(const NodeRef &input) override
Definition: Node.cpp:496
Buffer * getInternalBuffer()
Usually used internally by a Node subclass, returns a pointer to the internal buffer storage...
Definition: Node.h:163
void enable()
Enables this Node for processing. Same as setEnabled( true ).
Definition: Node.cpp:165
GLXContext context
Definition: GLee.h:16985
GLenum GLsizei GLenum format
Definition: GLee.h:969
ChannelMode getChannelMode() const
Definition: Node.h:83
const Buffer * getInternalBuffer() const
Usually used internally by a Node subclass, returns a pointer to the internal buffer storage...
Definition: Node.h:165
virtual void sumInputs()
Definition: Node.cpp:405
void setName(const std::string &name)
Sets this Node's name to a user-specified string.
Definition: Node.h:160
std::shared_ptr< class Node > NodeRef
Definition: Node.h:39
void disable()
Disables this Node for processing. Same as setEnabled( false ).
Definition: Node.cpp:177
Format & autoEnable(bool autoEnable=true)
Whether or not the Node will be auto-enabled when connection changes occur. Default is true for base ...
Definition: Node.h:80
void setChannelMode(ChannelMode mode)
Only Node subclasses can specify channel mode directly - users specify via Format at construction tim...
Definition: Node.cpp:257
size_t getNumConnectedInputs() const
Returns the number of inputs connected to this Node.
Definition: Node.cpp:194
Allows an audio parameter to be controlled over time with sample accuracate curves.
Definition: Param.h:81
size_t getNumChannels() const
Returns the number of channels this Node will process.
Definition: Node.h:130
Node(const Format &format)
Definition: Node.cpp:44
Format()
Definition: Node.h:73
virtual ~Node()
Definition: Node.cpp:57
bool isConnectedToInput(const NodeRef &input) const
Returns true if input is connected to this Node as an input, false otherwise.
Definition: Node.cpp:204
This Node matches it's channels with it's output.
virtual void disconnectAllOutputs() override
Overridden to also remove from Context's auto-pulled list.
Definition: Node.cpp:502
virtual void disableProcessing()
Callled when this Node should disable processing. Initiated from Node::disable(). ...
Definition: Node.h:178