2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 1999 - 2006, Digium, Inc.
6 * Mark Spencer <markster@digium.com>
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
20 * \brief Support for translation of data formats.
24 #ifndef _ASTERISK_TRANSLATE_H
25 #define _ASTERISK_TRANSLATE_H
27 //#define MAX_FORMAT 15 /* Do not include video here */
28 #define MAX_FORMAT 32 /* Do include video here */
30 #if defined(__cplusplus) || defined(c_plusplus)
34 #if 1 /* need lots of stuff... */
35 #include "asterisk/frame.h"
36 #include "asterisk/plc.h"
37 #include "asterisk/linkedlists.h"
38 // XXX #include "asterisk/module.h"
41 struct ast_trans_pvt; /* declared below */
44 * Descriptor of a translator.
46 * Name, callbacks, and various options
47 * related to run-time operation (size of buffers, auxiliary
50 * A codec registers itself by filling the relevant fields
51 * of a structure and passing it as an argument to
52 * ast_register_translator(). The structure should not be
53 * modified after a successful registration, and its address
54 * must be used as an argument to ast_unregister_translator().
56 * As a minimum, a translator should supply name, srcfmt and dstfmt,
57 * the required buf_size (in bytes) and buffer_samples (in samples),
58 * and a few callbacks (framein, frameout, sample).
59 * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
60 * spare bytes so generic routines can place data in there.
62 * Note, the translator is not supposed to do any memory allocation
63 * or deallocation, nor any locking, because all of this is done in
66 * Translators using generic plc (packet loss concealment) should
67 * supply a non-zero plc_samples indicating the size (in samples)
68 * of artificially generated frames and incoming data.
69 * Generic plc is only available for dstfmt = SLINEAR
71 struct ast_translator {
72 const char name[80]; /*!< Name of translator */
73 int srcfmt; /*!< Source format (note: bit position,
74 converted to index during registration) */
75 int dstfmt; /*!< Destination format (note: bit position,
76 converted to index during registration) */
78 int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data
79 associated with the translator */
81 int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
82 /*!< Input frame callback. Store
83 (and possibly convert) input frame. */
85 struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
86 /*!< Output frame callback. Generate a frame
87 with outbuf content. */
89 void (*destroy)(struct ast_trans_pvt *pvt);
90 /*!< cleanup private data, if needed
91 (often unnecessary). */
93 struct ast_frame * (*sample)(void); /*!< Generate an example frame */
95 /*! \brief size of outbuf, in samples. Leave it 0 if you want the framein
96 * callback deal with the frame. Set it appropriately if you
97 * want the code to checks if the incoming frame fits the
98 * outbuf (this is e.g. required for plc).
100 int buffer_samples; /*< size of outbuf, in samples */
102 /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
103 * allocate an AST_FRIENDLY_OFFSET space before.
107 int desc_size; /*!< size of private descriptor in pvt->pvt, if any */
108 int plc_samples; /*!< set to the plc block size if used, 0 otherwise */
109 int useplc; /*!< current status of plc, changed at runtime */
110 int native_plc; /*!< true if the translator can do native plc */
112 struct ast_module *module; /* opaque reference to the parent module */
114 int cost; /*!< Cost in milliseconds for encoding/decoding 1 second of sound */
115 int active; /*!< Whether this translator should be used or not */
116 AST_LIST_ENTRY(ast_translator) list; /*!< link field */
120 * Default structure for translators, with the basic fields and buffers,
121 * all allocated as part of the same chunk of memory. The buffer is
122 * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
123 * 'buf' points right after this space.
125 * *_framein() routines operate in two ways:
126 * 1. some convert on the fly and place the data directly in outbuf;
127 * in this case 'samples' and 'datalen' contain the number of samples
128 * and number of bytes available in the buffer.
129 * In this case we can use a generic *_frameout() routine that simply
130 * takes whatever is there and places it into the output frame.
131 * 2. others simply store the (unconverted) samples into a working
132 * buffer, and leave the conversion task to *_frameout().
133 * In this case, the intermediate buffer must be in the private
134 * descriptor, 'datalen' is left to 0, while 'samples' is still
135 * updated with the number of samples received.
137 struct ast_trans_pvt {
138 struct ast_translator *t;
139 struct ast_frame f; /*!< used in frameout */
140 int samples; /*!< samples available in outbuf */
141 int datalen; /*!< actual space used in outbuf */
142 void *pvt; /*!< more private data, if any */
143 char *outbuf; /*!< the useful portion of the buffer */
144 plc_state_t *plc; /*!< optional plc pointer */
145 struct ast_trans_pvt *next; /*!< next in translator chain */
146 struct timeval nextin;
147 struct timeval nextout;
150 /*! \brief generic frameout function */
151 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
152 int datalen, int samples);
154 struct ast_trans_pvt;
157 * \brief Register a translator
158 * This registers a codec translator with asterisk
159 * \param t populated ast_translator structure
160 * \param module handle to the module that owns this translator
161 * \return 0 on success, -1 on failure
163 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
165 /*! \brief See \ref __ast_register_translator() */
166 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
169 * \brief Unregister a translator
170 * Unregisters the given tranlator
171 * \param t translator to unregister
172 * \return 0 on success, -1 on failure
174 int ast_unregister_translator(struct ast_translator *t);
177 * \brief Activate a previously deactivated translator
178 * \param t translator to activate
181 * Enables the specified translator for use.
183 void ast_translator_activate(struct ast_translator *t);
186 * \brief Deactivate a translator
187 * \param t translator to deactivate
190 * Disables the specified translator from being used.
192 void ast_translator_deactivate(struct ast_translator *t);
195 * \brief Chooses the best translation path
197 * Given a list of sources, and a designed destination format, which should
199 * \return Returns 0 on success, -1 if no path could be found.
200 * \note Modifies dests and srcs in place
202 int ast_translator_best_choice(int *dsts, int *srcs);
205 * \brief Builds a translator path
206 * Build a path (possibly NULL) from source to dest
207 * \param dest destination format
208 * \param source source format
209 * \return ast_trans_pvt on success, NULL on failure
211 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
214 * \brief Frees a translator path
215 * Frees the given translator path structure
216 * \param tr translator path to get rid of
218 void ast_translator_free_path(struct ast_trans_pvt *tr);
221 * \brief translates one or more frames
222 * Apply an input frame into the translator and receive zero or one output frames. Consume
223 * determines whether the original frame should be freed
224 * \param tr translator structure to use for translation
225 * \param f frame to translate
226 * \param consume Whether or not to free the original frame
227 * \return an ast_frame of the new translation format on success, NULL on failure
229 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
232 * \brief Returns the number of steps required to convert from 'src' to 'dest'.
233 * \param dest destination format
234 * \param src source format
235 * \return the number of translation steps required, or -1 if no path is available
237 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src);
240 * \brief Mask off unavailable formats from a format bitmask
241 * \param dest possible destination formats
242 * \param src source formats
243 * \return the destination formats that are available in the source or translatable
245 * The result will include all formats from 'dest' that are either present
246 * in 'src' or translatable from a format present in 'src'.
248 * \note Only a single audio format and a single video format can be
249 * present in 'src', or the function will produce unexpected results.
251 unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src);
253 #if defined(__cplusplus) || defined(c_plusplus)
257 #endif /* _ASTERISK_TRANSLATE_H */