← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/third_party/portaudio/include/portaudio.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/third_party/portaudio/include/portaudio.h
1
 
#ifndef PORTAUDIO_H
2
 
#define PORTAUDIO_H
3
 
/*
4
 
 * $Id: portaudio.h 1337 2008-02-15 07:32:09Z rossb $
5
 
 * PortAudio Portable Real-Time Audio Library
6
 
 * PortAudio API Header File
7
 
 * Latest version available at: http://www.portaudio.com/
8
 
 *
9
 
 * Copyright (c) 1999-2002 Ross Bencina and Phil Burk
10
 
 *
11
 
 * Permission is hereby granted, free of charge, to any person obtaining
12
 
 * a copy of this software and associated documentation files
13
 
 * (the "Software"), to deal in the Software without restriction,
14
 
 * including without limitation the rights to use, copy, modify, merge,
15
 
 * publish, distribute, sublicense, and/or sell copies of the Software,
16
 
 * and to permit persons to whom the Software is furnished to do so,
17
 
 * subject to the following conditions:
18
 
 *
19
 
 * The above copyright notice and this permission notice shall be
20
 
 * included in all copies or substantial portions of the Software.
21
 
 *
22
 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23
 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24
 
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25
 
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
26
 
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
27
 
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28
 
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29
 
 */
30
 
 
31
 
/*
32
 
 * The text above constitutes the entire PortAudio license; however,
33
 
 * the PortAudio community also makes the following non-binding requests:
34
 
 *
35
 
 * Any person wishing to distribute modifications to the Software is
36
 
 * requested to send the modifications to the original developer so that
37
 
 * they can be incorporated into the canonical version. It is also
38
 
 * requested that these non-binding requests be included along with the
39
 
 * license above.
40
 
 */
41
 
 
42
 
/** @file
43
 
 @ingroup public_header
44
 
 @brief The portable PortAudio API.
45
 
*/
46
 
 
47
 
 
48
 
#ifdef __cplusplus
49
 
extern "C"
50
 
