checked in pd-0.43-0.src.tar.gz

svn path=/trunk/; revision=15557

18 files changed, 366 insertions, 225 deletions

diff --git a/pd/portaudio/src/common/pa_allocation.h b/pd/portaudio/src/common/pa_allocation.h
index b265b016..811dd72e 100644
--- a/pd/portaudio/src/common/pa_allocation.h
+++ b/pd/portaudio/src/common/pa_allocation.h
@@ -1,12 +1,12 @@
 #ifndef PA_ALLOCATION_H
 #define PA_ALLOCATION_H
 /*
- * $Id: pa_allocation.h 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_allocation.h 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library allocation context header
  * memory allocation context for tracking allocation groups
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -43,12 +43,12 @@
  @ingroup common_src
 
  @brief Allocation Group prototypes. An Allocation Group makes it easy to
- allocate multiple blocks of memory and free them all simultanously.
+ allocate multiple blocks of memory and free them all at once.
  
  An allocation group is useful for keeping track of multiple blocks
  of memory which are allocated at the same time (such as during initialization)
  and need to be deallocated at the same time. The allocation group maintains
- a list of allocated blocks, and can deallocate them all simultaneously which
+ a list of allocated blocks, and can free all allocations at once. This
  can be usefull for cleaning up after a partially initialized object fails.
 
  The allocation group implementation is built on top of the lower
diff --git a/pd/portaudio/src/common/pa_converters.c b/pd/portaudio/src/common/pa_converters.c
index 3b98c858..965c1460 100644
--- a/pd/portaudio/src/common/pa_converters.c
+++ b/pd/portaudio/src/common/pa_converters.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_converters.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_converters.c 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library sample conversion mechanism
  *
  * Based on the Open Source API proposed by Ross Bencina
@@ -39,7 +39,7 @@
 /** @file
  @ingroup common_src
 
- @brief Conversion functions implementations.
+ @brief Conversion function implementations.
  
  If the C9x function lrintf() is available, define PA_USE_C99_LRINTF to use it
 
diff --git a/pd/portaudio/src/common/pa_debugprint.c b/pd/portaudio/src/common/pa_debugprint.c
index 33fcf32e..a878028c 100644
--- a/pd/portaudio/src/common/pa_debugprint.c
+++ b/pd/portaudio/src/common/pa_debugprint.c
@@ -74,8 +74,11 @@ void PaUtil_SetDebugPrintFunction(PaUtilLogCallback cb)
  VERY dangerous alternative, vsprintf (with no n)

  */

 

-#if (_MSC_VER) && (_MSC_VER < 1400)

-#define VSNPRINTF  _vsnprintf

+#if _MSC_VER

+/* Some Windows Mobile SDKs don't define vsnprintf but all define _vsnprintf (hopefully).

+   According to MSDN "vsnprintf is identical to _vsnprintf". So we use _vsnprintf with MSC.

+*/

+#define VSNPRINTF  _vsnprintf 

 #else

 #define VSNPRINTF  vsnprintf

 #endif

diff --git a/pd/portaudio/src/common/pa_dither.c b/pd/portaudio/src/common/pa_dither.c
index 6f6c9a1a..7a1b1312 100644
--- a/pd/portaudio/src/common/pa_dither.c
+++ b/pd/portaudio/src/common/pa_dither.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_dither.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_dither.c 1418 2009-10-12 21:00:53Z philburk $
  * Portable Audio I/O Library triangular dither generator
  *
  * Based on the Open Source API proposed by Ross Bencina
@@ -42,9 +42,14 @@
  @brief Functions for generating dither noise
 */
 
-
-#include "pa_dither.h"
 #include "pa_types.h"
+#include "pa_dither.h"
+
+
+/* Note that the linear congruential algorithm requires 32 bit integers
+ * because it uses arithmetic overflow. So use PaUint32 instead of
+ * unsigned long so it will work on 64 bit systems.
+ */
 
 #define PA_DITHER_BITS_   (15)
 
@@ -57,9 +62,9 @@ void PaUtil_InitializeTriangularDitherState( PaUtilTriangularDitherGenerator *st
 }
 
 
