Enhancement Proposals Index, PortAudio Home Page
Updated: October 21, 2002
This proposal summarises the structure of the common implementation infrastructure developed in the v19-devel branch. At the time of writing, buffer conversion routines for blocking read/write streams still needed to be written.
PortAudio internally defines a set of helper functions that all implementations share. It is envisaged that these functions will need to be revised in response to the current API change proposals. It would also be beneficial to take this opportunity to refactor any other common code fragments that could be shared by multiple implementations.
A refactoring of the buffer data conversion functions was proposed here: http://techweb.rfa.org/pipermail/portaudio/2001-November/000244.html However the proposal below is not quite the same. A significant benefit of formally specifying the interface to the buffer conversion functions is that it would facilitate the creation of optimised assembly language versions for different platforms.
A common set of buffer conversion functions should be defined and shared by all implementations. The buffer conversion functions should handle all permutations of:
"Channel-compensation" is necessary when certain devices require a higher number of channels than the user requests. With the Midiman Delta1010, for example, the device always needs to be fed 10 channels of output and you must read 12 channels of input (at least under ALSA without the "plug" interface).
The conversions functions should conform to a common signature so that most code can just use opaque function pointers selected by a selector function based on parameters provided by the client.
When the client requested format and the host format are different a temporary buffer may be required to hold the converted data. However, in general PortAudio should aim to convert data in-place. Functions may be needed to establish when temporary buffers are needed, and to allocate them.
Due to a mismatch between the API buffer size and the PortAudio callback buffer size some Host APIs require PortAudio to shuffle data among multiple buffers in order to fulfil client requests.
Note: please see the documentation comments in the header files listed below for futher information about each feature.
The following functionality is required by more than one PortAudio implementation, and as a result is made available as common infrastructure:
In addition to the items listed above, a common framework (pa_front.c) is provided that implements support for multiple host APIs in a single build - this framework validates client input wherever possible and enforces many of the datails of the PortAudio API specification. It virtualizes both host API (pa_hostapi.h) and stream implementations (pa_stream.h).
Functions used by the framework that may be needed by more than one implementation on a single platform are declared in pa_util.h and must be implemented for each platform.
At one point it was suggested that the standard conversion functions should handle byte swapping. However, this would have doubled the number of conversion functions which was deemed unacceptable given the small number of host APIs requiring byte swapping. In the end it was concluded that implementations requiring byte swapping should perform the swapping themselves prior to calling the common conversion functions.
This proposal only effects PortAudio implementors. Increasing the utility of shared code will improve the quality of all PortAudio implementations in terms of speed, size, and robustness. It should also reduce the effort involved in porting PortAudio to a new host API.