{
51
 
#endif /* __cplusplus */
52
 
 
53
 
 
54
 
/** Retrieve the release number of the currently running PortAudio build,
55
 
 eg 1900.
56
 
*/
57
 
int Pa_GetVersion( void );
58
 
 
59
 
 
60
 
/** Retrieve a textual description of the current PortAudio build,
61
 
 eg "PortAudio V19-devel 13 October 2002".
62
 
*/
63
 
const char* Pa_GetVersionText( void );
64
 
 
65
 
 
66
 
/** Error codes returned by PortAudio functions.
67
 
 Note that with the exception of paNoError, all PaErrorCodes are negative.
68
 
*/
69
 
 
70
 
typedef int PaError;
71
 
typedef enum PaErrorCode
72
 
{
73
 
    paNoError = 0,
74
 
 
75
 
    paNotInitialized = -10000,
76
 
    paUnanticipatedHostError,
77
 
    paInvalidChannelCount,
78
 
    paInvalidSampleRate,
79
 
    paInvalidDevice,
80
 
    paInvalidFlag,
81
 
    paSampleFormatNotSupported,
82
 
    paBadIODeviceCombination,
83
 
    paInsufficientMemory,
84
 
    paBufferTooBig,
85
 
    paBufferTooSmall,
86
 
    paNullCallback,
87
 
    paBadStreamPtr,
88
 
    paTimedOut,
89
 
    paInternalError,
90
 
    paDeviceUnavailable,
91
 
    paIncompatibleHostApiSpecificStreamInfo,
92
 
    paStreamIsStopped,
93
 
    paStreamIsNotStopped,
94
 
    paInputOverflowed,
95
 
    paOutputUnderflowed,
96
 
    paHostApiNotFound,
97
 
    paInvalidHostApi,
98
 
    paCanNotReadFromACallbackStream,      /**< @todo review error code name */
99
 
    paCanNotWriteToACallbackStream,       /**< @todo review error code name */
100
 
    paCanNotReadFromAnOutputOnlyStream,   /**< @todo review error code name */
101
 
    paCanNotWriteToAnInputOnlyStream,     /**< @todo review error code name */
102
 
    paIncompatibleStreamHostApi,
103
 
    paBadBufferPtr
104
 
} PaErrorCode;
105
 
 
106
 
 
107
 
/** Translate the supplied PortAudio error code into a human readable
108
 
 message.
109
 
*/
110
 
const char *Pa_GetErrorText( PaError errorCode );
111
 
 
112
 
 
113
 
/** Library initialization function - call this before using PortAudio.
114
 
 This function initialises internal data structures and prepares underlying
115
 
 host APIs for use.  With the exception of Pa_GetVersion(), Pa_GetVersionText(),
116
 
 and Pa_GetErrorText(), this function MUST be called before using any other
117
 
 PortAudio API functions.
118
 
 
119
 
 If Pa_Initialize() is called multiple times, each successful
120
 
 call must be matched with a corresponding call to Pa_Terminate().
121
 
 Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not
122
 
 required to be fully nested.
123
 
 
124
 
 Note that if Pa_Initialize() returns an error code, Pa_Terminate() should
125
 
 NOT be called.
126
 
 
127
 
 @return paNoError if successful, otherwise an error code indicating the cause
128
 
 of failure.
129
 
 
130
 
 @see Pa_Terminate
131
 
*/
132
 
PaError Pa_Initialize( void );
133
 
 
134
 
 
135
 
/** Library termination function - call this when finished using PortAudio.
136
 
 This function deallocates all resources allocated by PortAudio since it was
137
 
 initializied by a call to Pa_Initialize(). In cases where Pa_Initialise() has
138
 
 been called multiple times, each call must be matched with a corresponding call
139
 
 to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically
140
 
 close any PortAudio streams that are still open.
141
 
 
142
 
 Pa_Terminate() MUST be called before exiting a program which uses PortAudio.
143
 
 Failure to do so may result in serious resource leaks, such as audio devices
144
 
 not being available until the next reboot.
145
 
 
146
 
 @return paNoError if successful, otherwise an error code indicating the cause
147
 
 of failure.
148
 
 
149
 
 @see Pa_Initialize
150
 
*/
151
 
PaError Pa_Terminate( void );
152
 
 
153
 
 
154
 
 
155
 
/** The type used to refer to audio devices. Values of this type usually
156
 
 range from 0 to (Pa_GetDeviceCount()-1), and may also take on the PaNoDevice
157
 
 and paUseHostApiSpecificDeviceSpecification values.
158
 
 
159
 
 @see Pa_GetDeviceCount, paNoDevice, paUseHostApiSpecificDeviceSpecification
160
 
*/
161
 
typedef int PaDeviceIndex;
162
 
 
163
 
 
164
 
/** A special PaDeviceIndex value indicating that no device is available,
165
 
 or should be used.
166
 
 
167
 
 @see PaDeviceIndex
168
 
*/
169
 
#define paNoDevice ((PaDeviceIndex)-1)
170
 
 
171
 
 
172
 
/** A special PaDeviceIndex value indicating that the device(s) to be used
173
 
 are specified in the host api specific stream info structure.
174
 
 
175
 
 @see PaDeviceIndex
176
 
*/
177
 
#define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
178
 
 
179
 
 
180
 
/* Host API enumeration mechanism */
181
 
 
182
 
/** The type used to enumerate to host APIs at runtime. Values of this type
183
 
 range from 0 to (Pa_GetHostApiCount()-1).
184
 
 
185
 
 @see Pa_GetHostApiCount
186
 
*/
187
 
typedef int PaHostApiIndex;
188
 
 
189
 
 
190
 
/** Retrieve the number of available host APIs. Even if a host API is
191
 
 available it may have no devices available.
192
 
 
193
 
 @return A non-negative value indicating the number of available host APIs
194
 
 or, a PaErrorCode (which are always negative) if PortAudio is not initialized
195
 
 or an error is encountered.
196
 
 
197
 
 @see PaHostApiIndex
198
 
*/
199
 
PaHostApiIndex Pa_GetHostApiCount( void );
200
 
 
201
 
 
202
 
/** Retrieve the index of the default host API. The default host API will be
203
 
 the lowest common denominator host API on the current platform and is
204
 
 unlikely to provide the best performance.
205
 
 
206
 
 @return A non-negative value ranging from 0 to (Pa_GetHostApiCount()-1)
207
 
 indicating the default host API index or, a PaErrorCode (which are always
208
 
 negative) if PortAudio is not initialized or an error is encountered.
209
 
*/
210
 
PaHostApiIndex Pa_GetDefaultHostApi( void );
211
 
 
212
 
 
213
 
/** Unchanging unique identifiers for each supported host API. This type
214
 
 is used in the PaHostApiInfo structure. The values are guaranteed to be
215
 
 unique and to never change, thus allowing code to be written that
216
 
 conditionally uses host API specific extensions.
217
 
 
218
 
 New type ids will be allocated when support for a host API reaches
219
 
 "public alpha" status, prior to that developers should use the
220
 
 paInDevelopment type id.
221
 
 
222
 
 @see PaHostApiInfo
223
 
*/
224
 
typedef enum PaHostApiTypeId
225
 
{
226
 
    paInDevelopment=0, /* use while developing support for a new host API */
227
 
    paDirectSound=1,
228
 
    paMME=2,
229
 
    paASIO=3,
230
 
    paSoundManager=4,
231
 
    paCoreAudio=5,
232
 
    paOSS=7,
233
 
    paALSA=8,
234
 
    paAL=9,
235
 
    paBeOS=10,
236
 
    paWDMKS=11,
237
 
    paJACK=12,
238
 
    paWASAPI=13,
239
 
    paAudioScienceHPI=14
240
 
} PaHostApiTypeId;
241
 
 
242
 
 
243
 
/** A structure containing information about a particular host API. */
244
 
 
245
 
typedef struct PaHostApiInfo
246
 
{
247
 
    /** this is struct version 1 */
248
 
    int structVersion;
249
 
    /** The well known unique identifier of this host API @see PaHostApiTypeId */
250
 
    PaHostApiTypeId type;
251
 
    /** A textual description of the host API for display on user interfaces. */
252
 
    const char *name;
253
 
 
254
 
    /**  The number of devices belonging to this host API. This field may be
255
 
     used in conjunction with Pa_HostApiDeviceIndexToDeviceIndex() to enumerate
256
 
     all devices for this host API.
257
 
     @see Pa_HostApiDeviceIndexToDeviceIndex
258
 
    */
259
 
    int deviceCount;
260
 
 
261
 
    /** The default input device for this host API. The value will be a
262
 
     device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice
263
 
     if no default input device is available.
264
 
    */
265
 
    PaDeviceIndex defaultInputDevice;
266
 
 
267
 
    /** The default output device for this host API. The value will be a
268
 
     device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice
269
 
     if no default output device is available.
270
 
    */
271
 
    PaDeviceIndex defaultOutputDevice;
272
 
 
273
 
} PaHostApiInfo;
274
 
 
275
 
 
276
 
/** Retrieve a pointer to a structure containing information about a specific
277
 
 host Api.
278
 
 
279
 
 @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1)
280
 
 
281
 
 @return A pointer to an immutable PaHostApiInfo structure describing
282
 
 a specific host API. If the hostApi parameter is out of range or an error
283
 
 is encountered, the function returns NULL.
284
 
 
285
 
 The returned structure is owned by the PortAudio implementation and must not
286
 
 be manipulated or freed. The pointer is only guaranteed to be valid between
287
 
 calls to Pa_Initialize() and Pa_Terminate().
288
 
*/
289
 
const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
290
 
 
291
 
 
292
 
/** Convert a static host API unique identifier, into a runtime
293
 
 host API index.
294
 
 
295
 
 @param type A unique host API identifier belonging to the PaHostApiTypeId
296
 
 enumeration.
297
 
 
298
 
 @return A valid PaHostApiIndex ranging from 0 to (Pa_GetHostApiCount()-1) or,
299
 
 a PaErrorCode (which are always negative) if PortAudio is not initialized
300
 
 or an error is encountered.
301
 
 
302
 
 The paHostApiNotFound error code indicates that the host API specified by the
303
 
 type parameter is not available.
304
 
 
305
 
 @see PaHostApiTypeId
306
 
*/
307
 
PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
308
 
 
309
 
 
310
 
/** Convert a host-API-specific device index to standard PortAudio device index.
311
 
 This function may be used in conjunction with the deviceCount field of
312
 
 PaHostApiInfo to enumerate all devices for the specified host API.
313
 
 
314
 
 @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1)
315
 
 
316
 
 @param hostApiDeviceIndex A valid per-host device index in the range
317
 
 0 to (Pa_GetHostApiInfo(hostApi)->deviceCount-1)
318
 
 
319
 
 @return A non-negative PaDeviceIndex ranging from 0 to (Pa_GetDeviceCount()-1)
320
 
 or, a PaErrorCode (which are always negative) if PortAudio is not initialized
321
 
 or an error is encountered.
322
 
 
323
 
 A paInvalidHostApi error code indicates that the host API index specified by
324
 
 the hostApi parameter is out of range.
325
 
 
326
 
 A paInvalidDevice error code indicates that the hostApiDeviceIndex parameter
327
 
 is out of range.
328
 
 
329
 
 @see PaHostApiInfo
330
 
*/
331
 
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
332
 
        int hostApiDeviceIndex );
