pa_mac_core_utilities.h

Go to the documentation of this file.
00001 /*
00002  * Helper and utility functions for pa_mac_core.c (Apple AUHAL implementation)
00003  *
00004  * PortAudio Portable Real-Time Audio Library
00005  * Latest Version at: http://www.portaudio.com
00006  *
00007  * Written by Bjorn Roche of XO Audio LLC, from PA skeleton code.
00008  * Portions copied from code by Dominic Mazzoni (who wrote a HAL implementation)
00009  *
00010  * Dominic's code was based on code by Phil Burk, Darren Gibbs,
00011  * Gord Peters, Stephane Letz, and Greg Pfiel.
00012  *
00013  * The following people also deserve acknowledgements:
00014  *
00015  * Olivier Tristan for feedback and testing
00016  * Glenn Zelniker and Z-Systems engineering for sponsoring the Blocking I/O
00017  * interface.
00018  * 
00019  *
00020  * Based on the Open Source API proposed by Ross Bencina
00021  * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
00022  *
00023  * Permission is hereby granted, free of charge, to any person obtaining
00024  * a copy of this software and associated documentation files
00025  * (the "Software"), to deal in the Software without restriction,
00026  * including without limitation the rights to use, copy, modify, merge,
00027  * publish, distribute, sublicense, and/or sell copies of the Software,
00028  * and to permit persons to whom the Software is furnished to do so,
00029  * subject to the following conditions:
00030  *
00031  * The above copyright notice and this permission notice shall be
00032  * included in all copies or substantial portions of the Software.
00033  *
00034  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00035  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00036  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00037  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00038  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00039  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00040  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00041  */
00042 
00043 /*
00044  * The text above constitutes the entire PortAudio license; however, 
00045  * the PortAudio community also makes the following non-binding requests:
00046  *
00047  * Any person wishing to distribute modifications to the Software is
00048  * requested to send the modifications to the original developer so that
00049  * they can be incorporated into the canonical version. It is also 
00050  * requested that these non-binding requests be included along with the 
00051  * license above.
00052  */
00053 
00059 #ifndef PA_MAC_CORE_UTILITIES_H__
00060 #define PA_MAC_CORE_UTILITIES_H__
00061 
00062 #include <pthread.h>
00063 #include "portaudio.h"
00064 #include "pa_util.h"
00065 #include <AudioUnit/AudioUnit.h>
00066 #include <AudioToolbox/AudioToolbox.h>
00067 
00068 #ifndef MIN
00069 #define MIN(a, b)  (((a)<(b))?(a):(b))
00070 #endif
00071 
00072 #ifndef MAX
00073 #define MAX(a, b)  (((a)<(b))?(b):(a))
00074 #endif
00075 
00076 #define ERR(mac_error) PaMacCore_SetError(mac_error, __LINE__, 1 ) 
00077 #define WARNING(mac_error) PaMacCore_SetError(mac_error, __LINE__, 0 )
00078 
00079 
00080 /* Help keep track of AUHAL element numbers */
00081 #define INPUT_ELEMENT  (1)
00082 #define OUTPUT_ELEMENT (0)
00083 
00084 /* Normal level of debugging: fine for most apps that don't mind the occational warning being printf'ed */
00085 /*
00086  */
00087 #define MAC_CORE_DEBUG
00088 #ifdef MAC_CORE_DEBUG
00089 # define DBUG(MSG) do { printf("||PaMacCore (AUHAL)|| "); printf MSG ; fflush(stdout); } while(0)
00090 #else
00091 # define DBUG(MSG)
00092 #endif
00093 
00094 /* Verbose Debugging: useful for developement */
00095 /*
00096 #define MAC_CORE_VERBOSE_DEBUG
00097 */
00098 #ifdef MAC_CORE_VERBOSE_DEBUG
00099 # define VDBUG(MSG) do { printf("||PaMacCore (v )|| "); printf MSG ; fflush(stdout); } while(0)
00100 #else
00101 # define VDBUG(MSG)
00102 #endif
00103 
00104 /* Very Verbose Debugging: Traces every call. */
00105 /*
00106 #define MAC_CORE_VERY_VERBOSE_DEBUG
00107  */
00108 #ifdef MAC_CORE_VERY_VERBOSE_DEBUG
00109 # define VVDBUG(MSG) do { printf("||PaMacCore (vv)|| "); printf MSG ; fflush(stdout); } while(0)
00110 #else
00111 # define VVDBUG(MSG)
00112 #endif
00113 
00114 
00115 
00116 
00117 
00118 #define UNIX_ERR(err) PaMacCore_SetUnixError( err, __LINE__ )
00119 
00120 PaError PaMacCore_SetUnixError( int err, int line );
00121 
00122 /*
00123  * Translates MacOS generated errors into PaErrors
00124  */
00125 PaError PaMacCore_SetError(OSStatus error, int line, int isError);
00126 
00127 /*
00128  * This function computes an appropriate ring buffer size given
00129  * a requested latency (in seconds), sample rate and framesPerBuffer.
00130  *
00131  * The returned ringBufferSize is computed using the following
00132  * constraints:
00133  *   - it must be at least 4.
00134  *   - it must be at least 3x framesPerBuffer.
00135  *   - it must be at least 2x the suggestedLatency.
00136  *   - it must be a power of 2.
00137  * This function attempts to compute the minimum such size.
00138  *
00139  */
00140 long computeRingBufferSize( const PaStreamParameters *inputParameters,
00141                                    const PaStreamParameters *outputParameters,
00142                                    long inputFramesPerBuffer,
00143                                    long outputFramesPerBuffer,
00144                                    double sampleRate );
00145 
00146 /*
00147  * Durring testing of core audio, I found that serious crashes could occur
00148  * if properties such as sample rate were changed multiple times in rapid
00149  * succession. The function below has some fancy logic to make sure that changes
00150  * are acknowledged before another is requested. That seems to help a lot.
00151  */
00152 
00153 typedef struct {
00154    bool once; /* I didn't end up using this. bdr */
00155    pthread_mutex_t mutex;
00156 } MutexAndBool ;
00157 
00158 OSStatus propertyProc(
00159     AudioDeviceID inDevice, 
00160     UInt32 inChannel, 
00161     Boolean isInput, 
00162     AudioDevicePropertyID inPropertyID, 
00163     void* inClientData );
00164 
00165 /* sets the value of the given property and waits for the change to 
00166    be acknowledged, and returns the final value, which is not guaranteed
00167    by this function to be the same as the desired value. Obviously, this
00168    function can only be used for data whose input and output are the
00169    same size and format, and their size and format are known in advance.*/
00170 PaError AudioDeviceSetPropertyNowAndWaitForChange(
00171     AudioDeviceID inDevice,
00172     UInt32 inChannel, 
00173     Boolean isInput, 
00174     AudioDevicePropertyID inPropertyID,
00175     UInt32 inPropertyDataSize, 
00176     const void *inPropertyData,
00177     void *outPropertyData );
00178 
00179 /*
00180  * Sets the sample rate the HAL device.
00181  * if requireExact: set the sample rate or fail.
00182  *
00183  * otherwise      : set the exact sample rate.
00184  *             If that fails, check for available sample rates, and choose one
00185  *             higher than the requested rate. If there isn't a higher one,
00186  *             just use the highest available.
00187  */
00188 PaError setBestSampleRateForDevice( const AudioDeviceID device,
00189                                     const bool isOutput,
00190                                     const bool requireExact,
00191                                     const Float64 desiredSrate );
00192 /*
00193    Attempts to set the requestedFramesPerBuffer. If it can't set the exact
00194    value, it settles for something smaller if available. If nothing smaller
00195    is available, it uses the smallest available size.
00196    actualFramesPerBuffer will be set to the actual value on successful return.
00197    OK to pass NULL to actualFramesPerBuffer.
00198    The logic is very simmilar too setBestSampleRate only failure here is
00199    not usually catastrophic.
00200 */
00201 PaError setBestFramesPerBuffer( const AudioDeviceID device,
00202                                        const bool isOutput,
00203                                        unsigned long requestedFramesPerBuffer, 
00204                                        unsigned long *actualFramesPerBuffer );
00205 #endif /* PA_MAC_CORE_UTILITIES_H__*/

Generated on Wed Aug 22 15:26:18 2007 for PortAudio by  doxygen 1.5.2