/[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 10 - (show annotations) (download)
Mon Sep 6 11:40:06 2010 UTC (9 years, 11 months ago) by william
File MIME type: text/plain
File size: 32591 byte(s)
exported r3113 from ./upstream/trunk
1 #ifndef PA_PROCESS_H
2 #define PA_PROCESS_H
3 /*
4 * $Id: pa_process.h 1097 2006-08-26 08:27:53Z rossb $
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 unsigned long framesPerTempBuffer;
260
261 unsigned int inputChannelCount;
262 unsigned int bytesPerHostInputSample;
263 unsigned int bytesPerUserInputSample;
264 int userInputIsInterleaved;
265 PaUtilConverter *inputConverter;
266 PaUtilZeroer *inputZeroer;
267
268 unsigned int outputChannelCount;
269 unsigned int bytesPerHostOutputSample;
270 unsigned int bytesPerUserOutputSample;
271 int userOutputIsInterleaved;
272 PaUtilConverter *outputConverter;
273 PaUtilZeroer *outputZeroer;
274
275 unsigned long initialFramesInTempInputBuffer;
276 unsigned long initialFramesInTempOutputBuffer;
277
278 void *tempInputBuffer; /**< used for slips, block adaption, and conversion. */
279 void **tempInputBufferPtrs; /**< storage for non-interleaved buffer pointers, NULL for interleaved user input */
280 unsigned long framesInTempInputBuffer; /**< frames remaining in input buffer from previous adaption iteration */
281
282 void *tempOutputBuffer; /**< used for slips, block adaption, and conversion. */
283 void **tempOutputBufferPtrs; /**< storage for non-interleaved buffer pointers, NULL for interleaved user output */
284 unsigned long framesInTempOutputBuffer; /**< frames remaining in input buffer from previous adaption iteration */
285
286 PaStreamCallbackTimeInfo *timeInfo;
287
288 PaStreamCallbackFlags callbackStatusFlags;
289
290 unsigned long hostInputFrameCount[2];
291 PaUtilChannelDescriptor *hostInputChannels[2]; /**< pointers to arrays of channel descriptors.
292 pointers are NULL for half-duplex output processing.
293 hostInputChannels[i].data is NULL when the caller
294 calls PaUtil_SetNoInput()
295 */
296 unsigned long hostOutputFrameCount[2];
297 PaUtilChannelDescriptor *hostOutputChannels[2]; /**< pointers to arrays of channel descriptors.
298 pointers are NULL for half-duplex input processing.
299 hostOutputChannels[i].data is NULL when the caller
300 calls PaUtil_SetNoOutput()
301 */
302
303 PaUtilTriangularDitherGenerator ditherGenerator;
304
305 double samplePeriod;
306
307 PaStreamCallback *streamCallback;
308 void *userData;
309 } PaUtilBufferProcessor;
310
311
312 /** @name Initialization, termination, resetting and info */
313 /*@{*/
314
315 /** Initialize a buffer processor's representation stored in a
316 PaUtilBufferProcessor structure. Be sure to call
317 PaUtil_TerminateBufferProcessor after finishing with a buffer processor.
318
319 @param bufferProcessor The buffer processor structure to initialize.
320
321 @param inputChannelCount The number of input channels as passed to
322 Pa_OpenStream or 0 for an output-only stream.
323
324 @param userInputSampleFormat Format of user input samples, as passed to
325 Pa_OpenStream. This parameter is ignored for ouput-only streams.
326
327 @param hostInputSampleFormat Format of host input samples. This parameter is
328 ignored for output-only streams. See note about host buffer interleave below.
329
330 @param outputChannelCount The number of output channels as passed to
331 Pa_OpenStream or 0 for an input-only stream.
332
333 @param userOutputSampleFormat Format of user output samples, as passed to
334 Pa_OpenStream. This parameter is ignored for input-only streams.
335
336 @param hostOutputSampleFormat Format of host output samples. This parameter is
337 ignored for input-only streams. See note about host buffer interleave below.
338
339 @param sampleRate Sample rate of the stream. The more accurate this is the
340 better - it is used for updating time stamps when adapting buffers.
341
342 @param streamFlags Stream flags as passed to Pa_OpenStream, this parameter is
343 used for selecting special sample conversion options such as clipping and
344 dithering.
345
346 @param framesPerUserBuffer Number of frames per user buffer, as requested
347 by the framesPerBuffer parameter to Pa_OpenStream. This parameter may be
348 zero to indicate that the user will accept any (and varying) buffer sizes.
349
350 @param framesPerHostBuffer Specifies the number of frames per host buffer
351 for the fixed buffer size mode, and the maximum number of frames
352 per host buffer for the bounded host buffer size mode. It is ignored for
353 the other modes.
354
355 @param hostBufferSizeMode A mode flag indicating the size variability of
356 host buffers that will be passed to the buffer processor. See
357 PaUtilHostBufferSizeMode for further details.
358
359 @param streamCallback The user stream callback passed to Pa_OpenStream.
360
361 @param userData The user data field passed to Pa_OpenStream.
362
363 @note The interleave flag is ignored for host buffer formats. Host
364 interleave is determined by the use of different SetInput and SetOutput
365 functions.
366
367 @return An error code indicating whether the initialization was successful.
368 If the error code is not PaNoError, the buffer processor was not initialized
369 and should not be used.
370
371 @see Pa_OpenStream, PaUtilHostBufferSizeMode, PaUtil_TerminateBufferProcessor
372 */
373 PaError PaUtil_InitializeBufferProcessor( PaUtilBufferProcessor* bufferProcessor,
374 int inputChannelCount, PaSampleFormat userInputSampleFormat,
375 PaSampleFormat hostInputSampleFormat,
376 int outputChannelCount, PaSampleFormat userOutputSampleFormat,
377 PaSampleFormat hostOutputSampleFormat,
378 double sampleRate,
379 PaStreamFlags streamFlags,
380 unsigned long framesPerUserBuffer, /* 0 indicates don't care */
381 unsigned long framesPerHostBuffer,
382 PaUtilHostBufferSizeMode hostBufferSizeMode,
383 PaStreamCallback *streamCallback, void *userData );
384
385
386 /** Terminate a buffer processor's representation. Deallocates any temporary
387 buffers allocated by PaUtil_InitializeBufferProcessor.
388
389 @param bufferProcessor The buffer processor structure to terminate.
390
391 @see PaUtil_InitializeBufferProcessor.
392 */
393 void PaUtil_TerminateBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
394
395
396 /** Clear any internally buffered data. If you call
397 PaUtil_InitializeBufferProcessor in your OpenStream routine, make sure you
398 call PaUtil_ResetBufferProcessor in your StartStream call.
399
400 @param bufferProcessor The buffer processor to reset.
401 */
402 void PaUtil_ResetBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
403
404
405 /** Retrieve the input latency of a buffer processor.
406
407 @param bufferProcessor The buffer processor examine.
408
409 @return The input latency introduced by the buffer processor, in frames.
410
411 @see PaUtil_GetBufferProcessorOutputLatency
412 */
413 unsigned long PaUtil_GetBufferProcessorInputLatency( PaUtilBufferProcessor* bufferProcessor );
414
415 /** Retrieve the output latency of a buffer processor.
416
417 @param bufferProcessor The buffer processor examine.
418
419 @return The output latency introduced by the buffer processor, in frames.
420
421 @see PaUtil_GetBufferProcessorInputLatency
422 */
423 unsigned long PaUtil_GetBufferProcessorOutputLatency( PaUtilBufferProcessor* bufferProcessor );
424
425 /*@}*/
426
427
428 /** @name Host buffer pointer configuration
429
430 Functions to set host input and output buffers, used by both callback streams
431 and blocking read/write streams.
432 */
433 /*@{*/
434
435
436 /** Set the number of frames in the input host buffer(s) specified by the
437 PaUtil_Set*InputChannel functions.
438
439 @param bufferProcessor The buffer processor.
440
441 @param frameCount The number of host input frames. A 0 frameCount indicates to
442 use the framesPerHostBuffer value passed to PaUtil_InitializeBufferProcessor.
443
444 @see PaUtil_SetNoInput, PaUtil_SetInputChannel,
445 PaUtil_SetInterleavedInputChannels, PaUtil_SetNonInterleavedInputChannel
446 */
447 void PaUtil_SetInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
448 unsigned long frameCount );
449
450
451 /** Indicate that no input is avalable. This function should be used when
452 priming the output of a full-duplex stream opened with the
453 paPrimeOutputBuffersUsingStreamCallback flag. Note that it is not necessary
454 to call this or any othe PaUtil_Set*Input* functions for ouput-only streams.
455
456 @param bufferProcessor The buffer processor.
457 */
458 void PaUtil_SetNoInput( PaUtilBufferProcessor* bufferProcessor );
459
460
461 /** Provide the buffer processor with a pointer to a host input channel.
462
463 @param bufferProcessor The buffer processor.
464 @param channel The channel number.
465 @param data The buffer.
466 @param stride The stride from one sample to the next, in samples. For
467 interleaved host buffers, the stride will usually be the same as the number of
468 channels in the buffer.
469 */
470 void PaUtil_SetInputChannel( PaUtilBufferProcessor* bufferProcessor,
471 unsigned int channel, void *data, unsigned int stride );
472
473
474 /** Provide the buffer processor with a pointer to an number of interleaved
475 host input channels.
476
477 @param bufferProcessor The buffer processor.
478 @param firstChannel The first channel number.
479 @param data The buffer.
480 @param channelCount The number of interleaved channels in the buffer. If
481 channelCount is zero, the number of channels specified to
482 PaUtil_InitializeBufferProcessor will be used.
483 */
484 void PaUtil_SetInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
485 unsigned int firstChannel, void *data, unsigned int channelCount );
486
487
488 /** Provide the buffer processor with a pointer to one non-interleaved host
489 output channel.
490
491 @param bufferProcessor The buffer processor.
492 @param channel The channel number.
493 @param data The buffer.
494 */
495 void PaUtil_SetNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
496 unsigned int channel, void *data );
497
498
499 /** Use for the second buffer half when the input buffer is split in two halves.
500 @see PaUtil_SetInputFrameCount
501 */
502 void PaUtil_Set2ndInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
503 unsigned long frameCount );
504
505 /** Use for the second buffer half when the input buffer is split in two halves.
506 @see PaUtil_SetInputChannel
507 */
508 void PaUtil_Set2ndInputChannel( PaUtilBufferProcessor* bufferProcessor,
509 unsigned int channel, void *data, unsigned int stride );
510
511 /** Use for the second buffer half when the input buffer is split in two halves.
512 @see PaUtil_SetInterleavedInputChannels
513 */
514 void PaUtil_Set2ndInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
515 unsigned int firstChannel, void *data, unsigned int channelCount );
516
517 /** Use for the second buffer half when the input buffer is split in two halves.
518 @see PaUtil_SetNonInterleavedInputChannel
519 */
520 void PaUtil_Set2ndNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
521 unsigned int channel, void *data );
522
523
524 /** Set the number of frames in the output host buffer(s) specified by the
525 PaUtil_Set*OutputChannel functions.
526
527 @param bufferProcessor The buffer processor.
528
529 @param frameCount The number of host output frames. A 0 frameCount indicates to
530 use the framesPerHostBuffer value passed to PaUtil_InitializeBufferProcessor.
531
532 @see PaUtil_SetOutputChannel, PaUtil_SetInterleavedOutputChannels,
533 PaUtil_SetNonInterleavedOutputChannel
534 */
535 void PaUtil_SetOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
536 unsigned long frameCount );
537
538
539 /** Indicate that the output will be discarded. This function should be used
540 when implementing the paNeverDropInput mode for full duplex streams.
541
542 @param bufferProcessor The buffer processor.
543 */
544 void PaUtil_SetNoOutput( PaUtilBufferProcessor* bufferProcessor );
545
546
547 /** Provide the buffer processor with a pointer to a host output channel.
548
549 @param bufferProcessor The buffer processor.
550 @param channel The channel number.
551 @param data The buffer.
552 @param stride The stride from one sample to the next, in samples. For
553 interleaved host buffers, the stride will usually be the same as the number of
554 channels in the buffer.
555 */
556 void PaUtil_SetOutputChannel( PaUtilBufferProcessor* bufferProcessor,
557 unsigned int channel, void *data, unsigned int stride );
558
559
560 /** Provide the buffer processor with a pointer to a number of interleaved
561 host output channels.
562
563 @param bufferProcessor The buffer processor.
564 @param firstChannel The first channel number.
565 @param data The buffer.
566 @param channelCount The number of interleaved channels in the buffer. If
567 channelCount is zero, the number of channels specified to
568 PaUtil_InitializeBufferProcessor will be used.
569 */
570 void PaUtil_SetInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
571 unsigned int firstChannel, void *data, unsigned int channelCount );
572
573
574 /** Provide the buffer processor with a pointer to one non-interleaved host
575 output channel.
576
577 @param bufferProcessor The buffer processor.
578 @param channel The channel number.
579 @param data The buffer.
580 */
581 void PaUtil_SetNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
582 unsigned int channel, void *data );
583
584
585 /** Use for the second buffer half when the output buffer is split in two halves.
586 @see PaUtil_SetOutputFrameCount
587 */
588 void PaUtil_Set2ndOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
589 unsigned long frameCount );
590
591 /** Use for the second buffer half when the output buffer is split in two halves.
592 @see PaUtil_SetOutputChannel
593 */
594 void PaUtil_Set2ndOutputChannel( PaUtilBufferProcessor* bufferProcessor,
595 unsigned int channel, void *data, unsigned int stride );
596
597 /** Use for the second buffer half when the output buffer is split in two halves.
598 @see PaUtil_SetInterleavedOutputChannels
599 */
600 void PaUtil_Set2ndInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
601 unsigned int firstChannel, void *data, unsigned int channelCount );
602
603 /** Use for the second buffer half when the output buffer is split in two halves.
604 @see PaUtil_SetNonInterleavedOutputChannel
605 */
606 void PaUtil_Set2ndNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
607 unsigned int channel, void *data );
608
609 /*@}*/
610
611
612 /** @name Buffer processing functions for callback streams
613 */
614 /*@{*/
615
616 /** Commence processing a host buffer (or a pair of host buffers in the
617 full-duplex case) for a callback stream.
618
619 @param bufferProcessor The buffer processor.
620
621 @param timeInfo Timing information for the first sample of the host
622 buffer(s). This information may be adjusted when buffer adaption is being
623 performed.
624
625 @param callbackStatusFlags Flags indicating whether underruns and overruns
626 have occurred since the last time the buffer processor was called.
627 */
628 void PaUtil_BeginBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
629 PaStreamCallbackTimeInfo* timeInfo, PaStreamCallbackFlags callbackStatusFlags );
630
631
632 /** Finish processing a host buffer (or a pair of host buffers in the
633 full-duplex case) for a callback stream.
634
635 @param bufferProcessor The buffer processor.
636
637 @param callbackResult On input, indicates a previous callback result, and on
638 exit, the result of the user stream callback, if it is called.
639 On entry callbackResult should contain one of { paContinue, paComplete, or
640 paAbort}. If paComplete is passed, the stream callback will not be called
641 but any audio that was generated by previous stream callbacks will be copied
642 to the output buffer(s). You can check whether the buffer processor's internal
643 buffer is empty by calling PaUtil_IsBufferProcessorOutputEmpty.
644
645 If the stream callback is called its result is stored in *callbackResult. If
646 the stream callback returns paComplete or paAbort, all output buffers will be
647 full of valid data - some of which may be zeros to acount for data that
648 wasn't generated by the terminating callback.
649
650 @return The number of frames processed. This usually corresponds to the
651 number of frames specified by the PaUtil_Set*FrameCount functions, exept in
652 the paUtilVariableHostBufferSizePartialUsageAllowed buffer size mode when a
653 smaller value may be returned.
654 */
655 unsigned long PaUtil_EndBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
656 int *callbackResult );
657
658
659 /** Determine whether any callback generated output remains in the bufffer
660 processor's internal buffers. This method may be used to determine when to
661 continue calling PaUtil_EndBufferProcessing() after the callback has returned
662 a callbackResult of paComplete.
663
664 @param bufferProcessor The buffer processor.
665
666 @return Returns non-zero when callback generated output remains in the internal
667 buffer and zero (0) when there internal buffer contains no callback generated
668 data.
669 */
670 int PaUtil_IsBufferProcessorOutputEmpty( PaUtilBufferProcessor* bufferProcessor );
671
672 /*@}*/
673
674
675 /** @name Buffer processing functions for blocking read/write streams
676 */
677 /*@{*/
678
679 /** Copy samples from host input channels set up by the PaUtil_Set*InputChannels
680 functions to a user supplied buffer. This function is intended for use with
681 blocking read/write streams. Copies the minimum of the number of
682 user frames (specified by the frameCount parameter) and the number of available
683 host frames (specified in a previous call to SetInputFrameCount()).
684
685 @param bufferProcessor The buffer processor.
686
687 @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
688 to an array of user buffer pointers for a non-interleaved stream. It is
689 important that this parameter points to a copy of the user buffer pointers,
690 not to the actual user buffer pointers, because this function updates the
691 pointers before returning.
692
693 @param frameCount The number of frames of data in the buffer(s) pointed to by
694 the buffer parameter.
695
696 @return The number of frames copied. The buffer pointer(s) pointed to by the
697 buffer parameter are advanced to point to the frame(s) following the last one
698 filled.
699 */
700 unsigned long PaUtil_CopyInput( PaUtilBufferProcessor* bufferProcessor,
701 void **buffer, unsigned long frameCount );
702
703
704 /* Copy samples from a user supplied buffer to host output channels set up by
705 the PaUtil_Set*OutputChannels functions. This function is intended for use with
706 blocking read/write streams. Copies the minimum of the number of
707 user frames (specified by the frameCount parameter) and the number of
708 host frames (specified in a previous call to SetOutputFrameCount()).
709
710 @param bufferProcessor The buffer processor.
711
712 @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
713 to an array of user buffer pointers for a non-interleaved stream. It is
714 important that this parameter points to a copy of the user buffer pointers,
715 not to the actual user buffer pointers, because this function updates the
716 pointers before returning.
717
718 @param frameCount The number of frames of data in the buffer(s) pointed to by
719 the buffer parameter.
720
721 @return The number of frames copied. The buffer pointer(s) pointed to by the
722 buffer parameter are advanced to point to the frame(s) following the last one
723 copied.
724 */
725 unsigned long PaUtil_CopyOutput( PaUtilBufferProcessor* bufferProcessor,
726 const void ** buffer, unsigned long frameCount );
727
728
729 /* Zero samples in host output channels set up by the PaUtil_Set*OutputChannels
730 functions. This function is useful for flushing streams.
731 Zeros the minimum of frameCount and the number of host frames specified in a
732 previous call to SetOutputFrameCount().
733
734 @param bufferProcessor The buffer processor.
735
736 @param frameCount The maximum number of frames to zero.
737
738 @return The number of frames zeroed.
739 */
740 unsigned long PaUtil_ZeroOutput( PaUtilBufferProcessor* bufferProcessor,
741 unsigned long frameCount );
742
743
744 /*@}*/
745
746
747 #ifdef __cplusplus
748 }
749 #endif /* __cplusplus */
750 #endif /* PA_PROCESS_H */

  ViewVC Help
Powered by ViewVC 1.1.22