Enhancement Proposals Index, PortAudio Home Page
Updated: July 23, 2002
This proposal is sufficiently well defined to be implemented and has been implemented in v19-devel.
PortAudio functions that return global information typically have names of the form Pa_Get*() (eg. Pa_GetDeviceInfo). However functions retrieving information from a stream do not currently (V18) follow this convention (Pa_StreamActive() and Pa_StreamTime()), additionally the Pa_GetCPULoad() function operates on a stream, but does not contain stream in its name.
PortAudio functions and parameter names that operate on integer identifiers use the string ID (all uppercase.) The paInvalidDeviceId error code is an exception to this convention.
Originally the basic stream type was PortAudioStream and there was a #define to make PaStream equivalent. The basic stream type will be renamed PaStream and PortAudioStream will no longer be defined.
PortAudioStream -> PaStream
Rename the stream accessor functions as follows:
Pa_StreamActive() -> Pa_IsStreamActive() Pa_GetCPULoad() -> Pa_GetStreamCpuLoad()
Note that CPU becomes Cpu, the convention of only capitalising the first letter of an acronym has been adopted in other proposals too.
Although a function Pa_GetStreamTime() exists in the new API, this function provides different functionality to the old Pa_StreamTime() function and is not simply a renaming.
Rename device identifier types and functions as follows:
paInvalidDeviceId -> paInvalidDevice PaDeviceID -> PaDeviceIndex Pa_GetDefaultInputDeviceID() -> Pa_GetDefaultInputDevice() Pa_GetDefaultOutputDeviceID() -> Pa_GetDefaultOutputDevice()
The use of the term index in PaDeviceIndex clearly denotes that the types has values within a closed range and may be incremented or decremented to access adjacent values. The ommission of "Index" from paInvalidDevice and the Pa_GetDefault* functions is justified by the fact that the only public representation of a device is its index.
This proposal improves the consistency of the naming scheme making the API easier to learn and remember. All clients which currently call Pa_GetCPULoad(), Pa_StreamActive(), Pa_GetDefaultInputDeviceID(), or Pa_GetDefaultOutputDeviceID() will need to alter their code by renaming the function call. Clients who explicitly check for the paInvalidDeviceId error code, or use the PaDeviceID type will have to edit the spelling of these identifiers.