From 9c0e19a3be2288db79e2502e5fa450c3e20a668d Mon Sep 17 00:00:00 2001 From: Guenter Geiger Date: Fri, 9 May 2003 16:04:00 +0000 Subject: This commit was generated by cvs2svn to compensate for changes in r610, which included commits to RCS files with non-trunk default branches. svn path=/trunk/; revision=611 --- pd/portaudio/docs/index.html | 60 +++++ pd/portaudio/docs/latency.html | 192 ++++++++++++++ pd/portaudio/docs/pa_impl_guide.html | 197 ++++++++++++++ pd/portaudio/docs/pa_impl_startstop.html | 190 ++++++++++++++ pd/portaudio/docs/pa_tut_asio.html | 55 ++++ pd/portaudio/docs/pa_tut_callback.html | 91 +++++++ pd/portaudio/docs/pa_tut_devs.html | 65 +++++ pd/portaudio/docs/pa_tut_explore.html | 42 +++ pd/portaudio/docs/pa_tut_init.html | 43 ++++ pd/portaudio/docs/pa_tut_mac.html | 41 +++ pd/portaudio/docs/pa_tut_mac_osx.html | 46 ++++ pd/portaudio/docs/pa_tut_open.html | 52 ++++ pd/portaudio/docs/pa_tut_oss.html | 46 ++++ pd/portaudio/docs/pa_tut_over.html | 92 +++++++ pd/portaudio/docs/pa_tut_pc.html | 78 ++++++ pd/portaudio/docs/pa_tut_run.html | 56 ++++ pd/portaudio/docs/pa_tut_rw.html | 79 ++++++ pd/portaudio/docs/pa_tut_term.html | 47 ++++ pd/portaudio/docs/pa_tut_util.html | 55 ++++ pd/portaudio/docs/pa_tutorial.html | 46 ++++ pd/portaudio/docs/portaudio_h.txt | 425 +++++++++++++++++++++++++++++++ pd/portaudio/docs/portaudio_icmc2001.pdf | Bin 0 -> 50968 bytes pd/portaudio/docs/proposals.html | 36 +++ pd/portaudio/docs/releases.html | 339 ++++++++++++++++++++++++ 24 files changed, 2373 insertions(+) create mode 100644 pd/portaudio/docs/index.html create mode 100644 pd/portaudio/docs/latency.html create mode 100644 pd/portaudio/docs/pa_impl_guide.html create mode 100644 pd/portaudio/docs/pa_impl_startstop.html create mode 100644 pd/portaudio/docs/pa_tut_asio.html create mode 100644 pd/portaudio/docs/pa_tut_callback.html create mode 100644 pd/portaudio/docs/pa_tut_devs.html create mode 100644 pd/portaudio/docs/pa_tut_explore.html create mode 100644 pd/portaudio/docs/pa_tut_init.html create mode 100644 pd/portaudio/docs/pa_tut_mac.html create mode 100644 pd/portaudio/docs/pa_tut_mac_osx.html create mode 100644 pd/portaudio/docs/pa_tut_open.html create mode 100644 pd/portaudio/docs/pa_tut_oss.html create mode 100644 pd/portaudio/docs/pa_tut_over.html create mode 100644 pd/portaudio/docs/pa_tut_pc.html create mode 100644 pd/portaudio/docs/pa_tut_run.html create mode 100644 pd/portaudio/docs/pa_tut_rw.html create mode 100644 pd/portaudio/docs/pa_tut_term.html create mode 100644 pd/portaudio/docs/pa_tut_util.html create mode 100644 pd/portaudio/docs/pa_tutorial.html create mode 100644 pd/portaudio/docs/portaudio_h.txt create mode 100644 pd/portaudio/docs/portaudio_icmc2001.pdf create mode 100644 pd/portaudio/docs/proposals.html create mode 100644 pd/portaudio/docs/releases.html (limited to 'pd/portaudio/docs') diff --git a/pd/portaudio/docs/index.html b/pd/portaudio/docs/index.html new file mode 100644 index 00000000..7d9b248d --- /dev/null +++ b/pd/portaudio/docs/index.html @@ -0,0 +1,60 @@ + + + + + + + + + PortAudio Docs + + +  +
+ + + +
+
+