-signed long PaUtil_Generate16BitTriangularDither( PaUtilTriangularDitherGenerator *state )
+PaInt32 PaUtil_Generate16BitTriangularDither( PaUtilTriangularDitherGenerator *state )
 {
-    signed long current, highPass;
+    PaInt32 current, highPass;
 
     /* Generate two random numbers. */
     state->randSeed1 = (state->randSeed1 * 196314165) + 907633515;
@@ -69,9 +74,10 @@ signed long PaUtil_Generate16BitTriangularDither( PaUtilTriangularDitherGenerato
      * Shift before adding to prevent overflow which would skew the distribution.
      * Also shift an extra bit for the high pass filter. 
      */
-#define DITHER_SHIFT_  ((SIZEOF_LONG*8 - PA_DITHER_BITS_) + 1)
-    current = (((signed long)state->randSeed1)>>DITHER_SHIFT_) +
-              (((signed long)state->randSeed2)>>DITHER_SHIFT_);
+#define DITHER_SHIFT_  ((sizeof(PaInt32)*8 - PA_DITHER_BITS_) + 1)
+	
+    current = (((PaInt32)state->randSeed1)>>DITHER_SHIFT_) +
+              (((PaInt32)state->randSeed2)>>DITHER_SHIFT_);
 
     /* High pass filter to reduce audibility. */
     highPass = current - state->previous;
@@ -86,7 +92,7 @@ static const float const_float_dither_scale_ = PA_FLOAT_DITHER_SCALE_;
 
 float PaUtil_GenerateFloatTriangularDither( PaUtilTriangularDitherGenerator *state )
 {
-    signed long current, highPass;
+    PaInt32 current, highPass;
 
     /* Generate two random numbers. */
     state->randSeed1 = (state->randSeed1 * 196314165) + 907633515;
@@ -96,9 +102,8 @@ float PaUtil_GenerateFloatTriangularDither( PaUtilTriangularDitherGenerator *sta
      * Shift before adding to prevent overflow which would skew the distribution.
      * Also shift an extra bit for the high pass filter. 
      */
-#define DITHER_SHIFT_  ((SIZEOF_LONG*8 - PA_DITHER_BITS_) + 1)
-    current = (((signed long)state->randSeed1)>>DITHER_SHIFT_) +
-              (((signed long)state->randSeed2)>>DITHER_SHIFT_);
+    current = (((PaInt32)state->randSeed1)>>DITHER_SHIFT_) +
+              (((PaInt32)state->randSeed2)>>DITHER_SHIFT_);
 
     /* High pass filter to reduce audibility. */
     highPass = current - state->previous;
diff --git a/pd/portaudio/src/common/pa_dither.h b/pd/portaudio/src/common/pa_dither.h
index e77ce470..a5131b27 100644
--- a/pd/portaudio/src/common/pa_dither.h
+++ b/pd/portaudio/src/common/pa_dither.h
@@ -1,7 +1,7 @@
 #ifndef PA_DITHER_H
 #define PA_DITHER_H
 /*
- * $Id: pa_dither.h 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_dither.h 1418 2009-10-12 21:00:53Z philburk $
  * Portable Audio I/O Library triangular dither generator
  *
  * Based on the Open Source API proposed by Ross Bencina
@@ -44,18 +44,24 @@
  @brief Functions for generating dither noise
 */
 
+#include "pa_types.h"
+
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif /* __cplusplus */
 
+/* Note that the linear congruential algorithm requires 32 bit integers
+ * because it uses arithmetic overflow. So use PaUint32 instead of
+ * unsigned long so it will work on 64 bit systems.
+ */
 
 /** @brief State needed to generate a dither signal */
 typedef struct PaUtilTriangularDitherGenerator{
-    unsigned long previous;
-    unsigned long randSeed1;
-    unsigned long randSeed2;
+    PaUint32 previous;
+    PaUint32 randSeed1;
+    PaUint32 randSeed2;
 } PaUtilTriangularDitherGenerator;
 
 
@@ -73,9 +79,9 @@ void PaUtil_InitializeTriangularDitherState( PaUtilTriangularDitherGenerator *di
     signed short out = (signed short)(((in>>1) + dither) >> 15);
 </pre>
  @return
- A signed long with a range of +32767 to -32768
+ A signed 32-bit integer with a range of +32767 to -32768
 */
-signed long PaUtil_Generate16BitTriangularDither( PaUtilTriangularDitherGenerator *ditherState );
+PaInt32 PaUtil_Generate16BitTriangularDither( PaUtilTriangularDitherGenerator *ditherState );
 
 
 /**
diff --git a/pd/portaudio/src/common/pa_endianness.h b/pd/portaudio/src/common/pa_endianness.h
index bdcc74f7..84e904ca 100644
--- a/pd/portaudio/src/common/pa_endianness.h
+++ b/pd/portaudio/src/common/pa_endianness.h
@@ -1,7 +1,7 @@
 #ifndef PA_ENDIANNESS_H
 #define PA_ENDIANNESS_H
 /*
- * $Id: pa_endianness.h 1216 2007-06-10 09:26:00Z aknudsen $
+ * $Id: pa_endianness.h 1324 2008-01-27 02:03:30Z bjornroche $
  * Portable Audio I/O Library current platform endianness macros
  *
  * Based on the Open Source API proposed by Ross Bencina
@@ -120,18 +120,22 @@ extern "C"
  and raises an assertion if they don't match. <assert.h> must be included in
  the context in which this macro is used.
 */
-#if defined(PA_LITTLE_ENDIAN)
-    #define PA_VALIDATE_ENDIANNESS \
-    { \
-        const long nativeOne = 1; \
-        assert( "PortAudio: compile time and runtime endianness don't match" && (((char *)&nativeOne)[0]) == 1 ); \
-    }
-#elif defined(PA_BIG_ENDIAN)
-    #define PA_VALIDATE_ENDIANNESS \
-    { \
-        const long nativeOne = 1; \
-        assert( "PortAudio: compile time and runtime endianness don't match" && (((char *)&nativeOne)[0]) == 0 ); \
-    }
+#if defined(NDEBUG)
+    #define PA_VALIDATE_ENDIANNESS
+#else
+    #if defined(PA_LITTLE_ENDIAN)
+        #define PA_VALIDATE_ENDIANNESS \
+        { \
+            const long nativeOne = 1; \
+            assert( "PortAudio: compile time and runtime endianness don't match" && (((char *)&nativeOne)[0]) == 1 ); \
+        }
+    #elif defined(PA_BIG_ENDIAN)
+        #define PA_VALIDATE_ENDIANNESS \
+        { \
+            const long nativeOne = 1; \
+            assert( "PortAudio: compile time and runtime endianness don't match" && (((char *)&nativeOne)[0]) == 0 ); \
+        }
+    #endif
 #endif
 
 
diff --git a/pd/portaudio/src/common/pa_front.c b/pd/portaudio/src/common/pa_front.c
index 5af90d45..28f0c60e 100644
--- a/pd/portaudio/src/common/pa_front.c
+++ b/pd/portaudio/src/common/pa_front.c
@@ -1,10 +1,10 @@
 /*
- * $Id: pa_front.c 1229 2007-06-15 16:11:11Z rossb $
+ * $Id: pa_front.c 1396 2008-11-03 19:31:30Z philburk $
  * Portable Audio I/O Library Multi-Host API front end
  * Validate function parameters and manage multiple host APIs.
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -40,17 +40,20 @@
 /** @file
  @ingroup common_src
 
- @brief Implements public PortAudio API, checks some errors, forwards to
- host API implementations.
+ @brief Implements PortAudio API functions defined in portaudio.h, checks 
+ some errors, delegates platform-specific behavior to host API implementations.
  
- Implements the functions defined in the PortAudio API, checks for
- some parameter and state inconsistencies and forwards API requests to
- specific Host API implementations (via the interface declared in
- pa_hostapi.h), and Streams (via the interface declared in pa_stream.h).
+ Implements the functions defined in the PortAudio API (portaudio.h), 
+ validates some parameters and checks for state inconsistencies before 
+ forwarding API requests to specific Host API implementations (via the 
+ interface declared in pa_hostapi.h), and Streams (via the interface 
+ declared in pa_stream.h).
 
- This file handles initialization and termination of Host API
- implementations via initializers stored in the paHostApiInitializers
- global variable.
+ This file manages initialization and termination of Host API
+ implementations via initializer functions stored in the paHostApiInitializers
+ global array (usually defined in an os-specific pa_[os]_hostapis.c file).
+
+ This file maintains a list of all open streams and closes them at Pa_Terminate().
 
  Some utility functions declared in pa_util.h are implemented in this file.
 
@@ -87,7 +90,7 @@
 
 
 #define PA_VERSION_  1899
-#define PA_VERSION_TEXT_ "PortAudio V19-devel (built " __DATE__  ")"
+#define PA_VERSION_TEXT_ "PortAudio V19-devel (built " __DATE__  " " __TIME__ ")"
 
 
 
@@ -405,6 +408,8 @@ const char *Pa_GetErrorText( PaError errorCode )
     case paCanNotWriteToACallbackStream:        result = "Can't write to a callback stream"; break;
     case paCanNotReadFromAnOutputOnlyStream:    result = "Can't read from an output only stream"; break;
     case paCanNotWriteToAnInputOnlyStream:      result = "Can't write to an input only stream"; break;
+    case paIncompatibleStreamHostApi: result = "Incompatible stream host API"; break;
+    case paBadBufferPtr:             result = "Bad buffer pointer"; break;
     default:                         
 		if( errorCode > 0 )
 			result = "Invalid error code (value greater than zero)"; 
@@ -1501,7 +1506,7 @@ const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream )
         result = 0;
 
         PA_LOGAPI(("Pa_GetStreamInfo returned:\n" ));
-        PA_LOGAPI(("\tconst PaStreamInfo*: 0 [PaError error:%d ( %s )]\n", result, error, Pa_GetErrorText( error ) ));
+        PA_LOGAPI(("\tconst PaStreamInfo*: 0 [PaError error:%d ( %s )]\n", error, Pa_GetErrorText( error ) ));
 
     }
     else
diff --git a/pd/portaudio/src/common/pa_hostapi.h b/pd/portaudio/src/common/pa_hostapi.h
index 5a86d4e9..5462d443 100644
--- a/pd/portaudio/src/common/pa_hostapi.h
+++ b/pd/portaudio/src/common/pa_hostapi.h
@@ -1,12 +1,12 @@
 #ifndef PA_HOSTAPI_H
 #define PA_HOSTAPI_H
 /*
- * $Id: pa_hostapi.h 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_hostapi.h 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library
  * host api representation
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -42,8 +42,8 @@
 /** @file
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- host APIs.
+ @brief Interfaces and representation structures used by pa_front.c 
+ to manage and communicate with host API implementations.
 */
 
 
@@ -224,13 +224,19 @@ typedef struct PaUtilHostApiRepresentation {
 /** Prototype for the initialization function which must be implemented by every
  host API.
  
+ This function 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.
+
  @see paHostApiInitializers
 */
 typedef PaError PaUtilHostApiInitializer( PaUtilHostApiRepresentation**, PaHostApiIndex );
 
 
 /** paHostApiInitializers is a NULL-terminated array of host API initialization
- functions. These functions are called by pa_front to initialize the host APIs
+ functions. These functions are called by pa_front.c to initialize the host APIs
  when the client calls Pa_Initialize().
 
  There is a platform specific file which defines paHostApiInitializers for that
diff --git a/pd/portaudio/src/common/pa_memorybarrier.h b/pd/portaudio/src/common/pa_memorybarrier.h
new file mode 100644
index 00000000..5efeed24
--- /dev/null
+++ b/pd/portaudio/src/common/pa_memorybarrier.h
@@ -0,0 +1,123 @@
+/*
+ * $Id: pa_memorybarrier.h 1240 2007-07-17 13:05:07Z bjornroche $
+ * Portable Audio I/O Library
+ * Memory barrier utilities
+ *
+ * Author: Bjorn Roche, XO Audio, LLC
+ *
+ * This program uses the PortAudio Portable Audio Library.
+ * For more information see: http://www.portaudio.com
+ * Copyright (c) 1999-2000 Ross Bencina and Phil Burk
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/*
+ * The text above constitutes the entire PortAudio license; however, 
+ * the PortAudio community also makes the following non-binding requests:
+ *
+ * Any person wishing to distribute modifications to the Software is
+ * requested to send the modifications to the original developer so that
+ * they can be incorporated into the canonical version. It is also 
+ * requested that these non-binding requests be included along with the 
+ * license above.
+ */
+
+/**
+ @file pa_memorybarrier.h
+ @ingroup common_src
+*/
+
+/****************
+ * Some memory barrier primitives based on the system.
+ * right now only OS X, FreeBSD, and Linux are supported. In addition to providing
+ * memory barriers, these functions should ensure that data cached in registers
+ * is written out to cache where it can be snooped by other CPUs. (ie, the volatile
+ * keyword should not be required)
+ *
+ * the primitives that must be defined are:
+ *
+ * PaUtil_FullMemoryBarrier()
+ * PaUtil_ReadMemoryBarrier()
+ * PaUtil_WriteMemoryBarrier()
+ *
+ ****************/
+
+#if defined(__APPLE__)
+#   include <libkern/OSAtomic.h>
+    /* Here are the memory barrier functions. Mac OS X only provides
+       full memory barriers, so the three types of barriers are the same,
+       however, these barriers are superior to compiler-based ones. */
+#   define PaUtil_FullMemoryBarrier()  OSMemoryBarrier()
+#   define PaUtil_ReadMemoryBarrier()  OSMemoryBarrier()
+#   define PaUtil_WriteMemoryBarrier() OSMemoryBarrier()
+#elif defined(__GNUC__)
+    /* GCC >= 4.1 has built-in intrinsics. We'll use those */
+#   if (__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1)
+#      define PaUtil_FullMemoryBarrier()  __sync_synchronize()
+#      define PaUtil_ReadMemoryBarrier()  __sync_synchronize()
+#      define PaUtil_WriteMemoryBarrier() __sync_synchronize()
+    /* as a fallback, GCC understands volatile asm and "memory" to mean it
+     * should not reorder memory read/writes */
+    /* Note that it is not clear that any compiler actually defines __PPC__,
+     * it can probably removed safely. */
+#   elif defined( __ppc__ ) || defined( __powerpc__) || defined( __PPC__ )
+#      define PaUtil_FullMemoryBarrier()  asm volatile("sync":::"memory")
+#      define PaUtil_ReadMemoryBarrier()  asm volatile("sync":::"memory")
+#      define PaUtil_WriteMemoryBarrier() asm volatile("sync":::"memory")
+#   elif defined( __i386__ ) || defined( __i486__ ) || defined( __i586__ ) || \
+         defined( __i686__ ) || defined( __x86_64__ )
+#      define PaUtil_FullMemoryBarrier()  asm volatile("mfence":::"memory")
+#      define PaUtil_ReadMemoryBarrier()  asm volatile("lfence":::"memory")
+#      define PaUtil_WriteMemoryBarrier() asm volatile("sfence":::"memory")
+#   else
+#      ifdef ALLOW_SMP_DANGERS
+#         warning Memory barriers not defined on this system or system unknown
+#         warning For SMP safety, you should fix this.
+#         define PaUtil_FullMemoryBarrier()
+#         define PaUtil_ReadMemoryBarrier()
+#         define PaUtil_WriteMemoryBarrier()
+#      else
+#         error Memory barriers are not defined on this system. You can still compile by defining ALLOW_SMP_DANGERS, but SMP safety will not be guaranteed.
+#      endif
+#   endif
+#elif (_MSC_VER >= 1400)
+#   include <intrin.h>
+#   pragma intrinsic(_ReadWriteBarrier)
+#   pragma intrinsic(_ReadBarrier)
+#   pragma intrinsic(_WriteBarrier)
+#   define PaUtil_FullMemoryBarrier()  _ReadWriteBarrier()
+#   define PaUtil_ReadMemoryBarrier()  _ReadBarrier()
+#   define PaUtil_WriteMemoryBarrier() _WriteBarrier()
+#elif defined(_MSC_VER) || defined(__BORLANDC__)
+#   define PaUtil_FullMemoryBarrier()  _asm { lock add    [esp], 0 }
+#   define PaUtil_ReadMemoryBarrier()  _asm { lock add    [esp], 0 }
+#   define PaUtil_WriteMemoryBarrier() _asm { lock add    [esp], 0 }
+#else
+#   ifdef ALLOW_SMP_DANGERS
+#      warning Memory barriers not defined on this system or system unknown
+#      warning For SMP safety, you should fix this.
+#      define PaUtil_FullMemoryBarrier()
+#      define PaUtil_ReadMemoryBarrier()
+#      define PaUtil_WriteMemoryBarrier()
+#   else
+#      error Memory barriers are not defined on this system. You can still compile by defining ALLOW_SMP_DANGERS, but SMP safety will not be guaranteed.
+#   endif
+#endif
diff --git a/pd/portaudio/src/common/pa_process.c b/pd/portaudio/src/common/pa_process.c
index fac474d5..4770610b 100644
--- a/pd/portaudio/src/common/pa_process.c
+++ b/pd/portaudio/src/common/pa_process.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_process.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_process.c 1408 2009-03-13 16:41:39Z rossb $
  * Portable Audio I/O Library
  * streamCallback <-> host buffer processing adapter
  *
@@ -56,8 +56,6 @@
 
     @todo Consider cache tilings for intereave<->deinterleave.
 
-    @todo implement timeInfo->currentTime int PaUtil_BeginBufferProcessing()
-
     @todo specify and implement some kind of logical policy for handling the
         underflow and overflow stream flags when the underflow/overflow overlaps
         multiple user buffers/callbacks.
@@ -683,7 +681,9 @@ void PaUtil_BeginBufferProcessing( PaUtilBufferProcessor* bp,
         
     bp->timeInfo->inputBufferAdcTime -= bp->framesInTempInputBuffer * bp->samplePeriod;
     
-    bp->timeInfo->currentTime = 0; /** FIXME: @todo time info currentTime not implemented */
+    /* We just pass through timeInfo->currentTime provided by the caller. This is
+        not strictly conformant to the word of the spec, since the buffer processor 
+        might call the callback multiple times, and we never refresh currentTime. */
 
     /* the first streamCallback will be called to generate samples which will be
         outputted after the frames currently in the output buffer have been
@@ -997,7 +997,7 @@ static unsigned long AdaptingInputOnlyProcess( PaUtilBufferProcessor *bp,
                         bp->framesPerUserBuffer, bp->timeInfo,
                         bp->callbackStatusFlags, bp->userData );
 
-                bp->timeInfo->inputBufferAdcTime += frameCount * bp->samplePeriod;
+                bp->timeInfo->inputBufferAdcTime += bp->framesPerUserBuffer * bp->samplePeriod;
             }
             
             bp->framesInTempInputBuffer = 0;
diff --git a/pd/portaudio/src/common/pa_ringbuffer.c b/pd/portaudio/src/common/pa_ringbuffer.c
index f4e1201a..ad9e2ae5 100644
--- a/pd/portaudio/src/common/pa_ringbuffer.c
+++ b/pd/portaudio/src/common/pa_ringbuffer.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_ringbuffer.c 1240 2007-07-17 13:05:07Z bjornroche $
+ * $Id: pa_ringbuffer.c 1346 2008-02-20 10:09:20Z rossb $
  * Portable Audio I/O Library
  * Ring Buffer utility.
  *
@@ -7,6 +7,8 @@
  * modified for SMP safety on Mac OS X by Bjorn Roche
  * modified for SMP safety on Linux by Leland Lucius
  * also, allowed for const where possible
+ * modified for multiple-byte-sized data elements by Sven Fischer 
+ *
  * Note that this is safe only for a single-thread reader and a
  * single-thread writer.
  *
@@ -55,93 +57,33 @@
 #include <math.h>
 #include "pa_ringbuffer.h"
 #include <string.h>
-
-/****************
- * First, we'll define some memory barrier primitives based on the system.
- * right now only OS X, FreeBSD, and Linux are supported. In addition to providing
- * memory barriers, these functions should ensure that data cached in registers
- * is written out to cache where it can be snooped by other CPUs. (ie, the volatile
- * keyword should not be required)
- *
- * the primitives that must be defined are:
- *
- * PaUtil_FullMemoryBarrier()
- * PaUtil_ReadMemoryBarrier()
- * PaUtil_WriteMemoryBarrier()
- *
- ****************/
-
-#if defined(__APPLE__)
-#   include <libkern/OSAtomic.h>
-    /* Here are the memory barrier functions. Mac OS X only provides
-       full memory barriers, so the three types of barriers are the same,
-       however, these barriers are superior to compiler-based ones. */
-#   define PaUtil_FullMemoryBarrier()  OSMemoryBarrier()
-#   define PaUtil_ReadMemoryBarrier()  OSMemoryBarrier()
-#   define PaUtil_WriteMemoryBarrier() OSMemoryBarrier()
-#elif defined(__GNUC__)
-    /* GCC >= 4.1 has built-in intrinsics. We'll use those */
-#   if (__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1)
-#      define PaUtil_FullMemoryBarrier()  __sync_synchronize()
-#      define PaUtil_ReadMemoryBarrier()  __sync_synchronize()
-#      define PaUtil_WriteMemoryBarrier() __sync_synchronize()
-    /* as a fallback, GCC understands volatile asm and "memory" to mean it
-     * should not reorder memory read/writes */
-#   elif defined( __PPC__ )
-#      define PaUtil_FullMemoryBarrier()  asm volatile("sync":::"memory")
-#      define PaUtil_ReadMemoryBarrier()  asm volatile("sync":::"memory")
-#      define PaUtil_WriteMemoryBarrier() asm volatile("sync":::"memory")
-#   elif defined( __i386__ ) || defined( __i486__ ) || defined( __i586__ ) || defined( __i686__ ) || defined( __x86_64__ )
-#      define PaUtil_FullMemoryBarrier()  asm volatile("mfence":::"memory")
-#      define PaUtil_ReadMemoryBarrier()  asm volatile("lfence":::"memory")
-#      define PaUtil_WriteMemoryBarrier() asm volatile("sfence":::"memory")
-#   else
-#      ifdef ALLOW_SMP_DANGERS
-#         warning Memory barriers not defined on this system or system unknown
-#         warning For SMP safety, you should fix this.
-#         define PaUtil_FullMemoryBarrier()
-#         define PaUtil_ReadMemoryBarrier()
-#         define PaUtil_WriteMemoryBarrier()
-#      else
-#         error Memory barriers are not defined on this system. You can still compile by defining ALLOW_SMP_DANGERS, but SMP safety will not be guaranteed.
-#      endif
-#   endif
-#else
-#   ifdef ALLOW_SMP_DANGERS
-#      warning Memory barriers not defined on this system or system unknown
-#      warning For SMP safety, you should fix this.
-#      define PaUtil_FullMemoryBarrier()
-#      define PaUtil_ReadMemoryBarrier()
-#      define PaUtil_WriteMemoryBarrier()
-#   else
-#      error Memory barriers are not defined on this system. You can still compile by defining ALLOW_SMP_DANGERS, but SMP safety will not be guaranteed.
-#   endif
-#endif
+#include "pa_memorybarrier.h"
 
 /***************************************************************************
  * Initialize FIFO.
- * numBytes must be power of 2, returns -1 if not.
+ * elementCount must be power of 2, returns -1 if not.
  */
-long PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, long numBytes, void *dataPtr )
+long PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, long elementSizeBytes, long elementCount, void *dataPtr )
 {
-    if( ((numBytes-1) & numBytes) != 0) return -1; /* Not Power of two. */
-    rbuf->bufferSize = numBytes;
+    if( ((elementCount-1) & elementCount) != 0) return -1; /* Not Power of two. */
+    rbuf->bufferSize = elementCount;
     rbuf->buffer = (char *)dataPtr;
     PaUtil_FlushRingBuffer( rbuf );
-    rbuf->bigMask = (numBytes*2)-1;
-    rbuf->smallMask = (numBytes)-1;
+    rbuf->bigMask = (elementCount*2)-1;
+    rbuf->smallMask = (elementCount)-1;
+    rbuf->elementSizeBytes = elementSizeBytes;
     return 0;
 }
 
 /***************************************************************************
-** Return number of bytes available for reading. */
+** Return number of elements available for reading. */
 long PaUtil_GetRingBufferReadAvailable( PaUtilRingBuffer *rbuf )
 {
     PaUtil_ReadMemoryBarrier();
     return ( (rbuf->writeIndex - rbuf->readIndex) & rbuf->bigMask );
 }
 /***************************************************************************
-** Return number of bytes available for writing. */
+** Return number of elements available for writing. */
 long PaUtil_GetRingBufferWriteAvailable( PaUtilRingBuffer *rbuf )
 {
     /* Since we are calling PaUtil_GetRingBufferReadAvailable, we don't need an aditional MB */
@@ -159,126 +101,126 @@ void PaUtil_FlushRingBuffer( PaUtilRingBuffer *rbuf )
 ** Get address of region(s) to which we can write data.
 ** If the region is contiguous, size2 will be zero.
 ** If non-contiguous, size2 will be the size of second region.
-** Returns room available to be written or numBytes, whichever is smaller.
+** Returns room available to be written or elementCount, whichever is smaller.
 */
-long PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, long numBytes,
+long PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, long elementCount,
                                        void **dataPtr1, long *sizePtr1,
                                        void **dataPtr2, long *sizePtr2 )
 {
     long   index;
     long   available = PaUtil_GetRingBufferWriteAvailable( rbuf );
-    if( numBytes > available ) numBytes = available;
+    if( elementCount > available ) elementCount = available;
     /* Check to see if write is not contiguous. */
     index = rbuf->writeIndex & rbuf->smallMask;
-    if( (index + numBytes) > rbuf->bufferSize )
+    if( (index + elementCount) > rbuf->bufferSize )
     {
         /* Write data in two blocks that wrap the buffer. */
         long   firstHalf = rbuf->bufferSize - index;
-        *dataPtr1 = &rbuf->buffer[index];
+        *dataPtr1 = &rbuf->buffer[index*rbuf->elementSizeBytes];
         *sizePtr1 = firstHalf;
         *dataPtr2 = &rbuf->buffer[0];
-        *sizePtr2 = numBytes - firstHalf;
+        *sizePtr2 = elementCount - firstHalf;
     }
     else
     {
-        *dataPtr1 = &rbuf->buffer[index];
-        *sizePtr1 = numBytes;
+        *dataPtr1 = &rbuf->buffer[index*rbuf->elementSizeBytes];
+        *sizePtr1 = elementCount;
         *dataPtr2 = NULL;
         *sizePtr2 = 0;
     }
-    return numBytes;
+    return elementCount;
 }
 
 
 /***************************************************************************
 */
-long PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, long numBytes )
+long PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, long elementCount )
 {
     /* we need to ensure that previous writes are seen before we update the write index */
     PaUtil_WriteMemoryBarrier();
-    return rbuf->writeIndex = (rbuf->writeIndex + numBytes) & rbuf->bigMask;
+    return rbuf->writeIndex = (rbuf->writeIndex + elementCount) & rbuf->bigMask;
 }
 
 /***************************************************************************
 ** Get address of region(s) from which we can read data.
 ** If the region is contiguous, size2 will be zero.
 ** If non-contiguous, size2 will be the size of second region.
-** Returns room available to be written or numBytes, whichever is smaller.
+** Returns room available to be written or elementCount, whichever is smaller.
 */
-long PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, long numBytes,
+long PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, long elementCount,
                                 void **dataPtr1, long *sizePtr1,
                                 void **dataPtr2, long *sizePtr2 )
 {
     long   index;
     long   available = PaUtil_GetRingBufferReadAvailable( rbuf );
-    if( numBytes > available ) numBytes = available;
+    if( elementCount > available ) elementCount = available;
     /* Check to see if read is not contiguous. */
     index = rbuf->readIndex & rbuf->smallMask;
-    if( (index + numBytes) > rbuf->bufferSize )
+    if( (index + elementCount) > rbuf->bufferSize )
     {
         /* Write data in two blocks that wrap the buffer. */
         long firstHalf = rbuf->bufferSize - index;
-        *dataPtr1 = &rbuf->buffer[index];
+        *dataPtr1 = &rbuf->buffer[index*rbuf->elementSizeBytes];
         *sizePtr1 = firstHalf;
         *dataPtr2 = &rbuf->buffer[0];
-        *sizePtr2 = numBytes - firstHalf;
+        *sizePtr2 = elementCount - firstHalf;
     }
     else
     {
-        *dataPtr1 = &rbuf->buffer[index];
-        *sizePtr1 = numBytes;
+        *dataPtr1 = &rbuf->buffer[index*rbuf->elementSizeBytes];
+        *sizePtr1 = elementCount;
         *dataPtr2 = NULL;
         *sizePtr2 = 0;
     }
-    return numBytes;
+    return elementCount;
 }
 /***************************************************************************
 */
-long PaUtil_AdvanceRingBufferReadIndex( PaUtilRingBuffer *rbuf, long numBytes )
+long PaUtil_AdvanceRingBufferReadIndex( PaUtilRingBuffer *rbuf, long elementCount )
 {
     /* we need to ensure that previous writes are always seen before updating the index. */
     PaUtil_WriteMemoryBarrier();
-    return rbuf->readIndex = (rbuf->readIndex + numBytes) & rbuf->bigMask;
+    return rbuf->readIndex = (rbuf->readIndex + elementCount) & rbuf->bigMask;
 }
 
 /***************************************************************************
-** Return bytes written. */
-long PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, long numBytes )
+** Return elements written. */
+long PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, long elementCount )
 {
     long size1, size2, numWritten;
     void *data1, *data2;
-    numWritten = PaUtil_GetRingBufferWriteRegions( rbuf, numBytes, &data1, &size1, &data2, &size2 );
+    numWritten = PaUtil_GetRingBufferWriteRegions( rbuf, elementCount, &data1, &size1, &data2, &size2 );
     if( size2 > 0 )
     {
 
-        memcpy( data1, data, size1 );
-        data = ((char *)data) + size1;
-        memcpy( data2, data, size2 );
+        memcpy( data1, data, size1*rbuf->elementSizeBytes );
+        data = ((char *)data) + size1*rbuf->elementSizeBytes;
+        memcpy( data2, data, size2*rbuf->elementSizeBytes );
     }
     else
     {
-        memcpy( data1, data, size1 );
+        memcpy( data1, data, size1*rbuf->elementSizeBytes );
     }
     PaUtil_AdvanceRingBufferWriteIndex( rbuf, numWritten );
     return numWritten;
 }
 
 /***************************************************************************
-** Return bytes read. */
-long PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, long numBytes )
+** Return elements read. */
+long PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, long elementCount )
 {
     long size1, size2, numRead;
     void *data1, *data2;
-    numRead = PaUtil_GetRingBufferReadRegions( rbuf, numBytes, &data1, &size1, &data2, &size2 );
+    numRead = PaUtil_GetRingBufferReadRegions( rbuf, elementCount, &data1, &size1, &data2, &size2 );
     if( size2 > 0 )
     {
-        memcpy( data, data1, size1 );
-        data = ((char *)data) + size1;
-        memcpy( data, data2, size2 );
+        memcpy( data, data1, size1*rbuf->elementSizeBytes );
+        data = ((char *)data) + size1*rbuf->elementSizeBytes;
+        memcpy( data, data2, size2*rbuf->elementSizeBytes );
     }
     else
     {
-        memcpy( data, data1, size1 );
+        memcpy( data, data1, size1*rbuf->elementSizeBytes );
     }
     PaUtil_AdvanceRingBufferReadIndex( rbuf, numRead );
     return numRead;
diff --git a/pd/portaudio/src/common/pa_ringbuffer.h b/pd/portaudio/src/common/pa_ringbuffer.h
index b3808898..fd92882a 100644
--- a/pd/portaudio/src/common/pa_ringbuffer.h
+++ b/pd/portaudio/src/common/pa_ringbuffer.h
@@ -1,13 +1,15 @@
 #ifndef PA_RINGBUFFER_H
 #define PA_RINGBUFFER_H
 /*
- * $Id: pa_ringbuffer.h 1151 2006-11-29 02:11:16Z leland_lucius $
+ * $Id: pa_ringbuffer.h 1347 2008-02-21 04:54:36Z rossb $
  * Portable Audio I/O Library
  * Ring Buffer utility.
  *
  * Author: Phil Burk, http://www.softsynth.com
  * modified for SMP safety on OS X by Bjorn Roche.
  * also allowed for const where possible.
+ * modified for multiple-byte-sized data elements by Sven Fischer 
+ *
  * Note that this is safe only for a single-thread reader
  * and a single-thread writer.
  *
@@ -48,6 +50,21 @@
 
 /** @file
  @ingroup common_src
+ @brief Single-reader single-writer lock-free ring buffer
+
+ PaUtilRingBuffer is a ring buffer used to transport samples between
+ different execution contexts (threads, OS callbacks, interrupt handlers)
+ without requiring the use of any locks. This only works when there is
+ a single reader and a single writer (ie. one thread or callback writes
+ to the ring buffer, another thread or callback reads from it).
+
+ The PaUtilRingBuffer structure manages a ring buffer containing N 
+ elements, where N must be a power of two. An element may be any size 
+ (specified in bytes).
+
+ The memory area used to store the buffer elements must be allocated by 
+ the client prior to calling PaUtil_InitializeRingBuffer() and must outlive
+ the use of the ring buffer.
 */
 
 #ifdef __cplusplus
@@ -57,26 +74,29 @@ extern "C"
 
 typedef struct PaUtilRingBuffer
 {
-    long   bufferSize; /* Number of bytes in FIFO. Power of 2. Set by PaUtil_InitRingBuffer. */
-    long   writeIndex; /* Index of next writable byte. Set by PaUtil_AdvanceRingBufferWriteIndex. */
-    long   readIndex;  /* Index of next readable byte. Set by PaUtil_AdvanceRingBufferReadIndex. */
-    long   bigMask;    /* Used for wrapping indices with extra bit to distinguish full/empty. */
-    long   smallMask;  /* Used for fitting indices to buffer. */
-    char  *buffer;
+    long  bufferSize; /**< Number of elements in FIFO. Power of 2. Set by PaUtil_InitRingBuffer. */
+    long  writeIndex; /**< Index of next writable element. Set by PaUtil_AdvanceRingBufferWriteIndex. */
+    long  readIndex;  /**< Index of next readable element. Set by PaUtil_AdvanceRingBufferReadIndex. */
+    long  bigMask;    /**< Used for wrapping indices with extra bit to distinguish full/empty. */
+    long  smallMask;  /**< Used for fitting indices to buffer. */
+    long  elementSizeBytes; /**< Number of bytes per element. */
+    char  *buffer;    /**< Pointer to the buffer containing the actual data. */
 }PaUtilRingBuffer;
 
 /** Initialize Ring Buffer.
 
  @param rbuf The ring buffer.
 
- @param numBytes The number of bytes in the buffer and must be power of 2.
+ @param elementSizeBytes The size of a single data element in bytes.
+
+ @param elementCount The number of elements in the buffer (must be power of 2).
 
  @param dataPtr A pointer to a previously allocated area where the data
- will be maintained.  It must be numBytes long.
+ will be maintained.  It must be elementCount*elementSizeBytes long.
 
- @return -1 if numBytes is not a power of 2, otherwise 0.
+ @return -1 if elementCount is not a power of 2, otherwise 0.
 */
-long PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, long numBytes, void *dataPtr );
+long PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, long elementSizeBytes, long elementCount, void *dataPtr );
 
 /** Clear buffer. Should only be called when buffer is NOT being read.
 
@@ -84,19 +104,19 @@ long PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, long numBytes, void *d
 */
 void PaUtil_FlushRingBuffer( PaUtilRingBuffer *rbuf );
 
