audacity/lib-src/portaudio/docs/pa_tut_callback.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet  (Win98; U) [Netscape]">
   <meta name="Author" content="Phil Burk">
   <meta name="Description" content="Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function.">
   <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,">
   <title>PortAudio Tutorial</title>
</head>
<body>
&nbsp;
<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" >
<tr>
<td>
<center>
<h1>
PortAudio Tutorial</h1></center>
</td>
</tr>
</table></center>

<h2>
Writing a Callback Function</h2>

<blockquote>To write a program using PortAudio, you must include the "portaudio.h"
include file. You may wish to read "<a href="portaudio_h.txt">portaudio.h</a>"
because it contains a complete description of the PortAudio functions and
constants.
<blockquote>
<pre>#include "portaudio.h"</pre>
</blockquote>
The next task is to write your custom callback function. It 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>Your callback function is often called by an interrupt, or low level
process so you should not do any complex system activities like allocating
memory, or reading or writing files, or printf(). Just crunch numbers and
generate audio signals. What is safe or not safe will vary from platform
to platform. On the Macintosh, for example, you can only call "interrupt
safe" routines. Also do not call any PortAudio functions in the callback
except for Pa_StreamTime() and Pa_GetCPULoad().
<p>Your callback function must return an int and accept the exact parameters
specified in this typedef:
<blockquote>
<pre>typedef int (PortAudioCallback)(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *inputBuffer, void *outputBuffer,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long framesPerBuffer,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; PaTimestamp outTime, void *userData );</pre>
</blockquote>
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 <tt>float</tt>
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. You
can pass a pointer to your data structure through PortAudio which will
appear as <tt>userData</tt>.
<blockquote>
<pre>int patestCallback(&nbsp; void *inputBuffer, void *outputBuffer,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long framesPerBuffer,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; PaTimestamp outTime, void *userData )
{
&nbsp;&nbsp;&nbsp; unsigned int i;
/* Cast data passed through stream to our structure type. */
&nbsp;&nbsp;&nbsp; paTestData *data = (paTestData*)userData;
&nbsp;&nbsp;&nbsp; float *out = (float*)outputBuffer;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; for( i=0; i&lt;framesPerBuffer; i++ )
&nbsp;&nbsp;&nbsp; {
&nbsp;&nbsp;&nbsp; /* Stereo channels are interleaved. */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; *out++ = data->left_phase;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* left */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; *out++ = data->right_phase;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* right */

&nbsp;&nbsp;&nbsp; /* Generate simple sawtooth phaser that ranges between -1.0 and 1.0. */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; data->left_phase += 0.01f;
&nbsp;&nbsp;&nbsp; /* When signal reaches top, drop back down. */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if( data->left_phase >= 1.0f ) data->left_phase -= 2.0f;

&nbsp;&nbsp;&nbsp; /* higher pitch so we can distinguish left and right. */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; data->right_phase += 0.03f;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if( data->right_phase >= 1.0f ) data->right_phase -= 2.0f;
&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; return 0;
}</pre>
</blockquote>
</blockquote>
<font size=+2><a href="http://www.portaudio.com/">home</a> |
<a href="pa_tutorial.html">contents</a>
| <a href="pa_tut_over.html">previous</a> |&nbsp; <a href="pa_tut_init.html">next</a></font>
</body>
</html>