333
 
 
334
 
 
335
 
 
336
 
/** Structure used to return information about a host error condition.
337
 
*/
338
 
typedef struct PaHostErrorInfo{
339
 
    PaHostApiTypeId hostApiType;    /**< the host API which returned the error code */
340
 
    long errorCode;                 /**< the error code returned */
341
 
    const char *errorText;          /**< a textual description of the error if available, otherwise a zero-length string */
342
 
}PaHostErrorInfo;
343
 
 
344
 
 
345
 
/** Return information about the last host error encountered. The error
346
 
 information returned by Pa_GetLastHostErrorInfo() will never be modified
347
 
 asyncronously by errors occurring in other PortAudio owned threads
348
 
 (such as the thread that manages the stream callback.)
349
 
 
350
 
 This function is provided as a last resort, primarily to enhance debugging
351
 
 by providing clients with access to all available error information.
352
 
 
353
 
 @return A pointer to an immutable structure constaining information about
354
 
 the host error. The values in this structure will only be valid if a
355
 
 PortAudio function has previously returned the paUnanticipatedHostError
356
 
 error code.
357
 
*/
358
 
const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );
359
 
 
360
 
 
361
 
 
362
 
/* Device enumeration and capabilities */
363
 
 
364
 
/** Retrieve the number of available devices. The number of available devices
365
 
 may be zero.
366
 
 
367
 
 @return A non-negative value indicating the number of available devices or,
368
 
 a PaErrorCode (which are always negative) if PortAudio is not initialized
369
 
 or an error is encountered.
370
 
*/
371
 
PaDeviceIndex Pa_GetDeviceCount( void );
372
 
 
373
 
 
374
 
/** Retrieve the index of the default input device. The result can be
375
 
 used in the inputDevice parameter to Pa_OpenStream().
376
 
 
377
 
 @return The default input device index for the default host API, or paNoDevice
378
 
 if no default input device is available or an error was encountered.
379
 
*/
380
 
PaDeviceIndex Pa_GetDefaultInputDevice( void );
381
 
 
382
 
 
383
 
/** Retrieve the index of the default output device. The result can be
384
 
 used in the outputDevice parameter to Pa_OpenStream().
385
 
 
386
 
 @return The default output device index for the defualt host API, or paNoDevice
387
 
 if no default output device is available or an error was encountered.
388
 
 
389
 
 @note
390
 
 On the PC, the user can specify a default device by
391
 
 setting an environment variable. For example, to use device #1.
392
 
<pre>
393
 
 set PA_RECOMMENDED_OUTPUT_DEVICE=1
394
 
</pre>
395
 
 The user should first determine the available device ids by using
396
 
 the supplied application "pa_devs".
397
 
*/
398
 
PaDeviceIndex Pa_GetDefaultOutputDevice( void );
399
 
 
400
 
 
401
 
/** The type used to represent monotonic time in seconds that can be used
402
 
 for syncronisation. The type is used for the outTime argument to the
403
 
 PaStreamCallback and as the result of Pa_GetStreamTime().
404
 
 
405
 
 @see PaStreamCallback, Pa_GetStreamTime
406
 
*/
407
 
typedef double PaTime;
408
 
 
409
 
 
410
 
/** A type used to specify one or more sample formats. Each value indicates
411
 
 a possible format for sound data passed to and from the stream callback,
412
 
 Pa_ReadStream and Pa_WriteStream.
413
 
 
414
 
 The standard formats paFloat32, paInt16, paInt32, paInt24, paInt8
415
 
 and aUInt8 are usually implemented by all implementations.
416
 
 
417
 
 The floating point representation (paFloat32) uses +1.0 and -1.0 as the
418
 
 maximum and minimum respectively.
419
 
 
420
 
 paUInt8 is an unsigned 8 bit format where 128 is considered "ground"
421
 
 
422
 
 The paNonInterleaved flag indicates that a multichannel buffer is passed
423
 
 as a set of non-interleaved pointers.
424
 
 
425
 
 @see Pa_OpenStream, Pa_OpenDefaultStream, PaDeviceInfo
426
 
 @see paFloat32, paInt16, paInt32, paInt24, paInt8
427
 
 @see paUInt8, paCustomFormat, paNonInterleaved
428
 
*/
429
 
typedef unsigned long PaSampleFormat;
430
 
 
431
 
 
432
 
#define paFloat32        ((PaSampleFormat) 0x00000001) /**< @see PaSampleFormat */
433
 
#define paInt32          ((PaSampleFormat) 0x00000002) /**< @see PaSampleFormat */
434
 
#define paInt24          ((PaSampleFormat) 0x00000004) /**< Packed 24 bit format. @see PaSampleFormat */
435
 
#define paInt16          ((PaSampleFormat) 0x00000008) /**< @see PaSampleFormat */
436
 
#define paInt8           ((PaSampleFormat) 0x00000010) /**< @see PaSampleFormat */
437
 
#define paUInt8          ((PaSampleFormat) 0x00000020) /**< @see PaSampleFormat */
438
 
#define paCustomFormat   ((PaSampleFormat) 0x00010000)/**< @see PaSampleFormat */
439
 
 
440
 
#define paNonInterleaved ((PaSampleFormat) 0x80000000)
441
 
 
442
 
/** A structure providing information and capabilities of PortAudio devices.
443
 
 Devices may support input, output or both input and output.
444
 
*/
445
 
typedef struct PaDeviceInfo
446
 
