← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/third_party/portaudio/src/common/pa_process.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/third_party/portaudio/src/common/pa_process.h
 
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 */