+PortAudio Documentation

+
+ +

Copyright 2000 Phil Burk and Ross Bencina +
  +

+API Reference

+ +
The Application Programmer Interface is documented in "portaudio.h".
+ +

+Tutorial

+ +
Describes how to write audio programs using the PortAudio API.
+ +

+Implementation Guide

+ +
Describes how to write an implementation of PortAudio for a +new computer platform.
+ +

+Paper Presented at ICMC2001 (PDF)

+ +
Describes the PortAudio API and discusses implementation issues. +Written July 2001.
+ +

+Improving Latency

+ +
How to tune your computer to achieve the lowest possible audio +delay.
+ +

+Proposed Changes

+ +
Describes API changes being considered by the developer community. +Feedback welcome.
+Return to PortAudio Home Page + + diff --git a/pd/portaudio/docs/latency.html b/pd/portaudio/docs/latency.html new file mode 100644 index 00000000..87f1d122 --- /dev/null +++ b/pd/portaudio/docs/latency.html @@ -0,0 +1,192 @@ + + + + + + + + + PortAudio Implementation - Start/Stop + + +  +
+ + + +
+
+

+PortAudio Latency

+
+ +

This page discusses the issues of audio latency for PortAudio +. It offers suggestions on how to lower latency to improve the responsiveness +of applications. +

What is Latency? +
PortAudio and Latency +
Macintosh +
Unix +
WIndows
+By Phil Burk, Copyright 2002 Phil Burk and Ross Bencina +

+What is Latency?

+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. +

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. +

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. +

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. +

+PortAudio and Latency

+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. +

The latency in milliseconds due to this buffering  is: +

latency_msec = 1000 * numBuffers * framesPerBuffer / framesPerSecond
+This is not the total latency, as we have seen, but it is the part we can +control. +

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. +

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: +

int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate +);
+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. +

+Macintosh

+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. +

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: +

setenv PA_MIN_LATENCY_MSEC 4
+ +

+Unix

+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. +

+Windows

+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. +

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. +

You can set the PA_MIN_LATENCY_MSEC variable to 50, for example, by +entering in MS-DOS: +

set PA_MIN_LATENCY_MSEC=50
+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. +

For Windows XP, you can set environment variables as follows: +

    +
  1. +Select "Control Panel" from the "Start Menu".
    2. + +
  2. +Launch the "System" Control Panel
    3. + +
  3. +Click on the "Advanced" tab.
    4. + +
  4. +Click on the "Environment Variables" button.
    5. + +
  5. +Click "New" button under  User Variables.
    6. + +
  6. +Enter PA_MIN_LATENCY_MSEC for the name and some optimistic number for the +value.
    7. + +
  7. +Click OK, OK, OK.
    8. +
+ +

+Improving Latency on Windows

+There are several steps you can take to improve latency under windows. +
    +
  1. +Avoid reading or writng to disk when doing audio.
    2. + +
  2. +Turn off all automated background tasks such as email clients, virus scanners, +backup programs, FTP servers, web servers, etc. when doing audio.
    3. + +
  3. +Disconnect from the network to prevent network traffic from interrupting +your CPU.
    4. +
+Important: 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. +
    +
  1. +Select "Control Panel" from the "Start Menu".
    2. + +
  2. +Launch the "System" Control Panel
    3. + +
  3. +Click on the "Advanced" tab.
    4. + +
  4. +Click on the "Settings" button in the Performance area.
    5. + +
  5. +Click on the "Advanced" tab.
    6. + +
  6. +Select "Background services" in the Processor Scheduling area.
    7. + +
  7. +Click OK, OK.
    8. +
+Please let us know if you have others sugestions for lowering latency. +
  +
  + + diff --git a/pd/portaudio/docs/pa_impl_guide.html b/pd/portaudio/docs/pa_impl_guide.html new file mode 100644 index 00000000..50abc304 --- /dev/null +++ b/pd/portaudio/docs/pa_impl_guide.html @@ -0,0 +1,197 @@ + + + + + + + + + PortAudio Implementation - Start/Stop + + +  +
+ + + +
+
+

+PortAudio Implementation Guide

+
+ +

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. +