{
447
 
    int structVersion;  /* this is struct version 2 */
448
 
    const char *name;
449
 
    PaHostApiIndex hostApi; /* note this is a host API index, not a type id*/
450
 
 
451
 
    int maxInputChannels;
452
 
    int maxOutputChannels;
453
 
 
454
 
    /* Default latency values for interactive performance. */
455
 
    PaTime defaultLowInputLatency;
456
 
    PaTime defaultLowOutputLatency;
457
 
    /* Default latency values for robust non-interactive applications (eg. playing sound files). */
458
 
    PaTime defaultHighInputLatency;
459
 
    PaTime defaultHighOutputLatency;
460
 
 
461
 
    double defaultSampleRate;
462
 
} PaDeviceInfo;
463
 
 
464
 
 
465
 
/** Retrieve a pointer to a PaDeviceInfo structure containing information
466
 
 about the specified device.
467
 
 @return A pointer to an immutable PaDeviceInfo structure. If the device
468
 
 parameter is out of range the function returns NULL.
469
 
 
470
 
 @param device A valid device index in the range 0 to (Pa_GetDeviceCount()-1)
471
 
 
472
 
 @note PortAudio manages the memory referenced by the returned pointer,
473
 
 the client must not manipulate or free the memory. The pointer is only
474
 
 guaranteed to be valid between calls to Pa_Initialize() and Pa_Terminate().
475
 
 
476
 
 @see PaDeviceInfo, PaDeviceIndex
477
 
*/
478
 
const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
479
 
 
480
 
 
481
 
/** Parameters for one direction (input or output) of a stream.
482
 
*/
483
 
typedef struct PaStreamParameters
484
 
{
485
 
    /** A valid device index in the range 0 to (Pa_GetDeviceCount()-1)
486
 
     specifying the device to be used or the special constant
487
 
     paUseHostApiSpecificDeviceSpecification which indicates that the actual
488
 
     device(s) to use are specified in hostApiSpecificStreamInfo.
489
 
     This field must not be set to paNoDevice.
490
 
    */
491
 
    PaDeviceIndex device;
492
 
 
493
 
    /** The number of channels of sound to be delivered to the
494
 
     stream callback or accessed by Pa_ReadStream() or Pa_WriteStream().
495
 
     It can range from 1 to the value of maxInputChannels in the
496
 
     PaDeviceInfo record for the device specified by the device parameter.
497
 
    */
498
 
    int channelCount;
499
 
 
500
 
    /** The sample format of the buffer provided to the stream callback,
501
 
     a_ReadStream() or Pa_WriteStream(). It may be any of the formats described
502
 
     by the PaSampleFormat enumeration.
503
 
    */
504
 
    PaSampleFormat sampleFormat;
505
 
 
506
 
    /** The desired latency in seconds. Where practical, implementations should
507
 
     configure their latency based on these parameters, otherwise they may
508
 
     choose the closest viable latency instead. Unless the suggested latency
509
 
     is greater than the absolute upper limit for the device implementations
510
 
     should round the suggestedLatency up to the next practial value - ie to
511
 
     provide an equal or higher latency than suggestedLatency wherever possibe.
512
 
     Actual latency values for an open stream may be retrieved using the
513
 
     inputLatency and outputLatency fields of the PaStreamInfo structure
514
 
     returned by Pa_GetStreamInfo().
515
 
     @see default*Latency in PaDeviceInfo, *Latency in PaStreamInfo
516
 
    */
517
 
    PaTime suggestedLatency;
518
 
 
519
 
    /** An optional pointer to a host api specific data structure
520
 
     containing additional information for device setup and/or stream processing.
521
 
     hostApiSpecificStreamInfo is never required for correct operation,
522
 
     if not used it should be set to NULL.
523
 
    */
524
 
    void *hostApiSpecificStreamInfo;
525
 
 
526
 
} PaStreamParameters;
527
 
 
528
 
 
529
 
/** Return code for Pa_IsFormatSupported indicating success. */
530
 
#define paFormatIsSupported (0)
531
 
 
532
 
/** Determine whether it would be possible to open a stream with the specified
533
 
 parameters.
534
 
 
535
 
 @param inputParameters A structure that describes the input parameters used to
536
 
 open a stream. The suggestedLatency field is ignored. See PaStreamParameters
537
 
 for a description of these parameters. inputParameters must be NULL for
538
 
 output-only streams.
539
 
 
540
 
 @param outputParameters A structure that describes the output parameters used
541
 
 to open a stream. The suggestedLatency field is ignored. See PaStreamParameters
542
 
 for a description of these parameters. outputParameters must be NULL for
543
 
 input-only streams.
544
 
 
545
 
 @param sampleRate The required sampleRate. For full-duplex streams it is the
546
 
 sample rate for both input and output
547
 
 
548
 
 @return Returns 0 if the format is supported, and an error code indicating why
549
 
 the format is not supported otherwise. The constant paFormatIsSupported is
550
 
 provided to compare with the return value for success.
551
 
 
552
 
 @see paFormatIsSupported, PaStreamParameters
553
 
*/
554
 
PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
555
 
                              const PaStreamParameters *outputParameters,
556
 
                              double sampleRate );
557
 
 
558
 
 
559
 
 
560
 
/* Streaming types and functions */
561
 
 
562
 
 
563
 
/**
564
 
 A single PaStream can provide multiple channels of real-time
565
 
 streaming audio input and output to a client application. A stream
566
 
 provides access to audio hardware represented by one or more
567
 
 PaDevices. Depending on the underlying Host API, it may be possible
568
 
 to open multiple streams using the same device, however this behavior
569
 
 is implementation defined. Portable applications should assume that
570
 
 a PaDevice may be simultaneously used by at most one PaStream.
571
 
 
572
 
 Pointers to PaStream objects are passed between PortAudio functions that
573
 
 operate on streams.
574
 
 
575
 
 @see Pa_OpenStream, Pa_OpenDefaultStream, Pa_OpenDefaultStream, Pa_CloseStream,
576
 
 Pa_StartStream, Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive,
577
 
 Pa_GetStreamTime, Pa_GetStreamCpuLoad
578
 
 
579
 
*/
580
 
typedef void PaStream;
581
 
 
582
 
 
583
 
/** Can be passed as the framesPerBuffer parameter to Pa_OpenStream()
584
 
 or Pa_OpenDefaultStream() to indicate that the stream callback will
585
 
 accept buffers of any size.
586
 
*/
587
 
#define paFramesPerBufferUnspecified  (0)
588
 
 
589
 
 
590
 
