diff options
author | kpfleming <kpfleming@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-04-08 21:40:57 +0000 |
---|---|---|
committer | kpfleming <kpfleming@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-04-08 21:40:57 +0000 |
commit | f1822bc2a6fdfea0a2fa629a0dc70336f22af185 (patch) | |
tree | 380e359c10d849c23bbe9bef0990dad66bdffdd2 /include | |
parent | 5adcee992f51b2ae0e6bd74e5f82a6b2a37e85d3 (diff) |
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
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/translate.h | 140 |
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) } |