By Phil Burk +
Copyright 2000 Phil Burk and Ross Bencina +

Note that the license says: "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.". +So when you have finished a new implementation, please send it back to +us at  "http://www.portaudio.com" +so that we can make it available for other users. Thank you! +

+Download the Latest PortAudio Implementation

+Always start with the latest implementation available at "http://www.portaudio.com". +Look for the nightly snapshot under the CVS section. +

+Select an Existing Implementation as a Basis

+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. + +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. +

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". +

+Read Docs and Code

+Famialiarize yourself with the system by reading the documentation provided. +here is a suggested order: +
    +
  1. +User Programming Tutorial
    2. + +
  2. +Header file "pa_common/portaudio.h" which defines API.
    3. + +
  3. +Header file "pa_common/pa_host.h" for host dependant code. This definces +the routine you will need to provide.
    4. + +
  4. +Shared code in "pa_common/pa_lib.c".
    5. + +
  5. +Docs on Implementation of Start/Stop +code.
    6. +
+ +

+Implement  Output to Default Device

+Now we are ready to crank some code. For instant gratification, let's try +to play a sine wave. +
    +
  1. +Link the test program "pa_tests/patest_sine.c" with the file "pa_lib.c" +and the implementation specific file you are creating.
    2. + +
  2. +For now, just stub out the device query code and the audio input code.
    3. + +
  3. +Modify PaHost_OpenStream() to open your default target device and get everything +setup.
    4. + +
  4. +Modify PaHost_StartOutput() to start playing audio.
    5. + +
  5. +Modify PaHost_StopOutput() to stop audio.
    6. + +
  6. +Modify PaHost_CloseStream() to clean up. Free all memory that you allocated +in PaHost_OpenStream().
    7. + +
  7. +Keep cranking until you can play a sine wave using "patest_sine.c".
    8. + +
  8. +Once that works, try "patest_pink.c", "patest_clip.c", "patest_sine8.c".
    9. + +
  9. +To test your Open and Close code, try "patest_many.c".
    10. + +
  10. +Now test to make sure that the three modes of stopping are properly supported +by running "patest_stop.c".
    11. + +
  11. +Test your implementation of time stamping with "patest_sync.c".
    12. +
+ +

+Implement Device Queries

+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. +

+Implement Input

+Implement audio input and test it with: +
    +
  1. +patest_record.c - record in half duplex, play back as recorded.
    2. + +
  2. +patest_wire.c - full duplex, copies input to output. Note that some HW +may not support full duplex.
    3. + +
  3. +patest_fuzz.c - plug in your guitar and get a feel for why latency is an +important issue in computer music.
    4. + +
  4. +paqa_devs.c - try to open every device and use it with every possible format
    5. +
+ +

+Debugging Tools

+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. +
    +
  1. +To enable trace mode, change TRACE_REALTIME_EVENTS in "pa_common/pa_trace.h" +from a (0) to a (1).
    2. + +
  2. +Link with "pa_common/pa_trace.c".
    3. + +
  3. +Add trace messages to your code by calling:
    4. + +
       void AddTraceMessage( char *msg, int data ); +
    for example +
       AddTraceMessage("Pa_TimeSlice: past_NumCallbacks ", +past->past_NumCallbacks ); +
  4. +Run your program. You will get a dump of events at the end.
    5. + +
  5. +You can leave the trace messages in your code. They will turn to NOOPs +when you change TRACE_REALTIME_EVENTS back to (0).
    6. +
+ +

+Delivery

+Please send your new code along with notes on the implementation back to +us at "http://www.portaudio.com". +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" please +send us those modifications and your notes. We will try to merge your changes +so that the "pa_common" code works with all implementations. +

If you have suggestions for how to make future implementations easier, +please let us know. +
THANKS! +
  + + diff --git a/pd/portaudio/docs/pa_impl_startstop.html b/pd/portaudio/docs/pa_impl_startstop.html new file mode 100644 index 00000000..0f2d0ce5 --- /dev/null +++ b/pd/portaudio/docs/pa_impl_startstop.html @@ -0,0 +1,190 @@ + + + + + + + + + PortAudio Implementation - Start/Stop + + +  +

+ + + +
+
+

+PortAudio Implementation

+
+ +

