Proposed Enhancements to PortAudio

Updated: April 26, 2004

Introduction

This document links to a series of proposals currently being considered by the PortAudio developer community. Most of the proposals propose changes to the definition of the PortAudio API or to the way that PortAudio behaves in specific circumstances, some proposals (such as the style guide) are concerned with the way in which PortAudio is implemented.

The proposals are intended to capture the current state of discussions - when finalised they will be treated as specifications that will guide implementation. The authors are the various members of the PortAudio community and are too numerous to mention here. Please refer to the mailing list archives to see who said what.

Open Proposals

The following table lists the proposals currently under consideration. The majority of the listed proposals have undergone considerable peer review and are considerd complete. Most have been fully or partially implemented for at least one platform in the v19-devel CVS branch. Until version 19 is released there is a small possibility that the content of these proposals may change in response to implementation experience. If you think something is missing, could be improved, or would just like to comment please do so on the PortAudio mailing list.

Proposal	Proposal Status
001 - Pass Underflow/Overflow Information to the Stream Callback	complete
002 - Improve Device Formats Query Interface	complete
003 - Improve Latency Specification Interface	complete
004 - Allow Callbacks to Accept Variable Number of Frames per Buffer	complete
005 - Blocking Read/Write Interface	complete
006 - Non-Interleaved Buffers	complete
007 - Support for Multiple Host APIs in a Single PortAudio Build	complete
008 - Host API Specific Pa_OpenStream() Parameters	complete
009 - Handling of Host API Specific Error Codes	complete
010 - Clarify Stream State Machine and State Querying Functions	complete
011 - Rename Existing Symbols such as Pa_GetCPULoad(), PaDeviceID etc. for Consistency	complete
012 - Additional Pa_Terminate() Behavior	complete
013 - Refactor Implementation Infrastructure	complete but could always expand
014 - Implementation Style Guidelines	stable but open for discussion - used in v19-devel
015 - Improve Callback Timestamp Info	complete
016 - Use Structs for Pa_OpenStream() Parameters	complete
017 - Method for Retrieving Actual Stream Sample Rate	complete
018 - Version Information Interface	complete
019 - Notify Client When All Buffers Have Played	complete
020 - Allow Callback to Prime Stream	complete
021 - New Directory Structure	under discussion
022 - Well Defined Sample Conversion Semantics	under discussion

Potential enhancements which have not yet been developed into proposals are listed here.

Status Summary

Due to the interdependency of many of the proposed enhancements, we plan to introduce all currently proposed API enhancements simultaneously as part of release 19. The CVS repository currently contains a branch named portaudio-v19-devel where enhancements are being implemented.

All listed proposals have been reviewed and discussed by the PortAudio developer comunity. All proposals pertaining to API changes are defined in sufficient detail to be implemented. Both the 014 - Implementation Style Guidelines and 013 - Refactor Implementation Infrastructure proposals only effect implementors and do not effect the API definition itself. Refinement of these proposals is desirable but not critical to the development of release 19.

Development status is documented on the development status page.

Client Impact

Some of the proposed changes will break existing client code. Usually these breakages involve renaming of constant identifiers or function calls. In a small number of cases additional parameters will be added to existing API functions. Concerned readers are advised to consult the Impact Analysis section of each proposal for further details.