support/espeak/portaudio.h

// NOTE: Copy this file to  portaudio.h  in order to compile with V18 portaudio


#ifndef PORT_AUDIO_H
#define PORT_AUDIO_H

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */

/*
 * $Id: portaudio.h,v 1.5 2002/03/26 18:04:22 philburk Exp $
 * 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,
    paDeviceUnavailable
} 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 );

/*
 Pa_GetHostError() returns a host specific error code.
 This can be called after receiving a PortAudio error code of paHostError.

*/

long Pa_GetHostError( void );

/*
 Pa_GetErrorText() translates the supplied PortAudio 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 
 PortAudio implementations.
 
 The floating point representation (paFloat32) uses +1.0 and -1.0 as the 
 maximum and minimum respectively.

 paUInt8 is an unsigned 8 bit format where 128 is considered "ground"

*/

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))
#define paCustomFormat ((PaSampleFormat) (1<<16))

/*
 Device enumeration mechanism.
 
 Device ids range from 0 to Pa_CountDevices()-1.
 
 Devices may support input, output or both.

*/

typedef int PaDeviceID;
#define paNoDevice -1

int Pa_CountDevices( void );

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;

/*
 Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() return the
 default device ids for input and output respectively, or paNoDevice if
 no device is available.
 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 ids by using
 the supplied application "pa_devs".

*/

PaDeviceID Pa_GetDefaultInputDeviceID( void );
PaDeviceID Pa_GetDefaultOutputDeviceID( void );


/*
 Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure
 for the device specified.
 If the device parameter is out of range the function returns NULL.

 PortAudio manages the memory referenced by the returned pointer, the client
 must not manipulate or free the memory. The pointer is only guaranteed to be
 valid between calls to Pa_Initialize() and Pa_Terminate().

*/

const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID device );

/*
 PaTimestamp is used to represent a continuous sample clock with arbitrary
 start time that can be used for syncronization. The type is used for the
 outTime argument to the PortAudioCallback and as the result of Pa_StreamTime()

*/

typedef double PaTimestamp;

/*
 PortAudioCallback is implemented by PortAudio clients.
 
 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 non-zero 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
 non-zero 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.

*/

#define   paNoFlag      (0)
#define   paClipOff     (1<<0)   /* disable default 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
 PaDeviceInfo record for the device specified by the inputDevice parameter.
 If inputDevice is paNoDevice numInputChannels is ignored.
 
 inputSampleFormat is the sample 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 device's 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 full-duplex streams it is the
 sample rate for both 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. If you pass zero, then an optimum
 value will be chosen for you internally. 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 behaviour 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:
 Upon 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 non-zero 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 output 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. This has the same effect 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 (1) when the stream is active (ie playing
 or recording audio), zero (0) 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 in samples for the stream.
 This time may be used as a time reference (for example synchronizing audio to
 MIDI).
 
*/

PaTimestamp Pa_StreamTime( PortAudioStream *stream );

/*
 Pa_GetCPULoad() returns the CPU Load for the stream.
 The "CPU Load" is a fraction of total CPU time consumed by the stream's
 audio processing routines including, but not limited to the client supplied
 callback.
 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 );

/*
 Pa_GetMinNumBuffers() returns the minimum number of buffers required by
 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 );

/*
 Pa_Sleep() puts the caller to sleep for at least 'msec' milliseconds.
 You may sleep longer than the requested time so don't rely on this for
 accurate musical timing.
 
 Pa_Sleep() is provided as a convenience for authors of portable code (such as
 the tests and examples in the PortAudio distribution.)
 
*/

void Pa_Sleep( long msec );

/*
 Pa_GetSampleSize() returns the size in bytes of a single sample in the
 supplied PaSampleFormat, or paSampleFormatNotSupported if the format is
 no supported.
  
*/

PaError Pa_GetSampleSize( PaSampleFormat format );


