Add Doxygen documentation for transform search BUG=aomedia:2718 Change-Id: I2b1be999272a7fdd13effc4ceaef93ef0fa64936
diff --git a/av1/encoder/tx_search.c b/av1/encoder/tx_search.c index 54f7a8c..b77dd3f 100644 --- a/av1/encoder/tx_search.c +++ b/av1/encoder/tx_search.c
@@ -2934,8 +2934,6 @@ if (args->current_rd > args->best_rd) args->exit_early = 1; } -// Search for the best transform type and return the transform coefficients RD -// cost of current luma coding block with the given uniform transform size. int64_t av1_uniform_txfm_yrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, int64_t ref_best_rd, BLOCK_SIZE bs, TX_SIZE tx_size, @@ -3285,10 +3283,6 @@ return ((model_rd * factor) >> 3) > ref_best_rd; } -// Search for best transform size and type for luma inter blocks. The transform -// block partitioning can be recursive resulting in non-uniform transform sizes. -// The best transform size and type, if found, will be saved in the MB_MODE_INFO -// structure, and the corresponding RD stats will be saved in rd_stats. void av1_pick_recursive_tx_size_type_yrd(const AV1_COMP *cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bsize, int64_t ref_best_rd) { @@ -3375,11 +3369,6 @@ } } -// Search for the best transform size and type for current coding block, with -// the assumption that all the transform blocks have a uniform size (VP9 style). -// The selected transform size and type will be saved in the MB_MODE_INFO -// structure; the corresponding RD stats will be saved in rd_stats. -// This function may be used for both intra and inter predicted blocks. void av1_pick_uniform_tx_size_type_yrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bs, int64_t ref_best_rd) { @@ -3448,10 +3437,6 @@ } } -// Calculate the transform coefficient RD cost for the given chroma coding block -// If the current mode is intra, then this function will compute the predictor. -// Return value 0: early termination triggered, no valid rd cost available; -// 1: rd cost values are valid. int av1_txfm_uvrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bsize, int64_t ref_best_rd) { av1_init_rd_stats(rd_stats); @@ -3510,9 +3495,6 @@ return is_cost_valid; } -// Search for the best transform type and calculate the transform coefficients -// RD cost of the current coding block with the specified (uniform) transform -// size and channel. The RD results will be saved in rd_stats. void av1_txfm_rd_in_plane(MACROBLOCK *x, const AV1_COMP *cpi, RD_STATS *rd_stats, int64_t ref_best_rd, int64_t current_rd, int plane, BLOCK_SIZE plane_bsize, @@ -3559,14 +3541,6 @@ } } -// This function combines y and uv planes' transform search processes together -// for inter-predicted blocks (including IntraBC), when the prediction is -// already generated. It first does subtraction to obtain the prediction error. -// Then it calls -// av1_pick_recursive_tx_size_type_yrd/av1_pick_uniform_tx_size_type_yrd and -// av1_txfm_uvrd sequentially and handles the early terminations -// happening in those functions. At the end, it computes the -// rd_stats/_y/_uv accordingly. int av1_txfm_search(const AV1_COMP *cpi, MACROBLOCK *x, BLOCK_SIZE bsize, RD_STATS *rd_stats, RD_STATS *rd_stats_y, RD_STATS *rd_stats_uv, int mode_rate, int64_t ref_best_rd) {
diff --git a/av1/encoder/tx_search.h b/av1/encoder/tx_search.h index 420de32..7c29345 100644 --- a/av1/encoder/tx_search.h +++ b/av1/encoder/tx_search.h
@@ -47,28 +47,152 @@ return x->mode_costs.tx_size_cost[tx_size_cat][tx_size_ctx][depth]; } +/*!\brief Transform type search for luma macroblock with fixed transform size. + * + * \ingroup transform_search + * Search for the best transform type and return the transform coefficients RD + * cost of current luma macroblock with the given uniform transform size. + * + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] cpi Top-level encoder structure + * \param[in] rd_stats Pointer to struct to keep track of the RD stats + * \param[in] ref_best_rd Best RD cost seen for this block so far + * \param[in] bs Size of the current macroblock + * \param[in] tx_size The given transform size + * \param[in] ftxs_mode Transform search mode specifying desired speed + and quality tradeoff + * \param[in] skip_trellis Binary flag indicating if trellis optimization + should be skipped + * \return An int64_t value that is the best RD cost found. + */ int64_t av1_uniform_txfm_yrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, int64_t ref_best_rd, BLOCK_SIZE bs, TX_SIZE tx_size, FAST_TX_SEARCH_MODE ftxs_mode, int skip_trellis); +/*!\brief Recursive transform size and type search. + * + * \ingroup transform_search + * Search for best transform size and type for luma inter blocks. The transform + * block partitioning can be recursive resulting in non-uniform transform sizes. + * The best transform size and type, if found, will be saved in the MB_MODE_INFO + * structure, and the corresponding RD stats will be saved in rd_stats. + * + * \param[in] cpi Top-level encoder structure + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] rd_stats Pointer to struct to keep track of the RD stats + * \param[in] bsize Current macroblock size + * \param[in] ref_best_rd Best RD cost seen for this block so far + * \return Nothing is returned. The selected transform size and type will + be saved in the MB_MODE_INFO structure + */ void av1_pick_recursive_tx_size_type_yrd(const AV1_COMP *cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bsize, int64_t ref_best_rd); +/*!\brief Uniform transform size and type search. + * + * \ingroup transform_search + * Search for the best transform size and type for current macroblock block, + * with the assumption that all the transform blocks have a uniform size + * (VP9 style). The selected transform size and type will be saved in the + * MB_MODE_INFO structure; the corresponding RD stats will be saved in rd_stats. + * This function may be used for both intra and inter predicted blocks. + * + * \param[in] cpi Top-level encoder structure + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] rd_stats Pointer to struct to keep track of the RD stats + * \param[in] bs Current macroblock size + * \param[in] ref_best_rd Best RD cost seen for this block so far + * \return Nothing is returned. The selected transform size and type will + be saved in the MB_MODE_INFO structure + */ void av1_pick_uniform_tx_size_type_yrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bs, int64_t ref_best_rd); +/*!\brief Chroma block transform search. + * + * \ingroup transform_search + * Calculate the transform coefficient RD cost for the given chroma macroblock + * If the current mode is intra, then this function will compute the predictor. + * + * \param[in] cpi Top-level encoder structure + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] rd_stats Pointer to struct to keep track of the RD stats + * \param[in] bsize Current macroblock size + * \param[in] ref_best_rd Best RD cost seen for this block so far + * \return An integer value is returned. 0: early termination triggered, + no valid rd cost available; 1: rd cost values are valid. + */ int av1_txfm_uvrd(const AV1_COMP *const cpi, MACROBLOCK *x, RD_STATS *rd_stats, BLOCK_SIZE bsize, int64_t ref_best_rd); +/*!\brief Transform type search with fixed transform size. + * + * \ingroup transform_search + * Search for the best transform type and calculate the transform coefficients + * RD cost of the current transform block with the specified (uniform) transform + * size and plane. The RD results will be saved in rd_stats. + * + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] cpi Top-level encoder structure + * \param[in] rd_stats Pointer to struct to keep track of the RD stats + * \param[in] ref_best_rd Best RD cost seen for this block so far + * \param[in] current_rd Current RD cost for this block so far + * \param[in] plane Plane index + * \param[in] plane_bsize Size of the current macroblock considering + sup-sampling + * \param[in] tx_size The given transform size + * \param[in] use_fast_coef_costing + Binary flag indicating if trellis optimization + should be skipped + * \param[in] ftxs_mode Transform search mode specifying desired speed + and quality tradeoff + * \param[in] skip_trellis Binary flag indicating if trellis optimization + should be skipped + * + * \return Nothing is returned. The RD results will be saved in rd_stats. + */ void av1_txfm_rd_in_plane(MACROBLOCK *x, const AV1_COMP *cpi, RD_STATS *rd_stats, int64_t ref_best_rd, - int64_t this_rd, int plane, BLOCK_SIZE plane_bsize, + int64_t current_rd, int plane, BLOCK_SIZE plane_bsize, TX_SIZE tx_size, int use_fast_coef_costing, FAST_TX_SEARCH_MODE ftxs_mode, int skip_trellis); +/*!\brief Recursive transform size and type search. + * + * \ingroup transform_search + * This function combines y and uv planes' transform search processes together + * for inter-predicted blocks (including IntraBC), when the prediction is + * already generated. It first does subtraction to obtain the prediction error. + * Then it calls + * av1_pick_recursive_tx_size_type_yrd/av1_pick_uniform_tx_size_type_yrd and + * av1_txfm_uvrd sequentially and handles possible early terminations. + * The RD metrics are calculated and stored in rd_stats/_y/_uv. + * + * \param[in] cpi Top-level encoder structure + * \param[in] x Pointer to structure holding the data for the + current encoding macroblock + * \param[in] bsize Current macroblock size + * \param[in] rd_stats Pointer to struct to keep track of the overal RD + stats + * \param[in] rd_stats_y Pointer to struct to keep track of the RD + stats for the luma plane + * \param[in] rd_stats_uv Pointer to struct to keep track of the RD + stats for the chroma planes + * \param[in] mode_rate Rate cost to encode the prediction mode info. of + the current macroblock + * \param[in] ref_best_rd Best RD cost seen for this block so far + * + * \return An integer value is returned indicating if a valid transform + candidate is found (1) or not (0). + */ int av1_txfm_search(const AV1_COMP *cpi, MACROBLOCK *x, BLOCK_SIZE bsize, RD_STATS *rd_stats, RD_STATS *rd_stats_y, RD_STATS *rd_stats_uv, int mode_rate, int64_t ref_best_rd);
diff --git a/docs.cmake b/docs.cmake index 94893e2..6286990 100644 --- a/docs.cmake +++ b/docs.cmake
@@ -119,7 +119,8 @@ "${AOM_ROOT}/av1/encoder/lookahead.h" "${AOM_ROOT}/av1/encoder/picklpf.h" "${AOM_ROOT}/av1/encoder/rdopt.h" - "${AOM_ROOT}/av1/encoder/rdopt.c") + "${AOM_ROOT}/av1/encoder/rdopt.c" + "${AOM_ROOT}/av1/encoder/tx_search.h") endif() if(CONFIG_AV1_DECODER AND CONFIG_AV1_ENCODER)