/usr/share/doc/portaudio19-doc/doc/html/writing_a_callback.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 | <!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: Writing a Callback Function</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">Writing a Callback Function </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>To write a program using PortAudio, you must include the "portaudio.h" include file. You may wish to read "portaudio.h" because it contains a complete description of the PortAudio functions and constants. Alternatively, you could browse the [<a href="http://www.portaudio.com/docs/v19-doxydocs/portaudio_8h.html">http://www.portaudio.com/docs/v19-doxydocs/portaudio_8h.html</a> "portaudio.h" Doxygen page] </p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="portaudio_8h.html">portaudio.h</a>"</span></div>
</div><!-- fragment --><p> The next task is to write your own "callback" function. The "callback" is a function that is called by the PortAudio engine whenever it has captured audio data, or when it needs more audio data for output.</p>
<p>Before we begin, it's important to realize that the callback is a delicate place. This is because some systems perform the callback in a special thread, or interrupt handler, and it is rarely treated the same as the rest of your code. In addition, if you want your audio to reach the speakers on time, you'll need to make sure whatever code you run in the callback runs quickly. What is safe or not safe will vary from platform to platform, but as a rule of thumb, don't do anything like allocating or freeing memory, reading or writing files, printf(), or anything else that might take an unbounded amount of time or rely on the OS or require a context switch. <em>Ed: is this still true?: Also do not call any PortAudio functions in the callback except for Pa_StreamTime() and Pa_GetCPULoad().</em></p>
<p>Your callback function must return an int and accept the exact parameters specified in this typedef:</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keywordtype">int</span> <a class="code" href="portaudio_8h.html#a8a60fb2a5ec9cbade3f54a9c978e2710">PaStreamCallback</a>( <span class="keyword">const</span> <span class="keywordtype">void</span> *input,</div>
<div class="line"> <span class="keywordtype">void</span> *output,</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> frameCount,</div>
<div class="line"> <span class="keyword">const</span> <a class="code" href="structPaStreamCallbackTimeInfo.html">PaStreamCallbackTimeInfo</a>* timeInfo,</div>
<div class="line"> <a class="code" href="portaudio_8h.html#a55a005924bcfa0424594f4f65cd4ae82">PaStreamCallbackFlags</a> statusFlags,</div>
<div class="line"> <span class="keywordtype">void</span> *userData ) ;</div>
</div><!-- fragment --><p> Here is an example callback function from the test file "patests/patest_saw.c". It calculates a simple left and right sawtooth signal and writes it to the output buffer. Notice that in this example, the signals are of float data type. The signals must be between -1.0 and +1.0. You can also use 16 bit integers or other formats which are specified during setup, but floats are easiest to work with. You can pass a pointer to your data structure through PortAudio which will appear as userData.</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span></div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">float</span> left_phase;</div>
<div class="line"> <span class="keywordtype">float</span> right_phase;</div>
<div class="line">} </div>
<div class="line"><a class="code" href="structpaTestData.html">paTestData</a>;</div>
<div class="line"></div>
<div class="line"><span class="comment">/* This routine will be called by the PortAudio engine when audio is needed.</span></div>
<div class="line"><span class="comment"> * It may called at interrupt level on some machines so don't do anything</span></div>
<div class="line"><span class="comment"> * that could mess up the system like calling malloc() or free().</span></div>
<div class="line"><span class="comment">*/</span> </div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">int</span> patestCallback( <span class="keyword">const</span> <span class="keywordtype">void</span> *inputBuffer, <span class="keywordtype">void</span> *outputBuffer,</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> framesPerBuffer,</div>
<div class="line"> <span class="keyword">const</span> <a class="code" href="structPaStreamCallbackTimeInfo.html">PaStreamCallbackTimeInfo</a>* timeInfo,</div>
<div class="line"> <a class="code" href="portaudio_8h.html#a55a005924bcfa0424594f4f65cd4ae82">PaStreamCallbackFlags</a> statusFlags,</div>
<div class="line"> <span class="keywordtype">void</span> *userData )</div>
<div class="line">{</div>
<div class="line"> <span class="comment">/* Cast data passed through stream to our structure. */</span></div>
<div class="line"> <a class="code" href="structpaTestData.html">paTestData</a> *data = (<a class="code" href="structpaTestData.html">paTestData</a>*)userData; </div>
<div class="line"> <span class="keywordtype">float</span> *out = (<span class="keywordtype">float</span>*)outputBuffer;</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i;</div>
<div class="line"> (void) inputBuffer; <span class="comment">/* Prevent unused variable warning. */</span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">for</span>( i=0; i<framesPerBuffer; i++ )</div>
<div class="line"> {</div>
<div class="line"> out++ = data->left_phase; <span class="comment">/* left */</span></div>
<div class="line"> out++ = data->right_phase; <span class="comment">/* right */</span></div>
<div class="line"> <span class="comment">/* Generate simple sawtooth phaser that ranges between -1.0 and 1.0. */</span></div>
<div class="line"> data->left_phase += 0.01f;</div>
<div class="line"> <span class="comment">/* When signal reaches top, drop back down. */</span></div>
<div class="line"> <span class="keywordflow">if</span>( data->left_phase >= 1.0f ) data->left_phase -= 2.0f;</div>
<div class="line"> <span class="comment">/* higher pitch so we can distinguish left and right. */</span></div>
<div class="line"> data->right_phase += 0.03f;</div>
<div class="line"> <span class="keywordflow">if</span>( data->right_phase >= 1.0f ) data->right_phase -= 2.0f;</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><p>Previous: <a class="el" href="tutorial_start.html">PortAudio Tutorials</a> | Next: <a class="el" href="initializing_portaudio.html">Initializing PortAudio</a> </p>
</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>
|