/** Flags used to control the behavior of a stream. They are passed as
591
 
 parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be
592
 
 ORed together.
593
 
 
594
 
 @see Pa_OpenStream, Pa_OpenDefaultStream
595
 
 @see paNoFlag, paClipOff, paDitherOff, paNeverDropInput,
596
 
  paPrimeOutputBuffersUsingStreamCallback, paPlatformSpecificFlags
597
 
*/
598
 
typedef unsigned long PaStreamFlags;
599
 
 
600
 
/** @see PaStreamFlags */
601
 
#define   paNoFlag          ((PaStreamFlags) 0)
602
 
 
603
 
/** Disable default clipping of out of range samples.
604
 
 @see PaStreamFlags
605
 
*/
606
 
#define   paClipOff         ((PaStreamFlags) 0x00000001)
607
 
 
608
 
/** Disable default dithering.
609
 
 @see PaStreamFlags
610
 
*/
611
 
#define   paDitherOff       ((PaStreamFlags) 0x00000002)
612
 
 
613
 
/** Flag requests that where possible a full duplex stream will not discard
614
 
 overflowed input samples without calling the stream callback. This flag is
615
 
 only valid for full duplex callback streams and only when used in combination
616
 
 with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using
617
 
 this flag incorrectly results in a paInvalidFlag error being returned from
618
 
 Pa_OpenStream and Pa_OpenDefaultStream.
619
 
 
620
 
 @see PaStreamFlags, paFramesPerBufferUnspecified
621
 
*/
622
 
#define   paNeverDropInput  ((PaStreamFlags) 0x00000004)
623
 
 
624
 
/** Call the stream callback to fill initial output buffers, rather than the
625
 
 default behavior of priming the buffers with zeros (silence). This flag has
626
 
 no effect for input-only and blocking read/write streams.
627
 
 
628
 
 @see PaStreamFlags
629
 
*/
630
 
#define   paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
631
 
 
632
 
/** A mask specifying the platform specific bits.
633
 
 @see PaStreamFlags
634
 
*/
635
 
#define   paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
636
 
 
637
 
/**
638
 
 Timing information for the buffers passed to the stream callback.
639
 
*/
640
 
typedef struct PaStreamCallbackTimeInfo{
641
 
    PaTime inputBufferAdcTime;
642
 
    PaTime currentTime;
643
 
    PaTime outputBufferDacTime;
644
 
} PaStreamCallbackTimeInfo;
645
 
 
646
 
 
647
 
/**
648
 
 Flag bit constants for the statusFlags to PaStreamCallback.
649
 
 
650
 
 @see paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflow,
651
 
 paPrimingOutput
652
 
*/
653
 
typedef unsigned long PaStreamCallbackFlags;
654
 
 
655
 
/** In a stream opened with paFramesPerBufferUnspecified, indicates that
656
 
 input data is all silence (zeros) because no real data is available. In a
657
 
 stream opened without paFramesPerBufferUnspecified, it indicates that one or
658
 
 more zero samples have been inserted into the input buffer to compensate
659
 
 for an input underflow.
660
 
 @see PaStreamCallbackFlags
661
 
*/
662
 
#define paInputUnderflow   ((PaStreamCallbackFlags) 0x00000001)
663
 
 
664
 
/** In a stream opened with paFramesPerBufferUnspecified, indicates that data
665
 
 prior to the first sample of the input buffer was discarded due to an
666
 
 overflow, possibly because the stream callback is using too much CPU time.
667
 
 Otherwise indicates that data prior to one or more samples in the
668
 
 input buffer was discarded.
669
 
 @see PaStreamCallbackFlags
670
 
*/
671
 
#define paInputOverflow    ((PaStreamCallbackFlags) 0x00000002)
672
 
 
673
 
/** Indicates that output data (or a gap) was inserted, possibly because the
674
 
 stream callback is using too much CPU time.
675
 
 @see PaStreamCallbackFlags
676
 
*/
677
 
#define paOutputUnderflow  ((PaStreamCallbackFlags) 0x00000004)
678
 
 
679
 
/** Indicates that output data will be discarded because no room is available.
680
 
 @see PaStreamCallbackFlags
681
 
*/
682
 
#define paOutputOverflow   ((PaStreamCallbackFlags) 0x00000008)
683
 
 
684
 
/** Some of all of the output data will be used to prime the stream, input
685
 
 data may be zero.
686
 
 @see PaStreamCallbackFlags
687
 
*/
688
 
#define paPrimingOutput    ((PaStreamCallbackFlags) 0x00000010)
689
 
 
690
 
/**
691
 
 Allowable return values for the PaStreamCallback.
692
 
 @see PaStreamCallback
693
 
*/
694
 
typedef enum PaStreamCallbackResult
695
 
{
696
 
    paContinue=0,
697
 
    paComplete=1,
698
 
    paAbort=2
699
 
} PaStreamCallbackResult;
700
 
 
701
 
 
702
 
/**
703
 
 Functions of type PaStreamCallback are implemented by PortAudio clients.
704
 
 They consume, process or generate audio in response to requests from an
705
 
 active PortAudio stream.
706
 
 
707
 
 @param input and @param output are arrays of interleaved samples,
708
 
 the format, packing and number of channels used by the buffers are
709
 
 determined by parameters to Pa_OpenStream().
710
 
 
711
 
 @param frameCount The number of sample frames to be processed by
712
 
 the stream callback.
713
 
 
714
 
 @param timeInfo The time in seconds when the first sample of the input
715
 
 buffer was received at the audio input, the time in seconds when the first
716
 
 sample of the output buffer will begin being played at the audio output, and
717
 
 the time in seconds when the stream callback was called.
718
 
 See also Pa_GetStreamTime()
719
 
 
720
 
 @param statusFlags Flags indicating whether input and/or output buffers
721
 
 have been inserted or will be dropped to overcome underflow or overflow
722
 
 conditions.
723
 
 
724
 
 @param userData The value of a user supplied pointer passed to
725
 
 Pa_OpenStream() intended for storing synthesis data etc.
726
 
 
727
 
 @return
728
 
 The stream callback should return one of the values in the
729
 
 PaStreamCallbackResult enumeration. To ensure that the callback continues
730
 
 to be called, it should return paContinue (0). Either paComplete or paAbort
731
 
 can be returned to finish stream processing, after either of these values is
732
 
 returned the callback will not be called again. If paAbort is returned the
733
 
 stream will finish as soon as possible. If paComplete is returned, the stream
734
 
 will continue until all buffers generated by the callback have been played.
735
 
 This may be useful in applications such as soundfile players where a specific
736
 
 duration of output is required. However, it is not necessary to utilise this
737
 
 mechanism as Pa_StopStream(), Pa_AbortStream() or Pa_CloseStream() can also
738
 
 be used to stop the stream. The callback must always fill the entire output
739
 
 buffer irrespective of its return value.
740
 
 
741
 
 @see Pa_OpenStream, Pa_OpenDefaultStream
742
 
 
743
 
 @note With the exception of Pa_GetStreamCpuLoad() it is not permissable to call
744
 
 PortAudio API functions from within the stream callback.
745
 
*/
746
 
