/*
	This file was a scribble area during the early phases of development.

	It's out of date but will probably hang around untill all the content 
	has been cleaned out or found a new home.

	Here's some tasks to undertake:
		o- make sure that the @brief comments in each file are at least
			as good as the file descriptions below, then delete the file
			descriptions below.

		o- make sure that the coding guidelines below appear in the
			pa_proposals style guide, then delete from below.

		o- verify and move the TODO items into TRAC
*/


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_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<MN>_ 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<PN>_ 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: (these need to be turned into TRAC items)
    write some new tests to exercise the multi-host-api functions

    write (doxygen) documentation for pa_trace (phil?)

    create a global configuration file which documents which PA_ defines can be
    used for configuration

    need a coding standard for comment formatting

    write style guide document (ross)