+Starting and Stopping Streams

+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. +

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. +

int   past_IsActive;     +/* Background is still playing. */ +
int   past_StopSoon;     /* Stop +when last buffer done. */ +
int   past_StopNow;      /* +Stop IMMEDIATELY. */
+ +

+Pa_AbortStream()

+This function causes the background thread to terminate as soon as possible +and audio I/O to stop abruptly. +
  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Foreground ThreadBackground Thread
sets StopNow
sees StopNow, 
clears IsActive, stops thread
waits for thread to exit
turns off audio I/O
+ +

+Pa_StopStream()

+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 +
  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Foreground ThreadBackground Thread
sets StopSoon
stops calling user callback
continues until output buffer empty
clears IsActive, stops thread
waits for thread to exit
turns off audio I/O
+ +

+User callback returns one.

+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. +
  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Foreground ThreadBackground Thread
callback returns 1
sets StopSoon
stops calling user callback
continues until output buffer empty
clears IsActive, stops thread
waits for thread to exit
turns off audio I/O
+ +
  + + diff --git a/pd/portaudio/docs/pa_tut_asio.html b/pd/portaudio/docs/pa_tut_asio.html new file mode 100644 index 00000000..1c3e5bfa --- /dev/null +++ b/pd/portaudio/docs/pa_tut_asio.html @@ -0,0 +1,55 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Compiling for ASIO (Windows or Macintosh)

+ +
ASIO is a low latency audio API from Steinberg. To compile +an ASIO application, you must first download +the ASIO SDK from Steinberg. You also need to obtain ASIO drivers for +your audio device. +

Note: I am using '/' as a file separator below. On Macintosh replace +'/' with ':'. On Windows, replace '/' with '\'. +

 To use ASIO with the PortAudio library add the following source +files to your project: +

+
pa_asio/pa_asio.cpp
+
+and also these files from the ASIO SDK: +
+
common/asio.cpp
+host/asiodrivers.cpp
+host/asiolist.cpp
+
+and add these directories to the path for include files +
+
asiosdk2/host/pc   (for Windows)
+asiosdk2/common
+asiosdk2/host
+
+You may try compiling the "pa_tests/patest_saw.c" file first because it +is the simplest.
+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_callback.html b/pd/portaudio/docs/pa_tut_callback.html new file mode 100644 index 00000000..f5ccaf0f --- /dev/null +++ b/pd/portaudio/docs/pa_tut_callback.html @@ -0,0 +1,91 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Writing a Callback Function

+ +
To write a program using PortAudio, you must include the "portaudio.h" +include file. You may wish to read "portaudio.h" +because it contains a complete description of the PortAudio functions and +constants. +
+
#include "portaudio.h"
+
+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. +

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(). +

Your callback function must return an int and accept the exact parameters +specified in this typedef: +

+
typedef int (PortAudioCallback)(
+               void *inputBuffer, void *outputBuffer,
+               unsigned long framesPerBuffer,
+               PaTimestamp outTime, void *userData );
+
+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 float +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 userData. +
+
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;
+}
+
+
+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_devs.html b/pd/portaudio/docs/pa_tut_devs.html new file mode 100644 index 00000000..1756992c --- /dev/null +++ b/pd/portaudio/docs/pa_tut_devs.html @@ -0,0 +1,65 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Querying for Available Devices

+ +
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". +

To determine the number of devices: +

