From 9c0e19a3be2288db79e2502e5fa450c3e20a668d Mon Sep 17 00:00:00 2001 From: Guenter Geiger Date: Fri, 9 May 2003 16:04:00 +0000 Subject: This commit was generated by cvs2svn to compensate for changes in r610, which included commits to RCS files with non-trunk default branches. svn path=/trunk/; revision=611 --- pd/portaudio/V19-devel-readme.txt | 230 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 pd/portaudio/V19-devel-readme.txt (limited to 'pd/portaudio/V19-devel-readme.txt') diff --git a/pd/portaudio/V19-devel-readme.txt b/pd/portaudio/V19-devel-readme.txt new file mode 100644 index 00000000..a6bca780 --- /dev/null +++ b/pd/portaudio/V19-devel-readme.txt @@ -0,0 +1,230 @@ +STATUS: + +MME, DirectSound and ASIO versions are more-or-less working. See FIXMEs @todos +and the proposals matrix at portaudio.com for further status. + + The following tests might run if you're lucky: + tests/pa_devs.c + tests/patest_sine.c + tests/pa_fuzz.c + + tests/patest1.c + +The PaUtil support code is finished enough for other implementations to be +ported. No changes are expected to be made to the definition of the PaUtil +functions. + +Note that it's not yet 100% clear how the current support functions +will interact with blocking read/write streams. + +BUILD INSTRUCTIONS + +to build tests/patest_sine.c you will need to compile and link the following +files (MME) +pa_common\pa_process.c +pa_common\pa_skeleton.c +pa_common\pa_stream.c +pa_common\pa_trace.c +pa_common\pa_byteswappers.c +pa_common\pa_converters.c +pa_common\pa_cpuload.c +pa_common\pa_dither.c +pa_common\pa_front.c +pa_common\pa_allocation.h +pa_win\pa_win_util.c +pa_win\pa_win_hostapis.c +pa_win_wmme\pa_win_wmme.c + +see below for a description of these files. + + +FILES: + +portaudio.h + public api header file + +pa_front.c + implements the interface defined in portaudio.h. manages multiple host apis. + validates function parameters before calling through to host apis. tracks + open streams and closes them at Pa_Terminate(). + +pa_util.h + declares utility functions for use my implementations. including utility + functions which must be implemented separately for each platform. + +pa_hostapi.h + hostapi representation structure used to interface between pa_front.c + and implementations + +pa_stream.c/h + stream interface and representation structures and helper functions + used to interface between pa_front.c and implementations + +pa_cpuload.c/h + source and header for cpu load calculation facility + +pa_trace.c/h + source and header for debug trace log facility + +pa_byteswappers.c/h + byte swapping facility + +pa_converters.c/h + sample buffer conversion facility + +pa_dither.c/h + dither noise generator + +pa_process.c/h + callback buffer processing facility including interleave and block adaption + +pa_allocation.c/h + allocation context for tracking groups of allocations + +pa_skeleton.c + an skeleton implementation showing how the common code can be used. + +pa_win_util.c + Win32 implementation of platform specific PaUtil functions (memory allocation, + usec clock, Pa_Sleep().) The file will be used with all Win32 host APIs. + +pa_win_hostapis.c + contains the paHostApiInitializers array and an implementation of + Pa_GetDefaultHostApi() for win32 builds. + +pa_win_wmme.c + Win32 host api implementation for the windows multimedia extensions audio API. + +pa_win_wmme.h + public header file containing interfaces to mme-specific functions and the + deviceInfo data structure. + + +CODING GUIDELINES: + +naming conventions: + #defines begin with PA_ + #defines local to a file end with _ + global utility variables begin with paUtil + global utility types begin with PaUtil (including function types) + global utility functions begin with PaUtil_ + static variables end with _ + static constants begin with const and end with _ + static funtions have no special prefix/suffix + +In general, implementations should declare all of their members static, +except for their initializer which should be exported. All exported names +should be preceeded by Pa_ where MN is the module name, for example +the windows mme initializer should be named PaWinWmme_Initialize(). + +Every host api should define an initializer which returns an error code +and a PaHostApiInterface*. The initializer should only return an error other +than paNoError if it encounters an unexpected and fatal error (memory allocation +error for example). In general, there may be conditions under which it returns +a NULL interface pointer and also returns paNoError. For example, if the ASIO +implementation detects that ASIO is not installed, it should return a +NULL interface, and paNoError. + +Platform-specific shared functions should begin with Pa_ where PN is the +platform name. eg. PaWin_ for windows, PaUnix_ for unix. + +The above two conventions should also be followed whenever it is necessary to +share functions accross multiple source files. + +Two utilities for debug messages are provided. The PA_DEBUG macro defined in +pa_implementation.h provides a simple way to print debug messages to stderr. +Due to real-time performance issues, PA_DEBUG may not be suitable for use +within the portaudio processing callback, or in other threads. In such cases +the event tracing facility provided in pa_trace.h may be more appropriate. + +If PA_LOG_API_CALLS is defined, all calls to the public PortAudio API +will be logged to stderr along with parameter and return values. + + +TODO: + (this list is totally out of date) + + finish coding converter functions in pa_converters.c (anyone?) + + implement block adaption in pa_process.c (phil?) + + fix all current tests to work with new code. this should mostly involve + changing PortAudioStream to PaStream, and GetDefaultDeviceID to GetDefaultDevice etc. + + write some new tests to exercise the multi-api functions + + write (doxygen) documentation for pa_trace (phil?) + + remove unused typeids from PaHostAPITypeID + + create a global configuration file which documents which PA_ defines can be + used for configuration + + need a coding standard for comment formatting + + migrate directx (phil) + + migrate asio (ross?, stephane?) + + see top of pa_win_wmme.c for MME todo items (ross) + + write style guide document (ross) + + +DESIGN ISSUES: + (this list is totally out of date) + + consider removing Pa_ConvertHostApiDeviceIndexToGlobalDeviceIndex() from the API + + switch to new latency parameter mechanism now (?) + + question: if input or outputDriverInfo structures are passed for a different + hostApi from the one being called, do we return an error or just ignore + them? (i think return error) + + consider renaming PortAudioCallback to PaStreamCallback + + consider renaming PaError, PaResult + + +ASSORTED DISORGANISED NOTES: + + NOTE: + pa_lib.c performs the following validations for Pa_OpenStream() which we do not currently do: + - checks the device info to make sure that the device supports the requested sample rate, + it may also change the sample rate to the "closest available" sample rate if it + is within a particular error margin + + rationale for breaking up internalPortAudioStream: + each implementation has its own requirements and behavior, and should be + able to choose the best way to operate without being limited by the + constraints imposed by a common infrastructure. in other words the + implementations should be able to pick and choose services from the + common infrastructure. currently identified services include: + + - cpu load tracking + - buffering and conversion service (same code works for input and output) + - should support buffer multiplexing (non-integer length input and output buffers) + - in-place conversion where possible (only for callback, read/write always copies) + - should manage allocation of temporary buffers if necessary + - instrumentation (should be able to be disabled): callback count, framesProcessed + - common data: magic, streamInterface, callback, userdata + + +- conversion functions: + - should handle temp buffer allocation + - dithering (random number state per-stream) + - buffer size mismatches + - with new buffer slip rules, temp buffers may always be needed + - we should aim for in-place conversion wherever possible + - does phil's code support in-place conversion? (yes) + +- dicuss relationship between user and host buffer sizes + - completely independent.. individual implementations may constrain + host buffer sizes if necessary + + +- discuss device capabilities: + - i'd like to be able to request certain information: + - channel count for example + -- cgit v1.2.1