typedef int PaStreamCallback(
747
 
    const void *input, void *output,
748
 
    unsigned long frameCount,
749
 
    const PaStreamCallbackTimeInfo* timeInfo,
750
 
    PaStreamCallbackFlags statusFlags,
751
 
    void *userData );
752
 
 
753
 
 
754
 
/** Opens a stream for either input, output or both.
755
 
 
756
 
 @param stream The address of a PaStream pointer which will receive
757
 
 a pointer to the newly opened stream.
758
 
 
759
 
 @param inputParameters A structure that describes the input parameters used by
760
 
 the opened stream. See PaStreamParameters for a description of these parameters.
761
 
 inputParameters must be NULL for output-only streams.
762
 
 
763
 
 @param outputParameters A structure that describes the output parameters used by
764
 
 the opened stream. See PaStreamParameters for a description of these parameters.
765
 
 outputParameters must be NULL for input-only streams.
766
 
 
767
 
 @param sampleRate The desired sampleRate. For full-duplex streams it is the
768
 
 sample rate for both input and output
769
 
 
770
 
 @param framesPerBuffer The number of frames passed to the stream callback
771
 
 function, or the preferred block granularity for a blocking read/write stream.
772
 
 The special value paFramesPerBufferUnspecified (0) may be used to request that
773
 
 the stream callback will recieve an optimal (and possibly varying) number of
774
 
 frames based on host requirements and the requested latency settings.
775
 
 Note: With some host APIs, the use of non-zero framesPerBuffer for a callback
776
 
 stream may introduce an additional layer of buffering which could introduce
777
 
 additional latency. PortAudio guarantees that the additional latency
778
 
 will be kept to the theoretical minimum however, it is strongly recommended
779
 
 that a non-zero framesPerBuffer value only be used when your algorithm
780
 
 requires a fixed number of frames per stream callback.
781
 
 
782
 
 @param streamFlags Flags which modify the behaviour of the streaming process.
783
 
 This parameter may contain a combination of flags ORed together. Some flags may
784
 
 only be relevant to certain buffer formats.
785
 
 
786
 
 @param streamCallback A pointer to a client supplied function that is responsible
787
 
 for processing and filling input and output buffers. If this parameter is NULL
788
 
 the stream will be opened in 'blocking read/write' mode. In blocking mode,
789
 
 the client can receive sample data using Pa_ReadStream and write sample data
790
 
 using Pa_WriteStream, the number of samples that may be read or written
791
 
 without blocking is returned by Pa_GetStreamReadAvailable and
792
 
 Pa_GetStreamWriteAvailable respectively.
793
 
 
794
 
 @param userData A client supplied pointer which is passed to the stream callback
795
 
 function. It could for example, contain a pointer to instance data necessary
796
 
 for processing the audio buffers. This parameter is ignored if streamCallback
797
 
 is NULL.
798
 
 
799
 
 @return
800
 
 Upon success Pa_OpenStream() returns paNoError and places a pointer to a
801
 
 valid PaStream in the stream argument. The stream is inactive (stopped).
802
 
 If a call to Pa_OpenStream() fails, a non-zero error code is returned (see
803
 
 PaError for possible error codes) and the value of stream is invalid.
804
 
 
805
 
 @see PaStreamParameters, PaStreamCallback, Pa_ReadStream, Pa_WriteStream,
806
 
 Pa_GetStreamReadAvailable, Pa_GetStreamWriteAvailable
807
 
*/
808
 
PaError Pa_OpenStream( PaStream** stream,
809
 
                       const PaStreamParameters *inputParameters,
810
 
                       const PaStreamParameters *outputParameters,
811
 
                       double sampleRate,
812
 
                       unsigned long framesPerBuffer,
813
 
                       PaStreamFlags streamFlags,
814
 
                       PaStreamCallback *streamCallback,
815
 
                       void *userData );
816
 
 
817
 
 
818
 
/** A simplified version of Pa_OpenStream() that opens the default input
819
 
 and/or output devices.
820
 
 
821
 
 @param stream The address of a PaStream pointer which will receive
822
 
 a pointer to the newly opened stream.
823
 
 
824
 
 @param numInputChannels  The number of channels of sound that will be supplied
825
 
 to the stream callback or returned by Pa_ReadStream. It can range from 1 to
826
 
 the value of maxInputChannels in the PaDeviceInfo record for the default input
827
 
 device. If 0 the stream is opened as an output-only stream.
828
 
 
829
 
 @param numOutputChannels The number of channels of sound to be delivered to the
830
 
 stream callback or passed to Pa_WriteStream. It can range from 1 to the value
831
 
 of maxOutputChannels in the PaDeviceInfo record for the default output dvice.
832
 
 If 0 the stream is opened as an output-only stream.
833
 
 
834
 
 @param sampleFormat The sample format of both the input and output buffers
835
 
 provided to the callback or passed to and from Pa_ReadStream and Pa_WriteStream.
836
 
 sampleFormat may be any of the formats described by the PaSampleFormat
837
 
 enumeration.
838
 
 
839
 
 @param sampleRate Same as Pa_OpenStream parameter of the same name.
840
 
 @param framesPerBuffer Same as Pa_OpenStream parameter of the same name.
841
 
 @param streamCallback Same as Pa_OpenStream parameter of the same name.
842
 
 @param userData Same as Pa_OpenStream parameter of the same name.
843
 
 
844
 
 @return As for Pa_OpenStream
845
 
 
846
 
 @see Pa_OpenStream, PaStreamCallback
847
 
*/
848
 
