[xiph-commits] r12149 - in trunk/speex: include/speex libspeex

[jm at svn.xiph.org]

Author: jm
Date: 2006-11-26 21:04:04 -0800 (Sun, 26 Nov 2006)
New Revision: 12149

Modified:
   trunk/speex/include/speex/speex_jitter.h
   trunk/speex/libspeex/jitter.c
Log:
new jitter_buffer_ctl() call to set the buffer margin and added some comments


Modified: trunk/speex/include/speex/speex_jitter.h
===================================================================
--- trunk/speex/include/speex/speex_jitter.h	2006-11-26 22:18:31 UTC (rev 12148)
+++ trunk/speex/include/speex/speex_jitter.h	2006-11-27 05:04:04 UTC (rev 12149)
@@ -76,6 +76,13 @@
 /** Invalid argument */
 #define JITTER_BUFFER_BAD_ARGUMENT -2
 
+
+/** Set minimum amount of extra buffering required (margin) */
+#define JITTER_BUFFER_SET_MARGIN 0
+/** Get minimum amount of extra buffering required (margin) */
+#define JITTER_BUFFER_GET_MARGIN 1
+
+
 /** Initialises jitter buffer 
  * 
  * @param tick Number of samples per "tick", i.e. the time period of the elements that will be retrieved
@@ -95,18 +102,42 @@
  */
 void jitter_buffer_destroy(JitterBuffer *jitter);
 
-/** Put one packet into the jitter buffer */
+/** Put one packet into the jitter buffer
+ * 
+ * @param jitter Jitter buffer state
+ * @param packet Incoming packet
+*/
 void jitter_buffer_put(JitterBuffer *jitter, const JitterBufferPacket *packet);
 
-/** Get one packet from the jitter buffer */
+/** Get one packet from the jitter buffer
+ * 
+ * @param jitter Jitter buffer state
+ * @param packet Returned packet
+ * @param current_timestamp Timestamp for the returned packet 
+*/
 int jitter_buffer_get(JitterBuffer *jitter, JitterBufferPacket *packet, spx_uint32_t *current_timestamp);
 
-/** Get pointer timestamp of jitter buffer */
+/** Get pointer timestamp of jitter buffer
+ * 
+ * @param jitter Jitter buffer state
+*/
 int jitter_buffer_get_pointer_timestamp(JitterBuffer *jitter);
 
-/** Advance by one tick */
+/** Advance by one tick
+ * 
+ * @param jitter Jitter buffer state
+*/
 void jitter_buffer_tick(JitterBuffer *jitter);
 
+/** Used like the ioctl function to control the jitter buffer parameters
+ * 
+ * @param jitter Jitter buffer state
+ * @param request ioctl-type request (one of the JITTER_BUFFER_* macros)
+ * @param ptr Data exchanged to-from function
+ * @return 0 if no error, -1 if request in unknown
+*/
+int jitter_buffer_ctl(JitterBuffer *jitter, int request, void *ptr);
+
 /* @} */
 
 /** @defgroup SpeexJitter SpeexJitter: Adaptive jitter buffer specifically for Speex
@@ -114,7 +145,7 @@
  * to maintain good quality and low latency. This is a simplified version that works only
  * with Speex, but is much easier to use.
  *  @{
- */
+*/
 
 /** Speex jitter-buffer state. Never use it directly! */
 typedef struct SpeexJitter {

Modified: trunk/speex/libspeex/jitter.c
===================================================================
--- trunk/speex/libspeex/jitter.c	2006-11-26 22:18:31 UTC (rev 12148)
+++ trunk/speex/libspeex/jitter.c	2006-11-27 05:04:04 UTC (rev 12149)
@@ -427,10 +427,25 @@
    jitter->current_timestamp += jitter->tick_size;
 }
 
+/* Used like the ioctl function to control the jitter buffer parameters */
+int jitter_buffer_ctl(JitterBuffer *jitter, int request, void *ptr)
+{
+   switch(request)
+   {
+      case JITTER_BUFFER_SET_MARGIN:
+         jitter->buffer_margin = *(spx_int32_t*)ptr;
+         break;
+      case JITTER_BUFFER_GET_MARGIN:
+         *(spx_int32_t*)ptr = jitter->buffer_margin;
+         break;
+      default:
+         speex_warning_int("Unknown jitter_buffer_ctl request: ", request);
+         return -1;
+   }
+}
 
 
 
-
 void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate)
 {
    jitter->dec = decoder;