+
numDevices = Pa_CountDevices();
+
+You can then query each device in turn by calling Pa_GetDeviceInfo() with +an index. +
+
for( i=0; i<numDevices; i++ ) {
+     pdi = Pa_GetDeviceInfo( i );
+
+It will return a pointer to a PaDeviceInfo structure which is +defined as: +
+
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;
+
+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. +

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().

+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_explore.html b/pd/portaudio/docs/pa_tut_explore.html new file mode 100644 index 00000000..91c08a5b --- /dev/null +++ b/pd/portaudio/docs/pa_tut_explore.html @@ -0,0 +1,42 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Exploring PortAudio

+ +
Now that you have a good idea of how PortAudio works, you can +try out the test programs. + +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.
+home | contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_init.html b/pd/portaudio/docs/pa_tut_init.html new file mode 100644 index 00000000..91bfa8d9 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_init.html @@ -0,0 +1,43 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Initializing PortAudio

+ +
Before making any other calls to PortAudio, you must call Pa_Initialize(). +This will trigger a scan of available devices which can be queried later. +Like most PA functions, it will return a result of type paError. +If the result is not paNoError, then an error has occurred. +
+
err = Pa_Initialize();
+if( err != paNoError ) goto error;
+
+You can get a text message that explains the error message by passing it +to +
+
printf(  "PortAudio error: %s\n", Pa_GetErrorText( err ) );
+
+
+home | contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_mac.html b/pd/portaudio/docs/pa_tut_mac.html new file mode 100644 index 00000000..bf3dafd1 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_mac.html @@ -0,0 +1,41 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Compiling for Macintosh

+ +
To compile a Macintosh application with the PortAudio library, +add the following source files to your project: +
+
pa_mac:pa_mac.c
+pa_common:pa_lib.c
+pa_common:portaudio.h
+pa_common:pa_host.h
+
+Also add the Apple SoundLib to your project. +

You may try compiling the "pa_tests:patest_saw.c" file first because +it is the simplest.

+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_mac_osx.html b/pd/portaudio/docs/pa_tut_mac_osx.html new file mode 100644 index 00000000..3af8c140 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_mac_osx.html @@ -0,0 +1,46 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Compiling for Macintosh OS X

+ +
To compile a Macintosh OS X CoreAudio application with the +PortAudio library: +

Create a new ProjectBuilder project. You can use a "Tool" project to +run the PortAudio examples. +

Add the following source files to your Project: +

+
pa_mac_core/pa_mac_core.c
+pa_common/pa_lib.c
+pa_common/portaudio.h
+pa_common/pa_host.h
+pa_common/pa_convert.c
+
+Add the Apple CoreAudio.framework to your project by selecting "Add FrameWorks..." +from the Project menu. +

Compile and run the "pa_tests:patest_saw.c" file first because it is +the simplest.

+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_open.html b/pd/portaudio/docs/pa_tut_open.html new file mode 100644 index 00000000..1621ef30 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_open.html @@ -0,0 +1,52 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Opening a Stream using Defaults

+ +
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. There are two calls for +opening streams, Pa_OpenStream() and Pa_OpenDefaultStream(). +

Pa_OpenStream() takes extra  parameters which give you +more control. You can normally just use Pa_OpenDefaultStream() +which just calls Pa_OpenStream() with some reasonable +default values.  Let's open a stream for stereo output, using floating +point data, at 44100 Hz. +

+
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 */
+
+If you want to use 16 bit integer data, pass paInt16 instead of +paFloat32.
+home | contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_oss.html b/pd/portaudio/docs/pa_tut_oss.html new file mode 100644 index 00000000..1bb76f25 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_oss.html @@ -0,0 +1,46 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Compiling for Unix OSS

+ +
[Skip this page if you are not using Unix and OSS] +

We currently support the OSS +audio drivers for Linux, Solaris, and FreeBSD. We hope to someday support +the newer ALSA drivers. +

    +
  1. +cd to pa_unix_oss directory
    2. + +
  2. +Edit the Makefile and uncomment one of the tests. You may try compiling +the "patest_sine.c" file first because it is very simple.
    3. + +
  3. +gmake run
    4. +
+
+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_over.html b/pd/portaudio/docs/pa_tut_over.html new file mode 100644 index 00000000..baa99205 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_over.html @@ -0,0 +1,92 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Overview of PortAudio

+ +
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. +

Here are the steps to writing a PortAudio application: +

    +
  1. +Write a callback function that will be called by PortAudio when audio processing +is needed.
    2. + +
  2. +Initialize the PA library and open a stream for audio I/O.
    3. + +
  3. +Start the stream. Your callback function will be now be called repeatedly +by PA in the background.
    4. + +
  4. +In your callback you can read audio data from the inputBuffer and/or write +data to the outputBuffer.
    5. + +
  5. +Stop the stream by returning 1 from your callback, or by calling a stop +function.
    6. + +
  6. +Close the stream and terminate the library.
    7. +
+
+ +
There is also another interface +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. +

Let's continue by building a simple application that will play a sawtooth +wave. +

Please select the page for the specific implementation you would like +to use: +

+or continue with the next page of the programming +tutorial.
+home | +contents +| previous + + diff --git a/pd/portaudio/docs/pa_tut_pc.html b/pd/portaudio/docs/pa_tut_pc.html new file mode 100644 index 00000000..87e5f9a0 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_pc.html @@ -0,0 +1,78 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Compiling for Windows (WMME or DirectSound)

+ +
To compile PortAudio for Windows, you can choose between two +options. One implementation uses the DirectSound API. The other uses the +Windows MultiMedia Extensions API (aka WMME or WAVE). +

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. So WMME is the best choice for most projects. +

For either implementation add the following source files to your project: +

+
pa_common\pa_lib.c
+pa_common\portaudio.h
+pa_common\pa_host.h
+
+Link with the system library "winmm.lib". For Visual C++: +
    +
  1. +select "Settings..." from the "Project" menu,
    2. + +
  2. +select the project name in the tree on the left,
    3. + +
  3. +choose "All Configurations" in the popup menu above the tree,
    4. + +
  4. +select the "Link" tab,
    5. + +
  5. +enter "winmm.lib", without quotes, as the first item in the "Object/library +modules:" field.
    6. +
+WMME - To use the WMME implementation, add the following source +files to your project: +
pa_win_wmme/pa_win_wmme.c
+DirectSound - If you want to use the DirectSound implementation +of PortAudio then you must have a recent copy of the free +DirectX +SDK for Developers from Microsoft installed on your computer. To compile +an application add the following source files to your project: +
+
pa_win_ds\dsound_wrapper.c
+pa_win_ds\pa_dsound.c
+
+Link with the system library "dsound.lib" using the procedure described +above for "winmm.lib".
+ +
You might try compiling the "pa_tests\patest_saw.c" file first +because it is the simplest.
+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_run.html b/pd/portaudio/docs/pa_tut_run.html new file mode 100644 index 00000000..5c70d089 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_run.html @@ -0,0 +1,56 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Starting and Stopping a Stream

+ +
The stream will not start running until you call Pa_StartStream(). +Then it will start calling your callback function to perform the audio +processing. +
+
err = Pa_StartStream( stream );
+if( err != paNoError ) goto error;
+
+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. +

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. +

+
/* Sleep for several seconds. */
+Pa_Sleep(NUM_SECONDS*1000);
+
+When you are through, you can stop the stream from the foreground. +
+
err = Pa_StopStream( stream );
+if( err != paNoError ) goto error;
+
+You can also stop the stream by returning 1 from your custom callback function.
+home | contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_rw.html b/pd/portaudio/docs/pa_tut_rw.html new file mode 100644 index 00000000..93c7b8bb --- /dev/null +++ b/pd/portaudio/docs/pa_tut_rw.html @@ -0,0 +1,79 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Blocking Read/Write Functions

+ +
[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.] +

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. +

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: +

+
#include "pablio.h"
+
+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". +
+
    #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 );
+
+
+home | +contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_term.html b/pd/portaudio/docs/pa_tut_term.html new file mode 100644 index 00000000..1c72209f --- /dev/null +++ b/pd/portaudio/docs/pa_tut_term.html @@ -0,0 +1,47 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Terminating PortAudio

+ +
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:
+ +
+
+
err = Pa_CloseStream( stream );
+if( err != paNoError ) goto error;
+
+Then when you are done using PortAudio, you should terminate the whole +system by calling: +
+
Pa_Terminate();
+
+That's basically it. You can now write an audio program in 'C' that will +run on multiple platforms, for example PCs and Macintosh. +

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.

+home | contents +| previous |  next + + diff --git a/pd/portaudio/docs/pa_tut_util.html b/pd/portaudio/docs/pa_tut_util.html new file mode 100644 index 00000000..f4b54750 --- /dev/null +++ b/pd/portaudio/docs/pa_tut_util.html @@ -0,0 +1,55 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

+Utility Functions

+ +
Here are several more functions that are not critical, but +may be handy when using PortAudio. +

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. +

+
PaError Pa_StreamActive( PortAudioStream *stream );
+
+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. +
+
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 );
+
+
+home | +contents | previous +|  next + + diff --git a/pd/portaudio/docs/pa_tutorial.html b/pd/portaudio/docs/pa_tutorial.html new file mode 100644 index 00000000..1371c44f --- /dev/null +++ b/pd/portaudio/docs/pa_tutorial.html @@ -0,0 +1,46 @@ + + + + + + + + + PortAudio Tutorial + + +  +
+ + + +
+
+