-/** Retrieve the number of bytes available in the ring buffer for writing.
+/** Retrieve the number of elements available in the ring buffer for writing.
 
  @param rbuf The ring buffer.
 
- @return The number of bytes available for writing.
+ @return The number of elements available for writing.
 */
 long PaUtil_GetRingBufferWriteAvailable( PaUtilRingBuffer *rbuf );
 
-/** Retrieve the number of bytes available in the ring buffer for reading.
+/** Retrieve the number of elements available in the ring buffer for reading.
 
  @param rbuf The ring buffer.
 
- @return The number of bytes available for reading.
+ @return The number of elements available for reading.
 */
 long PaUtil_GetRingBufferReadAvailable( PaUtilRingBuffer *rbuf );
 
@@ -106,11 +126,11 @@ long PaUtil_GetRingBufferReadAvailable( PaUtilRingBuffer *rbuf );
 
  @param data The address of new data to write to the buffer.
 
- @param numBytes The number of bytes to be written.
+ @param elementCount The number of elements to be written.
 
- @return The number of bytes written.
+ @return The number of elements written.
 */
-long PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, long numBytes );
+long PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, long elementCount );
 
 /** Read data from the ring buffer.
 
@@ -118,17 +138,17 @@ long PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, long numB
 
  @param data The address where the data should be stored.
 
- @param numBytes The number of bytes to be read.
+ @param elementCount The number of elements to be read.
 
- @return The number of bytes read.
+ @return The number of elements read.
 */
