aboutsummaryrefslogtreecommitdiff
path: root/pd/portaudio/docs/pa_impl_startstop.html
blob: 0f2d0ce516f28b350e3c704e76ddae84612d6916 (plain)
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
<!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.75 [en]C-gatewaynet  (Win98; U) [Netscape]">
   <meta name="Author" content="Phil Burk">
   <meta name="Description" content="Internal docs. How a stream is started or stopped.">
   <meta name="KeyWords" content="audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,">
   <title>PortAudio Implementation - Start/Stop</title>
</head>
<body>
&nbsp;
<center><table COLS=1 WIDTH="100%" BGCOLOR="#FADA7A" >
<tr>
<td>
<center>
<h1>
PortAudio Implementation</h1></center>
</td>
</tr>
</table></center>

<h2>
Starting and Stopping Streams</h2>
PortAudio is generally executed in two "threads". The foreground thread
is the application thread. The background "thread" may be implemented as
an actual thread, an interrupt handler, or a callback from a timer thread.
<p>There are three ways that PortAudio can stop a stream. In each case
we look at the sequence of events and the messages sent between the two
threads. The following variables are contained in the internalPortAudioStream.
<blockquote><tt>int&nbsp;&nbsp; past_IsActive;&nbsp;&nbsp;&nbsp;&nbsp;
/* Background is still playing. */</tt>
<br><tt>int&nbsp;&nbsp; past_StopSoon;&nbsp;&nbsp;&nbsp;&nbsp; /* Stop
when last buffer done. */</tt>
<br><tt>int&nbsp;&nbsp; past_StopNow;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /*
Stop IMMEDIATELY. */</tt></blockquote>

<h3>
Pa_AbortStream()</h3>
This function causes the background thread to terminate as soon as possible
and audio I/O to stop abruptly.
<br>&nbsp;
<table BORDER COLS=2 WIDTH="60%" >
<tr>
<td><b>Foreground Thread</b></td>

<td><b>Background Thread</b></td>
</tr>

<tr>
<td>sets <tt>StopNow</tt></td>

<td></td>
</tr>

<tr>
<td></td>

<td>sees <tt>StopNow</tt>,&nbsp;</td>
</tr>

<tr>
<td></td>

<td>clears IsActive, stops thread</td>
</tr>

<tr>
<td>waits for thread to exit</td>

<td></td>
</tr>

<tr>
<td>turns off audio I/O</td>

<td></td>
</tr>
</table>

<h3>
Pa_StopStream()</h3>
This function stops the user callback function from being called and then
waits for all audio data written to the output buffer to be played. In
a system with very low latency, you may not hear any difference between
<br>&nbsp;
<table BORDER COLS=2 WIDTH="60%" >
<tr>
<td><b>Foreground Thread</b></td>

<td><b>Background Thread</b></td>
</tr>

<tr>
<td>sets StopSoon</td>

<td></td>
</tr>

<tr>
<td></td>

<td>stops calling user callback</td>
</tr>

<tr>
<td></td>

<td>continues until output buffer empty</td>
</tr>

<tr>
<td></td>

<td>clears IsActive, stops thread</td>
</tr>

<tr>
<td>waits for thread to exit</td>

<td></td>
</tr>

<tr>
<td>turns off audio I/O</td>

<td></td>
</tr>
</table>

<h3>
User callback returns one.</h3>
If the user callback returns one then the user callback function will no
longer be called. Audio output will continue until all audio data written
to the output buffer has been played. Then the audio I/O is stopped, the
background thread terminates, and the stream becomes inactive.
<br>&nbsp;
<table BORDER COLS=2 WIDTH="60%" >
<tr>
<td><b>Foreground Thread</b></td>

<td><b>Background Thread</b></td>
</tr>

<tr>
<td></td>

<td>callback returns 1</td>
</tr>

<tr>
<td></td>

<td>sets StopSoon</td>
</tr>

<tr>
<td></td>

<td>stops calling user callback</td>
</tr>

<tr>
<td></td>

<td>continues until output buffer empty</td>
</tr>

<tr>
<td></td>

<td>clears IsActive, stops thread</td>
</tr>

<tr>
<td>waits for thread to exit</td>

<td></td>
</tr>

<tr>
<td>turns off audio I/O</td>

<td></td>
</tr>
</table>

<br>&nbsp;
</body>
</html>