+PortAudio Tutorial

+
+ +

Copyright 2000 Phil Burk and Ross Bencina +

+Table of Contents

+ +
Overview of PortAudio +
Compiling for Macintosh OS 7,8,9 +
Compiling for Macintosh OS X +
Compiling for Windows (DirectSound and WMME) +
Compiling for ASIO on Windows or Mac OS +8,9 +
Compiling for Unix OSS +
Writing a Callback Function +
Initializing PortAudio +
Opening a Stream using Defaults +
Starting and Stopping a Stream +
Cleaning Up +
Utilities +
Querying for Devices +
Blocking Read/Write Functions +
Exploring the PortAudio Package
+home | contents | +previous |  next + + diff --git a/pd/portaudio/docs/portaudio_h.txt b/pd/portaudio/docs/portaudio_h.txt new file mode 100644 index 00000000..6d60086f --- /dev/null +++ b/pd/portaudio/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/docs/portaudio_icmc2001.pdf b/pd/portaudio/docs/portaudio_icmc2001.pdf new file mode 100644 index 00000000..dd074b7d Binary files /dev/null and b/pd/portaudio/docs/portaudio_icmc2001.pdf differ diff --git a/pd/portaudio/docs/proposals.html b/pd/portaudio/docs/proposals.html new file mode 100644 index 00000000..0f9b8cb6 --- /dev/null +++ b/pd/portaudio/docs/proposals.html @@ -0,0 +1,36 @@ + + +Proposed Changes to PortAudio API + + + + + +  +
+ + + +
+
+