#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* PORT_AUDIO_H */
1	// NOTE: Copy this file to portaudio.h in order to compile with V18 portaudio
2
3
4	#ifndef PORT_AUDIO_H
5	#define PORT_AUDIO_H
6
7	#ifdef __cplusplus
8	extern "C"
9	{
10	#endif /* __cplusplus */
11
12	/*
13	* $Id: portaudio.h,v 1.5 2002/03/26 18:04:22 philburk Exp $
14	* PortAudio Portable Real-Time Audio Library
15	* PortAudio API Header File
16	* Latest version available at: http://www.audiomulch.com/portaudio/
17	*
18	* Copyright (c) 1999-2000 Ross Bencina and Phil Burk
19	*
20	* Permission is hereby granted, free of charge, to any person obtaining
21	* a copy of this software and associated documentation files
22	* (the "Software"), to deal in the Software without restriction,
23	* including without limitation the rights to use, copy, modify, merge,
24	* publish, distribute, sublicense, and/or sell copies of the Software,
25	* and to permit persons to whom the Software is furnished to do so,
26	* subject to the following conditions:
27	*
28	* The above copyright notice and this permission notice shall be
29	* included in all copies or substantial portions of the Software.
30	*
31	* Any person wishing to distribute modifications to the Software is
32	* requested to send the modifications to the original developer so that
33	* they can be incorporated into the canonical version.
34	*
35	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
36	* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
37	* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
38	* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
39	* ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
40	* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
41	* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
42	*
43	*/
44
45	typedef int PaError;
46	typedef enum {
47	paNoError = 0,
48
49	paHostError = -10000,
50	paInvalidChannelCount,
51	paInvalidSampleRate,
52	paInvalidDeviceId,
53	paInvalidFlag,
54	paSampleFormatNotSupported,
55	paBadIODeviceCombination,
56	paInsufficientMemory,
57	paBufferTooBig,
58	paBufferTooSmall,
59	paNullCallback,
60	paBadStreamPtr,
61	paTimedOut,
62	paInternalError,
63	paDeviceUnavailable
64	} PaErrorNum;
65
66	/*
67	Pa_Initialize() is the library initialisation function - call this before
68	using the library.
69
70	*/
71
72	PaError Pa_Initialize( void );
73
74	/*
75	Pa_Terminate() is the library termination function - call this after
76	using the library.
77
78	*/
79
80	PaError Pa_Terminate( void );
81
82	/*
83	Pa_GetHostError() returns a host specific error code.
84	This can be called after receiving a PortAudio error code of paHostError.
85
86	*/
87
88	long Pa_GetHostError( void );
89
90	/*
91	Pa_GetErrorText() translates the supplied PortAudio error number
92	into a human readable message.
93
94	*/
95
96	const char *Pa_GetErrorText( PaError errnum );
97
98	/*
99	Sample formats
100
101	These are formats used to pass sound data between the callback and the
102	stream. Each device has a "native" format which may be used when optimum
103	efficiency or control over conversion is required.
104
105	Formats marked "always available" are supported (emulated) by all
106	PortAudio implementations.
107
108	The floating point representation (paFloat32) uses +1.0 and -1.0 as the
109	maximum and minimum respectively.
110
111	paUInt8 is an unsigned 8 bit format where 128 is considered "ground"
112
113	*/
114
115	typedef unsigned long PaSampleFormat;
116	#define paFloat32 ((PaSampleFormat) (1<<0)) /always available/
117	#define paInt16 ((PaSampleFormat) (1<<1)) /always available/
118	#define paInt32 ((PaSampleFormat) (1<<2)) /always available/
119	#define paInt24 ((PaSampleFormat) (1<<3))
120	#define paPackedInt24 ((PaSampleFormat) (1<<4))
121	#define paInt8 ((PaSampleFormat) (1<<5))
122	#define paUInt8 ((PaSampleFormat) (1<<6))
123	#define paCustomFormat ((PaSampleFormat) (1<<16))
124
125	/*
126	Device enumeration mechanism.
127
128	Device ids range from 0 to Pa_CountDevices()-1.
129
130	Devices may support input, output or both.
131
132	*/
133
134	typedef int PaDeviceID;
135	#define paNoDevice -1
136
137	int Pa_CountDevices( void );
138
139	typedef struct
140	{
141	int structVersion;
142	const char *name;
143	int maxInputChannels;
144	int maxOutputChannels;
145	/* Number of discrete rates, or -1 if range supported. */
146	int numSampleRates;
147	/* Array of supported sample rates, or {min,max} if range supported. */
148	const double *sampleRates;
149	PaSampleFormat nativeSampleFormats;
150	}
151	PaDeviceInfo;
152
153	/*
154	Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() return the
155	default device ids for input and output respectively, or paNoDevice if
156	no device is available.
157	The result can be passed to Pa_OpenStream().
158
159	On the PC, the user can specify a default device by
160	setting an environment variable. For example, to use device #1.
161
162	set PA_RECOMMENDED_OUTPUT_DEVICE=1
163
164	The user should first determine the available device ids by using
165	the supplied application "pa_devs".
166
167	*/
168
169	PaDeviceID Pa_GetDefaultInputDeviceID( void );
170	PaDeviceID Pa_GetDefaultOutputDeviceID( void );
171
172
173
174	/*
175	Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure
176	for the device specified.
177	If the device parameter is out of range the function returns NULL.
178
179	PortAudio manages the memory referenced by the returned pointer, the client
180	must not manipulate or free the memory. The pointer is only guaranteed to be
181	valid between calls to Pa_Initialize() and Pa_Terminate().
182
183	*/
184
185	const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID device );
186
187	/*
188	PaTimestamp is used to represent a continuous sample clock with arbitrary
189	start time that can be used for syncronization. The type is used for the
190	outTime argument to the PortAudioCallback and as the result of Pa_StreamTime()
191
192	*/
193
194	typedef double PaTimestamp;
195
196	/*
197	PortAudioCallback is implemented by PortAudio clients.
198
199	inputBuffer and outputBuffer are arrays of interleaved samples,
200	the format, packing and number of channels used by the buffers are
201	determined by parameters to Pa_OpenStream() (see below).
202
203	framesPerBuffer is the number of sample frames to be processed by the callback.
204
205	outTime is the time in samples when the buffer(s) processed by
206	this callback will begin being played at the audio output.
207	See also Pa_StreamTime()
208
209	userData is the value of a user supplied pointer passed to Pa_OpenStream()
210	intended for storing synthesis data etc.
211
212	return value:
213	The callback can return a non-zero value to stop the stream. This may be
214	useful in applications such as soundfile players where a specific duration
215	of output is required. However, it is not necessary to utilise this mechanism
216	as StopStream() will also terminate the stream. A callback returning a
217	non-zero value must fill the entire outputBuffer.
218
219	NOTE: None of the other stream functions may be called from within the
220	callback function except for Pa_GetCPULoad().
221
222	*/
223
224	typedef int (PortAudioCallback)(
225	void inputBuffer, void outputBuffer,
226	unsigned long framesPerBuffer,
227	PaTimestamp outTime, void *userData );
228
229
230	/*
231	Stream flags
232
233	These flags may be supplied (ored together) in the streamFlags argument to
234	the Pa_OpenStream() function.
235
236	*/
237
238	#define paNoFlag (0)
239	#define paClipOff (1<<0) /* disable default clipping of out of range samples */
240	#define paDitherOff (1<<1) /* disable default dithering */
241	#define paPlatformSpecificFlags (0x00010000)
242	typedef unsigned long PaStreamFlags;
243
244	/*
245	A single PortAudioStream provides multiple channels of real-time
246	input and output audio streaming to a client application.
247	Pointers to PortAudioStream objects are passed between PortAudio functions.
248	*/
249
250	typedef void PortAudioStream;
251	#define PaStream PortAudioStream
252
253	/*
254	Pa_OpenStream() opens a stream for either input, output or both.
255
256	stream is the address of a PortAudioStream pointer which will receive
257	a pointer to the newly opened stream.
258
259	inputDevice is the id of the device used for input (see PaDeviceID above.)
260	inputDevice may be paNoDevice to indicate that an input device is not required.
261
262	numInputChannels is the number of channels of sound to be delivered to the
263	callback. It can range from 1 to the value of maxInputChannels in the
264	PaDeviceInfo record for the device specified by the inputDevice parameter.
265	If inputDevice is paNoDevice numInputChannels is ignored.
266
267	inputSampleFormat is the sample format of inputBuffer provided to the callback
268	function. inputSampleFormat may be any of the formats described by the
269	PaSampleFormat enumeration (see above). PortAudio guarantees support for
270	the device's native formats (nativeSampleFormats in the device info record)
271	and additionally 16 and 32 bit integer and 32 bit floating point formats.
272	Support for other formats is implementation defined.
273
274	inputDriverInfo is a pointer to an optional driver specific data structure
275	containing additional information for device setup or stream processing.
276	inputDriverInfo is never required for correct operation. If not used
277	inputDriverInfo should be NULL.
278
279	outputDevice is the id of the device used for output (see PaDeviceID above.)
280	outputDevice may be paNoDevice to indicate that an output device is not required.
281
282	numOutputChannels is the number of channels of sound to be supplied by the
283	callback. See the definition of numInputChannels above for more details.
284
285	outputSampleFormat is the sample format of the outputBuffer filled by the
286	callback function. See the definition of inputSampleFormat above for more
287	details.
288
289	outputDriverInfo is a pointer to an optional driver specific data structure
290	containing additional information for device setup or stream processing.
291	outputDriverInfo is never required for correct operation. If not used
292	outputDriverInfo should be NULL.
293
294	sampleRate is the desired sampleRate. For full-duplex streams it is the
295	sample rate for both input and output
296
297	framesPerBuffer is the length in sample frames of all internal sample buffers
298	used for communication with platform specific audio routines. Wherever
299	possible this corresponds to the framesPerBuffer parameter passed to the
300	callback function.
301
302	numberOfBuffers is the number of buffers used for multibuffered communication
303	with the platform specific audio routines. If you pass zero, then an optimum
304	value will be chosen for you internally. This parameter is provided only
305	as a guide - and does not imply that an implementation must use multibuffered
306	i/o when reliable double buffering is available (such as SndPlayDoubleBuffer()
307	on the Macintosh.)
308
309	streamFlags may contain a combination of flags ORed together.
310	These flags modify the behaviour of the streaming process. Some flags may only
311	be relevant to certain buffer formats.
312
313	callback is a pointer to a client supplied function that is responsible
314	for processing and filling input and output buffers (see above for details.)
315
316	userData is a client supplied pointer which is passed to the callback
317	function. It could for example, contain a pointer to instance data necessary
318	for processing the audio buffers.
319
320	return value:
321	Upon success Pa_OpenStream() returns PaNoError and places a pointer to a
322	valid PortAudioStream in the stream argument. The stream is inactive (stopped).
323	If a call to Pa_OpenStream() fails a non-zero error code is returned (see
324	PaError above) and the value of stream is invalid.
325
326	*/
327
328	PaError Pa_OpenStream( PortAudioStream** stream,
329	PaDeviceID inputDevice,
330	int numInputChannels,
331	PaSampleFormat inputSampleFormat,
332	void *inputDriverInfo,
333	PaDeviceID outputDevice,
334	int numOutputChannels,
335	PaSampleFormat outputSampleFormat,
336	void *outputDriverInfo,
337	double sampleRate,
338	unsigned long framesPerBuffer,
339	unsigned long numberOfBuffers,
340	PaStreamFlags streamFlags,
341	PortAudioCallback *callback,
342	void *userData );
343
344
345	/*
346	Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that opens
347	the default input and/or output devices. Most parameters have identical meaning
348	to their Pa_OpenStream() counterparts, with the following exceptions:
349
350	If either numInputChannels or numOutputChannels is 0 the respective device
351	is not opened. This has the same effect as passing paNoDevice in the device
352	arguments to Pa_OpenStream().
353
354	sampleFormat applies to both the input and output buffers.
355
356	*/
357
358	PaError Pa_OpenDefaultStream( PortAudioStream** stream,
359	int numInputChannels,
360	int numOutputChannels,
361	PaSampleFormat sampleFormat,
362	double sampleRate,
363	unsigned long framesPerBuffer,
364	unsigned long numberOfBuffers,
365	PortAudioCallback *callback,
366	void *userData );
367
368	/*
369	Pa_CloseStream() closes an audio stream, flushing any pending buffers.
370
371	*/
372
373	PaError Pa_CloseStream( PortAudioStream* );
374
375	/*
376	Pa_StartStream() and Pa_StopStream() begin and terminate audio processing.
377	Pa_StopStream() waits until all pending audio buffers have been played.
378	Pa_AbortStream() stops playing immediately without waiting for pending
379	buffers to complete.
380
381	*/
382
383	PaError Pa_StartStream( PortAudioStream *stream );
384
385	PaError Pa_StopStream( PortAudioStream *stream );
386
387	PaError Pa_AbortStream( PortAudioStream *stream );
388
389	/*
390	Pa_StreamActive() returns one (1) when the stream is active (ie playing
391	or recording audio), zero (0) when not playing, or a negative error number
392	if the stream is invalid.
393	The stream is active between calls to Pa_StartStream() and Pa_StopStream(),
394	but may also become inactive if the callback returns a non-zero value.
395	In the latter case, the stream is considered inactive after the last
396	buffer has finished playing.
397
398	*/
399
400	PaError Pa_StreamActive( PortAudioStream *stream );
401
402	/*
403	Pa_StreamTime() returns the current output time in samples for the stream.
404	This time may be used as a time reference (for example synchronizing audio to
405	MIDI).
406
407	*/
408
409	PaTimestamp Pa_StreamTime( PortAudioStream *stream );
410
411	/*
412	Pa_GetCPULoad() returns the CPU Load for the stream.
413	The "CPU Load" is a fraction of total CPU time consumed by the stream's
414	audio processing routines including, but not limited to the client supplied
415	callback.
416	A value of 0.5 would imply that PortAudio and the sound generating
417	callback was consuming roughly 50% of the available CPU time.
418	This function may be called from the callback function or the application.
419
420	*/
421
422	double Pa_GetCPULoad( PortAudioStream* stream );
423
424	/*
425	Pa_GetMinNumBuffers() returns the minimum number of buffers required by
426	the current host based on minimum latency.
427	On the PC, for the DirectSound implementation, latency can be optionally set
428	by user by setting an environment variable.
429	For example, to set latency to 200 msec, put:
430
431	set PA_MIN_LATENCY_MSEC=200
432
433	in the AUTOEXEC.BAT file and reboot.
434	If the environment variable is not set, then the latency will be determined
435	based on the OS. Windows NT has higher latency than Win95.
436
437	*/
438
439	int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate );
440
441	/*
442	Pa_Sleep() puts the caller to sleep for at least 'msec' milliseconds.
443	You may sleep longer than the requested time so don't rely on this for
444	accurate musical timing.
445
446	Pa_Sleep() is provided as a convenience for authors of portable code (such as
447	the tests and examples in the PortAudio distribution.)
448
449	*/
450
451	void Pa_Sleep( long msec );
452
453	/*
454	Pa_GetSampleSize() returns the size in bytes of a single sample in the
455	supplied PaSampleFormat, or paSampleFormatNotSupported if the format is
456	no supported.
457
458	*/
459
460	PaError Pa_GetSampleSize( PaSampleFormat format );
461
462
463	#ifdef __cplusplus
464	}
465	#endif /* __cplusplus */
466	#endif /* PORT_AUDIO_H */