[svn-commits] dvossel: branch dvossel/fixtheworld_phase1_step2 r299579 - in /team/dvossel/f...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Thu Dec 23 16:52:58 UTC 2010
Author: dvossel
Date: Thu Dec 23 10:52:54 2010
New Revision: 299579
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=299579
Log:
Improved documentation of translation cost table
Modified:
team/dvossel/fixtheworld_phase1_step2/include/asterisk/translate.h
team/dvossel/fixtheworld_phase1_step2/main/translate.c
Modified: team/dvossel/fixtheworld_phase1_step2/include/asterisk/translate.h
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/fixtheworld_phase1_step2/include/asterisk/translate.h?view=diff&rev=299579&r1=299578&r2=299579
==============================================================================
--- team/dvossel/fixtheworld_phase1_step2/include/asterisk/translate.h (original)
+++ team/dvossel/fixtheworld_phase1_step2/include/asterisk/translate.h Thu Dec 23 10:52:54 2010
@@ -40,9 +40,26 @@
struct ast_trans_pvt; /* declared below */
-/*! Translator Cost Table
- * The defined values in this table must be used to
- * set the translator's cost value. */
+/*!
+ * \brief Translator Cost Table definition.
+ *
+ * \note The defined values in this table must be used to set
+ * the translator's table_cost value.
+ *
+ * \note The cost value of the first two values must always add
+ * up to be greater than the largest value defined in this table.
+ * This is done to guarantee a direct translation will always
+ * have precedence over a multi step translation.
+ *
+ * \details This table is built in a way that allows translation
+ * paths to be built that guarantee the best possible balance
+ * between performance and quality. With this table direct
+ * translation paths between two formats always takes precedence
+ * over multi step paths, lossless intermediate steps are always
+ * chosen over lossy intermediate steps, and preservation of
+ * sample rate across the translation will always have precedence
+ * over a path that involves any re-sampling.
+ */
enum ast_trans_cost_table {
/* Lossless Source Translation Costs */
@@ -62,6 +79,11 @@
/*! [lossless -> lossy] down sample */
AST_TRANS_COST_LL_LY_DOWNSAMP = 875000,
+ /*! [lossless -> unknown] unknown.
+ * This value is for a lossless source translation
+ * with an unknown destination and or sample rate conversion. */
+ AST_TRANS_COST_LL_UNKNOWN = 885000,
+
/* Lossy Source Translation Costs */
/*! [lossy -> lossless] original sampling */
@@ -78,6 +100,12 @@
AST_TRANS_COST_LY_LL_DOWNSAMP = 960000,
/*! [lossy -> lossy] down sample */
AST_TRANS_COST_LY_LY_DOWNSAMP = 975000,
+
+ /*! [lossy -> unknown] unknown.
+ * This value is for a lossy source translation
+ * with an unknown destination and or sample rate conversion. */
+ AST_TRANS_COST_LY_UNKNOWN = 985000,
+
};
/*! \brief
Modified: team/dvossel/fixtheworld_phase1_step2/main/translate.c
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/fixtheworld_phase1_step2/main/translate.c?view=diff&rev=299579&r1=299578&r2=299579
==============================================================================
--- team/dvossel/fixtheworld_phase1_step2/main/translate.c (original)
+++ team/dvossel/fixtheworld_phase1_step2/main/translate.c Thu Dec 23 10:52:54 2010
@@ -86,9 +86,9 @@
/* index size grows by this as necessary */
#define GROW_INDEX 16
-/*! the current largest index used by the matrix_get( and __indextable tables */
+/*! the current largest index used by the __matrix and __indextable arrays*/
static int cur_max_index;
-/*! the largest index that can be used in eithr the __indextable or __matrix before resize must occur */
+/*! the largest index that can be used in either the __indextable or __matrix before resize must occur */
static int index_size;
static void matrix_rebuild(int samples);
@@ -528,11 +528,12 @@
/*!
* \internal
- *
-* \brief Compute the computational cost of a single translation step.
+ * \brief Compute the computational cost of a single translation step.
*
* \note This function is only used to decide which translation path to
- * use between two translators with identical src and dst formats.
+ * use between two translators with identical src and dst formats. Computational
+ * cost acts only as a tie breaker. This is done so hardware translators
+ * can naturally have precedence over software translators.
*/
static void generate_computational_cost(struct ast_translator *t, int seconds)
{
@@ -603,10 +604,11 @@
*
* \note This function allows older translators built before the translation cost
* changed away from using onely computational time to continue to be registered
- * correctly.
- *
- * \note This function is safe to use on any formats that used to be defined in the
- * first 32 bits of the old bit field codec representation.
+ * correctly. It is expected that translators built after the introduction of this
+ * function will manually assign their own table cost value.
+ *
+ * \note This function is safe to use on any audio formats that used to be defined in the
+ * first 64 bits of the old bit field codec representation.
*
* \retval Table Cost value greater than 0.
* \retval 0 on error.
@@ -619,7 +621,9 @@
int dst_ll = 0;
if (!(src & AST_FORMAT_AUDIO_MASK) || !(src & AST_FORMAT_AUDIO_MASK)) {
- /* this old method of generating table cost is limited to audio. */
+ /* This method of generating table cost is limited to audio.
+ * Translators for media other than audio must manually set their
+ * table cost. */
return 0;
}
if ((src == AST_FORMAT_SLINEAR) || (src == AST_FORMAT_SLINEAR16)) {
@@ -640,8 +644,10 @@
return AST_TRANS_COST_LL_LY_UPSAMP;
} else if (dst_ll && (src_rate > dst_rate)) {
return AST_TRANS_COST_LL_LL_DOWNSAMP;
+ } else if (!dst_ll && (src_rate > dst_rate)) {
+ return AST_TRANS_COST_LL_LY_DOWNSAMP;
} else {
- return AST_TRANS_COST_LL_LY_DOWNSAMP;
+ return AST_TRANS_COST_LL_UNKNOWN;
}
} else {
if (dst_ll && (src_rate == dst_rate)) {
@@ -654,8 +660,10 @@
return AST_TRANS_COST_LY_LY_UPSAMP;
} else if (dst_ll && (src_rate > dst_rate)) {
return AST_TRANS_COST_LY_LL_DOWNSAMP;
+ } else if (!dst_ll && (src_rate > dst_rate)) {
+ return AST_TRANS_COST_LY_LY_DOWNSAMP;
} else {
- return AST_TRANS_COST_LY_LY_DOWNSAMP;
+ return AST_TRANS_COST_LY_UNKNOWN;
}
}
}
@@ -1312,7 +1320,6 @@
return res;
}
-
int ast_translate_init(void)
{
ast_rwlock_init(&tablelock);
More information about the svn-commits
mailing list