-long PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, long numBytes );
+long PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, long elementCount );
 
 /** Get address of region(s) to which we can write data.
 
  @param rbuf The ring buffer.
 
- @param numBytes The number of bytes desired.
+ @param elementCount The number of elements desired.
 
  @param dataPtr1 The address where the first (or only) region pointer will be
  stored.
@@ -137,14 +157,14 @@ long PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, long numBytes );
  stored.
 
  @param dataPtr2 The address where the second region pointer will be stored if
- the first region is too small to satisfy numBytes.
+ the first region is too small to satisfy elementCount.
 
  @param sizePtr2 The address where the second region length will be stored if
- the first region is too small to satisfy numBytes.
+ the first region is too small to satisfy elementCount.
 
- @return The room available to be written or numBytes, whichever is smaller.
+ @return The room available to be written or elementCount, whichever is smaller.
 */
-long PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, long numBytes,
+long PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, long elementCount,
                                        void **dataPtr1, long *sizePtr1,
                                        void **dataPtr2, long *sizePtr2 );
 
@@ -152,17 +172,17 @@ long PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, long numBytes,
 
  @param rbuf The ring buffer.
 
- @param numBytes The number of bytes to advance.
+ @param elementCount The number of elements to advance.
 
  @return The new position.
 */
-long PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, long numBytes );
+long PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, long elementCount );
 
 /** Get address of region(s) from which we can write data.
 
  @param rbuf The ring buffer.
 
- @param numBytes The number of bytes desired.
+ @param elementCount The number of elements desired.
 
  @param dataPtr1 The address where the first (or only) region pointer will be
  stored.
@@ -171,14 +191,14 @@ long PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, long numBytes )
  stored.
 
  @param dataPtr2 The address where the second region pointer will be stored if
- the first region is too small to satisfy numBytes.
+ the first region is too small to satisfy elementCount.
 
  @param sizePtr2 The address where the second region length will be stored if
- the first region is too small to satisfy numBytes.
+ the first region is too small to satisfy elementCount.
 
- @return The number of bytes available for reading.
+ @return The number of elements available for reading.
 */
