Jamoma API  0.6.0.a19
TTAudioEngine.h
Go to the documentation of this file.
1 /** @file
2 
3  @ingroup dspLibrary
4 
5  @brief The #TTAudioEngine class is the Audio Engine of Jamoma DSP
6 
7  @details #TTAudioEngine is a class that is used to drive realtime audio and scheduling operations in the Jamoma DSP environment.
8  It is currently implemented as a wrapper around PortAudio.
9 
10  QUESTIONS
11 
12  - Should this be a singleton, like the environment object? Can be associated with a key in the global dictionary namespace
13  - How do we properly clean-up the environment from something like Max? I guess we need a quittask?
14 
15  THOUGHTS
16 
17  - A #TTAudioOutput class will work by writing to the #TTAudioEngine's output buffer.
18  - Likewise a #TTAudioInput class will work by retrieving from the #TTAudioEngine's input buffer.
19  - The scheduler, and others like the Jamoma AudioGraph output class, will subscribe to this class for notifications on each call from PortAudio.
20 
21  - PortAudio doesn't work on iOS, so perhaps PortAudio should be separated from the AudioEngine and provide audio driver classes to it.
22 
23  @authors Tim Place, Nathan Wolek, Trond Lossius
24 
25  @copyright Copyright © 2008 by Timothy Place @n
26  This code is licensed under the terms of the "New BSD License" @n
27  http://creativecommons.org/licenses/BSD/
28  */
29 
30 
31 #ifndef __TT_AUDIOENGINE_H__
32 #define __TT_AUDIOENGINE_H__
33 
34 #include "TTDSP.h"
35 #include "TTAudioSignal.h"
36 
37 #include "portaudio.h"
38 
39 /**
40  The #TTAudioEngine class is the Audio Engine of Jamoma DSP.
41  */
42 class TTDSP_EXPORT TTAudioEngine : public TTObjectBase {
44 
45 protected:
46 
47  TTChannelCount mNumInputChannels; ///< The number of input channels
48  TTChannelCount mNumOutputChannels; ///< The number of output channels
49  TTUInt16 mVectorSize; ///< Vector size (frames per buffer)
50  TTUInt32 mSampleRate; ///< Sample rate
51  PaStream* mStream;
52  TTListPtr mCallbackObservers;
53  TTSymbol mInputDevice; ///< The audio device used for audio input
54  TTSymbol mOutputDevice; ///< The audio device used for audio output
55  const PaDeviceInfo* mInputDeviceInfo; ///< A structure providing information and capabilities of PortAudio devices, including information on latency and max number of channels. Refer to the documentation of PortAudio for further references.
56  const PaDeviceInfo* mOutputDeviceInfo; ///< A structure providing information and capabilities of PortAudio devices, including information on latency and max number of channels. Refer to the documentation of PortAudio for further references.
57  TTInt16 mInputDeviceIndex; ///<
58  TTInt16 mOutputDeviceIndex; ///<
59  TTBoolean mIsRunning; ///< A flag indicating if audio is currently being processed
60 
61 public:
62 
63  TTAudioSignalPtr mInputBuffer;
64  TTAudioSignalPtr mOutputBuffer;
65 
66 public:
67 
68  // we are a singleton, so this is how we work with the lifecycle...
69 
70  /**
71  */
72  static TTObjectBasePtr sSingletonInstance;
73 
74  /** We use a dictionary to map the singleton instance to a symbol. */
76 
77  /**
78  */
79  static TTObjectBasePtr create();
80 
81 
82  /**
83  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
84  */
85  static TTErr destroy();
86 
87 
88  /**
89  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
90  */
91  TTErr initStream();
92 
93 
94  /** Start audio processing.
95  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
96  */
97  TTErr start();
98 
99 
100  /** Stop audio processing.
101  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
102  */
103  TTErr stop();
104 
105 
106  /** Monitor how taxing current audio processing is on the CPU.
107  @param unusedInput Not used
108  @param returnedValue Used to return current CPU load.
109  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
110  */
111  TTErr getCpuLoad(const TTValue& unusedInput, TTValue& returnedValue);
112 
113 
114  /** Get the names of all available input devices.
115  @param unusedInput Not used
116  @param returnedDeviceNames Used to return the names of all available input devices.
117  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
118  */
119  TTErr getAvailableInputDeviceNames(const TTValue& unusedInput, TTValue& returnedDeviceNames);
120 
121 
122  /** Get the names of all available output devices.
123  @param unusedInput Not used
124  @param returnedDeviceNames Used to return the names of all available output devices.
125  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
126  */
127  TTErr getAvailableOutputDeviceNames(const TTValue& unusedInput, TTValue& returnedDeviceNames);
128 
129 
130  /** Get the reference pointer for the input signal.
131  @return The reference pointer for the input signal.
132  */
133  TTErr getInputSignalReference(TTValue& anUnusedInput, TTValue& aReturnedAudioSignalPtr);
134 
135 
136  /** Get the reference pointer for the output signal.
137  @return The reference pointer for the output signal.
138  */
139  TTErr getOutputSignalReference(TTValue& anUnusedInput, TTValue& aReturnedAudioSignalPtr);
140 
141  ///// Attribute Accessors /////
142 
143  /** Set what audio input device to use.
144  @param newDeviceName The new audio input device to use.
145  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
146  */
147  TTErr setInputDevice(TTValue& newDeviceName);
148 
149 
150  /** Set what audio output device to use.
151  @param newDeviceName The new audio output device to use.
152  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
153  */
154  TTErr setOutputDevice(TTValue& newDeviceName);
155 
156 
157  /** Set vector size.
158  @param newVectorSize The new vector size to use.
159  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
160  */
161  TTErr setVectorSize(TTValue& newVectorSize);
162 
163 
164  /** Set the sample rate.
165  @param newSampleRate The new sample rate to use.
166  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
167  */
168  TTErr setSampleRate(TTValue& newSampleRate);
169 
170 
171  /**
172  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
173  */
174  TTErr addCallbackObserver(const TTValue& objectToReceiveNotifications, TTValue& unusedOutput);
175 
176 
177  /**
178  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
179  */
180  TTErr removeCallbackObserver(const TTValue& objectCurrentlyReceivingNotifications, TTValue& unusedOutput);
181 
182  /** This is called repeatedly by PortAudio every time a new vector of audio is needed.
183  @param input
184  @param output
185  @param frameCount
186  @param timeInfo
187  @param statusFlags
188  @return
189  */
190  TTInt32 callback(const TTFloat32* input,
191  TTFloat32* output,
192  TTUInt32 frameCount,
193  const PaStreamCallbackTimeInfo* timeInfo,
194  PaStreamCallbackFlags statusFlags);
195 };
196 
197 
198 /** A pointer to a #TTAudioEngine.
199  @ingroup typedefs
200  */
202 
203 
204 
205 
206 /** A C-function used for the callback from PortAudio.
207  @details This simply passes the call to the callback method in the TTAudioEngine object.
208  */
209 int TTAudioEngineStreamCallback(const void* input,
210  void* output,
211  unsigned long frameCount,
212  const PaStreamCallbackTimeInfo* timeInfo,
213  PaStreamCallbackFlags statusFlags,
214  void* userData ) ;
215 
216 
217 
218 #endif // __TT_AUDIOENGINE_H__
219 
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
std::uint16_t TTUInt16
16 bit unsigned integer
Definition: TTBase.h:176
void PaStream
A single PaStream can provide multiple channels of real-time streaming audio input and output to a cl...
Definition: portaudio.h:579
const PaDeviceInfo * mInputDeviceInfo
A structure providing information and capabilities of PortAudio devices, including information on lat...
Definition: TTAudioEngine.h:55
A structure providing information and capabilities of PortAudio devices.
Definition: portaudio.h:444
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
Jamoma DSP Library.
TTUInt32 mSampleRate
Sample rate.
Definition: TTAudioEngine.h:50
int TTAudioEngineStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
A C-function used for the callback from PortAudio.
TTBoolean mIsRunning
A flag indicating if audio is currently being processed.
Definition: TTAudioEngine.h:59
A type that represents the key as a C-String and the value as a pointer to the matching TTSymbol obje...
Definition: TTDictionary.h:47
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
std::int16_t TTInt16
16 bit signed integer
Definition: TTBase.h:175
TTUInt16 mVectorSize
Vector size (frames per buffer)
Definition: TTAudioEngine.h:49
The PortAudio API.
static TTDictionaryPtr sDictionary
We use a dictionary to map the singleton instance to a symbol.
Definition: TTAudioEngine.h:75
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTSymbol mInputDevice
The audio device used for audio input.
Definition: TTAudioEngine.h:53
float TTFloat32
32 bit floating point number
Definition: TTBase.h:187
The TTAudioSignal class represents N vectors of audio samples for M channels.
Definition: TTAudioSignal.h:57
TTSymbol mOutputDevice
The audio device used for audio output.
Definition: TTAudioEngine.h:54
std::int32_t TTInt32
32 bit signed integer
Definition: TTBase.h:177
Represents M channels containing N vectors of audio samples.
unsigned long PaStreamCallbackFlags
Flag bit constants for the statusFlags to PaStreamCallback.
Definition: portaudio.h:652
TTUInt16 TTChannelCount
Data type used when counting the number of channels in multi-channel audio signals and processes...
Definition: TTAudioSignal.h:31
const PaDeviceInfo * mOutputDeviceInfo
A structure providing information and capabilities of PortAudio devices, including information on lat...
Definition: TTAudioEngine.h:56
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
TTAudioEngine * TTAudioEnginePtr
A pointer to a TTAudioEngine.
The TTAudioEngine class is the Audio Engine of Jamoma DSP.
Definition: TTAudioEngine.h:42
TTChannelCount mNumInputChannels
The number of input channels.
Definition: TTAudioEngine.h:47
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
Timing information for the buffers passed to the stream callback.
Definition: portaudio.h:639
TTChannelCount mNumOutputChannels
The number of output channels.
Definition: TTAudioEngine.h:48