1
this file is very out of date, needs to be fixed -- rossb 23rd August 2006.
6
MME, DirectSound and ASIO versions are more-or-less working. See FIXMEs @todos
7
and the proposals matrix at portaudio.com for further status.
9
The pa_tests directory contains tests. pa_tests/README.txt notes which tests
12
The PaUtil support code is finished enough for other implementations to be
13
ported. No changes are expected to be made to the definition of the PaUtil
16
Note that it's not yet 100% clear how the current support functions
17
will interact with blocking read/write streams.
21
to build tests/patest_sine.c you will need to compile and link the following
23
pa_common\pa_process.c
24
pa_common\pa_skeleton.c
27
pa_common\pa_converters.c
28
pa_common\pa_cpuload.c
31
pa_common\pa_allocation.h
33
pa_win\pa_win_hostapis.c
34
pa_win_wmme\pa_win_wmme.c
36
see below for a description of these files.
42
public api header file
45
implements the interface defined in portaudio.h. manages multiple host apis.
46
validates function parameters before calling through to host apis. tracks
47
open streams and closes them at Pa_Terminate().
50
declares utility functions for use my implementations. including utility
51
functions which must be implemented separately for each platform.
54
hostapi representation structure used to interface between pa_front.c
58
stream interface and representation structures and helper functions
59
used to interface between pa_front.c and implementations
62
source and header for cpu load calculation facility
65
source and header for debug trace log facility
68
sample buffer conversion facility
71
dither noise generator
74
callback buffer processing facility including interleave and block adaption
77
allocation context for tracking groups of allocations
80
an skeleton implementation showing how the common code can be used.
83
Win32 implementation of platform specific PaUtil functions (memory allocation,
84
usec clock, Pa_Sleep().) The file will be used with all Win32 host APIs.
87
contains the paHostApiInitializers array and an implementation of
88
Pa_GetDefaultHostApi() for win32 builds.
91
Win32 host api implementation for the windows multimedia extensions audio API.
94
public header file containing interfaces to mme-specific functions and the
95
deviceInfo data structure.
101
#defines begin with PA_
102
#defines local to a file end with _
103
global utility variables begin with paUtil
104
global utility types begin with PaUtil (including function types)
105
global utility functions begin with PaUtil_
106
static variables end with _
107
static constants begin with const and end with _
108
static funtions have no special prefix/suffix
110
In general, implementations should declare all of their members static,
111
except for their initializer which should be exported. All exported names
112
should be preceeded by Pa<MN>_ where MN is the module name, for example
113
the windows mme initializer should be named PaWinWmme_Initialize().
115
Every host api should define an initializer which returns an error code
116
and a PaHostApiInterface*. The initializer should only return an error other
117
than paNoError if it encounters an unexpected and fatal error (memory allocation
118
error for example). In general, there may be conditions under which it returns
119
a NULL interface pointer and also returns paNoError. For example, if the ASIO
120
implementation detects that ASIO is not installed, it should return a
121
NULL interface, and paNoError.
123
Platform-specific shared functions should begin with Pa<PN>_ where PN is the
124
platform name. eg. PaWin_ for windows, PaUnix_ for unix.
126
The above two conventions should also be followed whenever it is necessary to
127
share functions accross multiple source files.
129
Two utilities for debug messages are provided. The PA_DEBUG macro defined in
130
pa_implementation.h provides a simple way to print debug messages to stderr.
131
Due to real-time performance issues, PA_DEBUG may not be suitable for use
132
within the portaudio processing callback, or in other threads. In such cases
133
the event tracing facility provided in pa_trace.h may be more appropriate.
135
If PA_LOG_API_CALLS is defined, all calls to the public PortAudio API
136
will be logged to stderr along with parameter and return values.
140
(this list is totally out of date)
142
finish coding converter functions in pa_converters.c (anyone?)
144
implement block adaption in pa_process.c (phil?)
146
fix all current tests to work with new code. this should mostly involve
147
changing PortAudioStream to PaStream, and GetDefaultDeviceID to GetDefaultDevice etc.
149
write some new tests to exercise the multi-api functions
151
write (doxygen) documentation for pa_trace (phil?)
153
remove unused typeids from PaHostAPITypeID
155
create a global configuration file which documents which PA_ defines can be
156
used for configuration
158
need a coding standard for comment formatting
160
migrate directx (phil)
162
migrate asio (ross?, stephane?)
164
see top of pa_win_wmme.c for MME todo items (ross)
166
write style guide document (ross)
170
(this list is totally out of date)
172
consider removing Pa_ConvertHostApiDeviceIndexToGlobalDeviceIndex() from the API
174
switch to new latency parameter mechanism now (?)
176
question: if input or outputDriverInfo structures are passed for a different
177
hostApi from the one being called, do we return an error or just ignore
178
them? (i think return error)
180
consider renaming PortAudioCallback to PaStreamCallback
182
consider renaming PaError, PaResult
185
ASSORTED DISORGANISED NOTES:
188
pa_lib.c performs the following validations for Pa_OpenStream() which we do not currently do:
189
- checks the device info to make sure that the device supports the requested sample rate,
190
it may also change the sample rate to the "closest available" sample rate if it
191
is within a particular error margin
193
rationale for breaking up internalPortAudioStream:
194
each implementation has its own requirements and behavior, and should be
195
able to choose the best way to operate without being limited by the
196
constraints imposed by a common infrastructure. in other words the
197
implementations should be able to pick and choose services from the
198
common infrastructure. currently identified services include:
201
- buffering and conversion service (same code works for input and output)
202
- should support buffer multiplexing (non-integer length input and output buffers)
203
- in-place conversion where possible (only for callback, read/write always copies)
204
- should manage allocation of temporary buffers if necessary
205
- instrumentation (should be able to be disabled): callback count, framesProcessed
206
- common data: magic, streamInterface, callback, userdata
209
- conversion functions:
210
- should handle temp buffer allocation
211
- dithering (random number state per-stream)
212
- buffer size mismatches
213
- with new buffer slip rules, temp buffers may always be needed
214
- we should aim for in-place conversion wherever possible
215
- does phil's code support in-place conversion? (yes)
217
- dicuss relationship between user and host buffer sizes
218
- completely independent.. individual implementations may constrain
219
host buffer sizes if necessary
222
- discuss device capabilities:
223
- i'd like to be able to request certain information:
224
- channel count for example
added
removed
lib-src/portaudio-v19/V19-devel-readme.txt
