| 39 | | <P>PortAudio defines a set of helper functions that all implementations share. It is envisaged that these internal functions will need to be revised in response to the changes proposed in this document. It would also be beneficial to take this opportunity to refactor any other common code fragments that could be shared by multiple implementations.</P> |
| 40 | | <P>A refactoring of the buffer data conversion functions was proposed here: <A HREF="http://techweb.rfa.org/pipermail/portaudio/2001-November/000244.html">http://techweb.rfa.org/pipermail/portaudio/2001-November/000244.html</A> 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.</P> |
| | 31 | <P>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. |
| | 32 | </P> |
| | 33 | <P> |
| | 34 | A refactoring of the buffer data conversion functions was proposed here: <A HREF="http://techweb.rfa.org/pipermail/portaudio/2001-November/000244.html">http://techweb.rfa.org/pipermail/portaudio/2001-November/000244.html</A> 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. |
| | 35 | </P> |
| 53 | | <P>"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).</P> |
| 54 | | <P>The conversion functions could look something like:</P> |
| 55 | | <PRE>void ConversionFunction_DestType_DestInterleave_SrcType_SrcInterleave_ ( void *dest, int destChannels, void *src, int srcChannels, int frames );</PRE> |
| 56 | | <P>The dest and src parameters have the same format as those supplied to the PortAudio client callback.</P> |
| 57 | | <P>Rather than have each implementation call these conversion functions directly, a 'factory function' could be implemented that returns a pointer to a conversion function based on parameters specifying the format of the source and destination buffers. This factory function could be called as needed when a stream is opened. The conversion functions could then be made static and hidden from the rest of PortAudio. The 'factory function' could have the following form:</P> |
| 58 | | <PRE>enum PaEndiannes { paBigEndian, paSmallEndian, paHostEndian }; |
| | 52 | <P> |
| | 53 | "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). |
| | 54 | </P> |
| 60 | | PaBufferConversionFunction* Pa_GetBufferConversionFunction( |
| 61 | | PaSampleFormat destFormat, int destChannels, PaEndianness destEndianness, |
| 62 | | PaSampleFormat srcFormat, int srcChannels, PaEndianness srcEndianness );</PRE> |
| 63 | | <P>Note that the interleave/deinterleave status is encoded in the destFormat and srcFormat parameters. paHostEndian is used to represent the endianness of the current platform since some host APIs (eg ASIO) allow the driver to use samples in a different endianness from the host endianness. Another alternative is to encode sample endianness in PaSampleFormat - this would allow clients to write sample data of either endianness to PortAudio (e.g. soundfile playback direct from file) and benefit from PortAudio's byte swapping code.</P> |
| 64 | | <P>The redundant use of channel parameters in both the conversion functions and the factory function is intentional and would allow channel-optimised conversion functions to be supplied for common cases such as 16-bit stereo.</P> |
| | 56 | <P> |
| | 57 | 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. |
| | 58 | </P> |
| | 59 | |
| | 60 | <P> |
| | 61 | 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. |
| | 62 | </P> |
| | 63 | |
| | 64 | <P> |
| | 65 | 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. |
| | 66 | </P> |
| | 67 | |
| | 68 | <H4>Proposal</H4> |
| | 69 | |
| | 70 | <P> |
| | 71 | Note: please see the documentation comments in the header files listed below for futher information about each feature. |
| | 72 | </P> |
| | 73 | |
| | 74 | <P> |
| | 75 | The following functionality is required by more than one PortAudio implementation, and as a result is made available as common infrastructure: |
| | 76 | </P> |
| | 77 | |
| | 78 | <UL> |
| | 79 | <LI>Sample format conversion including dithering (pa_converters.c/h)</LI> |
| | 80 | <LI>CPU load measurement (pa_cpuload.c/h)</LI> |
| | 81 | <LI>Callback buffer size and interleave adaption (pa_process.c/h)</LI> |
| | 82 | <LI>Debug tracing (pa_trace.c/h)</LI> |
| | 83 | </UL> |
| | 84 | |
| | 85 | <P> 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). |
| | 86 | </P> |
| | 87 | |
| | 88 | <P> |
| | 89 | 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. |
| | 90 | </P> |
| | 91 | |
| 68 | | <P>This proposal currently only addresses buffer conversion functions, however it is important to identify other common code fragments that could be placed in the shared PortAudio library.</P> |
| 69 | | <P>This proposal has not yet addressed the fact that the conversion functions also need to handle clipping and dithering.</P> |
| 70 | | <P>It is not clear whether additional conversion functions will be needed to accommodate the MME interleaved stereo pairs for multichannel devices proposal.</P> |
| 71 | | <P>It hasn't been established whether PortAudio will be extended to support all PaSampleFormats on all devices.</P> |
| 72 | | <P>It isn't clear whether paCustomFormat is viable under this proposal, or how it would be accommodated.</P> |
| 73 | | <P>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.</P> |
| 74 | | <P>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 - this has not yet been considered within the current proposal.</P> |
| 75 | | <P>Memory allocation should probably be handled with platform specific functions such as Win32 GlobalAlloc() rather than using malloc()</P> |
| | 95 | <P> |
| | 96 | 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. |
| | 97 | </P> |
| | 98 | |
| | 99 | |