-long PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, long numBytes,
+long PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, long elementCount,
                                       void **dataPtr1, long *sizePtr1,
                                       void **dataPtr2, long *sizePtr2 );
 
@@ -186,11 +206,11 @@ long PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, long numBytes,
 
  @param rbuf The ring buffer.
 
- @param numBytes The number of bytes to advance.
+ @param elementCount The number of elements to advance.
 
  @return The new position.
 */
-long PaUtil_AdvanceRingBufferReadIndex( PaUtilRingBuffer *rbuf, long numBytes );
+long PaUtil_AdvanceRingBufferReadIndex( PaUtilRingBuffer *rbuf, long elementCount );
 
 #ifdef __cplusplus
 }
diff --git a/pd/portaudio/src/common/pa_skeleton.c b/pd/portaudio/src/common/pa_skeleton.c
index e229b07b..d5cb52d8 100644
--- a/pd/portaudio/src/common/pa_skeleton.c
+++ b/pd/portaudio/src/common/pa_skeleton.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_skeleton.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_skeleton.c 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library skeleton implementation
  * demonstrates how to use the common functions to implement support
  * for a host API
@@ -43,8 +43,10 @@
 
  @brief Skeleton implementation of support for a host API.
 
- @note This file is provided as a starting point for implementing support for
- a new host API. IMPLEMENT ME comments are used to indicate functionality
+ This file is provided as a starting point for implementing support for
+ a new host API. It provides examples of how the common code can be used.
+
+ @note IMPLEMENT ME comments are used to indicate functionality
  which much be customised for each implementation.
 */
 
