pa_process.h (32053B)
1 #ifndef PA_PROCESS_H 2 #define PA_PROCESS_H 3 /* 4 * $Id$ 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, in frames. 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_GetBufferProcessorOutputLatencyFrames 416 */ 417 unsigned long PaUtil_GetBufferProcessorInputLatencyFrames( PaUtilBufferProcessor* bufferProcessor ); 418 419 /** Retrieve the output latency of a buffer processor, in frames. 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_GetBufferProcessorInputLatencyFrames 426 */ 427 unsigned long PaUtil_GetBufferProcessorOutputLatencyFrames( 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 */