pa_process.h

Go to the documentation of this file.

#ifndef PA_PROCESS_H
#define PA_PROCESS_H
/*
 * $Id$
 * Portable Audio I/O Library callback buffer processing adapters
 *
 * Based on the Open Source API proposed by Ross Bencina
 * Copyright (c) 1999-2002 Phil Burk, Ross Bencina
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files
 * (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge,
 * publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/*
 * The text above constitutes the entire PortAudio license; however, 
 * the PortAudio community also makes the following non-binding requests:
 *
 * Any person wishing to distribute modifications to the Software is
 * requested to send the modifications to the original developer so that
 * they can be incorporated into the canonical version. It is also 
 * requested that these non-binding requests be included along with the 
 * license above.
 */
 
#include "portaudio.h"
#include "pa_converters.h"
#include "pa_dither.h"

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */


typedef enum {
    paUtilFixedHostBufferSize,

    paUtilBoundedHostBufferSize,

    paUtilUnknownHostBufferSize,

    paUtilVariableHostBufferSizePartialUsageAllowed
}PaUtilHostBufferSizeMode;


typedef struct PaUtilChannelDescriptor{
    void *data;
    unsigned int stride;  
}PaUtilChannelDescriptor;


typedef struct {
    unsigned long framesPerUserBuffer;
    unsigned long framesPerHostBuffer;

    PaUtilHostBufferSizeMode hostBufferSizeMode;
    int useNonAdaptingProcess;
    int userOutputSampleFormatIsEqualToHost;
    int userInputSampleFormatIsEqualToHost;
    unsigned long framesPerTempBuffer;

    unsigned int inputChannelCount;
    unsigned int bytesPerHostInputSample;
    unsigned int bytesPerUserInputSample;
    int userInputIsInterleaved;
    PaUtilConverter *inputConverter;
    PaUtilZeroer *inputZeroer;
    
    unsigned int outputChannelCount;
    unsigned int bytesPerHostOutputSample;
    unsigned int bytesPerUserOutputSample;
    int userOutputIsInterleaved;
    PaUtilConverter *outputConverter;
    PaUtilZeroer *outputZeroer;

    unsigned long initialFramesInTempInputBuffer;
    unsigned long initialFramesInTempOutputBuffer;

    void *tempInputBuffer;          
    void **tempInputBufferPtrs;     
    unsigned long framesInTempInputBuffer; 
    void *tempOutputBuffer;         
    void **tempOutputBufferPtrs;    
    unsigned long framesInTempOutputBuffer; 
    PaStreamCallbackTimeInfo *timeInfo;

    PaStreamCallbackFlags callbackStatusFlags;

    int hostInputIsInterleaved;
    unsigned long hostInputFrameCount[2];
    PaUtilChannelDescriptor *hostInputChannels[2]; 
    int hostOutputIsInterleaved;
    unsigned long hostOutputFrameCount[2];
    PaUtilChannelDescriptor *hostOutputChannels[2]; 
    PaUtilTriangularDitherGenerator ditherGenerator;

    double samplePeriod;

    PaStreamCallback *streamCallback;
    void *userData;
} PaUtilBufferProcessor;



PaError PaUtil_InitializeBufferProcessor( PaUtilBufferProcessor* bufferProcessor,
            int inputChannelCount, PaSampleFormat userInputSampleFormat,
            PaSampleFormat hostInputSampleFormat,
            int outputChannelCount, PaSampleFormat userOutputSampleFormat,
            PaSampleFormat hostOutputSampleFormat,
            double sampleRate,
            PaStreamFlags streamFlags,
            unsigned long framesPerUserBuffer, /* 0 indicates don't care */
            unsigned long framesPerHostBuffer,
            PaUtilHostBufferSizeMode hostBufferSizeMode,
            PaStreamCallback *streamCallback, void *userData );


void PaUtil_TerminateBufferProcessor( PaUtilBufferProcessor* bufferProcessor );


void PaUtil_ResetBufferProcessor( PaUtilBufferProcessor* bufferProcessor );


