Thu Oct 11 06:33:57 2012

Asterisk developer's documentation


translate.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Support for translation of data formats.
00021  * \ref translate.c
00022  */
00023 
00024 #ifndef _ASTERISK_TRANSLATE_H
00025 #define _ASTERISK_TRANSLATE_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 #if 1 /* need lots of stuff... */
00032 #include "asterisk/frame.h"
00033 #include "asterisk/plc.h"
00034 #include "asterisk/linkedlists.h"
00035 #endif
00036 
00037 struct ast_trans_pvt;   /* declared below */
00038 
00039 /*!
00040  * \brief Translator Cost Table definition.
00041  *
00042  * \note The defined values in this table must be used to set
00043  * the translator's table_cost value.
00044  *
00045  * \note The cost value of the first two values must always add
00046  * up to be greater than the largest value defined in this table.
00047  * This is done to guarantee a direct translation will always
00048  * have precedence over a multi step translation.
00049  *
00050  * \details This table is built in a way that allows translation
00051  * paths to be built that guarantee the best possible balance
00052  * between performance and quality.  With this table direct
00053  * translation paths between two formats will always take precedence
00054  * over multi step paths, lossless intermediate steps will always
00055  * be chosen over lossy intermediate steps, and preservation of
00056  * sample rate across the translation will always have precedence
00057  * over a path that involves any re-sampling.
00058  */
00059 enum ast_trans_cost_table {
00060 
00061    /* Lossless Source Translation Costs */
00062 
00063    /*! [lossless -> lossless] original sampling */
00064    AST_TRANS_COST_LL_LL_ORIGSAMP = 400000,
00065    /*! [lossless -> lossy]    original sampling */
00066    AST_TRANS_COST_LL_LY_ORIGSAMP = 600000,
00067 
00068    /*! [lossless -> lossless] up sample */
00069    AST_TRANS_COST_LL_LL_UPSAMP   = 800000,
00070    /*! [lossless -> lossy]    up sample */
00071    AST_TRANS_COST_LL_LY_UPSAMP   = 825000,
00072 
00073    /*! [lossless -> lossless] down sample */
00074    AST_TRANS_COST_LL_LL_DOWNSAMP = 850000,
00075    /*! [lossless -> lossy]    down sample */
00076    AST_TRANS_COST_LL_LY_DOWNSAMP = 875000,
00077 
00078    /*! [lossless -> unknown]    unknown.
00079     * This value is for a lossless source translation
00080     * with an unknown destination and or sample rate conversion. */
00081    AST_TRANS_COST_LL_UNKNOWN     = 885000,
00082 
00083    /* Lossy Source Translation Costs */
00084 
00085    /*! [lossy -> lossless]    original sampling */
00086    AST_TRANS_COST_LY_LL_ORIGSAMP = 900000,
00087    /*! [lossy -> lossy]       original sampling */
00088    AST_TRANS_COST_LY_LY_ORIGSAMP = 915000,
00089 
00090    /*! [lossy -> lossless]    up sample */
00091    AST_TRANS_COST_LY_LL_UPSAMP   = 930000,
00092    /*! [lossy -> lossy]       up sample */
00093    AST_TRANS_COST_LY_LY_UPSAMP   = 945000,
00094 
00095    /*! [lossy -> lossless]    down sample */
00096    AST_TRANS_COST_LY_LL_DOWNSAMP = 960000,
00097    /*! [lossy -> lossy]       down sample */
00098    AST_TRANS_COST_LY_LY_DOWNSAMP = 975000,
00099 
00100    /*! [lossy -> unknown]    unknown.
00101     * This value is for a lossy source translation
00102     * with an unknown destination and or sample rate conversion. */
00103    AST_TRANS_COST_LY_UNKNOWN     = 985000,
00104 
00105 };
00106 
00107 /*! \brief
00108  * Descriptor of a translator. 
00109  *
00110  * Name, callbacks, and various options
00111  * related to run-time operation (size of buffers, auxiliary
00112  * descriptors, etc).
00113  *
00114  * A codec registers itself by filling the relevant fields
00115  * of a structure and passing it as an argument to
00116  * ast_register_translator(). The structure should not be
00117  * modified after a successful registration, and its address
00118  * must be used as an argument to ast_unregister_translator().
00119  *
00120  * As a minimum, a translator should supply name, srcfmt and dstfmt,
00121  * the required buf_size (in bytes) and buffer_samples (in samples),
00122  * and a few callbacks (framein, frameout, sample).
00123  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
00124  * spare bytes so generic routines can place data in there.
00125  *
00126  * Note, the translator is not supposed to do any memory allocation
00127  * or deallocation, nor any locking, because all of this is done in
00128  * the generic code.
00129  *
00130  * Translators using generic plc (packet loss concealment) should
00131  * supply a non-zero plc_samples indicating the size (in samples)
00132  * of artificially generated frames and incoming data.
00133  * Generic plc is only available for dstfmt = SLINEAR
00134  */
00135 struct ast_translator {
00136    char name[80];                         /*!< Name of translator */
00137    struct ast_format src_format;          /*!< Source format */
00138    struct ast_format dst_format;          /*!< Destination format */
00139 
00140    int table_cost;                        /*!< Cost value associated with this translator based
00141                                            *   on translation cost table. */
00142    int comp_cost;                         /*!< Cost value associated with this translator based
00143                                            *   on computation time. This cost value is computed based
00144                                  *   on the time required to translate sample data. */
00145 
00146    int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
00147                                             *   associated with the translator */
00148 
00149    int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
00150                                           /*!< Input frame callback. Store 
00151                                            *   (and possibly convert) input frame. */
00152 
00153    struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
00154                                           /*!< Output frame callback. Generate a frame 
00155                                            *   with outbuf content. */
00156 
00157    void (*destroy)(struct ast_trans_pvt *pvt);
00158                                           /*!< cleanup private data, if needed 
00159                                            *   (often unnecessary). */
00160 
00161    struct ast_frame * (*sample)(void);    /*!< Generate an example frame */
00162 
00163    /*!\brief size of outbuf, in samples. Leave it 0 if you want the framein
00164     * callback deal with the frame. Set it appropriately if you
00165     * want the code to checks if the incoming frame fits the
00166     * outbuf (this is e.g. required for plc).
00167     */
00168    int buffer_samples;                    /*< size of outbuf, in samples */
00169 
00170    /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
00171     * allocate an AST_FRIENDLY_OFFSET space before.
00172     */
00173    int buf_size;
00174 
00175    int desc_size;                         /*!< size of private descriptor in pvt->pvt, if any */
00176    int native_plc;                        /*!< true if the translator can do native plc */
00177 
00178    struct ast_module *module;             /*!< opaque reference to the parent module */
00179 
00180    int active;                            /*!< Whether this translator should be used or not */
00181    int src_fmt_index;                     /*!< index of the source format in the matrix table */
00182    int dst_fmt_index;                     /*!< index of the destination format in the matrix table */
00183    AST_LIST_ENTRY(ast_translator) list;   /*!< link field */
00184 };
00185 
00186 /*! \brief
00187  * Default structure for translators, with the basic fields and buffers,
00188  * all allocated as part of the same chunk of memory. The buffer is
00189  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
00190  * 'buf' points right after this space.
00191  *
00192  * *_framein() routines operate in two ways:
00193  * 1. some convert on the fly and place the data directly in outbuf;
00194  *    in this case 'samples' and 'datalen' contain the number of samples
00195  *    and number of bytes available in the buffer.
00196  *    In this case we can use a generic *_frameout() routine that simply
00197  *    takes whatever is there and places it into the output frame.
00198  * 2. others simply store the (unconverted) samples into a working
00199  *    buffer, and leave the conversion task to *_frameout().
00200  *    In this case, the intermediate buffer must be in the private
00201  *    descriptor, 'datalen' is left to 0, while 'samples' is still
00202  *    updated with the number of samples received.
00203  */
00204 struct ast_trans_pvt {
00205    struct ast_translator *t;
00206    struct ast_frame f;         /*!< used in frameout */
00207    /*! If a translation path using a format with attributes requires the output
00208     * to be a specific set of attributes, this variable will be set describing those
00209     * attributes to the translator.  Otherwise, the translator must choose a set
00210     * of format attributes for the destination that preserves the quality of the
00211     * audio in the best way possible. */
00212    struct ast_format explicit_dst;
00213    int samples;                /*!< samples available in outbuf */
00214    /*! \brief actual space used in outbuf */
00215    int datalen;
00216    void *pvt;                  /*!< more private data, if any */
00217    union {
00218       char *c;                /*!< the useful portion of the buffer */
00219       unsigned char *uc;      /*!< the useful portion of the buffer */
00220       int16_t *i16;
00221       uint8_t *ui8;
00222    } outbuf;
00223    plc_state_t *plc;           /*!< optional plc pointer */
00224    struct ast_trans_pvt *next; /*!< next in translator chain */
00225    struct timeval nextin;
00226    struct timeval nextout;
00227 };
00228 
00229 /*! \brief generic frameout function */
00230 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
00231         int datalen, int samples);
00232 
00233 struct ast_trans_pvt;
00234 
00235 /*!
00236  * \brief Register a translator
00237  * This registers a codec translator with asterisk
00238  * \param t populated ast_translator structure
00239  * \param mod module handle to the module that owns this translator
00240  * \return 0 on success, -1 on failure
00241  */
00242 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
00243 
00244 /*! \brief See \ref __ast_register_translator() */
00245 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
00246 
00247 /*!
00248  * \brief Unregister a translator
00249  * Unregisters the given tranlator
00250  * \param t translator to unregister
00251  * \return 0 on success, -1 on failure
00252  */
00253 int ast_unregister_translator(struct ast_translator *t);
00254 
00255 /*!
00256  * \brief Activate a previously deactivated translator
00257  * \param t translator to activate
00258  * \return nothing
00259  *
00260  * Enables the specified translator for use.
00261  */
00262 void ast_translator_activate(struct ast_translator *t);
00263 
00264 /*!
00265  * \brief Deactivate a translator
00266  * \param t translator to deactivate
00267  * \return nothing
00268  *
00269  * Disables the specified translator from being used.
00270  */
00271 void ast_translator_deactivate(struct ast_translator *t);
00272 
00273 /*!
00274  * \brief Chooses the best translation path
00275  *
00276  * Given a list of sources, and a designed destination format, which should
00277  * I choose?
00278  *
00279  * \param dst_cap destination capabilities
00280  * \param src_cap source capabilities
00281  * \param dst_fmt_out destination format chosen out of destination capabilities
00282  * \param src_fmt_out source format chosen out of source capabilities
00283  * \return Returns 0 on success, -1 if no path could be found.
00284  *
00285  * \note dst_cap and src_cap are not mondified.
00286  */
00287 int ast_translator_best_choice(struct ast_format_cap *dst_cap,
00288    struct ast_format_cap *src_cap,
00289    struct ast_format *dst_fmt_out,
00290    struct ast_format *src_fmt_out);
00291 
00292 /*! 
00293  * \brief Builds a translator path
00294  * Build a path (possibly NULL) from source to dest 
00295  * \param dst dest destination format
00296  * \param src source source format
00297  * \return ast_trans_pvt on success, NULL on failure
00298  * */
00299 struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
00300 
00301 /*!
00302  * \brief Frees a translator path
00303  * Frees the given translator path structure
00304  * \param tr translator path to get rid of
00305  */
00306 void ast_translator_free_path(struct ast_trans_pvt *tr);
00307 
00308 /*!
00309  * \brief translates one or more frames
00310  * Apply an input frame into the translator and receive zero or one output frames.  Consume
00311  * determines whether the original frame should be freed
00312  * \param path tr translator structure to use for translation
00313  * \param f frame to translate
00314  * \param consume Whether or not to free the original frame
00315  * \return an ast_frame of the new translation format on success, NULL on failure
00316  */
00317 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
00318 
00319 /*!
00320  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
00321  * \param dest destination format
00322  * \param src source format
00323  * \return the number of translation steps required, or -1 if no path is available
00324  */
00325 unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src);
00326 
00327 /*!
00328  * \brief Find available formats
00329  * \param dest possible destination formats
00330  * \param src source formats
00331  * \param result capabilities structure to store available formats in
00332  *
00333  * \return the destination formats that are available in the source or translatable
00334  *
00335  * The result will include all formats from 'dest' that are either present
00336  * in 'src' or translatable from a format present in 'src'.
00337  *
00338  * \note Only a single audio format and a single video format can be
00339  * present in 'src', or the function will produce unexpected results.
00340  */
00341 void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_format_cap *src, struct ast_format_cap *result);
00342 
00343 /*!
00344  * \brief Puts a string representation of the translation path into outbuf
00345  * \param t translator structure containing the translation path
00346  * \param str ast_str output buffer
00347  * \retval on success pointer to beginning of outbuf. on failure "".
00348  */
00349 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
00350 
00351 /*!
00352  * \brief Initialize the translation matrix and index to format conversion table.
00353  * \retval 0 on success
00354  * \retval -1 on failure
00355  */
00356 int ast_translate_init(void);
00357 
00358 #if defined(__cplusplus) || defined(c_plusplus)
00359 }
00360 #endif
00361 
00362 #endif /* _ASTERISK_TRANSLATE_H */

Generated on Thu Oct 11 06:33:57 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6