3rdparty/iaxclient/lib/portaudio/docs/pa_tut_callback.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="GENERATOR" content="Mozilla/4.77 [en]C-gatewaynet  (Win98; U) [Netscape]">
   6    <meta name="Author" content="Phil Burk">
   7    <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.">
   8    <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,">
   9    <title>PortAudio Tutorial</title>
  10 </head>
  11 <body>
  12 &nbsp;
  13 <center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" >
  14 <tr>
  15 <td>
  16 <center>
  17 <h1>
  18 PortAudio Tutorial</h1></center>
  19 </td>
  20 </tr>
  21 </table></center>
  22
  23 <h2>
  24 Writing a Callback Function</h2>
  25
  26 <blockquote>To write a program using PortAudio, you must include the "portaudio.h"
  27 include file. You may wish to read "<a href="portaudio_h.txt">portaudio.h</a>"
  28 because it contains a complete description of the PortAudio functions and
  29 constants.
  30 <blockquote>
  31 <pre>#include "portaudio.h"</pre>
  32 </blockquote>
  33 The next task is to write your custom callback function. It is a function
  34 that is called by the PortAudio engine whenever it has captured audio data,
  35 or when it needs more audio data for output.
  36 <p>Your callback function is often called by an interrupt, or low level
  37 process so you should not do any complex system activities like allocating
  38 memory, or reading or writing files, or printf(). Just crunch numbers and
  39 generate audio signals. What is safe or not safe will vary from platform
  40 to platform. On the Macintosh, for example, you can only call "interrupt
  41 safe" routines. Also do not call any PortAudio functions in the callback
  42 except for Pa_StreamTime() and Pa_GetCPULoad().
  43 <p>Your callback function must return an int and accept the exact parameters
  44 specified in this typedef:
  45 <blockquote>
  46 <pre>typedef int (PortAudioCallback)(
  47 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *inputBuffer, void *outputBuffer,
  48 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long framesPerBuffer,
  49 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; PaTimestamp outTime, void *userData );</pre>
  50 </blockquote>
  51 Here is an example callback function from the test file "patests/patest_saw.c".
  52 It calculates a simple left and right sawtooth signal and writes it to
  53 the output buffer. Notice that in this example, the signals are of <tt>float</tt>
  54 data type. The signals must be between -1.0 and +1.0. You can also use
  55 16 bit integers or other formats which are specified during setup. You
  56 can pass a pointer to your data structure through PortAudio which will
  57 appear as <tt>userData</tt>.
  58 <blockquote>
  59 <pre>int patestCallback(&nbsp; void *inputBuffer, void *outputBuffer,
  60 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long framesPerBuffer,
  61 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; PaTimestamp outTime, void *userData )
  62 {
  63 &nbsp;&nbsp;&nbsp; unsigned int i;
  64 /* Cast data passed through stream to our structure type. */
  65 &nbsp;&nbsp;&nbsp; paTestData *data = (paTestData*)userData;
  66 &nbsp;&nbsp;&nbsp; float *out = (float*)outputBuffer;
  67 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  68 &nbsp;&nbsp;&nbsp; for( i=0; i&lt;framesPerBuffer; i++ )
  69 &nbsp;&nbsp;&nbsp; {
  70 &nbsp;&nbsp;&nbsp; /* Stereo channels are interleaved. */
  71 &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 */
  72 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; *out++ = data->right_phase;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* right */
  73
  74 &nbsp;&nbsp;&nbsp; /* Generate simple sawtooth phaser that ranges between -1.0 and 1.0. */
  75 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; data->left_phase += 0.01f;
  76 &nbsp;&nbsp;&nbsp; /* When signal reaches top, drop back down. */
  77 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if( data->left_phase >= 1.0f ) data->left_phase -= 2.0f;
  78
  79 &nbsp;&nbsp;&nbsp; /* higher pitch so we can distinguish left and right. */
  80 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; data->right_phase += 0.03f;&nbsp;
  81 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if( data->right_phase >= 1.0f ) data->right_phase -= 2.0f;
  82 &nbsp;&nbsp;&nbsp; }
  83 &nbsp;&nbsp;&nbsp; return 0;
  84 }</pre>
  85 </blockquote>
  86 </blockquote>
  87 <font size=+2><a href="http://www.portaudio.com/">home</a> |
  88 <a href="pa_tutorial.html">contents</a>
  89 | <a href="pa_tut_over.html">previous</a> |&nbsp; <a href="pa_tut_init.html">next</a></font>
  90 </body>
  91 </html>