Proposed Changes to PortAudio API

+
+
+

PortAudio Home Page

+ +

Updated: July 27, 2002

+

The Proposals Have Moved

+ +

+All PortAudio Enhancement Proposal documentation has moved. On the web site, it is now located at: +http://www.portaudio.com/docs/proposals + +On the CVS server it is now located in a module named "pa_proposals". +

+ + + + diff --git a/pd/portaudio/docs/releases.html b/pd/portaudio/docs/releases.html new file mode 100644 index 00000000..aec80a1c --- /dev/null +++ b/pd/portaudio/docs/releases.html @@ -0,0 +1,339 @@ + + + + + + + + + PortAudio Release Notes + + +  +
+ + + +
+
+

+PortAudio - Release Notes

+
+ +

Link to PortAudio Home Page +

+V18 - 5/6/02

+ +
All source code and documentation now under CVS. +

Ran most of the code through AStyle +to cleanup ragged indentation caused by using different editors. Used this +command: +
   astyle --style=ansi -c -o --convert-tabs --indent-preprocessor +*.c

+ +
Added "pa_common/pa_convert.c" for Mac OS X. Start of new conversion +utilities. +

ASIO +

+Mac OS X + +Windows MME + +Windows DirectSound + +Unix OSS + +
+ +

+V17 - 10/15/01

+ +
Unix OSS + +
+ +
+

+Macintosh Sound Manager

+ + +
+ +

+V16 - 9/27/01

+ +
Added Alpha implementations for ASIO, SGI, and BeOS! +
  +
  • +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.
    • + +
  • +Fix dither and shift for recording PaUInt8 format data.
    • + +
  • +Added "patest_maxsines.c" which tests Pa_GetCPULoad().
    • +
    + +
    +

    +Windows WMME

    + + + +

    +Windows DirectSound

    + + + +

    +UNIX OSS

    + + + +

    +Macintosh Sound Manager

    + + +
    + +

    +V15 - 5/29/01

    + +
    + + +

    +Windows WMME

    + + + +

    +Macintosh Sound Manager

    + + +
    + +

    +V14 - 2/6/01

    + +
    + +
    + +

    +V12 - 1/9/01

    + +
    + +
    + + + -- cgit v1.2.1