PaError Pa_OpenDefaultStream( PaStream** stream,
849
 
                              int numInputChannels,
850
 
                              int numOutputChannels,
851
 
                              PaSampleFormat sampleFormat,
852
 
                              double sampleRate,
853
 
                              unsigned long framesPerBuffer,
854
 
                              PaStreamCallback *streamCallback,
855
 
                              void *userData );
856
 
 
857
 
 
858
 
/** Closes an audio stream. If the audio stream is active it
859
 
 discards any pending buffers as if Pa_AbortStream() had been called.
860
 
*/
861
 
PaError Pa_CloseStream( PaStream *stream );
862
 
 
863
 
 
864
 
/** Functions of type PaStreamFinishedCallback are implemented by PortAudio
865
 
 clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback
866
 
 function. Once registered they are called when the stream becomes inactive
867
 
 (ie once a call to Pa_StopStream() will not block).
868
 
 A stream will become inactive after the stream callback returns non-zero,
869
 
 or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio
870
 
 output, if the stream callback returns paComplete, or Pa_StopStream is called,
871
 
 the stream finished callback will not be called until all generated sample data
872
 
 has been played.
873
 
 
874
 
 @param userData The userData parameter supplied to Pa_OpenStream()
875
 
 
876
 
 @see Pa_SetStreamFinishedCallback
877
 
*/
878
 
typedef void PaStreamFinishedCallback( void *userData );
879
 
 
880
 
 
881
 
/** Register a stream finished callback function which will be called when the
882
 
 stream becomes inactive. See the description of PaStreamFinishedCallback for
883
 
 further details about when the callback will be called.
884
 
 
885
 
 @param stream a pointer to a PaStream that is in the stopped state - if the
886
 
 stream is not stopped, the stream's finished callback will remain unchanged
887
 
 and an error code will be returned.
888
 
 
889
 
 @param streamFinishedCallback a pointer to a function with the same signature
890
 
 as PaStreamFinishedCallback, that will be called when the stream becomes
891
 
 inactive. Passing NULL for this parameter will un-register a previously
892
 
 registered stream finished callback function.
893
 
 
894
 
 @return on success returns paNoError, otherwise an error code indicating the cause
895
 
 of the error.
896
 
 
897
 
 @see PaStreamFinishedCallback
898
 
*/
899
 
PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
900
 
 
901
 
 
902
 
/** Commences audio processing.
903
 
*/
904
 
PaError Pa_StartStream( PaStream *stream );
905
 
 
906
 
 
907
 
/** Terminates audio processing. It waits until all pending
908
 
 audio buffers have been played before it returns.
909
 
*/
910
 
PaError Pa_StopStream( PaStream *stream );
911
 
 
912
 
 
913
 
/** Terminates audio processing immediately without waiting for pending
914
 
 buffers to complete.
915
 
*/
916
 
PaError Pa_AbortStream( PaStream *stream );
917
 
 
918
 
 
919
 
/** Determine whether the stream is stopped.
920
 
 A stream is considered to be stopped prior to a successful call to
921
 
 Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream.
922
 
 If a stream callback returns a value other than paContinue the stream is NOT
923
 
 considered to be stopped.
924
 
 
925
 
 @return Returns one (1) when the stream is stopped, zero (0) when
926
 
 the stream is running or, a PaErrorCode (which are always negative) if
927
 
 PortAudio is not initialized or an error is encountered.
928
 
 
929
 
 @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive
930
 
*/
931
 
PaError Pa_IsStreamStopped( PaStream *stream );
932
 
 
933
 
 
934
 
/** Determine whether the stream is active.
935
 
 A stream is active after a successful call to Pa_StartStream(), until it
936
 
 becomes inactive either as a result of a call to Pa_StopStream() or
937
 
 Pa_AbortStream(), or as a result of a return value other than paContinue from
938
 
 the stream callback. In the latter case, the stream is considered inactive
939
 
 after the last buffer has finished playing.
940
 
 
941
 
 @return Returns one (1) when the stream is active (ie playing or recording
942
 
 audio), zero (0) when not playing or, a PaErrorCode (which are always negative)
943
 
 if PortAudio is not initialized or an error is encountered.
944
 
 
945
 
 @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamStopped
946
 
*/
947
 
PaError Pa_IsStreamActive( PaStream *stream );
948
 
 
949
 
 
950
 
 
951
 
/** A structure containing unchanging information about an open stream.
952
 
 @see Pa_GetStreamInfo
953
 
*/
954
 
 
955
 
typedef struct PaStreamInfo
956
 
{
957
 
    /** this is struct version 1 */
958
 
    int structVersion;
959
 
 
960
 
    /** The input latency of the stream in seconds. This value provides the most
961
 
     accurate estimate of input latency available to the implementation. It may
962
 
     differ significantly from the suggestedLatency value passed to Pa_OpenStream().
963
 
     The value of this field will be zero (0.) for output-only streams.
964
 
     @see PaTime
965
 
    */
966
 
    PaTime inputLatency;
967
 
 
968
 
    /** The output latency of the stream in seconds. This value provides the most
969
 
     accurate estimate of output latency available to the implementation. It may
970
 
     differ significantly from the suggestedLatency value passed to Pa_OpenStream().
971
 
     The value of this field will be zero (0.) for input-only streams.
972
 
     @see PaTime
973
 
    */
974
 
    PaTime outputLatency;
975
 
 
976
 
    /** The sample rate of the stream in Hertz (samples per second). In cases
977
 
     where the hardware sample rate is inaccurate and PortAudio is aware of it,
978
 
     the value of this field may be different from the sampleRate parameter
979
 
     passed to Pa_OpenStream(). If information about the actual hardware sample
980
 
     rate is not available, this field will have the same value as the sampleRate
981
 
     parameter passed to Pa_OpenStream().
982
 
    */
983
 
    double sampleRate;
984
 
 
985
 
} PaStreamInfo;
986
 
 
987
 
 
988
 
/** Retrieve a pointer to a PaStreamInfo structure containing information
989
 
 about the specified stream.
990
 
 @return A pointer to an immutable PaStreamInfo structure. If the stream
991
 
 parameter invalid, or an error is encountered, the function returns NULL.
992
 
 
993
 
 @param stream A pointer to an open stream previously created with Pa_OpenStream.
994
 
 
995
 
 @note PortAudio manages the memory referenced by the returned pointer,
996
 
 the client must not manipulate or free the memory. The pointer is only
997
 
 guaranteed to be valid until the specified stream is closed.
998
 
 
999
 
 @see PaStreamInfo
1000
 
*/
1001
 
