[asterisk-commits] dvossel: branch dvossel/fixtheworld_phase1_step2 r299579 - in /team/dvossel/f...

SVN commits to the Asterisk project asterisk-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 asterisk-commits mailing list