utils/iaxclient/lib/portaudio/docs/pa_impl_guide.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.79 [en] (Windows NT 5.0; U) [Netscape]">
   6    <meta name="Author" content="Phil Burk">
   7    <meta name="Description" content="Internal docs. How a stream is started or stopped.">
   8    <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,">
   9    <title>PortAudio Implementation - Start/Stop</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 <a href="http://www.portaudio.com">PortAudio</a> Implementation Guide</h1></center>
  19 </td>
  20 </tr>
  21 </table></center>
  22
  23 <p>This document describes how to implement the PortAudio API on a new
  24 computer platform. Implementing PortAudio on a new platform, makes it possible
  25 to port many existing audio applications to that platform.
  26 <p>By Phil Burk
  27 <br>Copyright 2000 Phil Burk and Ross Bencina
  28 <p>Note that the license says: <b>"Any person wishing to distribute modifications
  29 to the Software is requested to send the modifications to the original
  30 developer so that they can be incorporated into the canonical version."</b>.
  31 So when you have finished a new implementation, please send it back to
  32 us at&nbsp; "<a href="http://www.portaudio.com">http://www.portaudio.com</a>"
  33 so that we can make it available for other users. Thank you!
  34 <h2>
  35 Download the Latest PortAudio Implementation</h2>
  36 Always start with the latest implementation available at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>".
  37 Look for the nightly snapshot under the CVS section.
  38 <h2>
  39 Select an Existing Implementation as a Basis</h2>
  40 The fastest way to get started is to take an existing implementation and
  41 translate it for your new platform. Choose an implementation whose architecture
  42 is as close as possible to your target.
  43 <ul>
  44 <li>
  45 DirectSound Implementation - pa_win_ds - Uses a timer callback for the
  46 background "thread". Polls a circular buffer and writes blocks of data
  47 to keep it full.</li>
  48
  49 <li>
  50 Windows MME - pa_win_wmme - Spawns an actual Win32 thread. Writes blocks
  51 of data to the HW device and waits for events that signal buffer completion.</li>
  52
  53 <li>
  54 Linux OSS - pa_linux - Spawns a real thread that writes to the "/dev/dsp"
  55 stream using blocking I/O calls.</li>
  56 </ul>
  57 When you write a new implementation, you will be using some code that is
  58 in common with all implementations. This code is in the folder "pa_common".
  59 It provides various functions such as parameter checking, error code to
  60 text conversion, sample format conversion, clipping and dithering, etc.
  61 <p>The code that you write will go into a separate folder called "pa_{os}_{api}".
  62 For example, code specific to the DirectSound interface for Windows goes
  63 in "pa_win_ds".
  64 <h2>
  65 Read Docs and Code</h2>
  66 Famialiarize yourself with the system by reading the documentation provided.
  67 here is a suggested order:
  68 <ol>
  69 <li>
  70 User Programming <a href="pa_tutorial.html">Tutorial</a></li>
  71
  72 <li>
  73 Header file "pa_common/portaudio.h" which defines API.</li>
  74
  75 <li>
  76 Header file "pa_common/pa_host.h" for host dependant code. This definces
  77 the routine you will need to provide.</li>
  78
  79 <li>
  80 Shared code in "pa_common/pa_lib.c".</li>
  81
  82 <li>
  83 Docs on Implementation of <a href="pa_impl_startstop.html">Start/Stop</a>
  84 code.</li>
  85 </ol>
  86
  87 <h2>
  88 Implement&nbsp; Output to Default Device</h2>
  89 Now we are ready to crank some code. For instant gratification, let's try
  90 to play a sine wave.
  91 <ol>
  92 <li>
  93 Link the test program "pa_tests/patest_sine.c" with the file "pa_lib.c"
  94 and the implementation specific file you are creating.</li>
  95
  96 <li>
  97 For now, just stub out the device query code and the audio input code.</li>
  98
  99 <li>
 100 Modify PaHost_OpenStream() to open your default target device and get everything
 101 setup.</li>
 102
 103 <li>
 104 Modify PaHost_StartOutput() to start playing audio.</li>
 105
 106 <li>
 107 Modify PaHost_StopOutput() to stop audio.</li>
 108
 109 <li>
 110 Modify PaHost_CloseStream() to clean up. Free all memory that you allocated
 111 in PaHost_OpenStream().</li>
 112
 113 <li>
 114 Keep cranking until you can play a sine wave using "patest_sine.c".</li>
 115
 116 <li>
 117 Once that works, try "patest_pink.c", "patest_clip.c", "patest_sine8.c".</li>
 118
 119 <li>
 120 To test your Open and Close code, try "patest_many.c".</li>
 121
 122 <li>
 123 Now test to make sure that the three modes of stopping are properly supported
 124 by running "patest_stop.c".</li>
 125
 126 <li>
 127 Test your implementation of time stamping with "patest_sync.c".</li>
 128 </ol>
 129
 130 <h2>
 131 Implement Device Queries</h2>
 132 Now that output is working, lets implement the code for querying what devices
 133 are available to the user. Run "pa_tests/pa_devs.c". It should print all
 134 of the devices available and their characteristics.
 135 <h2>
 136 Implement Input</h2>
 137 Implement audio input and test it with:
 138 <ol>
 139 <li>
 140 patest_record.c - record in half duplex, play back as recorded.</li>
 141
 142 <li>
 143 patest_wire.c - full duplex, copies input to output. Note that some HW
 144 may not support full duplex.</li>
 145
 146 <li>
 147 patest_fuzz.c - plug in your guitar and get a feel for why latency is an
 148 important issue in computer music.</li>
 149
 150 <li>
 151 paqa_devs.c - try to open every device and use it with every possible format</li>
 152 </ol>
 153
 154 <h2>
 155 Debugging Tools</h2>
 156 You generally cannot use printf() calls to debug real-time processes because
 157 they disturb the timing. Also calling printf() from your background thread
 158 or interrupt could crash the machine. So PA includes a tool for capturing
 159 events and storing the information while it is running. It then prints
 160 the events when Pa_Terminate() is called.
 161 <ol>
 162 <li>
 163 To enable trace mode, change TRACE_REALTIME_EVENTS in "pa_common/pa_trace.h"
 164 from a (0) to a (1).</li>
 165
 166 <li>
 167 Link with "pa_common/pa_trace.c".</li>
 168
 169 <li>
 170 Add trace messages to your code by calling:</li>
 171
 172 <br><tt>&nbsp;&nbsp; void AddTraceMessage( char *msg, int data );</tt>
 173 <br><tt>for example</tt>
 174 <br><tt>&nbsp;&nbsp; AddTraceMessage("Pa_TimeSlice: past_NumCallbacks ",
 175 past->past_NumCallbacks );</tt>
 176 <li>
 177 Run your program. You will get a dump of events at the end.</li>
 178
 179 <li>
 180 You can leave the trace messages in your code. They will turn to NOOPs
 181 when you change TRACE_REALTIME_EVENTS back to (0).</li>
 182 </ol>
 183
 184 <h2>
 185 Delivery</h2>
 186 Please send your new code along with notes on the implementation back to
 187 us at "<a href="http://www.portaudio.com">http://www.portaudio.com</a>".
 188 We will review the implementation and post it with your name. If you had
 189 to make any modifications to the code in "pa_common" or "pa_tests" <b>please</b>
 190 send us those modifications and your notes. We will try to merge your changes
 191 so that the "pa_common" code works with <b>all</b> implementations.
 192 <p>If you have suggestions for how to make future implementations easier,
 193 please let us know.
 194 <br>THANKS!
 195 <br>&nbsp;
 196 </body>
 197 </html>