const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1002
 
 
1003
 
 
1004
 
/** Determine the current time for the stream according to the same clock used
1005
 
 to generate buffer timestamps. This time may be used for syncronising other
1006
 
 events to the audio stream, for example synchronizing audio to MIDI.
1007
 
 
1008
 
 @return The stream's current time in seconds, or 0 if an error occurred.
1009
 
 
1010
 
 @see PaTime, PaStreamCallback
1011
 
*/
1012
 
PaTime Pa_GetStreamTime( PaStream *stream );
1013
 
 
1014
 
 
1015
 
/** Retrieve CPU usage information for the specified stream.
1016
 
 The "CPU Load" is a fraction of total CPU time consumed by a callback stream's
1017
 
 audio processing routines including, but not limited to the client supplied
1018
 
 stream callback. This function does not work with blocking read/write streams.
1019
 
 
1020
 
 This function may be called from the stream callback function or the
1021
 
 application.
1022
 
 
1023
 
 @return
1024
 
 A floating point value, typically between 0.0 and 1.0, where 1.0 indicates
1025
 
 that the stream callback is consuming the maximum number of CPU cycles possible
1026
 
 to maintain real-time operation. A value of 0.5 would imply that PortAudio and
1027
 
 the stream callback was consuming roughly 50% of the available CPU time. The
1028
 
 return value may exceed 1.0. A value of 0.0 will always be returned for a
1029
 
 blocking read/write stream, or if an error occurrs.
1030
 
*/
1031
 
double Pa_GetStreamCpuLoad( PaStream* stream );
1032
 
 
1033
 
 
1034
 
/** Read samples from an input stream. The function doesn't return until
1035
 
 the entire buffer has been filled - this may involve waiting for the operating
1036
 
 system to supply the data.
1037
 
 
1038
 
 @param stream A pointer to an open stream previously created with Pa_OpenStream.
1039
 
 
1040
 
 @param buffer A pointer to a buffer of sample frames. The buffer contains
1041
 
 samples in the format specified by the inputParameters->sampleFormat field
1042
 
 used to open the stream, and the number of channels specified by
1043
 
 inputParameters->numChannels. If non-interleaved samples were requested,
1044
 
 buffer is a pointer to the first element of an array of non-interleaved
1045
 
 buffer pointers, one for each channel.
1046
 
 
1047
 
 @param frames The number of frames to be read into buffer. This parameter
1048
 
 is not constrained to a specific range, however high performance applications
1049
 
 will want to match this parameter to the framesPerBuffer parameter used
1050
 
 when opening the stream.
1051
 
 
1052
 
 @return On success PaNoError will be returned, or PaInputOverflowed if input
1053
 
 data was discarded by PortAudio after the previous call and before this call.
1054
 
*/
1055
 
PaError Pa_ReadStream( PaStream* stream,
1056
 
                       void *buffer,
1057
 
                       unsigned long frames );
1058
 
 
1059
 
 
1060
 
/** Write samples to an output stream. This function doesn't return until the
1061
 
 entire buffer has been consumed - this may involve waiting for the operating
1062
 
 system to consume the data.
1063
 
 
1064
 
 @param stream A pointer to an open stream previously created with Pa_OpenStream.
1065
 
 
1066
 
 @param buffer A pointer to a buffer of sample frames. The buffer contains
1067
 
 samples in the format specified by the outputParameters->sampleFormat field
1068
 
 used to open the stream, and the number of channels specified by
1069
 
 outputParameters->numChannels. If non-interleaved samples were requested,
1070
 
 buffer is a pointer to the first element of an array of non-interleaved
1071
 
 buffer pointers, one for each channel.
1072
 
 
1073
 
 @param frames The number of frames to be written from buffer. This parameter
1074
 
 is not constrained to a specific range, however high performance applications
1075
 
 will want to match this parameter to the framesPerBuffer parameter used
1076
 
 when opening the stream.
1077
 
 
1078
 
 @return On success PaNoError will be returned, or paOutputUnderflowed if
1079
 
 additional output data was inserted after the previous call and before this
1080
 
 call.
1081
 
*/
1082
 
PaError Pa_WriteStream( PaStream* stream,
1083
 
                        const void *buffer,
1084
 
                        unsigned long frames );
1085
 
 
1086
 
 
1087
 
/** Retrieve the number of frames that can be read from the stream without
1088
 
 waiting.
1089
 
 
1090
 
 @return Returns a non-negative value representing the maximum number of frames
1091
 
 that can be read from the stream without blocking or busy waiting or, a
1092
 
 PaErrorCode (which are always negative) if PortAudio is not initialized or an
1093
 
 error is encountered.
1094
 
*/
1095
 
signed long Pa_GetStreamReadAvailable( PaStream* stream );
1096
 
 
1097
 
 
1098
 
/** Retrieve the number of frames that can be written to the stream without
1099
 
 waiting.
1100
 
 
1101
 
 @return Returns a non-negative value representing the maximum number of frames
1102
 
 that can be written to the stream without blocking or busy waiting or, a
1103
 
 PaErrorCode (which are always negative) if PortAudio is not initialized or an
1104
 
 error is encountered.
1105
 
*/
1106
 
signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1107
 
 
1108
 
 
1109
 
/* Miscellaneous utilities */
1110
 
 
1111
 
 
1112
 
/** Retrieve the size of a given sample format in bytes.
1113
 
 
1114
 
 @return The size in bytes of a single sample in the specified format,
1115
 
 or paSampleFormatNotSupported if the format is not supported.
1116
 
*/
1117
 
PaError Pa_GetSampleSize( PaSampleFormat format );
1118
 
 
1119
 
 
1120
 
/** Put the caller to sleep for at least 'msec' milliseconds. This function is
1121
 
 provided only as a convenience for authors of portable code (such as the tests
1122
 
 and examples in the PortAudio distribution.)
1123
 
 
1124
 
 The function may sleep longer than requested so don't rely on this for accurate
1125
 
 musical timing.
1126
 
*/
1127
 
void Pa_Sleep( long msec );
1128
 
 
1129
 
 
1130
 
 
1131
 
#ifdef __cplusplus
1132
 
}
1133
 
#endif /* __cplusplus */
1134
 
#endif /* PORTAUDIO_H */