merge rizzo's codec module rework (very similar to the format module rework)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@18541 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 109 insertions, 31 deletions

diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h
index 118ba6d55..8f1a86759 100644
--- a/include/asterisk/translate.h
+++ b/include/asterisk/translate.h
@@ -17,7 +17,7 @@
  */
 
 /*! \file
- * \brief Translate via the use of pseudo channels
+ * \brief Support for translation of data formats.
  */
 
 #ifndef _ASTERISK_TRANSLATE_H
@@ -29,38 +29,116 @@
 extern "C" {
 #endif
 
+#if 1	/* need lots of stuff... */
 #include "asterisk/frame.h"
 #include "asterisk/plc.h"
 #include "asterisk/linkedlists.h"
+#include "asterisk/module.h"
+#endif
 
-/* Declared by individual translators */
-struct ast_translator_pvt;
+struct ast_trans_pvt;	/* declared below */
 
-/*! data structure associated with a translator */
+/*!
+ * Descriptor of a translator. Name, callbacks, and various options
+ * related to run-time operation (size of buffers, auxiliary
+ * descriptors, etc).
+ * A coded registers itself by filling the relevant fields
+ * of a structure and passing it as an argument to
+ * ast_register_translator(). The structure should not be
+ * modified after a successful register(), and its address
+ * must be used as an argument to ast_unregister_translator().
+ *
+ * As a minimum, a translator should supply name, srcfmt and dstfmt,
+ * the required buf_size (in bytes) and buffer_samples (in samples),
+ * and a few callbacks (framein, frameout, sample).
+ * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
+ * spare bytes so generic routines can place data in there.
+ *
+ * Note, the translator is not supposed to do any memory allocation
+ * or deallocation, nor any locking, because all of this is done in
+ * the generic code.
+ *
+ * Translators using generic plc (packet loss concealment) should
+ * supply a non-zero plc_samples indicating the size (in samples)
+ * of artificially generated frames and incoming data.
+ * Generic plc is only available for dstfmt = SLINEAR
+ */
 struct ast_translator {
-	/*! Name of translator */
-	char name[80];
-	/*! Source format */
-	int srcfmt;
-	/*! Destination format */
-	int dstfmt;
-	/*! Private data associated with the translator */
-	struct ast_translator_pvt *(*newpvt)(void);
-	/*! Input frame callback */
-	int (*framein)(struct ast_translator_pvt *pvt, struct ast_frame *in);
-	/*! Output frame callback */
-	struct ast_frame * (*frameout)(struct ast_translator_pvt *pvt);
-	/*! Destroy translator callback */
-	void (*destroy)(struct ast_translator_pvt *pvt);
-	/* For performance measurements */
-	/*! Generate an example frame */
-	struct ast_frame * (*sample)(void);
-	/*! Cost in milliseconds for encoding/decoding 1 second of sound */
-	int cost;
-	/*! For linking, not to be modified by the translator */
-	AST_LIST_ENTRY(ast_translator) list;
+	const char name[80];		/*! Name of translator */
+	int srcfmt;			/*! Source format (note: bit position) */
+	int dstfmt;			/*! Destination format (note: bit position) */
+
+	/*! initialize private data associated with the translator */
+	void *(*newpvt)(struct ast_trans_pvt *);
+
+	/*! Input frame callback. Store (and possibly convert) input frame. */
+	int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
+
+	/*! Output frame callback. Generate a frame with outbuf content. */
+	struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
+
+	/*! cleanup private data, if needed (often unnecessary). */
+	void (*destroy)(struct ast_trans_pvt *pvt);
+
+	struct ast_frame * (*sample)(void);	/*! Generate an example frame */
+
+	/*! size of outbuf, in samples. Leave it 0 if you want the framein
+	 * callback deal with the frame. Set it appropriately if you
+	 * want the code to checks if the incoming frame fits the
+	 * outbuf (this is e.g. required for plc).
+	 */
+	int buffer_samples;	/* size of outbuf, in samples */
+
+	/*! size of outbuf, in bytes. Mandatory. The wrapper code will also
+	 * allocate an AST_FRIENDLY_OFFSET space before.
+	 */
+	int buf_size;
+
+	int desc_size;		/*! size of private descriptor in pvt->pvt, if any */
+	int plc_samples;	/* set to the plc block size if used, 0 otherwise */
+	int useplc;		/* current status of plc, changed at runtime */
+
+	struct ast_module_lock *lockp;
+
+	int cost;		/*! Cost in milliseconds for encoding/decoding 1 second of sound */
+	AST_LIST_ENTRY(ast_translator) list;	/*! link field */
 };
 
+/*
+ * Default structure for translators, with the basic fields and buffers,
+ * all allocated as part of the same chunk of memory. The buffer is
+ * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion.
+ * 'buf' points right after this space.
+ *
+ * *_framein() routines operate in two ways:
+ * 1. some convert on the fly and place the data directly in outbuf;
+ *    in this case 'samples' and 'datalen' contain the number of samples
+ *    and number of bytes available in the buffer.
+ *    In this case we can use a generic *_frameout() routine that simply
+ *    takes whatever is there and places it into the output frame.
+ * 2. others simply store the (unconverted) samples into a working
+ *    buffer, and leave the conversion task to *_frameout().
+ *    In this case, the intermediate buffer must be in the private
+ *    descriptor, 'datalen' is left to 0, while 'samples' is still
+ *    updated with the number of samples received.
+ */
+struct ast_trans_pvt {
+	struct ast_translator *t;
+	struct ast_frame f;	/* used in frameout */
+	int samples;		/* samples available in outbuf */
+	int datalen;		/* actual space used in outbuf */
+	void *pvt;		/* more private data, if any */
+	char *outbuf;		/* the useful portion of the buffer */
+	plc_state_t *plc;	/* optional plc pointer */
+	struct ast_trans_pvt *next;	/* next in translator chain */
+	struct timeval nextin;
+	struct timeval nextout;
+};
+
+/* generic frameout function */
+struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
+        int datalen, int samples);
+
 struct ast_trans_pvt;
 
 /*!
@@ -69,7 +147,7 @@ struct ast_trans_pvt;
  * This registers a codec translator with asterisk
  * Returns 0 on success, -1 on failure
  */