diff --git a/pd/portaudio/src/common/pa_stream.c b/pd/portaudio/src/common/pa_stream.c
index 172e7d26..ea91821f 100644
--- a/pd/portaudio/src/common/pa_stream.c
+++ b/pd/portaudio/src/common/pa_stream.c
@@ -1,10 +1,10 @@
 /*
- * $Id: pa_stream.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_stream.c 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library
- * 
+ * stream interface
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 2002 Ross Bencina
+ * Copyright (c) 2008 Ross Bencina
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -40,8 +40,8 @@
 /** @file
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- streams.
+ @brief Stream interfaces, representation structures and helper functions
+ used to interface between pa_front.c host API implementations.
 */
 
 
diff --git a/pd/portaudio/src/common/pa_stream.h b/pd/portaudio/src/common/pa_stream.h
index f5363b3e..8d707b79 100644
--- a/pd/portaudio/src/common/pa_stream.h
+++ b/pd/portaudio/src/common/pa_stream.h
@@ -1,12 +1,12 @@
 #ifndef PA_STREAM_H
 #define PA_STREAM_H
 /*
- * $Id: pa_stream.h 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_stream.h 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library
  * stream interface
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -42,8 +42,8 @@
 /** @file
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- streams.
+ @brief Stream interfaces, representation structures and helper functions
+ used to interface between pa_front.c host API implementations.
 */
 
 
