PortAudio 2.0
pa_process.h
Go to the documentation of this file.
00001 #ifndef PA_PROCESS_H
00002 #define PA_PROCESS_H
00003 /*
00004  * $Id: pa_process.h 1523 2010-07-10 17:41:25Z dmitrykos $
00005  * Portable Audio I/O Library callback buffer processing adapters
00006  *
00007  * Based on the Open Source API proposed by Ross Bencina
00008  * Copyright (c) 1999-2002 Phil Burk, Ross Bencina
00009  *
00010  * Permission is hereby granted, free of charge, to any person obtaining
00011  * a copy of this software and associated documentation files
00012  * (the "Software"), to deal in the Software without restriction,
00013  * including without limitation the rights to use, copy, modify, merge,
00014  * publish, distribute, sublicense, and/or sell copies of the Software,
00015  * and to permit persons to whom the Software is furnished to do so,
00016  * subject to the following conditions:
00017  *
00018  * The above copyright notice and this permission notice shall be
00019  * included in all copies or substantial portions of the Software.
00020  *
00021  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00022  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00023  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00024  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00025  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00026  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00027  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00028  */
00029 
00030 /*
00031  * The text above constitutes the entire PortAudio license; however, 
00032  * the PortAudio community also makes the following non-binding requests:
00033  *
00034  * Any person wishing to distribute modifications to the Software is
00035  * requested to send the modifications to the original developer so that
00036  * they can be incorporated into the canonical version. It is also 
00037  * requested that these non-binding requests be included along with the 
00038  * license above.
00039  */
00040  
00203 #include "portaudio.h"
00204 #include "pa_converters.h"
00205 #include "pa_dither.h"
00206 
00207 #ifdef __cplusplus
00208 extern "C"
00209 {
00210 #endif /* __cplusplus */
00211 
00212 
00219 typedef enum {
00221     paUtilFixedHostBufferSize,
00222 
00224     paUtilBoundedHostBufferSize,
00225 
00227     paUtilUnknownHostBufferSize,
00228 
00236     paUtilVariableHostBufferSizePartialUsageAllowed
00237 }PaUtilHostBufferSizeMode;
00238 
00239 
00242 typedef struct PaUtilChannelDescriptor{
00243     void *data;
00244     unsigned int stride;  
00245 }PaUtilChannelDescriptor;
00246 
00247 
00253 typedef struct {
00254     unsigned long framesPerUserBuffer;
00255     unsigned long framesPerHostBuffer;
00256 
00257     PaUtilHostBufferSizeMode hostBufferSizeMode;
00258     int useNonAdaptingProcess;
00259     int userOutputSampleFormatIsEqualToHost;
00260     int userInputSampleFormatIsEqualToHost;
00261     unsigned long framesPerTempBuffer;
00262 
00263     unsigned int inputChannelCount;
00264     unsigned int bytesPerHostInputSample;
00265     unsigned int bytesPerUserInputSample;
00266     int userInputIsInterleaved;
00267     PaUtilConverter *inputConverter;
00268     PaUtilZeroer *inputZeroer;
00269     
00270     unsigned int outputChannelCount;
00271     unsigned int bytesPerHostOutputSample;
00272     unsigned int bytesPerUserOutputSample;
00273     int userOutputIsInterleaved;
00274     PaUtilConverter *outputConverter;
00275     PaUtilZeroer *outputZeroer;
00276 
00277     unsigned long initialFramesInTempInputBuffer;
00278     unsigned long initialFramesInTempOutputBuffer;
00279 
00280     void *tempInputBuffer;          
00281     void **tempInputBufferPtrs;     
00282     unsigned long framesInTempInputBuffer; 
00284     void *tempOutputBuffer;         
00285     void **tempOutputBufferPtrs;    
00286     unsigned long framesInTempOutputBuffer; 
00288     PaStreamCallbackTimeInfo *timeInfo;
00289 
00290     PaStreamCallbackFlags callbackStatusFlags;
00291 
00292     int hostInputIsInterleaved;
00293     unsigned long hostInputFrameCount[2];
00294     PaUtilChannelDescriptor *hostInputChannels[2]; 
00299     int hostOutputIsInterleaved;
00300     unsigned long hostOutputFrameCount[2];
00301     PaUtilChannelDescriptor *hostOutputChannels[2]; 
00307     PaUtilTriangularDitherGenerator ditherGenerator;
00308 
00309     double samplePeriod;
00310 
00311     PaStreamCallback *streamCallback;
00312     void *userData;
00313 } PaUtilBufferProcessor;
00314 
00315 
00318 
00377 PaError PaUtil_InitializeBufferProcessor( PaUtilBufferProcessor* bufferProcessor,
00378             int inputChannelCount, PaSampleFormat userInputSampleFormat,
00379             PaSampleFormat hostInputSampleFormat,
00380             int outputChannelCount, PaSampleFormat userOutputSampleFormat,
00381             PaSampleFormat hostOutputSampleFormat,
00382             double sampleRate,
00383             PaStreamFlags streamFlags,
00384             unsigned long framesPerUserBuffer, /* 0 indicates don't care */
00385             unsigned long framesPerHostBuffer,
00386             PaUtilHostBufferSizeMode hostBufferSizeMode,
00387             PaStreamCallback *streamCallback, void *userData );
00388 
00389 
00397 void PaUtil_TerminateBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
00398 
00399 
00406 void PaUtil_ResetBufferProcessor( PaUtilBufferProcessor* bufferProcessor );
00407 
00408 
00417 unsigned long PaUtil_GetBufferProcessorInputLatency( PaUtilBufferProcessor* bufferProcessor );
00418 
00427 unsigned long PaUtil_GetBufferProcessorOutputLatency( PaUtilBufferProcessor* bufferProcessor );
00428 
00438 
00439 
00451 void PaUtil_SetInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
00452         unsigned long frameCount );
00453 
00454         
00462 void PaUtil_SetNoInput( PaUtilBufferProcessor* bufferProcessor );
00463 
00464 
00474 void PaUtil_SetInputChannel( PaUtilBufferProcessor* bufferProcessor,
00475         unsigned int channel, void *data, unsigned int stride );
00476 
00477 
00488 void PaUtil_SetInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
00489         unsigned int firstChannel, void *data, unsigned int channelCount );
00490 
00491 
00499 void PaUtil_SetNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
00500         unsigned int channel, void *data );
00501 
00502 
00506 void PaUtil_Set2ndInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
00507         unsigned long frameCount );
00508 
00512 void PaUtil_Set2ndInputChannel( PaUtilBufferProcessor* bufferProcessor,
00513         unsigned int channel, void *data, unsigned int stride );
00514 
00518 void PaUtil_Set2ndInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
00519         unsigned int firstChannel, void *data, unsigned int channelCount );
00520 
00524 void PaUtil_Set2ndNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
00525         unsigned int channel, void *data );
00526 
00527         
00539 void PaUtil_SetOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
00540         unsigned long frameCount );
00541 
00542 
00548 void PaUtil_SetNoOutput( PaUtilBufferProcessor* bufferProcessor );
00549 
00550 
00560 void PaUtil_SetOutputChannel( PaUtilBufferProcessor* bufferProcessor,
00561         unsigned int channel, void *data, unsigned int stride );
00562 
00563 
00574 void PaUtil_SetInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
00575         unsigned int firstChannel, void *data, unsigned int channelCount );
00576 
00577         
00585 void PaUtil_SetNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
00586         unsigned int channel, void *data );
00587 
00588 
00592 void PaUtil_Set2ndOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
00593         unsigned long frameCount );
00594 
00598 void PaUtil_Set2ndOutputChannel( PaUtilBufferProcessor* bufferProcessor,
00599         unsigned int channel, void *data, unsigned int stride );
00600 
00604 void PaUtil_Set2ndInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
00605         unsigned int firstChannel, void *data, unsigned int channelCount );
00606 
00610 void PaUtil_Set2ndNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
00611         unsigned int channel, void *data );
00612 
00619 
00632 void PaUtil_BeginBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
00633         PaStreamCallbackTimeInfo* timeInfo, PaStreamCallbackFlags callbackStatusFlags );
00634 
00635         
00659 unsigned long PaUtil_EndBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
00660         int *callbackResult );
00661 
00662 
00674 int PaUtil_IsBufferProcessorOutputEmpty( PaUtilBufferProcessor* bufferProcessor );
00675 
00682 
00704 unsigned long PaUtil_CopyInput( PaUtilBufferProcessor* bufferProcessor,
00705         void **buffer, unsigned long frameCount );
00706 
00707 
00708 /* Copy samples from a user supplied buffer to host output channels set up by
00709  the PaUtil_Set*OutputChannels functions. This function is intended for use with
00710  blocking read/write streams. Copies the minimum of the number of
00711  user frames (specified by the frameCount parameter) and the number of
00712  host frames (specified in a previous call to SetOutputFrameCount()).
00713 
00714  @param bufferProcessor The buffer processor.
00715 
00716  @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
00717  to an array of user buffer pointers for a non-interleaved stream. It is
00718  important that this parameter points to a copy of the user buffer pointers,
00719  not to the actual user buffer pointers, because this function updates the
00720  pointers before returning.
00721 
00722  @param frameCount The number of frames of data in the buffer(s) pointed to by
00723  the buffer parameter.
00724 
00725  @return The number of frames copied. The buffer pointer(s) pointed to by the
00726  buffer parameter are advanced to point to the frame(s) following the last one
00727  copied.
00728 */
00729 unsigned long PaUtil_CopyOutput( PaUtilBufferProcessor* bufferProcessor,
00730         const void ** buffer, unsigned long frameCount );
00731 
00732 
00733 /* Zero samples in host output channels set up by the PaUtil_Set*OutputChannels
00734  functions. This function is useful for flushing streams.
00735  Zeros the minimum of frameCount and the number of host frames specified in a
00736  previous call to SetOutputFrameCount().
00737 
00738  @param bufferProcessor The buffer processor.
00739 
00740  @param frameCount The maximum number of frames to zero.
00741  
00742  @return The number of frames zeroed.
00743 */
00744 unsigned long PaUtil_ZeroOutput( PaUtilBufferProcessor* bufferProcessor,
00745         unsigned long frameCount );
00746 
00747 
00751 #ifdef __cplusplus
00752 }
00753 #endif /* __cplusplus */
00754 #endif /* PA_PROCESS_H */