-extern int ast_register_translator(struct ast_translator *t);
+int ast_register_translator(struct ast_translator *t);
 
 /*!
  * \brief Unregister a translator
@@ -77,7 +155,7 @@ extern int ast_register_translator(struct ast_translator *t);
  * Unregisters the given tranlator
  * Returns 0 on success, -1 on failure
  */
-extern int ast_unregister_translator(struct ast_translator *t);
+int ast_unregister_translator(struct ast_translator *t);
 
 /*!
  * \brief Chooses the best translation path
@@ -86,7 +164,7 @@ extern int ast_unregister_translator(struct ast_translator *t);
  * I choose? Returns 0 on success, -1 if no path could be found.  Modifies
  * dests and srcs in place 
  */
-extern int ast_translator_best_choice(int *dsts, int *srcs);
+int ast_translator_best_choice(int *dsts, int *srcs);
 
 /*! 
  * \brief Builds a translator path
@@ -95,14 +173,14 @@ extern int ast_translator_best_choice(int *dsts, int *srcs);
  * Build a path (possibly NULL) from source to dest 
  * Returns ast_trans_pvt on success, NULL on failure
  * */
-extern struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
+struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
 
 /*!
  * \brief Frees a translator path
  * \param tr translator path to get rid of
  * Frees the given translator path structure
  */
-extern void ast_translator_free_path(struct ast_trans_pvt *tr);
+void ast_translator_free_path(struct ast_trans_pvt *tr);
 
 /*!
  * \brief translates one or more frames
@@ -113,7 +191,7 @@ extern void ast_translator_free_path(struct ast_trans_pvt *tr);
  * determines whether the original frame should be freed
  * Returns an ast_frame of the new translation format on success, NULL on failure
  */
-extern struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
+struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }