/[pcsx2_0.9.7]/trunk/3rdparty/portaudio/src/common/pa_process.h
ViewVC logotype

Contents of /trunk/3rdparty/portaudio/src/common/pa_process.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 273 - (show annotations) (download)
Fri Nov 12 01:10:22 2010 UTC (9 years, 2 months ago) by william
File MIME type: text/plain
File size: 32058 byte(s)
Auto Commited Import of: pcsx2-0.9.7-DEBUG (upstream: v0.9.7.4013 local: v0.9.7.197-latest) in ./trunk
1 #ifndef PA_PROCESS_H
2 #define PA_PROCESS_H
3 /*
4 * $Id: pa_process.h 1523 2010-07-10 17:41:25Z dmitrykos $
5 * Portable Audio I/O Library callback buffer processing adapters
6 *
7 * Based on the Open Source API proposed by Ross Bencina
8 * Copyright (c) 1999-2002 Phil Burk, Ross Bencina
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining
11 * a copy of this software and associated documentation files
12 * (the "Software"), to deal in the Software without restriction,
13 * including without limitation the rights to use, copy, modify, merge,
14 * publish, distribute, sublicense, and/or sell copies of the Software,
15 * and to permit persons to whom the Software is furnished to do so,
16 * subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be
19 * included in all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
25 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
26 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
27 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 */
29
30 /*
31 * The text above constitutes the entire PortAudio license; however,
32 * the PortAudio community also makes the following non-binding requests:
33 *
34 * Any person wishing to distribute modifications to the Software is
35 * requested to send the modifications to the original developer so that
36 * they can be incorporated into the canonical version. It is also
37 * requested that these non-binding requests be included along with the
38 * license above.
39 */
40
41 /** @file
42 @ingroup common_src
43
44 @brief Buffer Processor prototypes. A Buffer Processor performs buffer length
45 adaption, coordinates sample format conversion, and interleaves/deinterleaves
46 channels.
47
48 <h3>Overview</h3>
49
50 The "Buffer Processor" (PaUtilBufferProcessor) manages conversion of audio
51 data from host buffers to user buffers and back again. Where required, the
52 buffer processor takes care of converting between host and user sample formats,
53 interleaving and deinterleaving multichannel buffers, and adapting between host
54 and user buffers with different lengths. The buffer processor may be used with
55 full and half duplex streams, for both callback streams and blocking read/write
56 streams.
57
58 One of the important capabilities provided by the buffer processor is
59 the ability to adapt between user and host buffer sizes of different lengths
60 with minimum latency. Although this task is relatively easy to perform when
61 the host buffer size is an integer multiple of the user buffer size, the
62 problem is more complicated when this is not the case - especially for
63 full-duplex callback streams. Where necessary the adaption is implemented by
64 internally buffering some input and/or output data. The buffer adation
65 algorithm used by the buffer processor was originally implemented by
66 Stephan Letz for the ASIO version of PortAudio, and is described in his
67 Callback_adaption_.pdf which is included in the distribution.
68
69 The buffer processor performs sample conversion using the functions provided
70 by pa_converters.c.
71
72 The following sections provide an overview of how to use the buffer processor.
73 Interested readers are advised to consult the host API implementations for
74 examples of buffer processor usage.
75
76
77 <h4>Initialization, resetting and termination</h4>
78
79 When a stream is opened, the buffer processor should be initialized using
80 PaUtil_InitializeBufferProcessor. This function initializes internal state
81 and allocates temporary buffers as neccesary according to the supplied
82 configuration parameters. Some of the parameters correspond to those requested
83 by the user in their call to Pa_OpenStream(), others reflect the requirements
84 of the host API implementation - they indicate host buffer sizes, formats,
85 and the type of buffering which the Host API uses. The buffer processor should
86 be initialized for callback streams and blocking read/write streams.
87
88 Call PaUtil_ResetBufferProcessor to clear any sample data which is present
89 in the buffer processor before starting to use it (for example when
90 Pa_StartStream is called).
91
92 When the buffer processor is no longer used call
93 PaUtil_TerminateBufferProcessor.
94
95
96 <h4>Using the buffer processor for a callback stream</h4>
97
98 The buffer processor's role in a callback stream is to take host input buffers
99 process them with the stream callback, and fill host output buffers. For a
100 full duplex stream, the buffer processor handles input and output simultaneously
101 due to the requirements of the minimum-latency buffer adation algorithm.
102
103 When a host buffer becomes available, the implementation should call
104 the buffer processor to process the buffer. The buffer processor calls the
105 stream callback to consume and/or produce audio data as necessary. The buffer
106 processor will convert sample formats, interleave/deinterleave channels,
107 and slice or chunk the data to the appropriate buffer lengths according to
108 the requirements of the stream callback and the host API.
109
110 To process a host buffer (or a pair of host buffers for a full-duplex stream)
111 use the following calling sequence:
112
113 -# Call PaUtil_BeginBufferProcessing
114 -# For a stream which takes input:
115 - Call PaUtil_SetInputFrameCount with the number of frames in the host input
116 buffer.
117 - Call one of the following functions one or more times to tell the
118 buffer processor about the host input buffer(s): PaUtil_SetInputChannel,
119 PaUtil_SetInterleavedInputChannels, PaUtil_SetNonInterleavedInputChannel.
120 Which function you call will depend on whether the host buffer(s) are
121 interleaved or not.
122 - If the available host data is split accross two buffers (for example a
123 data range at the end of a circular buffer and another range at the
124 beginning of the circular buffer), also call
125 PaUtil_Set2ndInputFrameCount, PaUtil_Set2ndInputChannel,
126 PaUtil_Set2ndInterleavedInputChannels,
127 PaUtil_Set2ndNonInterleavedInputChannel as necessary to tell the buffer
128 processor about the second buffer.
129 -# For a stream which generates output:
130 - Call PaUtil_SetOutputFrameCount with the number of frames in the host
131 output buffer.
132 - Call one of the following functions one or more times to tell the
133 buffer processor about the host output buffer(s): PaUtil_SetOutputChannel,
134 PaUtil_SetInterleavedOutputChannels, PaUtil_SetNonInterleavedOutputChannel.
135 Which function you call will depend on whether the host buffer(s) are
136 interleaved or not.
137 - If the available host output buffer space is split accross two buffers
138 (for example a data range at the end of a circular buffer and another
139 range at the beginning of the circular buffer), call
140 PaUtil_Set2ndOutputFrameCount, PaUtil_Set2ndOutputChannel,
141 PaUtil_Set2ndInterleavedOutputChannels,
142 PaUtil_Set2ndNonInterleavedOutputChannel as necessary to tell the buffer
143 processor about the second buffer.
144 -# Call PaUtil_EndBufferProcessing, this function performs the actual data
145 conversion and processing.
146
147
148 <h4>Using the buffer processor for a blocking read/write stream</h4>
149
150 Blocking read/write streams use the buffer processor to convert and copy user
151 output data to a host buffer, and to convert and copy host input data to
152 the user's buffer. The buffer processor does not perform any buffer adaption.
153 When using the buffer processor in a blocking read/write stream the input and
154 output conversion are performed separately by the PaUtil_CopyInput and
155 PaUtil_CopyOutput functions.
156
157 To copy data from a host input buffer to the buffer(s) which the user supplies
158 to Pa_ReadStream, use the following calling sequence.
159
160 - Repeat the following three steps until the user buffer(s) have been filled
161 with samples from the host input buffers:
162 -# Call PaUtil_SetInputFrameCount with the number of frames in the host
163 input buffer.
164 -# Call one of the following functions one or more times to tell the
165 buffer processor about the host input buffer(s): PaUtil_SetInputChannel,
166 PaUtil_SetInterleavedInputChannels, PaUtil_SetNonInterleavedInputChannel.
167 Which function you call will depend on whether the host buffer(s) are
168 interleaved or not.
169 -# Call PaUtil_CopyInput with the user buffer pointer (or a copy of the
170 array of buffer pointers for a non-interleaved stream) passed to
171 Pa_ReadStream, along with the number of frames in the user buffer(s).
172 Be careful to pass a <i>copy</i> of the user buffer pointers to
173 PaUtil_CopyInput because PaUtil_CopyInput advances the pointers to
174 the start of the next region to copy.
175 - PaUtil_CopyInput will not copy more data than is available in the
176 host buffer(s), so the above steps need to be repeated until the user
177 buffer(s) are full.
178
179
180 To copy data to the host output buffer from the user buffers(s) supplied
181 to Pa_WriteStream use the following calling sequence.
182
183 - Repeat the following three steps until all frames from the user buffer(s)
184 have been copied to the host API:
185 -# Call PaUtil_SetOutputFrameCount with the number of frames in the host
186 output buffer.
187 -# Call one of the following functions one or more times to tell the
188 buffer processor about the host output buffer(s): PaUtil_SetOutputChannel,
189 PaUtil_SetInterleavedOutputChannels, PaUtil_SetNonInterleavedOutputChannel.
190 Which function you call will depend on whether the host buffer(s) are
191 interleaved or not.
192 -# Call PaUtil_CopyOutput with the user buffer pointer (or a copy of the
193 array of buffer pointers for a non-interleaved stream) passed to
194 Pa_WriteStream, along with the number of frames in the user buffer(s).
195 Be careful to pass a <i>copy</i> of the user buffer pointers to
196 PaUtil_CopyOutput because PaUtil_CopyOutput advances the pointers to
197 the start of the next region to copy.
198 - PaUtil_CopyOutput will not copy more data than fits in the host buffer(s),
199 so the above steps need to be repeated until all user data is copied.
200 */
201
202
203 #include "portaudio.h"
204 #include "pa_converters.h"
205 #include "pa_dither.h"
206
207 #ifdef __cplusplus
208 extern "C"
209 {
210 #endif /* __cplusplus */
211
212
213 /** @brief Mode flag passed to PaUtil_InitializeBufferProcessor indicating the type
214 of buffering that the host API uses.
215
216 The mode used depends on whether the host API or the implementation manages
217 the buffers, and how these buffers are used (scatter gather, circular buffer).
218 */
219 typedef enum {
220 /** The host buffer size is a fixed known size. */
221 paUtilFixedHostBufferSize,
222
223 /** The host buffer size may vary, but has a known maximum size. */
224 paUtilBoundedHostBufferSize,
225
226 /** Nothing is known about the host buffer size. */
227 paUtilUnknownHostBufferSize,
228
229 /** The host buffer size varies, and the client does not require the buffer
230 processor to consume all of the input and fill all of the output buffer. This
231 is useful when the implementation has access to the host API's circular buffer
232 and only needs to consume/fill some of it, not necessarily all of it, with each
233 call to the buffer processor. This is the only mode where
234 PaUtil_EndBufferProcessing() may not consume the whole buffer.
235 */
236 paUtilVariableHostBufferSizePartialUsageAllowed
237 }PaUtilHostBufferSizeMode;
238
239
240 /** @brief An auxilliary data structure used internally by the buffer processor
241 to represent host input and output buffers. */
242 typedef struct PaUtilChannelDescriptor{
243 void *data;
244 unsigned int stride; /**< stride in samples, not bytes */
245 }PaUtilChannelDescriptor;
246
247
248 /** @brief The main buffer processor data structure.
249
250 Allocate one of these, initialize it with PaUtil_InitializeBufferProcessor
251 and terminate it with PaUtil_TerminateBufferProcessor.
252 */
253 typedef struct {
254 unsigned long framesPerUserBuffer;
255 unsigned long framesPerHostBuffer;
256
257 PaUtilHostBufferSizeMode hostBufferSizeMode;
258 int useNonAdaptingProcess;
259 int userOutputSampleFormatIsEqualToHost;
260 int userInputSampleFormatIsEqualToHost;
261 unsigned long framesPerTempBuffer;
262
263 unsigned int inputChannelCount;
264 unsigned int bytesPerHostInputSample;
265 unsigned int bytesPerUserInputSample;
266 int userInputIsInterleaved;
267 PaUtilConverter *inputConverter;
268 PaUtilZeroer *inputZeroer;
269
270 unsigned int outputChannelCount;
271 unsigned int bytesPerHostOutputSample;
272 unsigned int bytesPerUserOutputSample;
273 int userOutputIsInterleaved;
274 PaUtilConverter *outputConverter;
275 PaUtilZeroer *outputZeroer;
276
277 unsigned long initialFramesInTempInputBuffer;
278 unsigned long initialFramesInTempOutputBuffer;
279
280 void *tempInputBuffer; /**< used for slips, block adaption, and conversion. */
281 void **tempInputBufferPtrs; /**< storage for non-interleaved buffer pointers, NULL for interleaved user input */
282 unsigned long framesInTempInputBuffer; /**< frames remaining in input buffer from previous adaption iteration */
283
284 void *tempOutputBuffer; /**< used for slips, block adaption, and conversion. */
285 void **tempOutputBufferPtrs; /**< storage for non-interleaved buffer pointers, NULL for interleaved user output */
286 unsigned long framesInTempOutputBuffer; /**< frames remaining in input buffer from previous adaption iteration */
287
288 PaStreamCallbackTimeInfo *timeInfo;
289
290 PaStreamCallbackFlags callbackStatusFlags;
291
292 int hostInputIsInterleaved;
293 unsigned long hostInputFrameCount[2];
294 PaUtilChannelDescriptor *hostInputChannels[2]; /**< pointers to arrays of channel descriptors.
295 pointers are NULL for half-duplex output processing.
296 hostInputChannels[i].data is NULL when the caller
297 calls PaUtil_SetNoInput()
298 */
299 int hostOutputIsInterleaved;
300 unsigned long hostOutputFrameCount[2];
301 PaUtilChannelDescriptor *hostOutputChannels[2]; /**< pointers to arrays of channel descriptors.
302 pointers are NULL for half-duplex input processing.
303 hostOutputChannels[i].data is NULL when the caller
304 calls PaUtil_SetNoOutput()
305 */
306
307 PaUtilTriangularDitherGenerator ditherGenerator;
308
309 double samplePeriod;
310
311 PaStreamCallback *streamCallback;
312 void *userData;
313 } PaUtilBufferProcessor;
314
315
316 /** @name Initialization, termination, resetting and info */
317 /*@{*/
318
319 /** Initialize a buffer processor's representation stored in a
320 PaUtilBufferProcessor structure. Be sure to call
321 PaUtil_TerminateBufferProcessor after finishing with a buffer processor.
322
323 @param bufferProcessor The buffer processor structure to initialize.
324
325 @param inputChannelCount The number of input channels as passed to
326 Pa_OpenStream or 0 for an output-only stream.
327
328 @param userInputSampleFormat Format of user input samples, as passed to
329 Pa_OpenStream. This parameter is ignored for ouput-only streams.
330
331 @param hostInputSampleFormat Format of host input samples. This parameter is
332 ignored for output-only streams. See note about host buffer interleave below.
333
334 @param outputChannelCount The number of output channels as passed to
335 Pa_OpenStream or 0 for an input-only stream.
336
337 @param userOutputSampleFormat Format of user output samples, as passed to
338 Pa_OpenStream. This parameter is ignored for input-only streams.
339
340 @param hostOutputSampleFormat Format of host output samples. This parameter is
341 ignored for input-only streams. See note about host buffer interleave below.
342
343 @param sampleRate Sample rate of the stream. The more accurate this is the
344 better - it is used for updating time stamps when adapting buffers.
345
346 @param streamFlags Stream flags as passed to Pa_OpenStream, this parameter is
347 used for selecting special sample conversion options such as clipping and
348 dithering.
349
350 @param framesPerUserBuffer Number of frames per user buffer, as requested
351 by the framesPerBuffer parameter to Pa_OpenStream. This parameter may be
352 zero to indicate that the user will accept any (and varying) buffer sizes.
353
354 @param framesPerHostBuffer Specifies the number of frames per host buffer
355 for the fixed buffer size mode, and the maximum number of frames
356 per host buffer for the bounded host buffer size mode. It is ignored for
357 the other modes.
358
359 @param hostBufferSizeMode A mode flag indicating the size variability of
360 host buffers that will be passed to the buffer processor. See
361 PaUtilHostBufferSizeMode for further details.
362
363 @param streamCallback The user stream callback passed to Pa_OpenStream.
364
365 @param userData The user data field passed to Pa_OpenStream.
366
367 @note The interleave flag is ignored for host buffer formats. Host
368 interleave is determined by the use of different SetInput and SetOutput
369 functions.
370
371 @return An error code indicating whether the initialization was successful.
372 If the error code is not PaNoError, the buffer processor was not initialized
373 and should not be used.
374
375 @see Pa_OpenStream, PaUtilHostBufferSizeMode, PaUtil_TerminateBufferProcessor
376 */
377 PaError PaUtil_InitializeBufferProcessor( PaUtilBufferProcessor* bufferProcessor,
378 int inputChannelCount, PaSampleFormat userInputSampleFormat,
379 PaSampleFormat hostInputSampleFormat,
380 int outputChannelCount, PaSampleFormat userOutputSampleFormat,
381 PaSampleFormat hostOutputSampleFormat,
382 double sampleRate,
383 PaStreamFlags streamFlags,
384 unsigned long framesPerUserBuffer, /* 0 indicates don't care */
385 unsigned long framesPerHostBuffer,
386 PaUtilHostBufferSizeMode hostBufferSizeMode,
387 PaStreamCallback *streamCallback, void *userData );
388
389
390 /** Terminate a buffer processor's representation. Deallocates any temporary
391 buffers allocated by PaUtil_InitializeBufferProcessor.
392
393 @param bufferProcessor The buffer processor structure to terminate.
394
395 @see PaUtil_InitializeBufferProcessor.
396 */
397 void PaUtil_TerminateBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
398
399
400 /** Clear any internally buffered data. If you call
401 PaUtil_InitializeBufferProcessor in your OpenStream routine, make sure you
402 call PaUtil_ResetBufferProcessor in your StartStream call.
403
404 @param bufferProcessor The buffer processor to reset.
405 */
406 void PaUtil_ResetBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
407
408
409 /** Retrieve the input latency of a buffer processor.
410
411 @param bufferProcessor The buffer processor examine.
412
413 @return The input latency introduced by the buffer processor, in frames.
414
415 @see PaUtil_GetBufferProcessorOutputLatency
416 */
417 unsigned long PaUtil_GetBufferProcessorInputLatency( PaUtilBufferProcessor* bufferProcessor );
418
419 /** Retrieve the output latency of a buffer processor.
420
421 @param bufferProcessor The buffer processor examine.
422
423 @return The output latency introduced by the buffer processor, in frames.
424
425 @see PaUtil_GetBufferProcessorInputLatency
426 */
427 unsigned long PaUtil_GetBufferProcessorOutputLatency( PaUtilBufferProcessor* bufferProcessor );
428
429 /*@}*/
430
431
432 /** @name Host buffer pointer configuration
433
434 Functions to set host input and output buffers, used by both callback streams
435 and blocking read/write streams.
436 */
437 /*@{*/
438
439
440 /** Set the number of frames in the input host buffer(s) specified by the
441 PaUtil_Set*InputChannel functions.
442
443 @param bufferProcessor The buffer processor.
444
445 @param frameCount The number of host input frames. A 0 frameCount indicates to
446 use the framesPerHostBuffer value passed to PaUtil_InitializeBufferProcessor.
447
448 @see PaUtil_SetNoInput, PaUtil_SetInputChannel,
449 PaUtil_SetInterleavedInputChannels, PaUtil_SetNonInterleavedInputChannel
450 */
451 void PaUtil_SetInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
452 unsigned long frameCount );
453
454
455 /** Indicate that no input is avalable. This function should be used when
456 priming the output of a full-duplex stream opened with the
457 paPrimeOutputBuffersUsingStreamCallback flag. Note that it is not necessary
458 to call this or any othe PaUtil_Set*Input* functions for ouput-only streams.
459
460 @param bufferProcessor The buffer processor.
461 */
462 void PaUtil_SetNoInput( PaUtilBufferProcessor* bufferProcessor );
463
464
465 /** Provide the buffer processor with a pointer to a host input channel.
466
467 @param bufferProcessor The buffer processor.
468 @param channel The channel number.
469 @param data The buffer.
470 @param stride The stride from one sample to the next, in samples. For
471 interleaved host buffers, the stride will usually be the same as the number of
472 channels in the buffer.
473 */
474 void PaUtil_SetInputChannel( PaUtilBufferProcessor* bufferProcessor,
475 unsigned int channel, void *data, unsigned int stride );
476
477
478 /** Provide the buffer processor with a pointer to an number of interleaved
479 host input channels.
480
481 @param bufferProcessor The buffer processor.
482 @param firstChannel The first channel number.
483 @param data The buffer.
484 @param channelCount The number of interleaved channels in the buffer. If
485 channelCount is zero, the number of channels specified to
486 PaUtil_InitializeBufferProcessor will be used.
487 */
488 void PaUtil_SetInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
489 unsigned int firstChannel, void *data, unsigned int channelCount );
490
491
492 /** Provide the buffer processor with a pointer to one non-interleaved host
493 output channel.
494
495 @param bufferProcessor The buffer processor.
496 @param channel The channel number.
497 @param data The buffer.
498 */
499 void PaUtil_SetNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
500 unsigned int channel, void *data );
501
502
503 /** Use for the second buffer half when the input buffer is split in two halves.
504 @see PaUtil_SetInputFrameCount
505 */
506 void PaUtil_Set2ndInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
507 unsigned long frameCount );
508
509 /** Use for the second buffer half when the input buffer is split in two halves.
510 @see PaUtil_SetInputChannel
511 */
512 void PaUtil_Set2ndInputChannel( PaUtilBufferProcessor* bufferProcessor,
513 unsigned int channel, void *data, unsigned int stride );
514
515 /** Use for the second buffer half when the input buffer is split in two halves.
516 @see PaUtil_SetInterleavedInputChannels
517 */
518 void PaUtil_Set2ndInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
519 unsigned int firstChannel, void *data, unsigned int channelCount );
520
521 /** Use for the second buffer half when the input buffer is split in two halves.
522 @see PaUtil_SetNonInterleavedInputChannel
523 */
524 void PaUtil_Set2ndNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
525 unsigned int channel, void *data );
526
527
528 /** Set the number of frames in the output host buffer(s) specified by the
529 PaUtil_Set*OutputChannel functions.
530
531 @param bufferProcessor The buffer processor.
532
533 @param frameCount The number of host output frames. A 0 frameCount indicates to
534 use the framesPerHostBuffer value passed to PaUtil_InitializeBufferProcessor.
535
536 @see PaUtil_SetOutputChannel, PaUtil_SetInterleavedOutputChannels,
537 PaUtil_SetNonInterleavedOutputChannel
538 */
539 void PaUtil_SetOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
540 unsigned long frameCount );
541
542
543 /** Indicate that the output will be discarded. This function should be used
544 when implementing the paNeverDropInput mode for full duplex streams.
545
546 @param bufferProcessor The buffer processor.
547 */
548 void PaUtil_SetNoOutput( PaUtilBufferProcessor* bufferProcessor );
549
550
551 /** Provide the buffer processor with a pointer to a host output channel.
552
553 @param bufferProcessor The buffer processor.
554 @param channel The channel number.
555 @param data The buffer.
556 @param stride The stride from one sample to the next, in samples. For
557 interleaved host buffers, the stride will usually be the same as the number of
558 channels in the buffer.
559 */
560 void PaUtil_SetOutputChannel( PaUtilBufferProcessor* bufferProcessor,
561 unsigned int channel, void *data, unsigned int stride );
562
563
564 /** Provide the buffer processor with a pointer to a number of interleaved
565 host output channels.
566
567 @param bufferProcessor The buffer processor.
568 @param firstChannel The first channel number.
569 @param data The buffer.
570 @param channelCount The number of interleaved channels in the buffer. If
571 channelCount is zero, the number of channels specified to
572 PaUtil_InitializeBufferProcessor will be used.
573 */
574 void PaUtil_SetInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
575 unsigned int firstChannel, void *data, unsigned int channelCount );
576
577
578 /** Provide the buffer processor with a pointer to one non-interleaved host
579 output channel.
580
581 @param bufferProcessor The buffer processor.
582 @param channel The channel number.
583 @param data The buffer.
584 */
585 void PaUtil_SetNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
586 unsigned int channel, void *data );
587
588
589 /** Use for the second buffer half when the output buffer is split in two halves.
590 @see PaUtil_SetOutputFrameCount
591 */
592 void PaUtil_Set2ndOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
593 unsigned long frameCount );
594
595 /** Use for the second buffer half when the output buffer is split in two halves.
596 @see PaUtil_SetOutputChannel
597 */
598 void PaUtil_Set2ndOutputChannel( PaUtilBufferProcessor* bufferProcessor,
599 unsigned int channel, void *data, unsigned int stride );
600
601 /** Use for the second buffer half when the output buffer is split in two halves.
602 @see PaUtil_SetInterleavedOutputChannels
603 */
604 void PaUtil_Set2ndInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
605 unsigned int firstChannel, void *data, unsigned int channelCount );
606
607 /** Use for the second buffer half when the output buffer is split in two halves.
608 @see PaUtil_SetNonInterleavedOutputChannel
609 */
610 void PaUtil_Set2ndNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
611 unsigned int channel, void *data );
612
613 /*@}*/
614
615
616 /** @name Buffer processing functions for callback streams
617 */
618 /*@{*/
619
620 /** Commence processing a host buffer (or a pair of host buffers in the
621 full-duplex case) for a callback stream.
622
623 @param bufferProcessor The buffer processor.
624
625 @param timeInfo Timing information for the first sample of the host
626 buffer(s). This information may be adjusted when buffer adaption is being
627 performed.
628
629 @param callbackStatusFlags Flags indicating whether underruns and overruns
630 have occurred since the last time the buffer processor was called.
631 */
632 void PaUtil_BeginBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
633 PaStreamCallbackTimeInfo* timeInfo, PaStreamCallbackFlags callbackStatusFlags );
634
635
636 /** Finish processing a host buffer (or a pair of host buffers in the
637 full-duplex case) for a callback stream.
638
639 @param bufferProcessor The buffer processor.
640
641 @param callbackResult On input, indicates a previous callback result, and on
642 exit, the result of the user stream callback, if it is called.
643 On entry callbackResult should contain one of { paContinue, paComplete, or
644 paAbort}. If paComplete is passed, the stream callback will not be called
645 but any audio that was generated by previous stream callbacks will be copied
646 to the output buffer(s). You can check whether the buffer processor's internal
647 buffer is empty by calling PaUtil_IsBufferProcessorOutputEmpty.
648
649 If the stream callback is called its result is stored in *callbackResult. If
650 the stream callback returns paComplete or paAbort, all output buffers will be
651 full of valid data - some of which may be zeros to acount for data that
652 wasn't generated by the terminating callback.
653
654 @return The number of frames processed. This usually corresponds to the
655 number of frames specified by the PaUtil_Set*FrameCount functions, exept in
656 the paUtilVariableHostBufferSizePartialUsageAllowed buffer size mode when a
657 smaller value may be returned.
658 */
659 unsigned long PaUtil_EndBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
660 int *callbackResult );
661
662
663 /** Determine whether any callback generated output remains in the bufffer
664 processor's internal buffers. This method may be used to determine when to
665 continue calling PaUtil_EndBufferProcessing() after the callback has returned
666 a callbackResult of paComplete.
667
668 @param bufferProcessor The buffer processor.
669
670 @return Returns non-zero when callback generated output remains in the internal
671 buffer and zero (0) when there internal buffer contains no callback generated
672 data.
673 */
674 int PaUtil_IsBufferProcessorOutputEmpty( PaUtilBufferProcessor* bufferProcessor );
675
676 /*@}*/
677
678
679 /** @name Buffer processing functions for blocking read/write streams
680 */
681 /*@{*/
682
683 /** Copy samples from host input channels set up by the PaUtil_Set*InputChannels
684 functions to a user supplied buffer. This function is intended for use with
685 blocking read/write streams. Copies the minimum of the number of
686 user frames (specified by the frameCount parameter) and the number of available
687 host frames (specified in a previous call to SetInputFrameCount()).
688
689 @param bufferProcessor The buffer processor.
690
691 @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
692 to an array of user buffer pointers for a non-interleaved stream. It is
693 important that this parameter points to a copy of the user buffer pointers,
694 not to the actual user buffer pointers, because this function updates the
695 pointers before returning.
696
697 @param frameCount The number of frames of data in the buffer(s) pointed to by
698 the buffer parameter.
699
700 @return The number of frames copied. The buffer pointer(s) pointed to by the
701 buffer parameter are advanced to point to the frame(s) following the last one
702 filled.
703 */
704 unsigned long PaUtil_CopyInput( PaUtilBufferProcessor* bufferProcessor,
705 void **buffer, unsigned long frameCount );
706
707
708 /* Copy samples from a user supplied buffer to host output channels set up by
709 the PaUtil_Set*OutputChannels functions. This function is intended for use with
710 blocking read/write streams. Copies the minimum of the number of
711 user frames (specified by the frameCount parameter) and the number of
712 host frames (specified in a previous call to SetOutputFrameCount()).
713
714 @param bufferProcessor The buffer processor.
715
716 @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
717 to an array of user buffer pointers for a non-interleaved stream. It is
718 important that this parameter points to a copy of the user buffer pointers,
719 not to the actual user buffer pointers, because this function updates the
720 pointers before returning.
721
722 @param frameCount The number of frames of data in the buffer(s) pointed to by
723 the buffer parameter.
724
725 @return The number of frames copied. The buffer pointer(s) pointed to by the
726 buffer parameter are advanced to point to the frame(s) following the last one
727 copied.
728 */
729 unsigned long PaUtil_CopyOutput( PaUtilBufferProcessor* bufferProcessor,
730 const void ** buffer, unsigned long frameCount );
731
732
733 /* Zero samples in host output channels set up by the PaUtil_Set*OutputChannels
734 functions. This function is useful for flushing streams.
735 Zeros the minimum of frameCount and the number of host frames specified in a
736 previous call to SetOutputFrameCount().
737
738 @param bufferProcessor The buffer processor.
739
740 @param frameCount The maximum number of frames to zero.
741
742 @return The number of frames zeroed.
743 */
744 unsigned long PaUtil_ZeroOutput( PaUtilBufferProcessor* bufferProcessor,
745 unsigned long frameCount );
746
747
748 /*@}*/
749
750
751 #ifdef __cplusplus
752 }
753 #endif /* __cplusplus */
754 #endif /* PA_PROCESS_H */

  ViewVC Help
Powered by ViewVC 1.1.22