Jamoma API  0.6.0.a19
TTAudioGraphObject.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup audioGraphLibrary
4  *
5  * @brief Wraps an object from Jamoma DSP to function within AudioGraph
6  *
7  * @details The TTAudioGraphObjectBase wraps a Jamoma DSP object such that it is possible to build a dynamic graph of audio processing units. It is implemented as a #TTObjectBase so that it can receive dynamically bound messages,
8  * including notifications from other objects.
9  *
10  * @authors Timothy Place, Trond Lossius
11  *
12  * @copyright Copyright © 2010, Timothy Place @n
13  * This code is licensed under the terms of the "New BSD License" @n
14  * http://creativecommons.org/licenses/BSD/
15  */
16 
17 
18 #ifndef __TTAUDIOGRAPH_OBJECT_H__
19 #define __TTAUDIOGRAPH_OBJECT_H__
20 
21 #include "TTAudioGraph.h"
22 #include "TTGraphObjectBase.h"
23 #include "TTAudioGraphOutlet.h"
25 
26 
27 /******************************************************************************************/
28 
29 /**
30  * The TTAudioGraphObjectBase wraps a TTDSP object such that it is possible to
31  * build a dynamic graph of audio processing units.
32  *
33  * It is implemented as a TTObjectBase so that it can receive dynamically bound messages,
34  * including notifications from other objects.
35 */
36 class TTAUDIOGRAPH_EXPORT TTAudioGraphObjectBase : public TTGraphObjectBase {
38 
39 protected:
40 
41  TTAudioGraphProcessStatus mStatus; ///< Used to enable correct processing of feedback loops, multiple destinations, etc.
42  TTAudioGraphDescription mAudioDescription; ///< Used to prevent feedback loops etc. when describing a graph.
43  TTUInt32 mAudioFlags; ///< A bitmask of values defined in #TTAudioGraphFlags.
44  TTAudioGraphInletVector mAudioInlets; ///< The inlets through which we pull audio from sources.
45  TTAudioGraphOutletVector mAudioOutlets; ///< The outlets that processed audio sampled will be passed to.
46  TTUInt32 mNumAudioInlets; ///< Attribute: The number of inputs for this object.
47  TTUInt32 mNumAudioOutlets; ///< Attribute: The number of outlets for this object.
48  TTAudioArray mInputSignals; ///< The buffered input for processing audio with our object.
49  TTAudioArray mOutputSignals; ///< The results of processing audio with our object, buffered for objects requesting it.
50  TTUInt16 mVectorSize; ///< The most recent vector size info passed from the terminal object during a preprocess.
51  TTUInt64 mSampleStamp; ///< The current time in samples, as determined from the pulling of this object.
52  static TTMutexPtr sSharedMutex; ///< A critical region shared by all TTAudioGraphObjectBases to prevent changes to the graph while processing.
53 
54 
55  // Attribute Setters
56 
57  /** Set the number of audio inlets.
58  @param newNumInlets The number of inlets. Each inlet can receieve multichannel signals from several sources.
59  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
60  */
61  TTErr setNumAudioInlets(const TTValue& newNumInlets);
62 
63 
64  /** Set the number of audio outlets.
65  @param newNumOutlets The number of outlets. Each outlet can pass on multichannel signals to inlets of one or more downstream TTAudioGraphObjectBases.
66  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
67  */
68  TTErr setNumAudioOutlets(const TTValue& newNumOutlets);
69 
70 
71 public:
72 
73  /** ...
74  */
76  {
77  return (TTAudioObject&)mKernel;
78  }
79 
80 
81  void resetSampleStamp()
82  {
83  mSampleStamp = -1;
84  }
85 
86 
87  /** Set an audio flag. Flags are defined as bitmasks.
88  @param flag The flag to set.
89  */
91  {
92  mAudioFlags |= flag;
93  }
94 
95 
96  /** remove an audio flag. Flags are defined as bitmasks.
97  @param flag The flag to remove.
98  */
100  {
101  mAudioFlags = mAudioFlags & ~flag;
102  }
103 
104 
105  /** Get the number of channels for an outlet.
106  @param forOutletNumber The outlet that we want to retrieve informaiton about.
107  */
109  {
110  if (forOutletNumber < mAudioOutlets.size())
111  return mAudioOutlets[forOutletNumber].mBufferedOutput->getNumChannelsAsInt();
112  else
113  return 0;
114  }
115 
116 
117  /** Set the number of channels for an outlet.
118  @param forOutletNumber The outlet that we want to set information for.
119  @param numChannels The number of channels that the audio signal from this outlet is to have.
120  */
121  void setOutputNumChannels(TTUInt16 forOutletNumber, TTChannelCount numChannels)
122  {
123  sSharedMutex->lock();
124 
125  if (forOutletNumber < mAudioOutlets.size()) {
126  TTValue v(numChannels);
127 
128  // TODO: should not update MaxNumChannels unless we are growing it larger...
129  mAudioOutlets[forOutletNumber].mBufferedOutput->setMaxNumChannels(v);
130  mAudioOutlets[forOutletNumber].mBufferedOutput->setNumChannels(v);
131  }
132  sSharedMutex->unlock();
133  }
134 
135 
136  /** Get the vector size for an outlet.
137  @param forOutletNumber The outlet that we want to retrieve information about.
138  @return Vector size.
139  */
141  {
142  if (forOutletNumber < mAudioOutlets.size())
143  return mAudioOutlets[forOutletNumber].mBufferedOutput->getVectorSizeAsInt();
144  else
145  return 0;
146  }
147 
148 
149  /** Get the sample rate of the audio passed from one of the outlets.
150  @param forOutletNumber The outlet that we want to retrieve information about.
151  @param The sample rate of the audio passed from the outlet.
152  */
154  {
155  if (forOutletNumber < mAudioOutlets.size())
156  return mAudioOutlets[forOutletNumber].mBufferedOutput->getSampleRate();
157  else
158  return 0;
159  }
160 
161 
162  /** Get the sample rate that this object use when processing audio.
163  @return The current sample rate of the object.
164  */
166  {
167  TTUInt32 sr;
168  mKernel.get(kTTSym_sampleRate, sr);
169  return sr;
170  }
171 
172 
173  /** Prepare for a request to descibe all of the graph.
174  */
175  void prepareAudioDescription();
176 
177 
178  /** @brief Describe this object as part of the action of describing a complete audio graph.
179  @details The node is requested to declare itself as part of an action to describe all of the audio graph.
180  As part of this action the request is also propagated to its upstream neighboors, and retrieved information on the graph is passed back down again to the sink(s) of the graph.
181  @param descs Pointer to the graph description vector used by the downstream neighboor(s) to retrieve information on this node and its upstesream connections.
182  */
183  void getAudioDescription(TTAudioGraphDescription& desc);
184 
185 
186  /**
187  Clear the list of source objects from which this object will try to pull audio.
188  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
189  */
190  TTErr resetAudio();
191 
192 
193  /** Add a source to the list of objects from which to request audio.
194  @param anObject The Jamoma AudioGraph object which is supplying us with input.
195  @param anInletNumber If this object has a second input mechanism (e.g. a sidechain input), then that is indicated here.
196  Typically the value passed here will be 0, indicating the normal audio input.
197  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
198  */
199  TTErr connectAudio(TTAudioGraphObjectBasePtr anObject, TTUInt16 fromOutletNumber=0, TTUInt16 toInletNumber=0);
200 
201 
202  /** Drop a source from the list of objects from which to request audio. In other words, disconnect.
203  @param anObject The Jamoma AudioGraph object which is supplying us with input.
204  @param anInletNumber If this object has a second input mechanism (e.g. a sidechain input), then that is indicated here.
205  Typically the value passed here will be 0, indicating the normal audio input.
206  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
207  */
208  TTErr dropAudio(TTAudioGraphObjectBasePtr anObject, TTUInt16 fromOutletNumber=0, TTUInt16 toInletNumber=0);
209 
210 
211  /** The thread protection for processing is important: we cannot have the graph nodes being deleted or re-arranged while we are pulling.
212  Further more, this is true for the entire process cycle: preprocess, process, and postprocess.
213  Thus, this lock must be thrown by the code the is calling the methods from outside of this class.
214  */
216  {
217  sSharedMutex->lock();
218  }
219 
220  /** The thread protection for processing is important: we cannot have the graph nodes being deleted or re-arranged while we are pulling.
221  Further more, this is true for the entire process cycle: preprocess, process, and postprocess.
222  Thus, this lock must be thrown by the code the is calling the methods from outside of this class. */
224  {
225  sSharedMutex->unlock();
226  }
227 
228  /** This method is called by an object about to process audio, prior to calling getAudioOutput().
229  As with the getAudioOutput() method, this is driven by the destination object and working up through the chains.
230  @param initData Data provided by the terminal object so that the graph will be able to adapt to it.
231  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
232  */
233  virtual TTErr preprocess(const TTAudioGraphPreprocessData& initData);
234 
235 
236  /** This method is required to be implemented by all objects except for those existing solely as a destination.
237  @param audioOutput This method is passed a reference to an audio signal pointer.
238  We then set this audio signal pointer to point to the TTAudioSignal containing our calculated samples.
239  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
240  */
241  virtual TTErr process(TTAudioSignalPtr& returnedSignal, TTUInt64 sampleStamp, TTUInt16 forOutletNumber=0);
242 
243 };
244 
245 
246 class TTAudioGraphObject : public TTObject {
247 
248 public:
249  /* Don't need to a TTSymbol version because a c-string is converted to a TTValue automatically and the method below will work for both cases.
250  Further, the presence of both leads to compile errors regarding ambiguity between the two when compiling with clang.
251  TTAudioGraphObject(const TTSymbol aClassName) :
252  TTObject("audio.object", aClassName)
253  {}
254  */
255 
256  // first arg must be classname -- used by ruby language bindings
257  TTAudioGraphObject(const TTValue args) :
258  TTObject("audio.object", args)
259  {}
260 
261  TTErr send(const TTSymbol aName)
262  {
263  return ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().send(aName);
264  }
265 
266  TTErr send(const TTSymbol aName, const TTValue& anInputValue, TTValue& anOutputValue)
267  {
268  return ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().send(aName, anInputValue, anOutputValue);
269  }
270 
271  template <class T>
272  TTErr set(const TTSymbol aName, T aValue)
273  {
274  return ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().set(aName, aValue);
275  }
276 
277  template <class T>
278  TTErr get(const TTSymbol aName, T& aReturnedValue)
279  {
280  return ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().get(aName, aReturnedValue);
281  }
282 
283  /** Return a list of names of the available attributes.
284  @param attributeNameList Pointer to a list of all attributes registered with this TTObjectBase.
285  */
286  void attributes(TTValue& returnedAttributeNames)
287  {
288  ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().attributes(returnedAttributeNames);
289  }
290 
291  /** Return a list of names of the available messages.
292  @param messageNameList Pointer to a list of all messages registered with this TTObjectBase.
293  */
294  void messages(TTValue& returnedMessageNames)
295  {
296  ((TTAudioGraphObjectBase*)instance())->getUnitGenerator().messages(returnedMessageNames);
297  }
298 
299  TTErr connectAudio(TTAudioGraphObject& anObject, TTUInt16 fromOutletNumber=0, TTUInt16 toInletNumber=0)
300  {
301  return ((TTAudioGraphObjectBase*)instance())->connectAudio((TTAudioGraphObjectBase*)anObject.instance(), fromOutletNumber, toInletNumber);
302  }
303 
304  TTErr dropAudio(TTAudioGraphObject& anObject, TTUInt16 fromOutletNumber=0, TTUInt16 toInletNumber=0)
305  {
306  return ((TTAudioGraphObjectBase*)instance())->dropAudio((TTAudioGraphObjectBase*)anObject.instance(), fromOutletNumber, toInletNumber);
307  }
308 
309  /**
310  Clear the list of source objects from which this object will try to pull audio.
311  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
312  */
313  TTErr resetAudio()
314  {
315  return ((TTAudioGraphObjectBase*)instance())->resetAudio();
316  }
317 
318  /** @brief Describe this object as part of the action of describing a complete audio graph.
319  @details The node is requested to declare itself as part of an action to describe all of the audio graph.
320  As part of this action the request is also propagated to its upstream neighboors,
321  and retrieved information on the graph is passed back down again to the sink(s) of the graph.
322  @param descs Pointer to the graph description vector used by the downstream neighboor(s) to retrieve information on this node and its upstesream connections.
323  */
324  void getAudioDescription(TTAudioGraphDescription& desc)
325  {
326  ((TTAudioGraphObjectBase*)instance())->getAudioDescription(desc);
327  }
328 
329 };
330 
331 #endif // __TTAUDIOGRAPH_OBJECT_H__
The TTGraphObjectBase wraps a TTDSP object such that it is possible to build a dynamic graph of audio...
std::uint16_t TTUInt16
16 bit unsigned integer
Definition: TTBase.h:176
TTUInt32 getOutputSampleRate(TTUInt16 forOutletNumber)
Get the sample rate of the audio passed from one of the outlets.
TTErr send(const TTSymbol aName)
Send a message to this object with no arguments.
Definition: TTObject.cpp:135
void messages(TTValue &returnedMessageNames) const
Return a list of names of the available messages.
Definition: TTObject.cpp:123
TTUInt16 getOutputVectorSize(TTUInt16 forOutletNumber)
Get the vector size for an outlet.
TTUInt16 mVectorSize
The most recent vector size info passed from the terminal object during a preprocess.
std::uint64_t TTUInt64
64 bit unsigned integer
Definition: TTBase.h:180
void removeAudioFlag(TTAudioGraphFlags flag)
remove an audio flag.
Wrap TTAudioSignalArray instances for convenience.
Definition: TTAudioObject.h:88
Describes a node in an audio processing graph.
void setOutputNumChannels(TTUInt16 forOutletNumber, TTChannelCount numChannels)
Set the number of channels for an outlet.
Create and use Jamoma object instances.
Definition: TTObject.h:29
TTAudioGraphOutletVector mAudioOutlets
The outlets that processed audio sampled will be passed to.
This object provides a description of a TTAudioGraphObject and its sources.
void lockProcessing()
The thread protection for processing is important: we cannot have the graph nodes being deleted or re...
Registers classes for the primary AudioGraph library.
Defines a single 'outlet' from an individual AudioGraph object.
Wrap audio objects for convenience.
Jamoma Asynchronous Object Graph Layer.
TTAudioGraphDescription mAudioDescription
Used to prevent feedback loops etc. when describing a graph.
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
TTAudioArray mInputSignals
The buffered input for processing audio with our object.
TTErr set(const TTSymbol aName, T aValue)
Set an attribute value for an object.
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTUInt32 mNumAudioInlets
Attribute: The number of inputs for this object.
TTAudioGraphProcessStatus
[doxygenAppendixC_enumExample]
Definition: TTAudioGraph.h:48
The TTAudioSignal class represents N vectors of audio samples for M channels.
Definition: TTAudioSignal.h:57
TTAudioObject & getUnitGenerator()
...
TTUInt32 mNumAudioOutlets
Attribute: The number of outlets for this object.
void unlockProcessing()
The thread protection for processing is important: we cannot have the graph nodes being deleted or re...
TTUInt16 TTChannelCount
Data type used when counting the number of channels in multi-channel audio signals and processes...
Definition: TTAudioSignal.h:31
TTAudioGraphFlags
[doxygenAppendixC_bitmaskExample]
Definition: TTAudioGraph.h:70
void addAudioFlag(TTAudioGraphFlags flag)
Set an audio flag.
TTChannelCount getOutputNumChannels(TTUInt16 forOutletNumber)
Get the number of channels for an outlet.
TTUInt64 mSampleStamp
The current time in samples, as determined from the pulling of this object.
TTAudioArray mOutputSignals
The results of processing audio with our object, buffered for objects requesting it.
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
The TTAudioGraphObjectBase wraps a TTDSP object such that it is possible to build a dynamic graph of ...
[doxygenAppendixC_bitmaskExample]
Definition: TTAudioGraph.h:81
void attributes(TTValue &returnedAttributeNames) const
Return a list of names of the available attributes.
Definition: TTObject.cpp:111
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
TTAudioGraphInletVector mAudioInlets
The inlets through which we pull audio from sources.
TTObject mKernel
The actual TT object doing the processing.
TTObjectBase * instance() const
Return a direct pointer to the internal instance.
Definition: TTObject.cpp:105
TTUInt32 getSampleRate()
Get the sample rate that this object use when processing audio.
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
TTAudioGraphProcessStatus mStatus
Used to enable correct processing of feedback loops, multiple destinations, etc.
static TTMutexPtr sSharedMutex
A critical region shared by all TTAudioGraphObjectBases to prevent changes to the graph while process...
TTUInt32 mAudioFlags
A bitmask of values defined in TTAudioGraphFlags.