Jamoma API  0.6.0.a19
CAAudioUnit.h
1 /* Copyright 2007 Apple Inc. All Rights Reserved.
2 
3  Disclaimer: IMPORTANT: This Apple software is supplied to you by
4  Apple Inc. ("Apple") in consideration of your agreement to the
5  following terms, and your use, installation, modification or
6  redistribution of this Apple software constitutes acceptance of these
7  terms. If you do not agree with these terms, please do not use,
8  install, modify or redistribute this Apple software.
9 
10  In consideration of your agreement to abide by the following terms, and
11  subject to these terms, Apple grants you a personal, non-exclusive
12  license, under Apple's copyrights in this original Apple software (the
13  "Apple Software"), to use, reproduce, modify and redistribute the Apple
14  Software, with or without modifications, in source and/or binary forms;
15  provided that if you redistribute the Apple Software in its entirety and
16  without modifications, you must retain this notice and the following
17  text and disclaimers in all such redistributions of the Apple Software.
18  Neither the name, trademarks, service marks or logos of Apple Inc.
19  may be used to endorse or promote products derived from the Apple
20  Software without specific prior written permission from Apple. Except
21  as expressly stated in this notice, no other rights or licenses, express
22  or implied, are granted by Apple herein, including but not limited to
23  any patent rights that may be infringed by your derivative works or by
24  other works in which the Apple Software may be incorporated.
25 
26  The Apple Software is provided by Apple on an "AS IS" basis. APPLE
27  MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
28  THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS
29  FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND
30  OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
31 
32  IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL
33  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
34  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
35  INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION,
36  MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED
37  AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE),
38  STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE
39  POSSIBILITY OF SUCH DAMAGE.
40 */
41 #ifndef __CAAudioUnit_h__
42 #define __CAAudioUnit_h__
43 
44 #if !defined(__COREAUDIO_USE_FLAT_INCLUDES__)
45  #include <CoreAudio/CoreAudio.h>
46  #include <AudioUnit/AudioUnit.h>
47  #if !TARGET_OS_IPHONE
48  #include <AudioUnit/MusicDevice.h>
49  #endif
50  #include <AudioToolbox/AUGraph.h>
51 #else
52  #include <ConditionalMacros.h>
53  #include <CoreAudioTypes.h>
54  #include <AudioUnit.h>
55  #include <MusicDevice.h>
56  #include <AUGraph.h>
57  #include <MusicDevice.h>
58 #endif
59 
60 #include <vector>
61 #include "CAStreamBasicDescription.h"
62 #include "CAComponent.h"
63 #include "CAAudioChannelLayout.h"
64 
65 // defined below
66 class CAAUChanHelper;
67 
68 // These constructors will NOT throw exceptions - so "check" after creation if AU IsValid()
69 // The destructor will NOT automatically close the AU down
70 // This state should be managed by the Caller
71 // once closed, the unit represented by this object is no longer valid
72 // it is up to the user of this object to ensure its validity is in sync
73 // if it is removed from a graph
74 
75 // methods that can significantly change the state of the AU (like its format) are
76 // NOT const whereas those that don't change the externally related state of the AU are not const
77 
78 class CAAudioUnit {
79  enum {
80  paramErr = -50,
81  badComponentSelector = (long)0x80008002
82  };
83 public:
84  typedef std::vector<AudioChannelLayoutTag> ChannelTagVector;
85  typedef ChannelTagVector::iterator ChannelTagVectorIter;
86 
87 public:
88  CAAudioUnit ()
89  : mDataPtr(0) {}
90 
91  CAAudioUnit (const AudioUnit& inUnit);
92 
93  CAAudioUnit (const AUNode &inNode, const AudioUnit& inUnit);
94 
95  CAAudioUnit (const CAAudioUnit& y)
96  : mDataPtr(0) { *this = y; }
97 
98  static OSStatus Open (const CAComponent& inComp, CAAudioUnit &outUnit);
99 
100  ~CAAudioUnit ();
101 
102  void Close ();
103 
104 
105  CAAudioUnit& operator= (const CAAudioUnit& y);
106 
107  bool operator== (const CAAudioUnit& y) const;
108 
109  bool operator== (const AudioUnit& y) const;
110 
111 #pragma mark __State Management
112  bool IsValid () const;
113 
114  AudioUnit AU() const;
115  operator AudioUnit () const { return AU(); }
116 
117  const CAComponent& Comp() const { return mComp; }
118 
119  bool FromAUGraph () const { return GetAUNode() != 0 && GetAUNode() != kCAAU_DoNotKnowIfAUNode; }
120 
121  AUNode GetAUNode () const;
122  operator AUNode () const { return GetAUNode(); }
123 
124 #pragma mark __API Wrapper
125  OSStatus Initialize() const {
126  return AudioUnitInitialize(AU());
127  }
128  OSStatus Uninitialize() const {
129  return AudioUnitUninitialize(AU());
130  }
131  OSStatus GetPropertyInfo(AudioUnitPropertyID propID, AudioUnitScope scope, AudioUnitElement element,
132  UInt32 *outDataSize, Boolean *outWritable) const
133  {
134  return AudioUnitGetPropertyInfo(AU(), propID, scope, element, outDataSize, outWritable);
135  }
136  OSStatus GetProperty(AudioUnitPropertyID propID, AudioUnitScope scope, AudioUnitElement element,
137  void *outData, UInt32 *ioDataSize) const
138  {
139  return AudioUnitGetProperty(AU(), propID, scope, element, outData, ioDataSize);
140  }
141  OSStatus SetProperty(AudioUnitPropertyID propID, AudioUnitScope scope, AudioUnitElement element,
142  const void *inData, UInt32 inDataSize)
143  {
144  return AudioUnitSetProperty(AU(), propID, scope, element, inData, inDataSize);
145  }
146  OSStatus SetParameter(AudioUnitParameterID inID, AudioUnitScope scope, AudioUnitElement element,
147  Float32 value, UInt32 bufferOffsetFrames=0);
148 
149  OSStatus GetParameter(AudioUnitParameterID inID, AudioUnitScope scope, AudioUnitElement element,
150  Float32 &outValue) const;
151 
152  OSStatus Render (AudioUnitRenderActionFlags * ioActionFlags,
153  const AudioTimeStamp * inTimeStamp,
154  UInt32 inOutputBusNumber,
155  UInt32 inNumberFrames,
156  AudioBufferList * ioData);
157 
158  OSStatus Reset (AudioUnitScope scope, AudioUnitElement element)
159  {
160  return AudioUnitReset (AU(), scope, element);
161  }
162  OSStatus GlobalReset ()
163  {
164  return AudioUnitReset (AU(), kAudioUnitScope_Global, 0);
165  }
166 
167  OSStatus AddRenderNotify (AURenderCallback inProc, void *inProcRefCon)
168  {
169  return AudioUnitAddRenderNotify (AU(), inProc, inProcRefCon);
170  }
171 
172  OSStatus RemoveRenderNotify (AURenderCallback inProc, void *inProcRefCon)
173  {
174  return AudioUnitRemoveRenderNotify (AU(), inProc, inProcRefCon);
175  }
176 
177  OSStatus AddPropertyListener (AudioUnitPropertyID inID,
178  AudioUnitPropertyListenerProc inProc,
179  void * inProcRefCon)
180  {
181  return AudioUnitAddPropertyListener (AU(), inID, inProc, inProcRefCon);
182  }
183 
184  OSStatus RemovePropertyListener (AudioUnitPropertyID inID,
185  AudioUnitPropertyListenerProc inProc,
186  void * inProcUserData);
187 
188 #if !TARGET_OS_IPHONE
189 // Fast dispatch support for MIDI Effects or Music Devices
190  OSStatus MIDIEvent (UInt32 inStatus,
191  UInt32 inData1,
192  UInt32 inData2,
193  UInt32 inOffsetSampleFrame);
194 
195  // uses the default VoiceForGroup value - this is the normal case
196  OSStatus StartNote (MusicDeviceGroupID inGroupID,
197  NoteInstanceID * outNoteInstanceID,
198  UInt32 inOffsetSampleFrame,
199  const MusicDeviceNoteParams * inParams)
200  {
201  return StartNote (kMusicNoteEvent_UseGroupInstrument,
202  inGroupID, outNoteInstanceID,
203  inOffsetSampleFrame, inParams);
204  }
205 
206  OSStatus StartNote (MusicDeviceInstrumentID inInstrument,
207  MusicDeviceGroupID inGroupID,
208  NoteInstanceID * outNoteInstanceID,
209  UInt32 inOffsetSampleFrame,
210  const MusicDeviceNoteParams * inParams);
211 
212  OSStatus StopNote (MusicDeviceGroupID inGroupID,
213  NoteInstanceID inNoteInstanceID,
214  UInt32 inOffsetSampleFrame);
215 #endif
216 
217 #pragma mark __Format Utilities
218  // typically you ask this about an AU
219  // These Questions are asking about Input and Output...
220 
221  // These ones just say whether an AU can do a single combination of channels
222  // and is fine if the AU has a single output (and if an input, a single input)
223  bool CanDo (int inChannelsInOut) const
224  {
225  return CanDo (inChannelsInOut, inChannelsInOut);
226  }
227 
228  bool CanDo ( int inChannelsIn,
229  int inChannelsOut) const;
230 
231  // This version does a more thorough test for ANY AU with ANY ins/outs
232  // you pass in the channel helper (for the current element count on that scope)
233 
234  bool CanDo ( const CAAUChanHelper &input,
235  const CAAUChanHelper &output) const;
236 
237  bool SupportsNumChannels () const;
238 
239  bool HasChannelLayouts (AudioUnitScope inScope,
240  AudioUnitElement inEl) const;
241 
242  OSStatus GetChannelLayoutTags (AudioUnitScope inScope,
243  AudioUnitElement inEl,
244  ChannelTagVector &outChannelVector) const;
245 
246  bool HasChannelLayout (AudioUnitScope inScope,
247  AudioUnitElement inEl) const;
248 
249  OSStatus GetChannelLayout (AudioUnitScope inScope,
250  AudioUnitElement inEl,
251  CAAudioChannelLayout &outLayout) const;
252 
253  OSStatus SetChannelLayout (AudioUnitScope inScope,
254  AudioUnitElement inEl,
255  const CAAudioChannelLayout &inLayout);
256 
257  OSStatus SetChannelLayout (AudioUnitScope inScope,
258  AudioUnitElement inEl,
259  const AudioChannelLayout &inLayout,
260  UInt32 inSize);
261 
262  OSStatus ClearChannelLayout (AudioUnitScope inScope,
263  AudioUnitElement inEl);
264 
265  OSStatus GetFormat (AudioUnitScope inScope,
266  AudioUnitElement inEl,
267  AudioStreamBasicDescription &outFormat) const;
268  // if an AudioChannelLayout is either required or set, this call can fail
269  // and the SetChannelLayout call should be used to set the format
270  OSStatus SetFormat (AudioUnitScope inScope,
271  AudioUnitElement inEl,
272  const AudioStreamBasicDescription &inFormat);
273 
274  OSStatus GetSampleRate (AudioUnitScope inScope,
275  AudioUnitElement inEl,
276  Float64 &outRate) const;
277  OSStatus SetSampleRate (AudioUnitScope inScope,
278  AudioUnitElement inEl,
279  Float64 inRate);
280 
281  // this sets the sample rate on all in/out buses of the AU
282  OSStatus SetSampleRate (Float64 inSampleRate);
283 
284  OSStatus NumberChannels (AudioUnitScope inScope,
285  AudioUnitElement inEl,
286  UInt32 &outChans) const;
287 
288  OSStatus GetNumberChannels (AudioUnitScope inScope,
289  AudioUnitElement inEl,
290  UInt32 &outChans) const
291  {
292  return NumberChannels (inScope, inEl, outChans);
293  }
294 
295  OSStatus SetNumberChannels (AudioUnitScope inScope,
296  AudioUnitElement inEl,
297  UInt32 inChans);
298 
299  OSStatus IsElementCountWritable (AudioUnitScope inScope, bool &outWritable) const;
300 
301  OSStatus GetElementCount (AudioUnitScope inScope, UInt32 &outCount) const;
302 
303  OSStatus SetElementCount (AudioUnitScope inScope, UInt32 inCount);
304 
305  // value of -1 for outTotalNumChannels indicates no restriction on num channels
306  // for ex. the Matrix Mixer satisfies this (its in/out element count is writable, and can be set to
307  // any number of channels.
308  // outTotalNumChannels is only valid if method returns true...
309  bool HasDynamicInputs (SInt32 &outTotalNumChannels) const
310  {
311  return HasDynamicScope (kAudioUnitScope_Input, outTotalNumChannels);
312  }
313 
314  bool HasDynamicOutputs (SInt32 &outTotalNumChannels) const
315  {
316  return HasDynamicScope (kAudioUnitScope_Output, outTotalNumChannels);
317  }
318 
319  // here, if the in (or out) elements are dynamic, then you supply the number of elements
320  // you want on in (or out) scope, and the number of channels on each consecutive element
321  OSStatus ConfigureDynamicInput (UInt32 inNumElements, UInt32 *inChannelsPerElement, Float64 inSampleRate)
322  {
323  return ConfigureDynamicScope (kAudioUnitScope_Input, inNumElements, inChannelsPerElement, inSampleRate);
324  }
325 
326  OSStatus ConfigureDynamicOutput (UInt32 inNumElements, UInt32 *inChannelsPerElement, Float64 inSampleRate)
327  {
328  return ConfigureDynamicScope (kAudioUnitScope_Output, inNumElements, inChannelsPerElement, inSampleRate);
329  }
330 
331  bool CanBypass () const;
332 
333  bool GetBypass () const;
334 
335  OSStatus SetBypass (bool inBypass) const;
336 
337  Float64 Latency () const;
338 
339  // these calls just deal with the global preset state
340  // you could rescope them to deal with presets on the part scope
341  OSStatus GetAUPreset (CFPropertyListRef &outData) const;
342 
343  OSStatus SetAUPreset (CFPropertyListRef &inData);
344 
345  OSStatus SetAUPresetFromDocument (CFPropertyListRef &inData);
346 
347  OSStatus GetPresentPreset (AUPreset &outData) const;
348 
349  OSStatus SetPresentPreset (AUPreset &inData);
350 
351  bool HasCustomView () const;
352 
353 #pragma mark __Print
354  void Print () const { Print (stdout); }
355  void Print (FILE* file) const;
356 
357 private:
358  CAComponent mComp;
359 
360  class AUState;
361  AUState* mDataPtr;
362 
363  // this can throw - so wrap this up in a static that returns a result code...
364  CAAudioUnit (const CAComponent& inComp);
365 
366  bool HasDynamicScope (AudioUnitScope inScope, SInt32 &outTotalNumChannels) const;
367  OSStatus ConfigureDynamicScope (AudioUnitScope inScope,
368  UInt32 inNumElements,
369  UInt32 *inChannelsPerElement,
370  Float64 inSampleRate);
371  bool ValidateChannelPair (int inChannelsIn,
372  int inChannelsOut,
373  const AUChannelInfo * info,
374  UInt32 numChanInfo) const;
375 
376  bool ValidateDynamicScope (AudioUnitScope inScope,
377  SInt32 &outTotalNumChannels,
378  const AUChannelInfo * info,
379  UInt32 numInfo) const;
380  bool CheckOneSide (const CAAUChanHelper &inHelper,
381  bool checkOutput,
382  const AUChannelInfo *info,
383  UInt32 numInfo) const;
384  enum {
385  kCAAU_DoNotKnowIfAUNode = -1
386  };
387 };
388 
389 class CAAUChanHelper {
390 public:
391  CAAUChanHelper()
392  : mChans(mStaticChans), mNumEls(0), mDidAllocate(false)
393  {
394  memset (mChans, 0, sizeof(UInt32) * kStaticElCount);
395  }
396  CAAUChanHelper(UInt32 inMaxElems);
397  CAAUChanHelper(const CAAudioUnit &inAU, AudioUnitScope inScope);
398  CAAUChanHelper (const CAAUChanHelper &c)
399  : mChans(mStaticChans), mNumEls(0), mDidAllocate(false)
400  { *this = c; }
401 
402  ~CAAUChanHelper();
403 
404  CAAUChanHelper& operator= (const CAAUChanHelper &c);
405 
406  UInt32 * mChans;
407  UInt32 mNumEls;
408 
409 private:
410  enum {
411  kStaticElCount = 8
412  };
413  UInt32 mStaticChans[kStaticElCount];
414  bool mDidAllocate;
415 };
416 
417 #endif
bool TTFOUNDATION_EXPORT operator==(const TTObject &anObject, const TTObject &anotherObject)
Compare two objects for equality.
Definition: TTObject.cpp:167