libs/appleutility/CAAudioUnit.h

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