diff --git a/pd/portaudio/src/common/pa_trace.c b/pd/portaudio/src/common/pa_trace.c
index 583d3ae9..24305003 100644
--- a/pd/portaudio/src/common/pa_trace.c
+++ b/pd/portaudio/src/common/pa_trace.c
@@ -1,5 +1,5 @@
 /*
- * $Id: pa_trace.c 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_trace.c 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library Trace Facility
  * Store trace information in real-time for later printing.
  *
@@ -40,7 +40,7 @@
 /** @file
  @ingroup common_src
 
- @brief Event trace mechanism for debugging.
+ @brief Real-time safe event trace logging facility for debugging.
 */
 
 
diff --git a/pd/portaudio/src/common/pa_trace.h b/pd/portaudio/src/common/pa_trace.h
index a4d2a331..b11509e0 100644
--- a/pd/portaudio/src/common/pa_trace.h
+++ b/pd/portaudio/src/common/pa_trace.h
@@ -1,7 +1,7 @@
 #ifndef PA_TRACE_H
 #define PA_TRACE_H
 /*
- * $Id: pa_trace.h 1097 2006-08-26 08:27:53Z rossb $
+ * $Id: pa_trace.h 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library Trace Facility
  * Store trace information in real-time for later printing.
  *
@@ -42,14 +42,36 @@
 /** @file
  @ingroup common_src
 
- @brief Event trace mechanism for debugging.
+ @brief Real-time safe event trace logging facility for debugging.
 
- Allows data to be written to the buffer at interrupt time and dumped later.
+ Allows data to be logged to a fixed size trace buffer in a real-time
+ execution context (such as at interrupt time). Each log entry consists 
+ of a message comprising a string pointer and an int.  The trace buffer 
+ may be dumped to stdout later.
+
+ This facility is only active if PA_TRACE_REALTIME_EVENTS is set to 1,
+ otherwise the trace functions expand to no-ops.
+
+ @fn PaUtil_ResetTraceMessages
+ @brief Clear the trace buffer.
+
+ @fn PaUtil_AddTraceMessage
+ @brief Add a message to the trace buffer. A message consists of string and an int.
+ @param msg The string pointer must remain valid until PaUtil_DumpTraceMessages 
+    is called. As a result, usually only string literals should be passed as 
+    the msg parameter.
+
+ @fn PaUtil_DumpTraceMessages
+ @brief Print all messages in the trace buffer to stdout and clear the trace buffer.
 */
 
