portaudio.h   portaudio.h 
#ifndef PORTAUDIO_H #ifndef PORTAUDIO_H
#define PORTAUDIO_H #define PORTAUDIO_H
/* /*
* $Id: portaudio.h 1594 2011-02-05 14:33:29Z rossb $ * $Id: portaudio.h 1745 2011-08-25 17:44:01Z rossb $
* PortAudio Portable Real-Time Audio Library * PortAudio Portable Real-Time Audio Library
* PortAudio API Header File * PortAudio API Header File
* Latest version available at: http://www.portaudio.com/ * Latest version available at: http://www.portaudio.com/
* *
* Copyright (c) 1999-2002 Ross Bencina and Phil Burk * Copyright (c) 1999-2002 Ross Bencina and Phil Burk
* *
* Permission is hereby granted, free of charge, to any person obtaining * Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files * a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction, * (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge, * including without limitation the rights to use, copy, modify, merge,
skipping to change at line 424 skipping to change at line 424
#define paNonInterleaved ((PaSampleFormat) 0x80000000) /**< @see PaSampleFo rmat */ #define paNonInterleaved ((PaSampleFormat) 0x80000000) /**< @see PaSampleFo rmat */
/** A structure providing information and capabilities of PortAudio devices . /** A structure providing information and capabilities of PortAudio devices .
Devices may support input, output or both input and output. Devices may support input, output or both input and output.
*/ */
typedef struct PaDeviceInfo typedef struct PaDeviceInfo
{ {
int structVersion; /* this is struct version 2 */ int structVersion; /* this is struct version 2 */
const char *name; const char *name;
PaHostApiIndex hostApi; /* note this is a host API index, not a type id */ PaHostApiIndex hostApi; /**< note this is a host API index, not a type id*/
int maxInputChannels; int maxInputChannels;
int maxOutputChannels; int maxOutputChannels;
/* Default latency values for interactive performance. */ /** Default latency values for interactive performance. */
PaTime defaultLowInputLatency; PaTime defaultLowInputLatency;
PaTime defaultLowOutputLatency; PaTime defaultLowOutputLatency;
/* Default latency values for robust non-interactive applications (eg. playing sound files). */ /** Default latency values for robust non-interactive applications (eg. playing sound files). */
PaTime defaultHighInputLatency; PaTime defaultHighInputLatency;
PaTime defaultHighOutputLatency; PaTime defaultHighOutputLatency;
double defaultSampleRate; double defaultSampleRate;
} PaDeviceInfo; } PaDeviceInfo;
/** Retrieve a pointer to a PaDeviceInfo structure containing information /** Retrieve a pointer to a PaDeviceInfo structure containing information
about the specified device. about the specified device.
@return A pointer to an immutable PaDeviceInfo structure. If the device @return A pointer to an immutable PaDeviceInfo structure. If the device
parameter is out of range the function returns NULL. parameter is out of range the function returns NULL.
skipping to change at line 606 skipping to change at line 606
*/ */
#define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x000000 08) #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x000000 08)
/** A mask specifying the platform specific bits. /** A mask specifying the platform specific bits.
@see PaStreamFlags @see PaStreamFlags
*/ */
#define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000) #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
/** /**
Timing information for the buffers passed to the stream callback. Timing information for the buffers passed to the stream callback.
Time values are expressed in seconds and are synchronised with the time ba
se used by Pa_GetStreamTime() for the associated stream.
@see PaStreamCallback, Pa_GetStreamTime
*/ */
typedef struct PaStreamCallbackTimeInfo{ typedef struct PaStreamCallbackTimeInfo{
PaTime inputBufferAdcTime; PaTime inputBufferAdcTime; /**< The time when the first sample of the
PaTime currentTime; input buffer was captured at the ADC input */
PaTime outputBufferDacTime; PaTime currentTime; /**< The time when the stream callback was
invoked */
PaTime outputBufferDacTime; /**< The time when the first sample of the
output buffer will output the DAC */
} PaStreamCallbackTimeInfo; } PaStreamCallbackTimeInfo;
/** /**
Flag bit constants for the statusFlags to PaStreamCallback. Flag bit constants for the statusFlags to PaStreamCallback.
@see paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflo w, @see paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflo w,
paPrimingOutput paPrimingOutput
*/ */
typedef unsigned long PaStreamCallbackFlags; typedef unsigned long PaStreamCallbackFlags;
skipping to change at line 662 skipping to change at line 666
@see PaStreamCallbackFlags @see PaStreamCallbackFlags
*/ */
#define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010) #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
/** /**
Allowable return values for the PaStreamCallback. Allowable return values for the PaStreamCallback.
@see PaStreamCallback @see PaStreamCallback
*/ */
typedef enum PaStreamCallbackResult typedef enum PaStreamCallbackResult
{ {
paContinue=0, paContinue=0, /**< Signal that the stream should continue invoking th
paComplete=1, e callback and processing audio. */
paAbort=2 paComplete=1, /**< Signal that the stream should stop invoking the ca
llback and finish once all output samples have played. */
paAbort=2 /**< Signal that the stream should stop invoking the ca
llback and finish as soon as possible. */
} PaStreamCallbackResult; } PaStreamCallbackResult;
/** /**
Functions of type PaStreamCallback are implemented by PortAudio clients. Functions of type PaStreamCallback are implemented by PortAudio clients.
They consume, process or generate audio in response to requests from an They consume, process or generate audio in response to requests from an
active PortAudio stream. active PortAudio stream.
When a stream is running, PortAudio calls the stream callback periodically
.
The callback function is responsible for processing buffers of audio sampl
es
passed via the input and output parameters.
The PortAudio stream callback runs at very high or real-time priority.
It is required to consistently meet its time deadlines. Do not allocate
memory, access the file system, call library functions or call other funct
ions
from the stream callback that may block or take an unpredictable amount of
time to complete.
In order for a stream to maintain glitch-free operation the callback
must consume and return audio data faster than it is recorded and/or
played. PortAudio anticipates that each callback invocation may execute fo
r
a duration approaching the duration of frameCount audio frames at the stre
am
sample rate. It is reasonable to expect to be able to utilise 70% or more
of
the available CPU time in the PortAudio callback. However, due to buffer s
ize
adaption and other factors, not all host APIs are able to guarantee audio
stability under heavy CPU load with arbitrary fixed callback buffer sizes.
When high callback CPU utilisation is required the most robust behavior
can be achieved by using paFramesPerBufferUnspecified as the
Pa_OpenStream() framesPerBuffer parameter.
@param input and @param output are either arrays of interleaved samples or ; @param input and @param output are either arrays of interleaved samples or ;
if non-interleaved samples were requested using the paNonInterleaved sampl e if non-interleaved samples were requested using the paNonInterleaved sampl e
format flag, an array of buffer pointers, one non-interleaved buffer for format flag, an array of buffer pointers, one non-interleaved buffer for
each channel. each channel.
The format, packing and number of channels used by the buffers are The format, packing and number of channels used by the buffers are
determined by parameters to Pa_OpenStream(). determined by parameters to Pa_OpenStream().
@param frameCount The number of sample frames to be processed by @param frameCount The number of sample frames to be processed by
the stream callback. the stream callback.
@param timeInfo The time in seconds when the first sample of the input @param timeInfo Timestamps indicating the ADC capture time of the first sa
buffer was received at the audio input, the time in seconds when the first mple
sample of the output buffer will begin being played at the audio output, a in the input buffer, the DAC output time of the first sample in the output
nd buffer
the time in seconds when the stream callback was called. and the time the callback was invoked.
See also Pa_GetStreamTime() See PaStreamCallbackTimeInfo and Pa_GetStreamTime()
@param statusFlags Flags indicating whether input and/or output buffers @param statusFlags Flags indicating whether input and/or output buffers
have been inserted or will be dropped to overcome underflow or overflow have been inserted or will be dropped to overcome underflow or overflow
conditions. conditions.
@param userData The value of a user supplied pointer passed to @param userData The value of a user supplied pointer passed to
Pa_OpenStream() intended for storing synthesis data etc. Pa_OpenStream() intended for storing synthesis data etc.
@return @return
The stream callback should return one of the values in the The stream callback should return one of the values in the
PaStreamCallbackResult enumeration. To ensure that the callback continues ::PaStreamCallbackResult enumeration. To ensure that the callback continue s
to be called, it should return paContinue (0). Either paComplete or paAbor t to be called, it should return paContinue (0). Either paComplete or paAbor t
can be returned to finish stream processing, after either of these values is can be returned to finish stream processing, after either of these values is
returned the callback will not be called again. If paAbort is returned the returned the callback will not be called again. If paAbort is returned the
stream will finish as soon as possible. If paComplete is returned, the str eam stream will finish as soon as possible. If paComplete is returned, the str eam
will continue until all buffers generated by the callback have been played . will continue until all buffers generated by the callback have been played .
This may be useful in applications such as soundfile players where a speci fic This may be useful in applications such as soundfile players where a speci fic
duration of output is required. However, it is not necessary to utilize th is duration of output is required. However, it is not necessary to utilize th is
mechanism as Pa_StopStream(), Pa_AbortStream() or Pa_CloseStream() can als o mechanism as Pa_StopStream(), Pa_AbortStream() or Pa_CloseStream() can als o
be used to stop the stream. The callback must always fill the entire outpu t be used to stop the stream. The callback must always fill the entire outpu t
buffer irrespective of its return value. buffer irrespective of its return value.
 End of changes. 10 change blocks. 
17 lines changed or deleted 57 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/