Clean up doxygen warnings
[asterisk/asterisk.git] / include / asterisk / translate.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
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.
13  *
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.
17  */
18
19 /*! \file
20  * \brief Support for translation of data formats.
21  * \ref translate.c
22  */
23
24 #ifndef _ASTERISK_TRANSLATE_H
25 #define _ASTERISK_TRANSLATE_H
26
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30
31 #if 1   /* need lots of stuff... */
32 #include "asterisk/frame.h"
33 #include "asterisk/plc.h"
34 #include "asterisk/linkedlists.h"
35 #endif
36
37 struct ast_trans_pvt;   /* declared below */
38
39 /*!
40  * \brief Translator Cost Table definition.
41  *
42  * \note The defined values in this table must be used to set
43  * the translator's table_cost value.
44  *
45  * \note The cost value of the first two values must always add
46  * up to be greater than the largest value defined in this table.
47  * This is done to guarantee a direct translation will always
48  * have precedence over a multi step translation.
49  *
50  * \details This table is built in a way that allows translation
51  * paths to be built that guarantee the best possible balance
52  * between performance and quality.  With this table direct
53  * translation paths between two formats will always take precedence
54  * over multi step paths, lossless intermediate steps will always
55  * be chosen over lossy intermediate steps, and preservation of
56  * sample rate across the translation will always have precedence
57  * over a path that involves any re-sampling.
58  */
59 enum ast_trans_cost_table {
60
61         /* Lossless Source Translation Costs */
62
63         /*! [lossless -> lossless] original sampling */
64         AST_TRANS_COST_LL_LL_ORIGSAMP = 400000,
65         /*! [lossless -> lossy]    original sampling */
66         AST_TRANS_COST_LL_LY_ORIGSAMP = 600000,
67
68         /*! [lossless -> lossless] up sample */
69         AST_TRANS_COST_LL_LL_UPSAMP   = 800000,
70         /*! [lossless -> lossy]    up sample */
71         AST_TRANS_COST_LL_LY_UPSAMP   = 825000,
72
73         /*! [lossless -> lossless] down sample */
74         AST_TRANS_COST_LL_LL_DOWNSAMP = 850000,
75         /*! [lossless -> lossy]    down sample */
76         AST_TRANS_COST_LL_LY_DOWNSAMP = 875000,
77
78         /*! [lossless -> unknown]    unknown.
79          * This value is for a lossless source translation
80          * with an unknown destination and or sample rate conversion. */
81         AST_TRANS_COST_LL_UNKNOWN     = 885000,
82
83         /* Lossy Source Translation Costs */
84
85         /*! [lossy -> lossless]    original sampling */
86         AST_TRANS_COST_LY_LL_ORIGSAMP = 900000,
87         /*! [lossy -> lossy]       original sampling */
88         AST_TRANS_COST_LY_LY_ORIGSAMP = 915000,
89
90         /*! [lossy -> lossless]    up sample */
91         AST_TRANS_COST_LY_LL_UPSAMP   = 930000,
92         /*! [lossy -> lossy]       up sample */
93         AST_TRANS_COST_LY_LY_UPSAMP   = 945000,
94
95         /*! [lossy -> lossless]    down sample */
96         AST_TRANS_COST_LY_LL_DOWNSAMP = 960000,
97         /*! [lossy -> lossy]       down sample */
98         AST_TRANS_COST_LY_LY_DOWNSAMP = 975000,
99
100         /*! [lossy -> unknown]    unknown.
101          * This value is for a lossy source translation
102          * with an unknown destination and or sample rate conversion. */
103         AST_TRANS_COST_LY_UNKNOWN     = 985000,
104
105 };
106
107 /*! \brief
108  * Descriptor of a translator. 
109  *
110  * Name, callbacks, and various options
111  * related to run-time operation (size of buffers, auxiliary
112  * descriptors, etc).
113  *
114  * A codec registers itself by filling the relevant fields
115  * of a structure and passing it as an argument to
116  * ast_register_translator(). The structure should not be
117  * modified after a successful registration, and its address
118  * must be used as an argument to ast_unregister_translator().
119  *
120  * As a minimum, a translator should supply name, srcfmt and dstfmt,
121  * the required buf_size (in bytes) and buffer_samples (in samples),
122  * and a few callbacks (framein, frameout, sample).
123  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
124  * spare bytes so generic routines can place data in there.
125  *
126  * Note, the translator is not supposed to do any memory allocation
127  * or deallocation, nor any locking, because all of this is done in
128  * the generic code.
129  *
130  * Translators using generic plc (packet loss concealment) should
131  * supply a non-zero plc_samples indicating the size (in samples)
132  * of artificially generated frames and incoming data.
133  * Generic plc is only available for dstfmt = SLINEAR
134  */
135 struct ast_translator {
136         char name[80];                         /*!< Name of translator */
137         struct ast_format src_format;          /*!< Source format */
138         struct ast_format dst_format;          /*!< Destination format */
139
140         int table_cost;                        /*!< Cost value associated with this translator based
141                                                 *   on translation cost table. */
142         int comp_cost;                         /*!< Cost value associated with this translator based
143                                                 *   on computation time. This cost value is computed based
144                                                                                         *   on the time required to translate sample data. */
145
146         int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
147                                             *   associated with the translator */
148
149         int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
150                                                /*!< Input frame callback. Store 
151                                                 *   (and possibly convert) input frame. */
152
153         struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
154                                                /*!< Output frame callback. Generate a frame 
155                                                 *   with outbuf content. */
156
157         void (*destroy)(struct ast_trans_pvt *pvt);
158                                                /*!< cleanup private data, if needed 
159                                                 *   (often unnecessary). */
160
161         struct ast_frame * (*sample)(void);    /*!< Generate an example frame */
162
163         /*!\brief size of outbuf, in samples. Leave it 0 if you want the framein
164          * callback deal with the frame. Set it appropriately if you
165          * want the code to checks if the incoming frame fits the
166          * outbuf (this is e.g. required for plc).
167          */
168         int buffer_samples;                    /*< size of outbuf, in samples */
169
170         /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
171          * allocate an AST_FRIENDLY_OFFSET space before.
172          */
173         int buf_size;
174
175         int desc_size;                         /*!< size of private descriptor in pvt->pvt, if any */
176         int native_plc;                        /*!< true if the translator can do native plc */
177
178         struct ast_module *module;             /*!< opaque reference to the parent module */
179
180         int active;                            /*!< Whether this translator should be used or not */
181         int src_fmt_index;                     /*!< index of the source format in the matrix table */
182         int dst_fmt_index;                     /*!< index of the destination format in the matrix table */
183         AST_LIST_ENTRY(ast_translator) list;   /*!< link field */
184 };
185
186 /*! \brief
187  * Default structure for translators, with the basic fields and buffers,
188  * all allocated as part of the same chunk of memory. The buffer is
189  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
190  * 'buf' points right after this space.
191  *
192  * *_framein() routines operate in two ways:
193  * 1. some convert on the fly and place the data directly in outbuf;
194  *    in this case 'samples' and 'datalen' contain the number of samples
195  *    and number of bytes available in the buffer.
196  *    In this case we can use a generic *_frameout() routine that simply
197  *    takes whatever is there and places it into the output frame.
198  * 2. others simply store the (unconverted) samples into a working
199  *    buffer, and leave the conversion task to *_frameout().
200  *    In this case, the intermediate buffer must be in the private
201  *    descriptor, 'datalen' is left to 0, while 'samples' is still
202  *    updated with the number of samples received.
203  */
204 struct ast_trans_pvt {
205         struct ast_translator *t;
206         struct ast_frame f;         /*!< used in frameout */
207         /*! If a translation path using a format with attributes requires the output
208          * to be a specific set of attributes, this variable will be set describing those
209          * attributes to the translator.  Otherwise, the translator must choose a set
210          * of format attributes for the destination that preserves the quality of the
211          * audio in the best way possible. */
212         struct ast_format explicit_dst;
213         int samples;                /*!< samples available in outbuf */
214         /*! \brief actual space used in outbuf */
215         int datalen;
216         void *pvt;                  /*!< more private data, if any */
217         union {
218                 char *c;                /*!< the useful portion of the buffer */
219                 unsigned char *uc;      /*!< the useful portion of the buffer */
220                 int16_t *i16;
221                 uint8_t *ui8;
222         } outbuf;
223         plc_state_t *plc;           /*!< optional plc pointer */
224         struct ast_trans_pvt *next; /*!< next in translator chain */
225         struct timeval nextin;
226         struct timeval nextout;
227 };
228
229 /*! \brief generic frameout function */
230 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
231         int datalen, int samples);
232
233 struct ast_trans_pvt;
234
235 /*!
236  * \brief Register a translator
237  * This registers a codec translator with asterisk
238  * \param t populated ast_translator structure
239  * \param mod module handle to the module that owns this translator
240  * \return 0 on success, -1 on failure
241  */
242 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
243
244 /*! \brief See \ref __ast_register_translator() */
245 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
246
247 /*!
248  * \brief Unregister a translator
249  * Unregisters the given tranlator
250  * \param t translator to unregister
251  * \return 0 on success, -1 on failure
252  */
253 int ast_unregister_translator(struct ast_translator *t);
254
255 /*!
256  * \brief Activate a previously deactivated translator
257  * \param t translator to activate
258  * \return nothing
259  *
260  * Enables the specified translator for use.
261  */
262 void ast_translator_activate(struct ast_translator *t);
263
264 /*!
265  * \brief Deactivate a translator
266  * \param t translator to deactivate
267  * \return nothing
268  *
269  * Disables the specified translator from being used.
270  */
271 void ast_translator_deactivate(struct ast_translator *t);
272
273 /*!
274  * \brief Chooses the best translation path
275  *
276  * Given a list of sources, and a designed destination format, which should
277  * I choose?
278  *
279  * \param dst_cap destination capabilities
280  * \param src_cap source capabilities
281  * \param dst_fmt_out destination format chosen out of destination capabilities
282  * \param src_fmt_out source format chosen out of source capabilities
283  * \return Returns 0 on success, -1 if no path could be found.
284  *
285  * \note dst_cap and src_cap are not mondified.
286  */
287 int ast_translator_best_choice(struct ast_format_cap *dst_cap,
288         struct ast_format_cap *src_cap,
289         struct ast_format *dst_fmt_out,
290         struct ast_format *src_fmt_out);
291
292 /*! 
293  * \brief Builds a translator path
294  * Build a path (possibly NULL) from source to dest 
295  * \param dst dest destination format
296  * \param src source source format
297  * \return ast_trans_pvt on success, NULL on failure
298  * */
299 struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
300
301 /*!
302  * \brief Frees a translator path
303  * Frees the given translator path structure
304  * \param tr translator path to get rid of
305  */
306 void ast_translator_free_path(struct ast_trans_pvt *tr);
307
308 /*!
309  * \brief translates one or more frames
310  * Apply an input frame into the translator and receive zero or one output frames.  Consume
311  * determines whether the original frame should be freed
312  * \param path tr translator structure to use for translation
313  * \param f frame to translate
314  * \param consume Whether or not to free the original frame
315  * \return an ast_frame of the new translation format on success, NULL on failure
316  */
317 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
318
319 /*!
320  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
321  * \param dest destination format
322  * \param src source format
323  * \return the number of translation steps required, or -1 if no path is available
324  */
325 unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src);
326
327 /*!
328  * \brief Find available formats
329  * \param dest possible destination formats
330  * \param src source formats
331  * \param result capabilities structure to store available formats in
332  *
333  * \return the destination formats that are available in the source or translatable
334  *
335  * The result will include all formats from 'dest' that are either present
336  * in 'src' or translatable from a format present in 'src'.
337  *
338  * \note Only a single audio format and a single video format can be
339  * present in 'src', or the function will produce unexpected results.
340  */
341 void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_format_cap *src, struct ast_format_cap *result);
342
343 /*!
344  * \brief Puts a string representation of the translation path into outbuf
345  * \param t translator structure containing the translation path
346  * \param str ast_str output buffer
347  * \retval on success pointer to beginning of outbuf. on failure "".
348  */
349 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
350
351 /*!
352  * \brief Initialize the translation matrix and index to format conversion table.
353  * \retval 0 on success
354  * \retval -1 on failure
355  */
356 int ast_translate_init(void);
357
358 #if defined(__cplusplus) || defined(c_plusplus)
359 }
360 #endif
361
362 #endif /* _ASTERISK_TRANSLATE_H */