/usr/share/doc/portaudio19-doc/doc/html/api_overview.html is in portaudio19-doc 19+svn20140130-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>PortAudio: PortAudio API Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">PortAudio
 <span id="projectnumber">2.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">PortAudio API Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This page provides a top-down overview of the entire PortAudio API. It describes how all of the PortAudio data types and functions fit together. It provides links to the documentation for each function and data type. You can find all of the detailed documentation for each API function and data type on the <a class="el" href="portaudio_8h.html" title="The portable PortAudio API. ">portaudio.h</a> page.</p>
<h1><a class="anchor" id="introduction"></a>
Introduction</h1>
<p>PortAudio provides a uniform application programming interface (API) across all supported platforms. You can think of the PortAudio library as a wrapper that converts calls to the PortAudio API into calls to platform-specific native audio APIs. Operating systems often offer more than one native audio API and some APIs (such as JACK) may be available on multiple target operating systems. PortAudio supports all the major native audio APIs on each supported platform. The diagram below illustrates the relationship between your application, PortAudio, and the supported native audio APIs:</p>
<div class="image">
<img src="portaudio-external-architecture-diagram.png" alt="portaudio-external-architecture-diagram.png"/>
</div>
<p>PortAudio provides a uniform interface to native audio APIs. However, it doesn't always provide totally uniform functionality. There are cases where PortAudio is limited by the capabilities of the underlying native audio API. For example, PortAudio doesn't provide sample rate conversion if you request a sample rate that is not supported by the native audio API. Another example is that the ASIO SDK only allows one device to be open at a time, so PortAudio/ASIO doesn't currently support opening multiple ASIO devices simultaneously.</p>
<h1><a class="anchor" id="key_abstractions"></a>
Key abstractions: Host APIs, Devices and Streams</h1>
<p>The PortAudio processing model includes three main abstractions: <em>Host APIs</em>, audio <em>Devices</em> and audio <em>Streams</em>.</p>
<p>Host APIs represent platform-specific native audio APIs. Some examples of Host APIs are Core Audio on Mac OS, WMME and DirectSound on Windows and OSS and ALSA on Linux. The diagram in the previous section shows many of the supported native APIs. Sometimes it's useful to know which Host APIs you're dealing with, but it is easy to use PortAudio without ever interacting directly with the Host API abstraction.</p>
<p>Devices represent individual hardware audio interfaces or audio ports on the host platform. Devices have names and certain capabilities such as supported sample rates and the number of supported input and output channels. PortAudio provides functions to enumerate available Devices and to query for Device capabilities.</p>
<p>Streams manage active audio input and output from and to Devices. Streams may be half duplex (input or output) or full duplex (simultaneous input and output). Streams operate at a specific sample rate with particular sample formats, buffer sizes and internal buffering latencies. You specify these parameters when you open the Stream. Audio data is communicated between a Stream and your application via a user provided asynchronous callback function or by invoking synchronous read and write functions.</p>
<p>PortAudio supports audio input and output in a variety of sample formats: 8, 16, 24 and 32 bit integer formats and 32 bit floating point, irrespective of the formats supported by the native audio API. PortAudio also supports multichannel buffers in both interleaved and non-interleaved (separate buffer per channel) formats and automatically performs conversion when necessary. If requested, PortAudio can clamp out-of range samples and/or dither to a native format.</p>
<p>The PortAudio API offers the following functionality:</p>
<ul>
<li>Initialize and terminate the library</li>
<li>Enumerate available Host APIs</li>
<li>Enumerate available Devices either globally, or within each Host API</li>
<li>Discover default or recommended Devices and Device settings</li>
<li>Discover Device capabilities such as supported audio data formats and sample rates</li>
<li>Create and control audio Streams to acquire audio from and output audio to Devices</li>
<li>Provide Stream timing information to support synchronising audio with other parts of your application</li>
<li>Retrieve version and error information.</li>
</ul>
<p>These functions are described in more detail below.</p>
<h1><a class="anchor" id="top_level_functions"></a>
Initialization, termination and utility functions</h1>
<p>The PortAudio library must be initialized before it can be used and terminated to clean up afterwards. You initialize PortAudio by calling <a class="el" href="portaudio_8h.html#abed859482d156622d9332dff9b2d89da">Pa_Initialize()</a> and clean up by calling <a class="el" href="portaudio_8h.html#a0db317604e916e8bd6098e60e6237221">Pa_Terminate()</a>.</p>
<p>You can query PortAudio for version information using <a class="el" href="portaudio_8h.html#a66da08bcf908e0849c62a6b47f50d7b4">Pa_GetVersion()</a> to get a numeric version number and <a class="el" href="portaudio_8h.html#a28f3fd9e6d9f933cc695abea71c4b445">Pa_GetVersionText()</a> to get a string.</p>
<p>The size in bytes of the various sample formats represented by the <a class="el" href="portaudio_8h.html#a4582d93c2c2e60e12be3d74c5fe00b96">PaSampleFormat</a> enumeration can be obtained using <a class="el" href="portaudio_8h.html#a541ed0b734df2631bc4c229acf92abc1">Pa_GetSampleSize()</a>.</p>
<p><a class="el" href="portaudio_8h.html#a1b3c20044c9401c42add29475636e83d">Pa_Sleep()</a> sleeps for a specified number of milliseconds. This isn't intended for use in production systems; it's provided only as a simple portable way to implement tests and examples where the main thread sleeps while audio is acquired or played by an asynchronous callback function.</p>
<h1><a class="anchor" id="host_apis"></a>
Host APIs</h1>
<p>A Host API acts as a top-level grouping for all of the Devices offered by a single native platform audio API. Each Host API has a unique type identifier, a name, zero or more Devices, and nominated default input and output Devices.</p>
<p>Host APIs are usually referenced by index: an integer of type <a class="el" href="portaudio_8h.html#aeef6da084c57c70aa94be97411e19930">PaHostApiIndex</a> that ranges between zero and <a class="el" href="portaudio_8h.html#a19dbdb7c8702e3f4bfc0cdb99dac3dd9">Pa_GetHostApiCount()</a> - 1. You can enumerate all available Host APIs by counting across this range.</p>
<p>You can retrieve the index of the default Host API by calling <a class="el" href="portaudio_8h.html#ae55c77f9b7e3f8eb301a6f1c0e2347ac">Pa_GetDefaultHostApi()</a>.</p>
<p>Information about a Host API, such as it's name and default devices, is stored in a <a class="el" href="structPaHostApiInfo.html">PaHostApiInfo</a> structure. You can retrieve a pointer to a particular Host API's <a class="el" href="structPaHostApiInfo.html">PaHostApiInfo</a> structure by calling <a class="el" href="portaudio_8h.html#a7c650aede88ea553066bab9bbe97ea90">Pa_GetHostApiInfo()</a> with the Host API's index as a parameter.</p>
<p>Most PortAudio functions reference Host APIs by <a class="el" href="portaudio_8h.html#aeef6da084c57c70aa94be97411e19930">PaHostApiIndex</a> indices. Each Host API also has a unique type identifier defined in the <a class="el" href="portaudio_8h.html#ae247ec252e84112170079ece319fc42c">PaHostApiTypeId</a> enumeration. You can call <a class="el" href="portaudio_8h.html#a081c3975126d20b4226facfb7ba0620f">Pa_HostApiTypeIdToHostApiIndex()</a> to retrieve the current <a class="el" href="portaudio_8h.html#aeef6da084c57c70aa94be97411e19930">PaHostApiIndex</a> for a particular <a class="el" href="portaudio_8h.html#ae247ec252e84112170079ece319fc42c">PaHostApiTypeId</a>.</p>
<h1><a class="anchor" id="devices"></a>
Devices</h1>
<p>A Device represents an audio endpoint provided by a particular native audio API. This usually corresponds to a specific input or output port on a hardware audio interface, or to the interface as a whole. Each Host API operates independently, so a single physical audio port may be addressable via different Devices exposed by different Host APIs.</p>
<p>A Device has a name, is associated with a Host API, and has a maximum number of supported input and output channels. PortAudio provides recommended default latency values and a default sample rate for each Device. To obtain more detailed information about device capabilities you can call <a class="el" href="portaudio_8h.html#abdb313743d6efef26cecdae787a2bd3d">Pa_IsFormatSupported()</a> to query whether it is possible to open a Stream using particular Devices, parameters and sample rate.</p>
<p>Although each Device conceptually belongs to a specific Host API, most PortAudio functions and data structures refer to Devices using a global, Host API-independent index of type <a class="el" href="portaudio_8h.html#ad79317e65bde63d76c4b8e711ac5a361">PaDeviceIndex</a> – an integer of that ranges between zero and <a class="el" href="portaudio_8h.html#acfe4d3c5ec1a343f459981bfa2057f8d">Pa_GetDeviceCount()</a> - 1. The reasons for this are partly historical but it also makes it easy for applications to ignore the Host API abstraction and just work with Devices and Streams.</p>
<p>If you want to enumerate Devices belonging to a particular Host API you can count between 0 and <a class="el" href="structPaHostApiInfo.html#a44e3adfaba0117a6780e2493468c96b1">PaHostApiInfo::deviceCount</a> - 1. You can convert this Host API-specific index value to a global <a class="el" href="portaudio_8h.html#ad79317e65bde63d76c4b8e711ac5a361">PaDeviceIndex</a> value by calling <a class="el" href="portaudio_8h.html#a54f306b5e5258323c95a27c5722258cd">Pa_HostApiDeviceIndexToDeviceIndex()</a>.</p>
<p>Information about a Device is stored in a <a class="el" href="structPaDeviceInfo.html">PaDeviceInfo</a> structure. You can retrieve a pointer to a Devices's <a class="el" href="structPaDeviceInfo.html">PaDeviceInfo</a> structure by calling <a class="el" href="portaudio_8h.html#ac7d8e091ffc1d1d4a035704660e117eb">Pa_GetDeviceInfo()</a> with the Device's index as a parameter.</p>
<p>You can retrieve the indices of the global default input and output devices using <a class="el" href="portaudio_8h.html#abf9f2f82da95553d5adb929af670f74b">Pa_GetDefaultInputDevice()</a> and <a class="el" href="portaudio_8h.html#adc955dfab007624000695c48d4f876dc">Pa_GetDefaultOutputDevice()</a>. Default Devices for each Host API are stored in the Host API's <a class="el" href="structPaHostApiInfo.html">PaHostApiInfo</a> structures.</p>
<p>For an example of enumerating devices and printing information about their capabilities see the <a class="el" href="pa__devs_8c.html" title="List available devices, including device information. ">pa_devs.c</a> program in the test directory of the PortAudio distribution.</p>
<h1><a class="anchor" id="streams"></a>
Streams</h1>
<p>A Stream represents an active flow of audio data between your application and one or more audio Devices. A Stream operates at a specific sample rate with specific sample formats and buffer sizes.</p>
<h2><a class="anchor" id="io_methods"></a>
I/O Methods: callback and read/write</h2>
<p>PortAudio offers two methods for communicating audio data between an open Stream and your Application: (1) an asynchronous callback interface, where PortAudio calls a user defined callback function when new audio data is available or required, and (2) synchronous read and write functions which can be used in a blocking or non-blocking manner. You choose between the two methods when you open a Stream. The two methods are discussed in more detail below.</p>
<h2><a class="anchor" id="opening_and_closing_streams"></a>
Opening and Closing Streams</h2>
<p>You call <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> to open a Stream, specifying the Device(s) to use, the number of input and output channels, sample formats, suggested latency values and flags that control dithering, clipping and overflow handling. You specify many of these parameters in two <a class="el" href="structPaStreamParameters.html">PaStreamParameters</a> structures, one for input and one for output. If you're using the callback I/O method you also pass a callback buffer size, callback function pointer and user data pointer.</p>
<p>Devices may be full duplex (supporting simultaneous input and output) or half duplex (supporting input or output) – usually this reflects the structure of the underlying native audio API. When opening a Stream you can specify one full duplex Device for both input and output, or two different Devices for input and output. Some Host APIs only support full-duplex operation with a full-duplex device (e.g. ASIO) but most are able to aggregate two half duplex devices into a full duplex Stream. PortAudio requires that all devices specified in a call to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> belong to the same Host API.</p>
<p>A successful call to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> creates a pointer to a <a class="el" href="portaudio_8h.html#a19874734f89958fccf86785490d53b4c">PaStream</a> – an opaque handle representing the open Stream. All PortAudio API functions that operate on open Streams take a pointer to a <a class="el" href="portaudio_8h.html#a19874734f89958fccf86785490d53b4c">PaStream</a> as their first parameter.</p>
<p>PortAudio also provides <a class="el" href="portaudio_8h.html#a0a12735ac191200f696a43b87667b714">Pa_OpenDefaultStream()</a> – a simpler alternative to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> which you can use when you want to open the default audio Device(s) with default latency parameters.</p>
<p>You call <a class="el" href="portaudio_8h.html#a92f56f88cbd14da0e8e03077e835d104">Pa_CloseStream()</a> to close a Stream when you've finished using it.</p>
<h2><a class="anchor" id="starting_and_stopping_streams"></a>
Starting and Stopping Streams</h2>
<p>Newly opened Streams are initially stopped. You call <a class="el" href="portaudio_8h.html#a7432aadd26c40452da12fa99fc1a047b">Pa_StartStream()</a> to start a Stream. You can stop a running Stream using <a class="el" href="portaudio_8h.html#af18dd60220251286c337631a855e38a0">Pa_StopStream()</a> or <a class="el" href="portaudio_8h.html#a138e57abde4e833c457b64895f638a25">Pa_AbortStream()</a> (the Stop function plays out all internally queued audio data, while Abort tries to stop as quickly as possible). An open Stream can be started and stopped multiple times. You can call <a class="el" href="portaudio_8h.html#a52d778c985ae9d566de7e13529cc771f">Pa_IsStreamStopped()</a> to query whether a Stream is running or stopped.</p>
<p>By calling <a class="el" href="portaudio_8h.html#aa11e7b06b2cde8621551f5d527965838">Pa_SetStreamFinishedCallback()</a> it is possible to register a special <a class="el" href="portaudio_8h.html#ab2530ee0cb756c67726f9074d3482ef2">PaStreamFinishedCallback</a> that will be called when the Stream has completed playing any internally queued buffers. This can be used in conjunction with the <a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32aa01800db52ead393d8b0016f63d76650">paComplete</a> stream callback return value (see below) to avoid blocking on a call to <a class="el" href="portaudio_8h.html#af18dd60220251286c337631a855e38a0">Pa_StopStream()</a> while queued audio data is still playing.</p>
<h2><a class="anchor" id="callback_io_method"></a>
The Callback I/O Method</h2>
<p>So-called 'callback Streams' operate by periodically invoking a callback function you supply to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a>. The callback function must implement the <a class="el" href="portaudio_8h.html#a8a60fb2a5ec9cbade3f54a9c978e2710">PaStreamCallback</a> signature. It gets called by PortAudio every time PortAudio needs your application to consume or produce audio data. The callback is passed pointers to buffers containing the audio to process. The format (interleave, sample data type) and size of these buffers is determined by the parameters passed to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> when the Stream was opened.</p>
<p>Stream callbacks usually return <a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32acba49cbf0e3bf605bb3deecef3b4fce3">paContinue</a> to indicate that PortAudio should keep the stream running. It is possible to deactivate a Stream from the stream callback by returning either <a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32aa01800db52ead393d8b0016f63d76650">paComplete</a> or <a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32acaf141eb5d71420ffb4474da1dbd8de2">paAbort</a>. In this case the Stream enters a deactivated state after the last buffer has finished playing (<a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32aa01800db52ead393d8b0016f63d76650">paComplete</a>) or as soon as possible (<a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32acaf141eb5d71420ffb4474da1dbd8de2">paAbort</a>). You can detect the deactivated state by calling <a class="el" href="portaudio_8h.html#a1f8709c4971932643681a6f374c4bb5a">Pa_IsStreamActive()</a> or by using <a class="el" href="portaudio_8h.html#aa11e7b06b2cde8621551f5d527965838">Pa_SetStreamFinishedCallback()</a> to subscribe to a stream finished notification. Note that even if the stream callback returns <a class="el" href="portaudio_8h.html#ae9bfb9c4e1895326f30f80d415c66c32aa01800db52ead393d8b0016f63d76650">paComplete</a> it's still necessary to call <a class="el" href="portaudio_8h.html#af18dd60220251286c337631a855e38a0">Pa_StopStream()</a> or <a class="el" href="portaudio_8h.html#a138e57abde4e833c457b64895f638a25">Pa_AbortStream()</a> to enter the stopped state.</p>
<p>Many of the tests in the /tests directory of the PortAudio distribution implement PortAudio stream callbacks. For example see: patest_sine.c (audio output), patest_record.c (audio input), patest_wire.c (audio pass-through) and <a class="el" href="pa__fuzz_8c.html" title="Distort input like a fuzz box. ">pa_fuzz.c</a> (simple audio effects processing).</p>
<p><b>IMPORTANT:</b> The stream callback function often needs to operate with very high or real-time priority. As a result there are strict requirements placed on the type of code that can be executed in a stream callback. In general this means avoiding any code that might block, including: acquiring locks, calling OS API functions including allocating memory. With the exception of <a class="el" href="portaudio_8h.html#a83b8c624464dd7bb6a01b06ab596c115">Pa_GetStreamCpuLoad()</a> you may not call PortAudio API functions from within the stream callback.</p>
<h2><a class="anchor" id="read_write_io_method"></a>
The Read/Write I/O Method</h2>
<p>As an alternative to the callback I/O method, PortAudio provides a synchronous read/write interface for acquiring and playing audio. This can be useful for applications that don't require the lowest possibly latency, or don't warrant the increased complexity of synchronising with an asynchronous callback funciton. This I/O method is also useful when calling PortAudio from programming languages that don't support asynchronous callbacks.</p>
<p>To open a Stream in read/write mode you pass a NULL stream callback function pointer to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a>.</p>
<p>To write audio data to a Stream call <a class="el" href="portaudio_8h.html#a075a6efb503a728213bdae24347ed27d">Pa_WriteStream()</a> and to read data call <a class="el" href="portaudio_8h.html#a0b62d4b74b5d3d88368e9e4c0b8b2dc7">Pa_ReadStream()</a>. These functions will block if the internal buffers are full, making them safe to call in a tight loop. If you want to avoid blocking you can query the amount of available read or write space using <a class="el" href="portaudio_8h.html#ad04c33f045fa58d7b705b56b1fd3e816">Pa_GetStreamReadAvailable()</a> or <a class="el" href="portaudio_8h.html#a25595acf48733ec32045aa189c3caa61">Pa_GetStreamWriteAvailable()</a> and use the returned values to limit the amount of data you read or write.</p>
<p>For examples of the read/write I/O method see the following examples in the /tests directory of the PortAudio distribution: patest_read_record.c (audio input), patest_write_sine.c (audio output), patest_read_write_wire.c (audio pass-through).</p>
<h2><a class="anchor" id="stream_info"></a>
Retrieving Stream Information</h2>
<p>You can retrieve information about an open Stream by calling <a class="el" href="portaudio_8h.html#a3d9c4cbda4e9f381b76f287c3de8a758">Pa_GetStreamInfo()</a>. This returns a <a class="el" href="structPaStreamInfo.html">PaStreamInfo</a> structure containing the actual input and output latency and sample rate of the stream. It's possible for these values to be different from the suggested values passed to <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a>.</p>
<p>When using a callback stream you can call <a class="el" href="portaudio_8h.html#a83b8c624464dd7bb6a01b06ab596c115">Pa_GetStreamCpuLoad()</a> to retrieve a rough estimate of the amount of CPU time your callback function is using.</p>
<h2><a class="anchor" id="stream_timing"></a>
Stream Timing Information</h2>
<p>When using the callback I/O method your stream callback function receives timing information via a pointer to a <a class="el" href="structPaStreamCallbackTimeInfo.html">PaStreamCallbackTimeInfo</a> structure. This structure contains the current time along with the estimated hardware capture and playback time of the first sample of the input and output buffers. All times are measured in seconds relative to a Stream-specific clock. The current Stream clock time can be retrieved using <a class="el" href="portaudio_8h.html#a2b3fb60e6949f37f7f134105ff425749">Pa_GetStreamTime()</a>.</p>
<p>You can use the stream callback <a class="el" href="structPaStreamCallbackTimeInfo.html">PaStreamCallbackTimeInfo</a> times in conjunction with timestamps returned by <a class="el" href="portaudio_8h.html#a2b3fb60e6949f37f7f134105ff425749">Pa_GetStreamTime()</a> to implement time synchronization schemes such as time aligning your GUI display with rendered audio, or maintaining synchronization between MIDI and audio playback.</p>
<h1><a class="anchor" id="error_handling"></a>
Error Handling</h1>
<p>Most PortAudio functions return error codes using values from the <a class="el" href="portaudio_8h.html#a4949e4a8ef9f9dbe8cbee414ce69841d">PaError</a> enumeration. All error codes are negative values. Some functions return values greater than or equal to zero for normal results and a negative error code in case of error.</p>
<p>You can convert <a class="el" href="portaudio_8h.html#a4949e4a8ef9f9dbe8cbee414ce69841d">PaError</a> error codes to human readable text by calling <a class="el" href="portaudio_8h.html#ae606855a611cf29c7d2d7421df5e3b5d">Pa_GetErrorText()</a>.</p>
<p>PortAudio usually tries to translate error conditions into portable <a class="el" href="portaudio_8h.html#a4949e4a8ef9f9dbe8cbee414ce69841d">PaError</a> error codes. However if an unexpected error is encountered the paUnanticipatedHostError code may be returned. In this case a further mechanism is provided to query for Host API-specific error information. If PortAudio returns paUnanticipatedHostError you can call <a class="el" href="portaudio_8h.html#aad573f208b60577f21d2777a7c5054e0">Pa_GetLastHostErrorInfo()</a> to retrieve a pointer to a <a class="el" href="structPaHostErrorInfo.html">PaHostErrorInfo</a> structure that provides more information, including the Host API that encountered the error, a native API error code and error text.</p>
<h1><a class="anchor" id="host_api_extensions"></a>
Host API and Platform-specific Extensions</h1>
<p>The public PortAudio API only exposes functionality that can be provided across all target platforms. In some cases individual native audio APIs offer unique functionality. Some PortAudio Host APIs expose this functionality via Host API-specific extensions. Examples include access to low-level buffering and priority parameters, opening a Stream with only a subset of a Device's channels, or accessing channel metadata such as channel names.</p>
<p>Host API-specific extensions are provided in the form of additional functions and data structures defined in Host API-specific header files found in the /include directory.</p>
<p>The <a class="el" href="structPaStreamParameters.html">PaStreamParameters</a> structure passed to <a class="el" href="portaudio_8h.html#abdb313743d6efef26cecdae787a2bd3d">Pa_IsFormatSupported()</a> and <a class="el" href="portaudio_8h.html#a443ad16338191af364e3be988014cbbe">Pa_OpenStream()</a> has a field named <a class="el" href="structPaStreamParameters.html#aff01b9fa0710ad1654471e97665c06a9">PaStreamParameters::hostApiSpecificStreamInfo</a> that is sometimes used to pass low level information when opening a Stream.</p>
<p>See the documentation for the individual Host API-specific header files for details of the extended functionality they expose:</p>
<ul>
<li><a class="el" href="pa__asio_8h.html" title="ASIO-specific PortAudio API extension header file. ">pa_asio.h</a></li>
<li><a class="el" href="pa__jack_8h.html" title="JACK-specific PortAudio API extension header file. ">pa_jack.h</a></li>
<li><a class="el" href="pa__linux__alsa_8h.html" title="ALSA-specific PortAudio API extension header file. ">pa_linux_alsa.h</a></li>
<li><a class="el" href="pa__mac__core_8h.html" title="CoreAudio-specific PortAudio API extension header file. ">pa_mac_core.h</a></li>
<li><a class="el" href="pa__win__ds_8h.html" title="DirectSound-specific PortAudio API extension header file. ">pa_win_ds.h</a></li>
<li><a class="el" href="pa__win__wasapi_8h.html" title="WASAPI-specific PortAudio API extension header file. ">pa_win_wasapi.h</a></li>
<li><a class="el" href="pa__win__wmme_8h.html" title="WMME-specific PortAudio API extension header file. ">pa_win_wmme.h</a></li>
<li><a class="el" href="pa__win__waveformat_8h.html" title="Windows specific PortAudio API extension and utilities header file. ">pa_win_waveformat.h</a> </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Tue Feb 25 2014 21:08:45 for PortAudio by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
|