+#ifndef PA_TRACE_REALTIME_EVENTS
+#define PA_TRACE_REALTIME_EVENTS     (0)   /**< Set to 1 to enable logging using the trace functions defined below */
+#endif
 
-#define PA_TRACE_REALTIME_EVENTS     (0)   /* Keep log of various real-time events. */
-#define PA_MAX_TRACE_RECORDS      (2048)
+#ifndef PA_MAX_TRACE_RECORDS
+#define PA_MAX_TRACE_RECORDS      (2048)   /**< Maximum number of records stored in trace buffer */   
+#endif
 
 #ifdef __cplusplus
 extern "C"
diff --git a/pd/portaudio/src/common/pa_util.h b/pd/portaudio/src/common/pa_util.h
index 55eaa138..95ea6789 100644
--- a/pd/portaudio/src/common/pa_util.h
+++ b/pd/portaudio/src/common/pa_util.h
@@ -1,12 +1,12 @@
 #ifndef PA_UTIL_H
 #define PA_UTIL_H
 /*
- * $Id: pa_util.h 1229 2007-06-15 16:11:11Z rossb $
+ * $Id: pa_util.h 1339 2008-02-15 07:50:33Z rossb $
  * Portable Audio I/O Library implementation utilities header
  * common implementation utilities and interfaces
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files
@@ -44,6 +44,9 @@
 
     @brief Prototypes for utility functions used by PortAudio implementations.
 
+    Some functions declared here are defined in pa_front.c while others
+    are implemented separately for each platform.
+
     @todo Document and adhere to the alignment guarantees provided by
     PaUtil_AllocateMemory().
 */