diff options
Diffstat (limited to 'pd/portaudio_v18/docs')
26 files changed, 3117 insertions, 0 deletions
diff --git a/pd/portaudio_v18/docs/index.html b/pd/portaudio_v18/docs/index.html new file mode 100644 index 00000000..bd94eaa7 --- /dev/null +++ b/pd/portaudio_v18/docs/index.html @@ -0,0 +1,78 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="PortAudio Docs, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Docs</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Documentation</h1></center> +</td> +</tr> +</table></center> + +<p>Copyright 2000 Phil Burk and Ross Bencina +<br> +<hr WIDTH="100%"> +<h2> +V18</h2> + +<h3> +<a href="portaudio_h.txt">API Reference for V18</a></h3> + +<blockquote>The Application Programmer Interface is documented in "portaudio.h".</blockquote> + +<h3> +<a href="pa_tutorial.html">Tutorial</a></h3> + +<blockquote>Describes how to write audio programs using the PortAudio API.</blockquote> + +<h3> +<a href="pa_impl_guide.html">Implementation Guide</a></h3> + +<blockquote>Describes how to write an implementation of PortAudio for a +new computer platform.</blockquote> + +<h3> +<a href="portaudio_icmc2001.pdf">Paper Presented at ICMC2001</a> (PDF)</h3> + +<blockquote>Describes the PortAudio API and discusses implementation issues. +Written July 2001.</blockquote> + +<hr WIDTH="100%"> +<h2> +V19 - improved API</h2> + +<h3> +<a href="proposals/index.html">Proposed V19 Changes</a></h3> + +<blockquote>Describes API changes being considered by the developer community. +Feedback welcome.</blockquote> + +<h3> +<a href="v19-doxydocs/">API Reference for V19</a></h3> + +<blockquote>Reference documents for the Application Programmer Interface +for V19 generated by doxygen.</blockquote> + +<hr WIDTH="100%"> +<h2> +Miscellaneous</h2> + +<h3> +<a href="latency.html">Improving Latency</a></h3> + +<blockquote>How to tune your computer to achieve the lowest possible audio +delay.</blockquote> +<a href="http://www.portaudio.com/">Return to PortAudio Home Page</a> +</body> +</html> diff --git a/pd/portaudio_v18/docs/latency.html b/pd/portaudio_v18/docs/latency.html new file mode 100644 index 00000000..87f1d122 --- /dev/null +++ b/pd/portaudio_v18/docs/latency.html @@ -0,0 +1,192 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +<a href="http://www.portaudio.com">PortAudio</a> Latency</h1></center> +</td> +</tr> +</table></center> + +<p>This page discusses the issues of audio latency for <a href="http://www.portaudio.com">PortAudio</a> +. It offers suggestions on how to lower latency to improve the responsiveness +of applications. +<blockquote><b><a href="#what">What is Latency?</a></b> +<br><b><a href="#portaudio">PortAudio and Latency</a></b> +<br><b><a href="#macintosh">Macintosh</a></b> +<br><b><a href="#unix">Unix</a></b> +<br><b><a href="#windows">WIndows</a></b></blockquote> +By Phil Burk, Copyright 2002 Phil Burk and Ross Bencina +<h2> +<a NAME="what"></a>What is Latency?</h2> +Latency is basically longest time that you have to wait before you obtain +a desired result. For digital audio output it is the time between making +a sound in software and finally hearing it. +<p>Consider the example of pressing a key on the ASCII keyboard to play +a note. There are several stages in this process which each contribute +their own latency. First the operating system must respond to the keypress. +Then the audio signal generated must work its way through the PortAudio +buffers. Then it must work its way through the audio card hardware. Then +it must go through the audio amplifier which is very quick and then travel +through the air. Sound travels at abous one foot per millisecond through +air so placing speakers across the room can add 5-20 msec of delay. +<p>The reverse process occurs when recording or responding to audio input. +If you are processing audio, for example if you implement a software guitar +fuzz box, then you have both the audio input and audio output latencies +added together. +<p>The audio buffers are used to prevent glitches in the audio stream. +The user software writes audio into the output buffers. That audio is read +by the low level audio driver or by DMA and sent to the DAC. If the computer +gets busy doing something like reading the disk or redrawing the screen, +then it may not have time to fill the audio buffer. The audio hardware +then runs out of audio data, which causes a glitch. By using a large enough +buffer we can ensure that there is always enough audio data for the audio +hardware to play. But if the buffer is too large then the latency is high +and the system feels sluggish. If you play notes on the keyboard then the +"instrument" will feel unresponsive. So you want the buffers to be as small +as possible without glitching. +<h2> +<a NAME="portaudio"></a>PortAudio and Latency</h2> +The only delay that PortAudio can control is the total length of its buffers. +The Pa_OpenStream() call takes two parameters: numBuffers and framesPerBuffer. +The latency is also affected by the sample rate which we will call framesPerSecond. +A frame is a set of samples that occur simultaneously. For a stereo stream, +a frame is two samples. +<p>The latency in milliseconds due to this buffering is: +<blockquote><tt>latency_msec = 1000 * numBuffers * framesPerBuffer / framesPerSecond</tt></blockquote> +This is not the total latency, as we have seen, but it is the part we can +control. +<p>If you call Pa_OpenStream() with numBuffers equal to zero, then PortAudio +will select a conservative number that will prevent audio glitches. If +you still get glitches, then you can pass a larger value for numBuffers +until the glitching stops. if you try to pass a numBuffers value that is +too small, then PortAudio will use its own idea of the minimum value. +<p>PortAudio decides on the minimum number of buffers in a conservative +way based on the frameRate, operating system and other variables. You can +query the value that PortAudio will use by calling: +<blockquote><tt>int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate +);</tt></blockquote> +On some systems you can override the PortAudio minimum if you know your +system can handle a lower value. You do this by setting an environment +variable called PA_MIN_LATENCY_MSEC which is read by PortAudio when it +starts up. This is supported on the PortAudio implementations for Windows +MME, Windows DirectSound, and Unix OSS. +<h2> +<a NAME="macintosh"></a>Macintosh</h2> +The best thing you can do to improve latency on Mac OS 8 and 9 is to turn +off Virtual Memory. PortAudio V18 will detect that Virtual Memory is turned +off and use a very low latency. +<p>For Mac OS X the latency is very low because Apple Core Audio is so +well written. You can set the PA_MIN_LATENCY_MSEC variable using: +<blockquote><tt>setenv PA_MIN_LATENCY_MSEC 4</tt></blockquote> + +<h2> +<a NAME="unix"></a>Unix</h2> +PortAudio under Unix currently uses a backgroud thread that reads and writes +to OSS. This gives you decent but not great latency. But if you raise the +priority of the background thread to a very priority then you can get under +10 milliseconds latency. In order to raise your priority you must run the +PortAudio program as root! You must also set PA_MIN_LATENCY_MSEC using +the appropriate command for your shell. +<h2> +<a NAME="windows"></a>Windows</h2> +Latency under Windows is a complex issue because of all the alternative +operating system versions and device drivers. I have seen latency range +from 8 milliseconds to 400 milliseconds. The worst case is when using Windows +NT. Windows 98 is a little better, and Windows XP can be quite good if +properly tuned. +<p>The underlying audio API also makes a lot of difference. If the audio +device has its own DirectSound driver then DirectSound can often provide +better latency than WMME. But if a real DirectSound driver is not available +for your device then it is emulated using WMME and the latency can be very +high. That's where I saw the 400 millisecond latency. The ASIO implementation +is generally very good and will give the lowest latency if available. +<p>You can set the PA_MIN_LATENCY_MSEC variable to 50, for example, by +entering in MS-DOS: +<blockquote><tt>set PA_MIN_LATENCY_MSEC=50</tt></blockquote> +If you enter this in a DOS window then you must run the PortAudio program +from that same window for the variable to have an effect. You can add that +line to your C:\AUTOEXEC.BAT file and reboot if you want it to affect any +PortAudio based program. +<p>For Windows XP, you can set environment variables as follows: +<ol> +<li> +Select "Control Panel" from the "Start Menu".</li> + +<li> +Launch the "System" Control Panel</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Click on the "Environment Variables" button.</li> + +<li> +Click "New" button under User Variables.</li> + +<li> +Enter PA_MIN_LATENCY_MSEC for the name and some optimistic number for the +value.</li> + +<li> +Click OK, OK, OK.</li> +</ol> + +<h3> +Improving Latency on Windows</h3> +There are several steps you can take to improve latency under windows. +<ol> +<li> +Avoid reading or writng to disk when doing audio.</li> + +<li> +Turn off all automated background tasks such as email clients, virus scanners, +backup programs, FTP servers, web servers, etc. when doing audio.</li> + +<li> +Disconnect from the network to prevent network traffic from interrupting +your CPU.</li> +</ol> +<b>Important: </b>Windows XP users can also tune the OS to favor background +tasks, such as audio, over foreground tasks, such as word processing. I +lowered my latency from 40 to 10 milliseconds using this simple technique. +<ol> +<li> +Select "Control Panel" from the "Start Menu".</li> + +<li> +Launch the "System" Control Panel</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Click on the "Settings" button in the Performance area.</li> + +<li> +Click on the "Advanced" tab.</li> + +<li> +Select "Background services" in the Processor Scheduling area.</li> + +<li> +Click OK, OK.</li> +</ol> +Please let us know if you have others sugestions for lowering latency. +<br> +<br> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_drivermodel.c.txt b/pd/portaudio_v18/docs/pa_drivermodel.c.txt new file mode 100644 index 00000000..956f664c --- /dev/null +++ b/pd/portaudio_v18/docs/pa_drivermodel.c.txt @@ -0,0 +1,488 @@ +/* + This file contains the host-neutral code for implementing multiple driver model + support in PortAudio. + + It has not been compiled, but it is supplied only for example purposes at this stage. + + TODO: use of CHECK_DRIVER_MODEL is bogus in some instances since some + of those functions don't return a PaError + + +*/ + +#include "pa_drivermodel.h.txt" + + +#ifndef PA_MULTIDRIVER +/* single driver support, most functions will stay in the implementation files */ + +PaDriverModelID Pa_CountDriverModels() +{ + return 1; +} + +/* +Perhaps all drivers should define this with this signature +const PaDriverModelInfo* Pa_GetDriverModelInfo( PaDriverModelID driverModelID ) +{ +} +*/ + +PaDeviceID Pa_DriverModelDefaultInputDeviceID( PaDriverModelID driverModelID ) +{ + return Pa_GetDefaultInputDeviceID(); +} + + +PaDeviceID Pa_DriverModelDefaultOutputDeviceID( PaDriverModelID driverModelID ) +{ + return Pa_GetDefaultInputDeviceID(); +} + +/* +Perhaps all drivers should define with this signature +int Pa_DriverModelMinNumBuffers( PaDriverModelID driverModelID, int framesPerBuffer, double sampleRate ) +{ + +} +*/ + +int Pa_DriverModelCountDevices( PaDriverModelID driverModelID ) +{ + return Pa_CountDevices(); +} + +PaDeviceID Pa_DriverModelGetDeviceID(PaDriverModelID driverModelID, int perDriverModelIndex ) +{ + return perDriverModelIndex; +} + + +#else +/* multidriver support */ + + +typedef PaError (*PaInitializeFunPtr)( PaDriverModelImplementation** ); + +/* + the initializers array is a static table of function pointers + to all the available driverModels on the current platform. + + the order of pointers in the array is important. the first + pointer is always considered to be the "default" driver model. +*/ + +static PaInitializeFunPtr driverModelInitializers[] = { +#ifdef WINDOWS + PaWin32WMME_MultiDriverInitialize, + PaWin32DS_MultiDriverInitialize, + PaASIO_MultiDriverInitialize +#endif +#ifdef MAC + PaMacSM_MultiDriverInitialize, + PaMacCA_MultiDriverInitialize, + PaASIO_MultiDriverInitialize +#endif +/* other platforms here */ + (PaInitializeFunPtr*)0 /* NULL terminate the list */ +}; + + +/* + the driverModels array is a dynamically created table of + currently available driverModels. +*/ +static PaDriverModelImplementation* driverModels = 0; +static int numDriverModels = 0; + + +#define PA_CHECK_INITIALIZED\ + if( driverModels == 0 ) + return paLibraryNotInitialised + +#define PA_CHECK_DRIVER_MODEL_ID( id ) + if( id < 0 || id >= numDriverModels ) + return paBadDriverModelID; + + +/* + ConvertPublicDeviceIdToImplementationDeviceId converts deviceId + from a public device id, to a device id for a particular + PortAudio implementation. On return impl will either point + to a valid implementation or will be NULL. +*/ +static void ConvertPublicDeviceIDToImplementationDeviceID( + PaDriverModelImplementation *impl, PaDeviceID deviceID ) +{ + int i, count; + + impl = NULL; + + for( i=0; i < numDriverModels; ++i ){ + count = driverModels[i]->countDevices(); + if( deviceID < count ){ + impl = driverModels[i]; + return NULL; + }else{ + deviceID -= count; + } + } +} + +static PaDeviceID ConvertImplementationDeviceIDToPublicDeviceID( + PaDriverModelID driverModelID, PaDeviceID deviceID ) +{ + int i; + + for( i=0; i < driverModelID; ++i ) + deviceID += driverModels[i]->countDevices(); +} + + +PaError Pa_Initialize( void ) +{ + PaError result = paNoError; + int i, initializerCount; + PaDriverModelImplementation *impl; + + if( driverModels != 0 ) + return paAlreadyInitialized; + + /* count the number of driverModels */ + initializerCount=0; + while( driverModelInitializers[initializerCount] != 0 ){ + ++initializerCount; + } + + driverModels = malloc( sizeof(PaDriverModelImplementation*) * initializerCount ); + if( driverModels == NULL ) + return paInsufficientMemory; + + numDriverModels = 0; + for( i=0; i<initializerCount; ++i ){ + result = (*driverModelInitializers[i])( &impl ); + if( result == paNoError ){ + driverModels[numDriverModels] = impl; + ++numDriverModels; + }else{ + // TODO: terminate the drivers which have already been initialized. + } + } + + return result; +} + + + +PaError Pa_Terminate( void ) +{ + int i; + + PA_CHECK_INITIALIZED; + + /* + rather than require each implementation to do it separately we could + keep track of all open streams and close them here + */ + + for( i=0; i<numDriverModels; ++i ) + driverModels[i]->terminate( driverModels[i] ); +} + + +long Pa_GetHostError( void ) +{ + PA_CHECK_INITIALIZED; + + under construction. depends on error text proposal. +} + + +const char *Pa_GetErrorText( PaError errnum ) +{ + PA_CHECK_INITIALIZED; + + under construction. may need to call driver model specific code + depending on how the error text proposal pans out. +} + + + +int Pa_CountDevices() +{ + int i, result; + + PA_CHECK_INITIALIZED; + + result = 0; + for( i=0; i < numDriverModels; ++i ) + result += driverModels[i]->countDevices(); + + return result; +} + + +PaDeviceID Pa_GetDefaultInputDeviceID( void ) +{ + PA_CHECK_INITIALIZED; + + return driverModels[0]->getDefaultInputDeviceID(); +} + +PaDeviceID Pa_GetDefaultOutputDeviceID( void ) +{ + PA_CHECK_INITIALIZED; + + return driverModels[0]->getDefaultInputDeviceID(); +} + + +const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID deviceID ) +{ + PaDriverModelImplementation *impl; + + PA_CHECK_INITIALIZED; + + ConvertPublicDeviceIDToImplementationDeviceID( impl, deviceID ); + if( impl == NULL ) + return paInvalidDeviceID; + + return impl->getDeviceInfo( deviceID ); +} + +/* NEW MULTIPLE DRIVER MODEL FUNCTIONS ---------------------------------- */ + +PaDriverModelID Pa_CountDriverModels() +{ + PA_CHECK_INITIALIZED; + + return numDriverModels; +} + + +const PaDriverModelInfo* Pa_GetDriverModelInfo( PaDriverModelID driverModelID ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return driverModels[ driverModelID ]->getDriverModelInfo(); +} + + +PaDeviceID Pa_DriverModelDefaultInputDeviceID( PaDriverModelID driverModelID ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return ConvertImplementationDeviceIDToPublicDeviceID( driverModelID, + driverModels[ driverModelID ]->getDefaultInputDeviceID(); +} + + +PaDeviceID Pa_DriverModelDefaultOutputDeviceID( PaDriverModelID driverModelID ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return ConvertImplementationDeviceIDToPublicDeviceID( driverModelID, + driverModels[ driverModelID ]->getDefaultOutputDeviceID(); +} + + +int Pa_DriverModelMinNumBuffers( PaDriverModelID driverModelID, int framesPerBuffer, double sampleRate ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return driverModels[ driverModelID ]->getMinNumBuffers( int framesPerBuffer, double sampleRate ); +} + + +int Pa_DriverModelCountDevices( PaDriverModelID driverModelID ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return driverModels[ driverModelID ]->coundDevices(); +} + +PaDeviceID Pa_DriverModelGetDeviceID(PaDriverModelID driverModelID, int perDriverModelIndex ) +{ + PA_CHECK_INITIALIZED; + PA_CHECK_DRIVER_MODEL_ID( driverModelID ); + + return ConvertImplementationDeviceIDToPublicDeviceID( driverModelID, perDriverModelIndex ); +} + +/* END NEW MULTIPLE DRIVER MODEL FUNCTIONS ------------------------------ */ + + +PaError Pa_OpenStream( PortAudioStream** stream, + PaDeviceID inputDevice, + int numInputChannels, + PaSampleFormat inputSampleFormat, + void *inputDriverInfo, + PaDeviceID outputDevice, + int numOutputChannels, + PaSampleFormat outputSampleFormat, + void *outputDriverInfo, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PaStreamFlags streamFlags, + PortAudioCallback *callback, + void *userData ) +{ + PaError result; + PaDriverModelImplementation *inputImpl, *outputImpl, impl; + + PA_CHECK_INITIALIZED; + + if( inputDevice != paNoDevice ){ + ConvertPublicDeviceIDToImplementationDeviceID( inputImpl, inputDevice ); + if( inputImpl == NULL ) + return paInvalidDeviceID; + else + impl = inputImpl; + } + + if( outputDevice != paNoDevice ){ + ConvertPublicDeviceIDToImplementationDeviceID( outputImpl, outputDevice ); + if( outputImpl == NULL ) + return paInvalidDeviceID; + else + impl = outputImpl; + } + + if( inputDevice != paNoDevice && outputDevice != paNoDevice ){ + if( inputImpl != outputImpl ) + return paDevicesMustBelongToTheSameDriverModel; + } + + + result = impl->openStream( stream, inputDevice, numInputChannels, inputSampleFormat, inputDriverInfo, + outputDevice, numOutputChannels, outputSampleFormat, outputDriverInfo, + sampleRate, framesPerBuffer, numberOfBuffers, streamFlags, callback, userData ); + + + if( result == paNoError ) + ((PaStreamImplementation*)stream)->magic = PA_STREAM_MAGIC; + + return result; +} + + +PaError Pa_OpenDefaultStream( PortAudioStream** stream, + int numInputChannels, + int numOutputChannels, + PaSampleFormat sampleFormat, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PortAudioCallback *callback, + void *userData ) +{ + PaError result; + int inputDevice = driverModels[0]->getDefaultInputDeviceID; + int outputDevice = driverModels[0]->getDefaultOutputDeviceID; + + result = driverModels[0]->openStream( stream, inputDevice, numInputChannels, sampleFormat, 0, + outputDevice, numOutputChannels, sampleFormat, 0, + sampleRate, framesPerBuffer, numberOfBuffers, + streamFlags, callback, userData ); + + if( result == paNoError ) + ((PaStreamImplementation*)stream)->magic = PA_STREAM_MAGIC; + + return result; +} + + +PaError Pa_CloseStream( PortAudioStream* stream ) +{ + PA_CHECK_INITIALIZED; + + PaError result = ((PaStreamImplementation*)stream)->close(); + + if( result == PaNoError ) + ((PaStreamImplementation*)stream)->magic = 0; /* clear magic number */ + + return result; +} + + +PaError Pa_StartStream( PortAudioStream *stream ); +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->start(); +} + + +PaError Pa_StopStream( PortAudioStream *stream ); +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->stop(); +} + + +PaError Pa_AbortStream( PortAudioStream *stream ); +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->abort(); +} + + +PaError Pa_StreamActive( PortAudioStream *stream ) +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->active(); +} + +PaTimestamp Pa_StreamTime( PortAudioStream *stream ) +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->time(); +} + + +double Pa_StreamCPULoad( PortAudioStream* stream ) +{ + PA_CHECK_INITIALIZED; + + return ((PaStreamImplementation*)stream)->cpuLoad(); +} + + + +int Pa_GetMinNumBuffers( PaDeviceID deviceID, int framesPerBuffer, double sampleRate ) +{ + PaDriverModelImplementation *impl; + PA_CHECK_INITIALIZED; + + ConvertPublicDeviceIDToImplementationDeviceID( impl, deviceID ); + if( impl == NULL ) + return paInvalidDeviceID; + + return impl->getMinNumBuffers( framesPerBuffer, sampleRate ); +} + + +void Pa_Sleep( long msec ) +{ + same as existing implementaion +} + + +PaError Pa_GetSampleSize( PaSampleFormat format ) +{ + same as existing implementation +} + +#endif /* PA_MULTIDRIVER */ + + diff --git a/pd/portaudio_v18/docs/pa_drivermodel.h.txt b/pd/portaudio_v18/docs/pa_drivermodel.h.txt new file mode 100644 index 00000000..f3f2ca2a --- /dev/null +++ b/pd/portaudio_v18/docs/pa_drivermodel.h.txt @@ -0,0 +1,143 @@ +#ifndef PA_MULTIDRIVERMODEL_H +#define PA_MULTIDRIVERMODEL_H + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + + +/* + This file contains the host-neutral code for implementing multiple driver model + support in PortAudio. + + It has not been compiled, but it is supplied only for example purposes at this stage. +*/ + + +#include "portaudio.h" + + +#define PA_MULTIDRIVER // for multidriver support + + + +TODO: declare function pointer types for the following function pointers + +/* + Each driver model implementation needs to implement an initialize function + which is added to the driverModelInitializers array in pa_multidrivermodel.c + + the initializer function needs to return a pointer to a + PaDriverModelImplementation structure, or NULL if initiliazation failed. TODO: need error code instead + + the function pointer members of this structure point to funtions + which operate in exactly the same way as the corresponding functions + in the PortAudio API. +*/ + +struct{ + fptr terminate; /* takes the PaDriverModelImplementation* returned by initialize */ + fptr getDriverModelInfo; + fptr getHostError; + fptr getHostErrorText; + fptr countDevices; + fptr getDefaultInputDeviceID; + fptr getDefaultOutputDeviceID; + fptr getDeviceInfo; + fptr openStream; + fptr getMinNumBuffers; +} PaDriverModelImplementation; + +/* + whenever an implementaion's openstream method is called it should return a + PortAudioStream* whose first segment is actually the following structure. + + the functions pointer members of this structure point to funcitons + which operate in exactly the same way as the corresponding functions + in the PortAudio API. +*/ +struct{ + unsigned long magic; + fptr close; + fptr start; + fptr stop; + fptr abort; + fptr active; + fptr time; + fptr cpuLoad; +} PaStreamImplementation; + +/* + Implementations should set magic to PA_STREAM_MAGIC when opening + a stream _and_ clear it to zero when closing a stream. + All functions which operate on streams should check the validity + of magic. +*/ + +#define PA_STREAM_MAGIC 0x12345678 + +#define PA_CHECK_STREAM( stream )\ + if( ((PaStreamImplementation*)stream)->magic != PA_STREAM_MAGIC )\ + return paBadStreamPtr; + + +/* + PA_API allows the same implementation to be used for single + driver model and multi-driver model operation. If + PA_MULTIDRIVER not defined, PA_API will declare api + functions as global, otherwise they will be static, and include + the drivermodel code. + + Usage would be something like: + + int PA_API(CountDevices)(); + + The PA_MULTIDRIVER_SUPPORT macro declares the initialization and + termination functions required by the multidriver support. it also + allocates and deallocates the PaDriverModelImplementation structure. + + TODO: add macros for initializing PaStreamImplementation PortAudioStream + these would be PA_INITIALIZE_STREAM and PA_TERMINATE_STREAM + they would assign and clear the magic number and assign the + interface functions if neceassary. +*/ + +#ifdef PA_MULTIDRIVER + +#define PA_API( model, name ) static Pa ## model ## _ ## name + +#define PA_MULTIDRIVER_SUPPORT( model )\ +PaError Pa_ ## model ## _MultiDriverTerminate( PaStreamImplementation *impl )\ +{\ + free( impl );\ + return Pa ## model ## _Terminate();\ +}\ +PaError Pa ## model ## _MultiDriverInitialize( PaStreamImplementation** impl )\ +{\ + PaError result = Pa ## model ## _Initialize();\ +\ + if( result == paNoError ){\ + *impl = malloc( sizeof( PaDriverModelImplementation ) );\ + if( impl == NULL ){\ + // TODO: call terminate, return an error + }else{\ + (*impl)->terminate = Pa ## model ## _MultiDriverTerminate();\ + (*impl)->getDriverModelInfo = Pa ## model ## _GetDriverModelInfo();\ + (*impl)->getHostError = Pa ## model ## _GetHostError();\ + // TODO: assign the rest of the interface functions + }\ + }\ + return result;\ +} + +#else /* !PA_MULTIDRIVER */ + +#define PA_API( model, name ) Pa_ ## name + +#define PA_MULTIDRIVER_SUPPORT + +#endif /* PA_MULTIDRIVER */ + + + +#endif /* PA_MULTIDRIVERMODEL_H */ diff --git a/pd/portaudio_v18/docs/pa_impl_guide.html b/pd/portaudio_v18/docs/pa_impl_guide.html new file mode 100644 index 00000000..50abc304 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_impl_guide.html @@ -0,0 +1,197 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +<a href="http://www.portaudio.com">PortAudio</a> Implementation Guide</h1></center> +</td> +</tr> +</table></center> + +<p>This document describes how to implement the PortAudio API on a new +computer platform. Implementing PortAudio on a new platform, makes it possible +to port many existing audio applications to that platform. +<p>By Phil Burk +<br>Copyright 2000 Phil Burk and Ross Bencina +<p>Note that the license says: <b>"Any person wishing to distribute modifications +to the Software is requested to send the modifications to the original +developer so that they can be incorporated into the canonical version."</b>. +So when you have finished a new implementation, please send it back to +us at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>" +so that we can make it available for other users. Thank you! +<h2> +Download the Latest PortAudio Implementation</h2> +Always start with the latest implementation available at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>". +Look for the nightly snapshot under the CVS section. +<h2> +Select an Existing Implementation as a Basis</h2> +The fastest way to get started is to take an existing implementation and +translate it for your new platform. Choose an implementation whose architecture +is as close as possible to your target. +<ul> +<li> +DirectSound Implementation - pa_win_ds - Uses a timer callback for the +background "thread". Polls a circular buffer and writes blocks of data +to keep it full.</li> + +<li> +Windows MME - pa_win_wmme - Spawns an actual Win32 thread. Writes blocks +of data to the HW device and waits for events that signal buffer completion.</li> + +<li> +Linux OSS - pa_linux - Spawns a real thread that writes to the "/dev/dsp" +stream using blocking I/O calls.</li> +</ul> +When you write a new implementation, you will be using some code that is +in common with all implementations. This code is in the folder "pa_common". +It provides various functions such as parameter checking, error code to +text conversion, sample format conversion, clipping and dithering, etc. +<p>The code that you write will go into a separate folder called "pa_{os}_{api}". +For example, code specific to the DirectSound interface for Windows goes +in "pa_win_ds". +<h2> +Read Docs and Code</h2> +Famialiarize yourself with the system by reading the documentation provided. +here is a suggested order: +<ol> +<li> +User Programming <a href="pa_tutorial.html">Tutorial</a></li> + +<li> +Header file "pa_common/portaudio.h" which defines API.</li> + +<li> +Header file "pa_common/pa_host.h" for host dependant code. This definces +the routine you will need to provide.</li> + +<li> +Shared code in "pa_common/pa_lib.c".</li> + +<li> +Docs on Implementation of <a href="pa_impl_startstop.html">Start/Stop</a> +code.</li> +</ol> + +<h2> +Implement Output to Default Device</h2> +Now we are ready to crank some code. For instant gratification, let's try +to play a sine wave. +<ol> +<li> +Link the test program "pa_tests/patest_sine.c" with the file "pa_lib.c" +and the implementation specific file you are creating.</li> + +<li> +For now, just stub out the device query code and the audio input code.</li> + +<li> +Modify PaHost_OpenStream() to open your default target device and get everything +setup.</li> + +<li> +Modify PaHost_StartOutput() to start playing audio.</li> + +<li> +Modify PaHost_StopOutput() to stop audio.</li> + +<li> +Modify PaHost_CloseStream() to clean up. Free all memory that you allocated +in PaHost_OpenStream().</li> + +<li> +Keep cranking until you can play a sine wave using "patest_sine.c".</li> + +<li> +Once that works, try "patest_pink.c", "patest_clip.c", "patest_sine8.c".</li> + +<li> +To test your Open and Close code, try "patest_many.c".</li> + +<li> +Now test to make sure that the three modes of stopping are properly supported +by running "patest_stop.c".</li> + +<li> +Test your implementation of time stamping with "patest_sync.c".</li> +</ol> + +<h2> +Implement Device Queries</h2> +Now that output is working, lets implement the code for querying what devices +are available to the user. Run "pa_tests/pa_devs.c". It should print all +of the devices available and their characteristics. +<h2> +Implement Input</h2> +Implement audio input and test it with: +<ol> +<li> +patest_record.c - record in half duplex, play back as recorded.</li> + +<li> +patest_wire.c - full duplex, copies input to output. Note that some HW +may not support full duplex.</li> + +<li> +patest_fuzz.c - plug in your guitar and get a feel for why latency is an +important issue in computer music.</li> + +<li> +paqa_devs.c - try to open every device and use it with every possible format</li> +</ol> + +<h2> +Debugging Tools</h2> +You generally cannot use printf() calls to debug real-time processes because +they disturb the timing. Also calling printf() from your background thread +or interrupt could crash the machine. So PA includes a tool for capturing +events and storing the information while it is running. It then prints +the events when Pa_Terminate() is called. +<ol> +<li> +To enable trace mode, change TRACE_REALTIME_EVENTS in "pa_common/pa_trace.h" +from a (0) to a (1).</li> + +<li> +Link with "pa_common/pa_trace.c".</li> + +<li> +Add trace messages to your code by calling:</li> + +<br><tt> void AddTraceMessage( char *msg, int data );</tt> +<br><tt>for example</tt> +<br><tt> AddTraceMessage("Pa_TimeSlice: past_NumCallbacks ", +past->past_NumCallbacks );</tt> +<li> +Run your program. You will get a dump of events at the end.</li> + +<li> +You can leave the trace messages in your code. They will turn to NOOPs +when you change TRACE_REALTIME_EVENTS back to (0).</li> +</ol> + +<h2> +Delivery</h2> +Please send your new code along with notes on the implementation back to +us at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>". +We will review the implementation and post it with your name. If you had +to make any modifications to the code in "pa_common" or "pa_tests" <b>please</b> +send us those modifications and your notes. We will try to merge your changes +so that the "pa_common" code works with <b>all</b> implementations. +<p>If you have suggestions for how to make future implementations easier, +please let us know. +<br>THANKS! +<br> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_impl_startstop.html b/pd/portaudio_v18/docs/pa_impl_startstop.html new file mode 100644 index 00000000..0f2d0ce5 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_impl_startstop.html @@ -0,0 +1,190 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Internal docs. How a stream is started or stopped."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Implementation - Start/Stop</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Implementation</h1></center> +</td> +</tr> +</table></center> + +<h2> +Starting and Stopping Streams</h2> +PortAudio is generally executed in two "threads". The foreground thread +is the application thread. The background "thread" may be implemented as +an actual thread, an interrupt handler, or a callback from a timer thread. +<p>There are three ways that PortAudio can stop a stream. In each case +we look at the sequence of events and the messages sent between the two +threads. The following variables are contained in the internalPortAudioStream. +<blockquote><tt>int past_IsActive; +/* Background is still playing. */</tt> +<br><tt>int past_StopSoon; /* Stop +when last buffer done. */</tt> +<br><tt>int past_StopNow; /* +Stop IMMEDIATELY. */</tt></blockquote> + +<h3> +Pa_AbortStream()</h3> +This function causes the background thread to terminate as soon as possible +and audio I/O to stop abruptly. +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td>sets <tt>StopNow</tt></td> + +<td></td> +</tr> + +<tr> +<td></td> + +<td>sees <tt>StopNow</tt>, </td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<h3> +Pa_StopStream()</h3> +This function stops the user callback function from being called and then +waits for all audio data written to the output buffer to be played. In +a system with very low latency, you may not hear any difference between +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td>sets StopSoon</td> + +<td></td> +</tr> + +<tr> +<td></td> + +<td>stops calling user callback</td> +</tr> + +<tr> +<td></td> + +<td>continues until output buffer empty</td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<h3> +User callback returns one.</h3> +If the user callback returns one then the user callback function will no +longer be called. Audio output will continue until all audio data written +to the output buffer has been played. Then the audio I/O is stopped, the +background thread terminates, and the stream becomes inactive. +<br> +<table BORDER COLS=2 WIDTH="60%" > +<tr> +<td><b>Foreground Thread</b></td> + +<td><b>Background Thread</b></td> +</tr> + +<tr> +<td></td> + +<td>callback returns 1</td> +</tr> + +<tr> +<td></td> + +<td>sets StopSoon</td> +</tr> + +<tr> +<td></td> + +<td>stops calling user callback</td> +</tr> + +<tr> +<td></td> + +<td>continues until output buffer empty</td> +</tr> + +<tr> +<td></td> + +<td>clears IsActive, stops thread</td> +</tr> + +<tr> +<td>waits for thread to exit</td> + +<td></td> +</tr> + +<tr> +<td>turns off audio I/O</td> + +<td></td> +</tr> +</table> + +<br> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_asio.html b/pd/portaudio_v18/docs/pa_tut_asio.html new file mode 100644 index 00000000..a7fa7d3a --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_asio.html @@ -0,0 +1,108 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font></h2> + +<h2> +Compiling for ASIO (Windows or Macintosh)</h2> + +<blockquote>ASIO is a low latency audio API from Steinberg. To compile +an ASIO application, you must first <a href="http://www.steinberg.net/en/ps/support/3rdparty/">download +the ASIO SDK</a> from Steinberg. You also need to obtain ASIO drivers from +the manufacturer of your audio hardware. +<p>Note: I am using '/' as a file separator below. On Macintosh replace +'/' with ':'. On Windows, replace '/' with '\'. +<p>You may try compiling the "pa_tests/patest_saw.c" file first because +it is the simplest. +<p>Several files are common to all PortAudio implementations. Add the following +source files to your project: +<blockquote>pa_common/pa_lib.c +<br>pa_common/portaudio.h +<br>pa_common/pa_host.h</blockquote> +To use ASIO with the PortAudio library add the following: +<blockquote> +<pre>pa_asio/pa_asio.cpp</pre> +</blockquote> +</blockquote> + +<h3> +Macintosh Specific</h3> + +<blockquote>Note: there is a bug in the <b>Macintosh</b> ASIO code. Mac +users should read the file "pa_asio:readme_asio_sdk_patch.txt" for information +on how to fix the bug. +<p>Add these files from the ASIO SDK downloaded from Steinberg:</blockquote> + +<blockquote> +<blockquote><tt>host/asiodrivers.cpp</tt> +<br><tt>host/mac/asioshlib.cpp</tt> +<br><tt>host/mac/codefragements.cpp</tt></blockquote> +The ASIO drivers should be in a folder called "ASIO Drivers" beneath your +application.</blockquote> + +<h3> +Windows Specific</h3> + +<blockquote>Add these files from the ASIO SDK downloaded from Steinberg:</blockquote> + +<blockquote> +<blockquote><tt>host/asiodrivers.cpp</tt> +<br><tt>host/asiolist.cpp</tt> +<br><tt>common/asio.cpp</tt></blockquote> +</blockquote> + +<blockquote>Add these directories to the path for include files:</blockquote> + +<blockquote> +<blockquote><tt>host</tt> +<br><tt>host/pc</tt> +<br><tt>common</tt></blockquote> +</blockquote> + +<blockquote>and link with the system library "<b>winmm.lib</b>". For MS +Visual C++: +<ul> +<li> +select "Settings..." from the "Project" menu,</li> + +<li> +select the project name in the tree on the left,</li> + +<li> +choose "All Configurations" in the popup menu above the tree,</li> + +<li> +select the "Link" tab,</li> + +<li> +enter "winmm.lib", without quotes, as the first item in the "Object/library +modules:" field.</li> +</ul> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_callback.html b/pd/portaudio_v18/docs/pa_tut_callback.html new file mode 100644 index 00000000..f5ccaf0f --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_callback.html @@ -0,0 +1,91 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Writing a Callback Function</h2> + +<blockquote>To write a program using PortAudio, you must include the "portaudio.h" +include file. You may wish to read "<a href="portaudio_h.txt">portaudio.h</a>" +because it contains a complete description of the PortAudio functions and +constants. +<blockquote> +<pre>#include "portaudio.h"</pre> +</blockquote> +The next task is to write your custom callback function. It is a function +that is called by the PortAudio engine whenever it has captured audio data, +or when it needs more audio data for output. +<p>Your callback function is often called by an interrupt, or low level +process so you should not do any complex system activities like allocating +memory, or reading or writing files, or printf(). Just crunch numbers and +generate audio signals. What is safe or not safe will vary from platform +to platform. On the Macintosh, for example, you can only call "interrupt +safe" routines. Also do not call any PortAudio functions in the callback +except for Pa_StreamTime() and Pa_GetCPULoad(). +<p>Your callback function must return an int and accept the exact parameters +specified in this typedef: +<blockquote> +<pre>typedef int (PortAudioCallback)( + void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData );</pre> +</blockquote> +Here is an example callback function from the test file "patests/patest_saw.c". +It calculates a simple left and right sawtooth signal and writes it to +the output buffer. Notice that in this example, the signals are of <tt>float</tt> +data type. The signals must be between -1.0 and +1.0. You can also use +16 bit integers or other formats which are specified during setup. You +can pass a pointer to your data structure through PortAudio which will +appear as <tt>userData</tt>. +<blockquote> +<pre>int patestCallback( void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData ) +{ + unsigned int i; +/* Cast data passed through stream to our structure type. */ + paTestData *data = (paTestData*)userData; + float *out = (float*)outputBuffer; + + for( i=0; i<framesPerBuffer; i++ ) + { + /* Stereo channels are interleaved. */ + *out++ = data->left_phase; /* left */ + *out++ = data->right_phase; /* right */ + + /* Generate simple sawtooth phaser that ranges between -1.0 and 1.0. */ + data->left_phase += 0.01f; + /* When signal reaches top, drop back down. */ + if( data->left_phase >= 1.0f ) data->left_phase -= 2.0f; + + /* higher pitch so we can distinguish left and right. */ + data->right_phase += 0.03f; + if( data->right_phase >= 1.0f ) data->right_phase -= 2.0f; + } + return 0; +}</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_init.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_devs.html b/pd/portaudio_v18/docs/pa_tut_devs.html new file mode 100644 index 00000000..1756992c --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_devs.html @@ -0,0 +1,65 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Querying for Available Devices</h2> + +<blockquote>There are often several different audio devices available in +a computer with different capabilities. They can differ in the sample rates +supported, bit widths, etc. PortAudio provides a simple way to query for +the available devices, and then pass the selected device to Pa_OpenStream(). +For an example, see the file "pa_tests/pa_devs.c". +<p>To determine the number of devices: +<blockquote> +<pre>numDevices = Pa_CountDevices();</pre> +</blockquote> +You can then query each device in turn by calling Pa_GetDeviceInfo() with +an index. +<blockquote> +<pre>for( i=0; i<numDevices; i++ ) { + pdi = Pa_GetDeviceInfo( i );</pre> +</blockquote> +It will return a pointer to a <tt>PaDeviceInfo</tt> structure which is +defined as: +<blockquote> +<pre>typedef struct{ + int structVersion; + const char *name; + int maxInputChannels; + int maxOutputChannels; +/* Number of discrete rates, or -1 if range supported. */ + int numSampleRates; +/* Array of supported sample rates, or {min,max} if range supported. */ + const double *sampleRates; + PaSampleFormat nativeSampleFormat; +}PaDeviceInfo;</pre> +</blockquote> +If the device supports a continuous range of sample rates, then numSampleRates +will equal -1, and the sampleRates array will have two values, the minimum +and maximum rate. +<p>The device information is allocated by Pa_Initialize() and freed by +Pa_Terminate() so you do not have to free() the structure returned by Pa_GetDeviceInfo().</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_util.html">previous</a> | <a href="pa_tut_rw.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_explore.html b/pd/portaudio_v18/docs/pa_tut_explore.html new file mode 100644 index 00000000..91c08a5b --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_explore.html @@ -0,0 +1,42 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Exploring PortAudio</h2> + +<blockquote>Now that you have a good idea of how PortAudio works, you can +try out the test programs. +<ul> +<li> +For an example of playing a sine wave, see "pa_tests/patest_sine.c".</li> + +<li> +For an example of recording and playing back a sound, see "pa_tests/patest_record.c".</li> +</ul> +I also encourage you to examine the source for the PortAudio libraries. +If you have suggestions on ways to improve them, please let us know. if +you want to implement PortAudio on a new platform, please let us know as +well so we can coordinate people's efforts.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_rw.html">previous</a> | next</font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_init.html b/pd/portaudio_v18/docs/pa_tut_init.html new file mode 100644 index 00000000..91bfa8d9 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_init.html @@ -0,0 +1,43 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Initializing PortAudio</h2> + +<blockquote>Before making any other calls to PortAudio, you must call <tt>Pa_Initialize</tt>(). +This will trigger a scan of available devices which can be queried later. +Like most PA functions, it will return a result of type <tt>paError</tt>. +If the result is not <tt>paNoError</tt>, then an error has occurred. +<blockquote> +<pre>err = Pa_Initialize(); +if( err != paNoError ) goto error;</pre> +</blockquote> +You can get a text message that explains the error message by passing it +to +<blockquote> +<pre>printf( "PortAudio error: %s\n", Pa_GetErrorText( err ) );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_callback.html">previous</a> | <a href="pa_tut_open.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_mac.html b/pd/portaudio_v18/docs/pa_tut_mac.html new file mode 100644 index 00000000..bf3dafd1 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_mac.html @@ -0,0 +1,41 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Macintosh</h2> + +<blockquote>To compile a Macintosh application with the PortAudio library, +add the following source files to your project: +<blockquote> +<pre>pa_mac:pa_mac.c +pa_common:pa_lib.c +pa_common:portaudio.h +pa_common:pa_host.h</pre> +</blockquote> +Also add the Apple <b>SoundLib</b> to your project. +<p>You may try compiling the "pa_tests:patest_saw.c" file first because +it is the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_mac_osx.html b/pd/portaudio_v18/docs/pa_tut_mac_osx.html new file mode 100644 index 00000000..44b13883 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_mac_osx.html @@ -0,0 +1,84 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font></h2> + +<h2> +Compiling for Macintosh OS X</h2> + +<blockquote>To compile a Macintosh OS X CoreAudio application with the +PortAudio library you will use the following source files: +<blockquote>pa_mac_core/pa_mac_core.c<br> +pa_common/pa_lib.c<br> +pa_common/portaudio.h<br> +pa_common/pa_host.h<br> +pa_common/pa_convert.c<br> +pablio/ringbuffer.c<br> +pablio/ringbuffer.h</blockquote> +</blockquote> + +<h3> +Using Apple Project Builder</h3> + +<blockquote>Create a new ProjectBuilder project. You can use a "Tool" project +to run the PortAudio examples. +<p>Add the source files from above to your Project. +<p>Add both the Apple CoreAudio.framework and the AudioToolbox.framework +to your project by selecting "Add FrameWorks..." from the Project menu. +<p>Compile and run the "pa_tests:patest_saw.c" file first because it is +the simplest.</blockquote> + +<h3> +Or Using Metrowerks CodeWarrior 8</h3> + +<blockquote>by James Vanlommel</blockquote> + +<blockquote>Create a new CodeWarrior project using Mac OS C++ Stationery. +<br>Then choose Mac OS X Mach-O > Standard Console > C++ Console Mach-O. +<p>In the project window, Clear the HelloWorld.cpp file and add the source +files from above to your Project. +<p>Add a test file of your choosing, like +<br> patests /patest_sine8.c +<br> +<br>Add the frameworks to the Frameworks tab using Project > Add Files... +<br> CoreAudio +<br> AudioToolbox +<p>(The System framework should already be a part of the project.) +<p>Open the current target's settings, and in Language Settings > C/C++ +Language, uncheck (disable) the "ANSI Strict" setting. (Do this for both +Debug and Release projects, if necessary.) +<p>Edit pa_mac_core.c: +<br> On line 1546, cast the PaHost_AllocateFastMemory() result +to a (char *) or you will get a compile error. +<br> +<br>Compile and run. (may need to run from a terminal window) +<p>I've successfully built patest_sine8.c this way using the CVS .tar version +of portaudio (date: 2003-04-27). I get 17 warnings during compilation, +all of which deal with unused variables or arguments.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_open.html b/pd/portaudio_v18/docs/pa_tut_open.html new file mode 100644 index 00000000..12772811 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_open.html @@ -0,0 +1,56 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Opening a Stream using Defaults</h2> + +<blockquote>The next step is to open a stream which is similar to opening +a file. You can specify whether you want audio input and/or output, how +many channels, the data format, sample rate, etc. +<p>First declare a variable to receive the stream pointer: +<blockquote> +<pre>PortAudioStream *stream;</pre> +</blockquote> +There are two calls for opening streams, <tt>Pa_OpenStream</tt>() and <tt>Pa_OpenDefaultStream</tt>(). +P<tt>a_OpenStream()</tt> takes extra parameters which give you more +control. You can normally just use <tt>Pa_OpenDefaultStream</tt>() which +just calls <tt>Pa_OpenStream()</tt> <tt>with</tt> some reasonable default +values. Let's open a stream for stereo output, using floating point +data, at 44100 Hz. +<blockquote> +<pre>err = Pa_OpenDefaultStream( + &stream, /* passes back stream pointer */ + 0, /* no input channels */ + 2, /* stereo output */ + paFloat32, /* 32 bit floating point output */ + 44100, /* sample rate */ + 256, /* frames per buffer */ + 0, /* number of buffers, if zero then use default minimum */ + patestCallback, /* specify our custom callback */ + &data ); /* pass our data through to callback */</pre> +</blockquote> +If you want to use 16 bit integer data, pass <tt>paInt16</tt> instead of +<tt>paFloat32</tt>.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_init.html">previous</a> | <a href="pa_tut_run.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_oss.html b/pd/portaudio_v18/docs/pa_tut_oss.html new file mode 100644 index 00000000..1bb76f25 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_oss.html @@ -0,0 +1,46 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Unix OSS</h2> + +<blockquote>[Skip this page if you are not using Unix and OSS] +<p>We currently support the <a href="http://www.opensound.com/">OSS</a> +audio drivers for Linux, Solaris, and FreeBSD. We hope to someday support +the newer ALSA drivers. +<ol> +<li> +cd to pa_unix_oss directory</li> + +<li> +Edit the Makefile and uncomment one of the tests. You may try compiling +the "patest_sine.c" file first because it is very simple.</li> + +<li> +gmake run</li> +</ol> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_pc.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_over.html b/pd/portaudio_v18/docs/pa_tut_over.html new file mode 100644 index 00000000..baa99205 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_over.html @@ -0,0 +1,92 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Overview of PortAudio</h2> + +<blockquote>PortAudio is a library that provides streaming audio input +and output. It is a cross-platform API (Application Programming Interface) +that works on Windows, Macintosh, Unix running OSS, SGI, BeOS, and perhaps +other platforms by the time you read this. This means that you can write +a simple 'C' program to process or generate an audio signal, and that program +can run on several different types of computer just by recompiling the +source code. +<p>Here are the steps to writing a PortAudio application: +<ol> +<li> +Write a callback function that will be called by PortAudio when audio processing +is needed.</li> + +<li> +Initialize the PA library and open a stream for audio I/O.</li> + +<li> +Start the stream. Your callback function will be now be called repeatedly +by PA in the background.</li> + +<li> +In your callback you can read audio data from the inputBuffer and/or write +data to the outputBuffer.</li> + +<li> +Stop the stream by returning 1 from your callback, or by calling a stop +function.</li> + +<li> +Close the stream and terminate the library.</li> +</ol> +</blockquote> + +<blockquote>There is also <a href="pa_tut_rw.html">another interface</a> +provided that allows you to generate audio in the foreground. You then +simply write data to the stream and the tool will not return until it is +ready to accept more data. This interface is simpler to use but is usually +not preferred for large applications because it requires that you launch +a thread to perform the synthesis. Launching a thread may be difficult +on non-multi-tasking systems such as the Macintosh prior to MacOS X. +<p>Let's continue by building a simple application that will play a sawtooth +wave. +<p>Please select the page for the specific implementation you would like +to use: +<ul> +<li> +<a href="pa_tut_pc.html">Windows (WMME or DirectSound)</a></li> + +<li> +<a href="pa_tut_mac.html">Macintosh SoundManager for OS 7,8,9</a></li> + +<li> +<a href="pa_tut_mac_osx.html">Macintosh CoreAudio for OS X</a></li> + +<li> +<a href="pa_tut_asio.html">ASIO on Windows or Macintosh</a></li> + +<li> +<a href="pa_tut_oss.html">Unix OSS</a></li> +</ul> +or continue with the <a href="pa_tut_callback.html">next page of the programming +tutorial</a>.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tutorial.html">previous</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_pc.html b/pd/portaudio_v18/docs/pa_tut_pc.html new file mode 100644 index 00000000..f7a70101 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_pc.html @@ -0,0 +1,114 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Compiling for Windows (WMME or DirectSound)</h2> + +<blockquote>To compile PortAudio for Windows, you can choose between three +options: +<ul> +<li> +DirectSound API.</li> + +<li> +Windows MultiMedia Extensions API (aka WMME or WAVE).</li> + +<li> +<a href="pa_tut_asio.html">Steinberg's ASIO API</a></li> +</ul> +Some advantages of using DirectSound are that DirectSound may have lower +latency than WMME, and supports effects processing plugins. But one disadvantage +is that DirectSound is not installed on all PCs, and is not well supported +under Windows NT. <b>So WMME is the best choice for most projects.</b><b></b> +<p><b>Note: </b>If you are compiling one of the PortAudio test programs +with Visual C++, then create a new Project of type "Win32 Console Application". +<h3> +All</h3> +For any Windows implementation, add the following source files to your +project: +<blockquote> +<pre><b>pa_common\pa_lib.c +pa_common\portaudio.h +pa_common\pa_host.h</b></pre> +</blockquote> +Link with the system library "<b>winmm.lib</b>". For Visual C++: +<ol> +<li> +select "Settings..." from the "Project" menu,</li> + +<li> +select the project name in the tree on the left,</li> + +<li> +choose "All Configurations" in the popup menu above the tree,</li> + +<li> +select the "Link" tab,</li> + +<li> +enter "winmm.lib", without quotes, as the first item in the "Object/library +modules:" field.</li> +</ol> + +<h3> +WMME</h3> +To use the WMME implementation, add the following source files to your +project: +<blockquote><b><tt>pa_win_wmme/pa_win_wmme.c</tt></b></blockquote> + +<h3> +DirectSound</h3> +If you want to use the DirectSound implementation of PortAudio then you +must have a recent copy of the free +<a href="http://www.microsoft.com/directx/download.asp">DirectX</a> +SDK for Developers from Microsoft installed on your computer. To compile +an application add the following source files to your project: +<blockquote> +<pre><b>pa_win_ds\dsound_wrapper.c +pa_win_ds\pa_dsound.c</b></pre> +</blockquote> +Link with both system libraries "<b>dsound.lib</b>" and "<b>winmm.lib</b>" +using the procedure described above for "winmm.lib". +<br> +<table BORDER > +<tr> +<td><b>Borland</b> users cannot link with the "dsound.lib" from Microsoft +directly. Emmanuel offered this advice: +<p>One can use implib from Borland to generate a new .lib file which is +compatible with Borland C++. +<p>Use: "implib dsound.dll dsound.lib" and include dsound.lib into your +project. +<p>I still had a problem executing the patest_record example. The thread +ended with an error like 'Floating point overflow at...'. This problem +was caused due to a fault in the compiler. Now I'm using Borland 5.02 (instead +of 5.01). Everything seems to be working fine at the moment.</td> +</tr> +</table> +</blockquote> + +<blockquote>You might try compiling the "pa_tests\patest_saw.c" file first +because it is the simplest.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_over.html">previous</a> | <a href="pa_tut_callback.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_run.html b/pd/portaudio_v18/docs/pa_tut_run.html new file mode 100644 index 00000000..5c70d089 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_run.html @@ -0,0 +1,56 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Starting and Stopping a Stream</h2> + +<blockquote>The stream will not start running until you call Pa_StartStream(). +Then it will start calling your callback function to perform the audio +processing. +<blockquote> +<pre>err = Pa_StartStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +At this point, audio is being generated. You can communicate to your callback +routine through the data structure you passed in on the open call, or through +global variables, or using other interprocess communication techniques. +Please be aware that your callback function may be called at interrupt +time when your foreground process is least expecting it. So avoid sharing +complex data structures that are easily corrupted like double linked lists. +<p>In many of the tests we simply sleep for a few seconds so we can hear +the sound. This is easy to do with Pa_Sleep() which will sleep for some +number of milliseconds. Do not rely on this function for accurate scheduling. +it is mostly for writing examples. +<blockquote> +<pre>/* Sleep for several seconds. */ +Pa_Sleep(NUM_SECONDS*1000);</pre> +</blockquote> +When you are through, you can stop the stream from the foreground. +<blockquote> +<pre>err = Pa_StopStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +You can also stop the stream by returning 1 from your custom callback function.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_open.html">previous</a> | <a href="pa_tut_term.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_rw.html b/pd/portaudio_v18/docs/pa_tut_rw.html new file mode 100644 index 00000000..93c7b8bb --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_rw.html @@ -0,0 +1,79 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Blocking Read/Write Functions</h2> + +<blockquote>[Note: These functions are not part of the official PortAudio +API. They are simply built on top of PortAudio as an extra utility. Also +note that they are under evaluation and their definition may change.] +<p>There are two fundamentally different ways to design an audio API. One +is to use callback functions the way we have already shown. The callback +function operates under an interrupt or background thread This leaves the +foreground application free to do other things while the audio just runs +in the background. But this can sometimes be awkward. +<p>So we have provided an alternative technique that lets a program generate +audio in the foreground and then just write it to the audio stream as if +it was a file. If there is not enough room in the audio buffer for more +data, then the write function will just block until more room is available. +This can make it very easy to write an audio example. To use this tool, +you must add the files "pablio/pablio.c" and "pablio/ringbuffer.c" to your +project. You must also: +<blockquote> +<pre>#include "pablio.h"</pre> +</blockquote> +Here is a short excerpt of a program that opens a stream for input and +output. It then reads a block of samples from input, and writes them to +output, in a loop. The complete example can be found in "pablio/test_rw.c". +<blockquote> +<pre> #define SAMPLES_PER_FRAME (2) + #define FRAMES_PER_BLOCK (1024) + SAMPLE samples[SAMPLES_PER_FRAME * FRAMES_PER_BLOCK]; + PaError err; + PABLIO_Stream *aStream; + +/* Open simplified blocking I/O layer on top of PortAudio. */ + err = OpenAudioStream( &rwbl, SAMPLE_RATE, paFloat32, + (PABLIO_READ_WRITE | PABLIO_STEREO) ); + if( err != paNoError ) goto error; + +/* Process samples in the foreground. */ + for( i=0; i<(NUM_SECONDS * SAMPLE_RATE); i++ ) + { + /* Read one block of data into sample array from audio input. */ + ReadAudioStream( aStream, samples, FRAMES_PER_BLOCK ); + /* + ** At this point you could process the data in samples array, + ** and write the result back to the same samples array. + */ + /* Write that same frame of data to output. */ + WriteAudioStream( aStream, samples, FRAMES_PER_BLOCK ); + } + + CloseAudioStream( aStream );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_devs.html">previous</a> | <a href="pa_tut_explore.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_term.html b/pd/portaudio_v18/docs/pa_tut_term.html new file mode 100644 index 00000000..1c72209f --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_term.html @@ -0,0 +1,47 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.73 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Terminating PortAudio</h2> + +<blockquote>You can start and stop a stream as many times as you like. +But when you are done using it, you should close it by calling:</blockquote> + +<blockquote> +<blockquote> +<pre>err = Pa_CloseStream( stream ); +if( err != paNoError ) goto error;</pre> +</blockquote> +Then when you are done using PortAudio, you should terminate the whole +system by calling: +<blockquote> +<pre>Pa_Terminate();</pre> +</blockquote> +That's basically it. You can now write an audio program in 'C' that will +run on multiple platforms, for example PCs and Macintosh. +<p>In the rest of the tutorial we will look at some additional utility +functions, and a different way of using PortAudio that does not require +the use of a callback function.</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | <a href="pa_tutorial.html">contents</a> +| <a href="pa_tut_run.html">previous</a> | <a href="pa_tut_util.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tut_util.html b/pd/portaudio_v18/docs/pa_tut_util.html new file mode 100644 index 00000000..f4b54750 --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tut_util.html @@ -0,0 +1,55 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en]C-gatewaynet (Win98; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<h2> +Utility Functions</h2> + +<blockquote>Here are several more functions that are not critical, but +may be handy when using PortAudio. +<p>Pa_StreamActive() returns one when the stream in playing audio, zero +when not playing, or a negative error number if the stream is invalid. +The stream is active between calls to Pa_StartStream() and Pa_StopStream(), +but may also become inactive if the callback returns a non-zero value. +In the latter case, the stream is considered inactive after the last buffer +has finished playing. +<blockquote> +<pre>PaError Pa_StreamActive( PortAudioStream *stream );</pre> +</blockquote> +Pa_StreamTime() returns the number of samples that have been generated. +PaTimeStamp is a double precision number which is a convenient way to pass +big numbers around even though we only need integers. +<blockquote> +<pre>PaTimestamp Pa_StreamTime( PortAudioStream *stream );</pre> +</blockquote> +The "CPU Load" is a fraction of total CPU time consumed by the stream's +audio processing. A value of 0.5 would imply that PortAudio and the sound +generating callback was consuming roughly 50% of the available CPU time. +This function may be called from the callback function or the application. +<blockquote> +<pre>double Pa_GetCPULoad( PortAudioStream* stream );</pre> +</blockquote> +</blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | +<a href="pa_tutorial.html">contents</a> | <a href="pa_tut_term.html">previous</a> +| <a href="pa_tut_devs.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/pa_tutorial.html b/pd/portaudio_v18/docs/pa_tutorial.html new file mode 100644 index 00000000..1371c44f --- /dev/null +++ b/pd/portaudio_v18/docs/pa_tutorial.html @@ -0,0 +1,46 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Tutorial</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio Tutorial</h1></center> +</td> +</tr> +</table></center> + +<p>Copyright 2000 Phil Burk and Ross Bencina +<h2> +Table of Contents</h2> + +<blockquote><a href="pa_tut_over.html">Overview of PortAudio</a> +<br><a href="pa_tut_mac.html">Compiling for Macintosh OS 7,8,9</a> +<br><a href="pa_tut_mac_osx.html">Compiling for Macintosh OS X</a> +<br><a href="pa_tut_pc.html">Compiling for Windows (DirectSound and WMME)</a> +<br><a href="pa_tut_asio.html">Compiling for ASIO on Windows or Mac OS +8,9</a> +<br><a href="pa_tut_oss.html">Compiling for Unix OSS</a> +<br><a href="pa_tut_callback.html">Writing a Callback Function</a> +<br><a href="pa_tut_init.html">Initializing PortAudio</a> +<br><a href="pa_tut_open.html">Opening a Stream using Defaults</a> +<br><a href="pa_tut_run.html">Starting and Stopping a Stream</a> +<br><a href="pa_tut_term.html">Cleaning Up</a> +<br><a href="pa_tut_util.html">Utilities</a> +<br><a href="pa_tut_devs.html">Querying for Devices</a> +<br><a href="pa_tut_rw.html">Blocking Read/Write Functions</a> +<br><a href="pa_tut_explore.html">Exploring the PortAudio Package</a></blockquote> +<font size=+2><a href="http://www.portaudio.com/">home</a> | contents | +previous | <a href="pa_tut_over.html">next</a></font> +</body> +</html> diff --git a/pd/portaudio_v18/docs/portaudio_h.txt b/pd/portaudio_v18/docs/portaudio_h.txt new file mode 100644 index 00000000..6d60086f --- /dev/null +++ b/pd/portaudio_v18/docs/portaudio_h.txt @@ -0,0 +1,425 @@ +#ifndef PORT_AUDIO_H +#define PORT_AUDIO_H + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* + * PortAudio Portable Real-Time Audio Library + * PortAudio API Header File + * Latest version available at: http://www.audiomulch.com/portaudio/ + * + * Copyright (c) 1999-2000 Ross Bencina and Phil Burk + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files + * (the "Software"), to deal in the Software without restriction, + * including without limitation the rights to use, copy, modify, merge, + * publish, distribute, sublicense, and/or sell copies of the Software, + * and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * Any person wishing to distribute modifications to the Software is + * requested to send the modifications to the original developer so that + * they can be incorporated into the canonical version. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR + * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * + */ + +typedef int PaError; +typedef enum { + paNoError = 0, + + paHostError = -10000, + paInvalidChannelCount, + paInvalidSampleRate, + paInvalidDeviceId, + paInvalidFlag, + paSampleFormatNotSupported, + paBadIODeviceCombination, + paInsufficientMemory, + paBufferTooBig, + paBufferTooSmall, + paNullCallback, + paBadStreamPtr, + paTimedOut, + paInternalError +} PaErrorNum; + +/* + Pa_Initialize() is the library initialisation function - call this before + using the library. +*/ + +PaError Pa_Initialize( void ); + +/* + Pa_Terminate() is the library termination function - call this after + using the library. +*/ + +PaError Pa_Terminate( void ); + +/* + Return host specific error. + This can be called after receiving a paHostError. +*/ +long Pa_GetHostError( void ); + +/* + Translate the error number into a human readable message. +*/ +const char *Pa_GetErrorText( PaError errnum ); + +/* + Sample formats + + These are formats used to pass sound data between the callback and the + stream. Each device has a "native" format which may be used when optimum + efficiency or control over conversion is required. + + Formats marked "always available" are supported (emulated) by all devices. + + The floating point representation uses +1.0 and -1.0 as the respective + maximum and minimum. + +*/ + +typedef unsigned long PaSampleFormat; +#define paFloat32 ((PaSampleFormat) (1<<0)) /*always available*/ +#define paInt16 ((PaSampleFormat) (1<<1)) /*always available*/ +#define paInt32 ((PaSampleFormat) (1<<2)) /*always available*/ +#define paInt24 ((PaSampleFormat) (1<<3)) +#define paPackedInt24 ((PaSampleFormat) (1<<4)) +#define paInt8 ((PaSampleFormat) (1<<5)) +#define paUInt8 ((PaSampleFormat) (1<<6)) /* unsigned 8 bit, 128 is "ground" */ +#define paCustomFormat ((PaSampleFormat) (1<<16)) + +/* + Device enumeration mechanism. + + Device ids range from 0 to Pa_CountDevices()-1. + + Devices may support input, output or both. Device 0 is always the "default" + device and should support at least stereo in and out if that is available + on the taget platform _even_ if this involves kludging an input/output + device on platforms that usually separate input from output. Other platform + specific devices are specified by positive device ids. +*/ + +typedef int PaDeviceID; +#define paNoDevice -1 + +typedef struct{ + int structVersion; + const char *name; + int maxInputChannels; + int maxOutputChannels; +/* Number of discrete rates, or -1 if range supported. */ + int numSampleRates; +/* Array of supported sample rates, or {min,max} if range supported. */ + const double *sampleRates; + PaSampleFormat nativeSampleFormats; +} PaDeviceInfo; + + +int Pa_CountDevices(); +/* + Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() + + Return the default device ID or paNoDevice if there is no devices. + The result can be passed to Pa_OpenStream(). + + On the PC, the user can specify a default device by + setting an environment variable. For example, to use device #1. + + set PA_RECOMMENDED_OUTPUT_DEVICE=1 + + The user should first determine the available device ID by using + the supplied application "pa_devs". +*/ +PaDeviceID Pa_GetDefaultInputDeviceID( void ); +PaDeviceID Pa_GetDefaultOutputDeviceID( void ); + +/* + PaTimestamp is used to represent a continuous sample clock with arbitrary + start time useful for syncronisation. The type is used in the outTime + argument to the callback function and the result of Pa_StreamTime() +*/ + +typedef double PaTimestamp; + +/* + Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure + referring to the device specified by id. + If id is out of range the function returns NULL. + + The returned structure is owned by the PortAudio implementation and must + not be manipulated or freed. The pointer is guaranteed to be valid until + between calls to Pa_Initialize() and Pa_Terminate(). +*/ + +const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID devID ); + +/* + PortAudioCallback is implemented by clients of the portable audio api. + + inputBuffer and outputBuffer are arrays of interleaved samples, + the format, packing and number of channels used by the buffers are + determined by parameters to Pa_OpenStream() (see below). + + framesPerBuffer is the number of sample frames to be processed by the callback. + + outTime is the time in samples when the buffer(s) processed by + this callback will begin being played at the audio output. + See also Pa_StreamTime() + + userData is the value of a user supplied pointer passed to Pa_OpenStream() + intended for storing synthesis data etc. + + return value: + The callback can return a nonzero value to stop the stream. This may be + useful in applications such as soundfile players where a specific duration + of output is required. However, it is not necessary to utilise this mechanism + as StopStream() will also terminate the stream. A callback returning a + nonzero value must fill the entire outputBuffer. + + NOTE: None of the other stream functions may be called from within the + callback function except for Pa_GetCPULoad(). + +*/ + +typedef int (PortAudioCallback)( + void *inputBuffer, void *outputBuffer, + unsigned long framesPerBuffer, + PaTimestamp outTime, void *userData ); + + +/* + Stream flags + + These flags may be supplied (ored together) in the streamFlags argument to + the Pa_OpenStream() function. + + [ suggestions? ] +*/ + +#define paNoFlag (0) +#define paClipOff (1<<0) /* disable defult clipping of out of range samples */ +#define paDitherOff (1<<1) /* disable default dithering */ +#define paPlatformSpecificFlags (0x00010000) +typedef unsigned long PaStreamFlags; + +/* + A single PortAudioStream provides multiple channels of real-time + input and output audio streaming to a client application. + Pointers to PortAudioStream objects are passed between PortAudio functions. +*/ + +typedef void PortAudioStream; +#define PaStream PortAudioStream + +/* + Pa_OpenStream() opens a stream for either input, output or both. + + stream is the address of a PortAudioStream pointer which will receive + a pointer to the newly opened stream. + + inputDevice is the id of the device used for input (see PaDeviceID above.) + inputDevice may be paNoDevice to indicate that an input device is not required. + + numInputChannels is the number of channels of sound to be delivered to the + callback. It can range from 1 to the value of maxInputChannels in the + device input record for the device specified in the inputDevice parameter. + If inputDevice is paNoDevice numInputChannels is ignored. + + inputSampleFormat is the format of inputBuffer provided to the callback + function. inputSampleFormat may be any of the formats described by the + PaSampleFormat enumeration (see above). PortAudio guarantees support for + the sound devices native formats (nativeSampleFormats in the device info + record) and additionally 16 and 32 bit integer and 32 bit floating point + formats. Support for other formats is implementation defined. + + inputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or stream processing. + inputDriverInfo is never required for correct operation. If not used + inputDriverInfo should be NULL. + + outputDevice is the id of the device used for output (see PaDeviceID above.) + outputDevice may be paNoDevice to indicate that an output device is not required. + + numOutputChannels is the number of channels of sound to be supplied by the + callback. See the definition of numInputChannels above for more details. + + outputSampleFormat is the sample format of the outputBuffer filled by the + callback function. See the definition of inputSampleFormat above for more + details. + + outputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or stream processing. + outputDriverInfo is never required for correct operation. If not used + outputDriverInfo should be NULL. + + sampleRate is the desired sampleRate for input and output + + framesPerBuffer is the length in sample frames of all internal sample buffers + used for communication with platform specific audio routines. Wherever + possible this corresponds to the framesPerBuffer parameter passed to the + callback function. + + numberOfBuffers is the number of buffers used for multibuffered + communication with the platform specific audio routines. This parameter is + provided only as a guide - and does not imply that an implementation must + use multibuffered i/o when reliable double buffering is available (such as + SndPlayDoubleBuffer() on the Macintosh.) + + streamFlags may contain a combination of flags ORed together. + These flags modify the behavior of the + streaming process. Some flags may only be relevant to certain buffer formats. + + callback is a pointer to a client supplied function that is responsible + for processing and filling input and output buffers (see above for details.) + + userData is a client supplied pointer which is passed to the callback + function. It could for example, contain a pointer to instance data necessary + for processing the audio buffers. + + return value: + Apon success Pa_OpenStream() returns PaNoError and places a pointer to a + valid PortAudioStream in the stream argument. The stream is inactive (stopped). + If a call to Pa_OpenStream() fails a nonzero error code is returned (see + PAError above) and the value of stream is invalid. + +*/ + +PaError Pa_OpenStream( PortAudioStream** stream, + PaDeviceID inputDevice, + int numInputChannels, + PaSampleFormat inputSampleFormat, + void *inputDriverInfo, + PaDeviceID outputDevice, + int numOutputChannels, + PaSampleFormat outputSampleFormat, + void *outputDriverInfo, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PaStreamFlags streamFlags, + PortAudioCallback *callback, + void *userData ); + + +/* + Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that + opens the default input and/or ouput devices. Most parameters have + identical meaning to their Pa_OpenStream() counterparts, with the following + exceptions: + + If either numInputChannels or numOutputChannels is 0 the respective device + is not opened (same as passing paNoDevice in the device arguments to Pa_OpenStream() ) + + sampleFormat applies to both the input and output buffers. +*/ + +PaError Pa_OpenDefaultStream( PortAudioStream** stream, + int numInputChannels, + int numOutputChannels, + PaSampleFormat sampleFormat, + double sampleRate, + unsigned long framesPerBuffer, + unsigned long numberOfBuffers, + PortAudioCallback *callback, + void *userData ); + +/* + Pa_CloseStream() closes an audio stream, flushing any pending buffers. +*/ + +PaError Pa_CloseStream( PortAudioStream* ); + +/* + Pa_StartStream() and Pa_StopStream() begin and terminate audio processing. + Pa_StopStream() waits until all pending audio buffers have been played. + Pa_AbortStream() stops playing immediately without waiting for pending + buffers to complete. +*/ + +PaError Pa_StartStream( PortAudioStream *stream ); + +PaError Pa_StopStream( PortAudioStream *stream ); + +PaError Pa_AbortStream( PortAudioStream *stream ); + +/* + Pa_StreamActive() returns one when the stream is playing audio, + zero when not playing, or a negative error number if the + stream is invalid. + The stream is active between calls to Pa_StartStream() and Pa_StopStream(), + but may also become inactive if the callback returns a non-zero value. + In the latter case, the stream is considered inactive after the last + buffer has finished playing. +*/ + +PaError Pa_StreamActive( PortAudioStream *stream ); + +/* + Pa_StreamTime() returns the current output time for the stream in samples. + This time may be used as a time reference (for example syncronising audio to + MIDI). +*/ + +PaTimestamp Pa_StreamTime( PortAudioStream *stream ); + +/* + The "CPU Load" is a fraction of total CPU time consumed by the + stream's audio processing. + A value of 0.5 would imply that PortAudio and the sound generating + callback was consuming roughly 50% of the available CPU time. + This function may be called from the callback function or the application. +*/ +double Pa_GetCPULoad( PortAudioStream* stream ); + +/* + Use Pa_GetMinNumBuffers() to determine minimum number of buffers required for + the current host based on minimum latency. + On the PC, for the DirectSound implementation, latency can be optionally set + by user by setting an environment variable. + For example, to set latency to 200 msec, put: + + set PA_MIN_LATENCY_MSEC=200 + + in the AUTOEXEC.BAT file and reboot. + If the environment variable is not set, then the latency will be determined + based on the OS. Windows NT has higher latency than Win95. +*/ + +int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate ); + +/* + Sleep for at least 'msec' milliseconds. + You may sleep longer than the requested time so don't rely + on this for accurate musical timing. +*/ +void Pa_Sleep( long msec ); + +/* + Return size in bytes of a single sample in a given PaSampleFormat + or paSampleFormatNotSupported. +*/ +PaError Pa_GetSampleSize( PaSampleFormat format ); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif /* PORT_AUDIO_H */ diff --git a/pd/portaudio_v18/docs/portaudio_icmc2001.pdf b/pd/portaudio_v18/docs/portaudio_icmc2001.pdf Binary files differnew file mode 100644 index 00000000..747016e1 --- /dev/null +++ b/pd/portaudio_v18/docs/portaudio_icmc2001.pdf diff --git a/pd/portaudio_v18/docs/proposals.html b/pd/portaudio_v18/docs/proposals.html Binary files differnew file mode 100644 index 00000000..88dd2d07 --- /dev/null +++ b/pd/portaudio_v18/docs/proposals.html diff --git a/pd/portaudio_v18/docs/releases.html b/pd/portaudio_v18/docs/releases.html new file mode 100644 index 00000000..aec80a1c --- /dev/null +++ b/pd/portaudio_v18/docs/releases.html @@ -0,0 +1,339 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> + <meta name="Author" content="Phil Burk"> + <meta name="Description" content="PortAudio is a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function."> + <meta name="KeyWords" content="audio, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,"> + <title>PortAudio Release Notes</title> +</head> +<body> + +<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" > +<tr> +<td> +<center> +<h1> +PortAudio - Release Notes</h1></center> +</td> +</tr> +</table></center> + +<p>Link to <a href="http://www.portaudio.com">PortAudio Home Page</a> +<h2> +<b>V18 - 5/6/02</b></h2> + +<blockquote>All source code and documentation now under <a href="http://www.portaudio.com/usingcvs.html">CVS</a>. +<p>Ran most of the code through <a href="http://astyle.sourceforge.net/">AStyle</a> +to cleanup ragged indentation caused by using different editors. Used this +command: +<br><tt> astyle --style=ansi -c -o --convert-tabs --indent-preprocessor +*.c</tt></blockquote> + +<blockquote>Added "pa_common/pa_convert.c" for Mac OS X. Start of new conversion +utilities. +<p><b>ASIO</b> +<ul> +<li> +New Pa_ASIO_Adaptor_Init function to init Callback adpatation variables,</li> + +<li> +Cleanup of Pa_ASIO_Callback_Input</li> + +<li> +Break apart device loading to debug random failure in Pa_ASIO_QueryDeviceInfo</li> + +<li> +Deallocate all resources in PaHost_Term for cases where Pa_CloseStream +is not called properly</li> + +<li> +New Pa_ASIO_loadDriver that calls CoInitialize on each thread on Windows. +Allows use by multiple threads.</li> + +<li> +Correct error code management in PaHost_Term, removed various compiler +warning</li> + +<li> +Add Mac includes for <Devices.h> and <Timer.h></li> + +<li> +Pa_ASIO_QueryDeviceInfo bug correction, memory allocation checking, better +error handling</li> +</ul> +<b>Mac OS X</b> +<ul> +<li> +Major cleanup and improvements.</li> + +<li> +Fixed device queries for numChannels and sampleRates,</li> + +<li> +Audio input works if using same CoreAudio device (some HW devices make +separate CoreAudio devices).</li> + +<li> +Added paInt16, paInt8, format using new "pa_common/pa_convert.c" file.</li> + +<li> +Return error if opened in mono mode cuz not supported.</li> + +<li> +Check for getenv("PA_MIN_LATEWNCY_MSEC") to set latency externally.</li> + +<li> +Use getrusage() instead of gettimeofday() for CPU Load calculation.</li> +</ul> +<b>Windows MME</b> +<ul> +<li> +Fixed bug that caused TIMEOUT in Pa_StopStream(). Added check for past_StopSoon() +in Pa_TimeSlice(). Thanks Julien Maillard.</li> + +<li> +Detect Win XP versus NT, use lower latency.</li> + +<li> +Fix DBUG typo;</li> + +<li> +removed init of CurrentCount which was not compiling on Borland</li> + +<li> +general cleanup, factored streamData alloc and cpu usage initialization</li> + +<li> +stopped counting WAVE_MAPPER when there were no audio cards plugged in</li> +</ul> +<b>Windows DirectSound</b> +<ul> +<li> +Detect Win XP and Win 2K properly when determining latency.</li> +</ul> +<b>Unix OSS</b> +<ul> +<li> +Use high real-time priority if app is running with root priveledges. Lowers +latency.</li> + +<li> +Added watch dog thread that prevents real-time thread from hogging CPU +and hanging the computer.</li> + +<li> +Check error return from read() and write().</li> + +<li> +Check CPU endianness instead of assuming Little Endian.</li> +</ul> +</blockquote> + +<h2> +<b>V17 - 10/15/01</b></h2> + +<blockquote><b>Unix OSS</b> +<ul> +<li> +Set num channels back to two after device query for ALSA. This fixed a +bug in V16 that sometimes caused a failure when querying for the sample +rates. Thanks Stweart Greenhill.</li> +</ul> +</blockquote> + +<blockquote> +<h4> +<b>Macintosh Sound Manager</b></h4> + +<ul> +<li> +Use NewSndCallBackUPP() for CARBON compatibility.</li> +</ul> +</blockquote> + +<h2> +<b>V16 - 9/27/01</b></h2> + +<blockquote><b>Added Alpha implementations for ASIO, SGI, and BeOS!</b> +<br> +<li> +CPULoad is now calculated based on the time spent to generate a known number +of frames. This is more accurate than a simple percentage of real-time. +Implemented in pa_unix_oss, pa_win_wmme and pa_win_ds.</li> + +<li> +Fix dither and shift for recording PaUInt8 format data.</li> + +<li> +Added "patest_maxsines.c" which tests <tt>Pa_GetCPULoad().</tt></li> +</blockquote> + +<blockquote> +<h4> +Windows WMME</h4> + +<ul> +<li> +sDevicePtrs now allocated using <tt>GlobalAlloc()</tt>. This prevents a +crash in Pa_Terminate() on Win2000. Thanks Mike Berry for finding this. +Thanks Mike Berry.</li> + +<li> +Pass process instead of thread to <tt>SetPriorityClass</tt>(). This fixes +a bug that caused the priority to not be increased. Thanks to Alberto di +Bene for spotting this.</li> +</ul> + +<h4> +Windows DirectSound</h4> + +<ul> +<li> +Casts for compiling with __MWERKS__ CodeWarrior.</li> +</ul> + +<h4> +UNIX OSS</h4> + +<ul> +<li> +Derived from Linux OSS implementation.</li> + +<li> +Numerous patches from Heiko Purnhagen, Stephen Brandon, etc.</li> + +<li> +Improved query mechanism which often bailed out unnecessarily.</li> + +<li> +Removed sNumDevices and potential related bugs,</li> + +<li> +Use <tt>getenv("PA_MIN_LATENCY_MSEC")</tt> in code to set desired latency. +User can set by entering:</li> + +<br> <tt>export PA_MIN_LATENCY_MSEC=40</tt></ul> + +<h4> +Macintosh Sound Manager</h4> + +<ul> +<li> +Pass unused event to WaitNextEvent instead of NULL to prevent Mac OSX crash. +Thanks Dominic Mazzoni.</li> + +<li> +Use requested number of input channels.</li> + +<br> </ul> +</blockquote> + +<h2> +<b>V15 - 5/29/01</b></h2> + +<blockquote> +<ul> +<li> +<b>New Linux OSS Beta</b></li> +</ul> + +<h4> +Windows WMME</h4> + +<ul> +<li> + sDevicePtrs now allocated based on sizeof(pointer). Was allocating +too much space.</li> + +<li> + Check for excessive numbers of channels. Some drivers reported bogus +numbers.</li> + +<li> +Apply Mike Berry's changes for CodeWarrior on PC including condition including +of memory.h, and explicit typecasting on memory allocation.</li> +</ul> + +<h4> +Macintosh Sound Manager</h4> + +<ul> +<li> +ScanInputDevices was setting sDefaultOutputDeviceID instead of sDefaultInputDeviceID.</li> + +<li> +Device Scan was crashing for anything other than siBadSoundInDevice, but +some Macs may return other errors! Caused failure to init on some G4s under +OS9.</li> + +<li> +Fix TIMEOUT in record mode.</li> + +<li> +Change CARBON_COMPATIBLE to TARGET_API_MAC_CARBON</li> +</ul> +</blockquote> + +<h2> +<b>V14 - 2/6/01</b></h2> + +<blockquote> +<ul> +<li> +Added implementation for Windows MultiMedia Extensions (WMME) by Ross and +Phil</li> + +<li> +Changed Pa_StopStream() so that it waits for the buffers to drain.</li> + +<li> +Added Pa_AbortStream() that stops immediately without waiting.</li> + +<li> +Added new test: patest_stop.c to test above two mods.</li> + +<li> +Fixed Pa_StreamTime() so that it returns current play position instead +of the write position. Added "patest_sync.c" to demo audio/video sync.</li> + +<li> +Improved stability of Macintosh implementation. Added timeouts to prevent +hangs.</li> + +<li> +Added Pa_GetSampleSize( PaSampleFormat format );</li> + +<li> +Changes some "int"s to "long"s so that PA works properly on Macintosh which +often compiles using 16 bit ints.</li> + +<li> +Added Implementation Guide</li> +</ul> +</blockquote> + +<h2> +<b>V12 - 1/9/01</b></h2> + +<blockquote> +<ul> +<li> +Mac now scans for and queries all devices. But it does not yet support +selecting any other than the default device.</li> + +<li> +Blocking I/O calls renamed to separate them from the PortAudio API.</li> + +<li> +Cleaned up indentation problems with tabs versus spaces.</li> + +<li> +Now attempts to correct bogus sample rate info returned from DirectSound +device queries.</li> +</ul> +</blockquote> + +</body> +</html> |