unsigned long PaUtil_GetBufferProcessorInputLatencyFrames( PaUtilBufferProcessor* bufferProcessor );

unsigned long PaUtil_GetBufferProcessorOutputLatencyFrames( PaUtilBufferProcessor* bufferProcessor );



void PaUtil_SetInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
        unsigned long frameCount );

        
void PaUtil_SetNoInput( PaUtilBufferProcessor* bufferProcessor );


void PaUtil_SetInputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data, unsigned int stride );


void PaUtil_SetInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
        unsigned int firstChannel, void *data, unsigned int channelCount );


void PaUtil_SetNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data );


void PaUtil_Set2ndInputFrameCount( PaUtilBufferProcessor* bufferProcessor,
        unsigned long frameCount );

void PaUtil_Set2ndInputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data, unsigned int stride );

void PaUtil_Set2ndInterleavedInputChannels( PaUtilBufferProcessor* bufferProcessor,
        unsigned int firstChannel, void *data, unsigned int channelCount );

void PaUtil_Set2ndNonInterleavedInputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data );

        
void PaUtil_SetOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
        unsigned long frameCount );


void PaUtil_SetNoOutput( PaUtilBufferProcessor* bufferProcessor );


void PaUtil_SetOutputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data, unsigned int stride );


void PaUtil_SetInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
        unsigned int firstChannel, void *data, unsigned int channelCount );

        
void PaUtil_SetNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data );


void PaUtil_Set2ndOutputFrameCount( PaUtilBufferProcessor* bufferProcessor,
        unsigned long frameCount );

void PaUtil_Set2ndOutputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data, unsigned int stride );

void PaUtil_Set2ndInterleavedOutputChannels( PaUtilBufferProcessor* bufferProcessor,
        unsigned int firstChannel, void *data, unsigned int channelCount );

void PaUtil_Set2ndNonInterleavedOutputChannel( PaUtilBufferProcessor* bufferProcessor,
        unsigned int channel, void *data );


void PaUtil_BeginBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
        PaStreamCallbackTimeInfo* timeInfo, PaStreamCallbackFlags callbackStatusFlags );

        
unsigned long PaUtil_EndBufferProcessing( PaUtilBufferProcessor* bufferProcessor,
        int *callbackResult );


int PaUtil_IsBufferProcessorOutputEmpty( PaUtilBufferProcessor* bufferProcessor );


unsigned long PaUtil_CopyInput( PaUtilBufferProcessor* bufferProcessor,
        void **buffer, unsigned long frameCount );


/* Copy samples from a user supplied buffer to host output channels set up by
 the PaUtil_Set*OutputChannels functions. This function is intended for use with
 blocking read/write streams. Copies the minimum of the number of
 user frames (specified by the frameCount parameter) and the number of
 host frames (specified in a previous call to SetOutputFrameCount()).

 @param bufferProcessor The buffer processor.

 @param buffer A pointer to the user buffer pointer, or a pointer to a pointer
 to an array of user buffer pointers for a non-interleaved stream. It is
 important that this parameter points to a copy of the user buffer pointers,
 not to the actual user buffer pointers, because this function updates the
 pointers before returning.

 @param frameCount The number of frames of data in the buffer(s) pointed to by
 the buffer parameter.

 @return The number of frames copied. The buffer pointer(s) pointed to by the
 buffer parameter are advanced to point to the frame(s) following the last one
 copied.
*/
unsigned long PaUtil_CopyOutput( PaUtilBufferProcessor* bufferProcessor,
        const void ** buffer, unsigned long frameCount );


/* Zero samples in host output channels set up by the PaUtil_Set*OutputChannels
 functions. This function is useful for flushing streams.
 Zeros the minimum of frameCount and the number of host frames specified in a
 previous call to SetOutputFrameCount().

 @param bufferProcessor The buffer processor.

 @param frameCount The maximum number of frames to zero.
 
 @return The number of frames zeroed.
*/
unsigned long PaUtil_ZeroOutput( PaUtilBufferProcessor* bufferProcessor,
        unsigned long frameCount );


#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* PA_PROCESS_H */