PageRenderTime 70ms CodeModel.GetById 13ms app.highlight 45ms RepoModel.GetById 2ms app.codeStats 0ms

/native/external/espeak/src/portaudio19.h

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