Add Doxygen comments to block.h BUG=aomedia:2715 Change-Id: I7d77d1110e717a29bfcff67cd7c1cf25b67b5619
diff --git a/av1/encoder/block.h b/av1/encoder/block.h index 23be6aa..bda5f7c 100644 --- a/av1/encoder/block.h +++ b/av1/encoder/block.h
@@ -9,6 +9,9 @@ * PATENTS file, you can obtain it at www.aomedia.org/license/patent. */ +/*! \file + * Declares various structs used to encode the current partition block. + */ #ifndef AOM_AV1_ENCODER_BLOCK_H_ #define AOM_AV1_ENCODER_BLOCK_H_ @@ -28,727 +31,1165 @@ extern "C" { #endif +//! Linear dimension of a tpl block #define MC_FLOW_BSIZE_1D 16 +//! Number of pixels in a tpl block #define MC_FLOW_NUM_PELS (MC_FLOW_BSIZE_1D * MC_FLOW_BSIZE_1D) +//! Number of tpl block in a super block #define MAX_MC_FLOW_BLK_IN_SB (MAX_SB_SIZE / MC_FLOW_BSIZE_1D) +//! Number of intra winner modes kept #define MAX_WINNER_MODE_COUNT_INTRA 3 +//! Number of inter winner modes kept #define MAX_WINNER_MODE_COUNT_INTER 1 +//! Number of txfm hash records kept for the partition block. +#define RD_RECORD_BUFFER_LEN 8 +//! Number of txfm hash records kept for the txfm block. +#define TX_SIZE_RD_RECORD_BUFFER_LEN 256 -// SuperblockEnc stores superblock level information used by the encoder for -// more efficient encoding. +/*! \brief Superblock level encoder info + * + * SuperblockEnc stores superblock level information used by the encoder for + * more efficient encoding. Currently this is mostly used to store TPL data + * for the current superblock. + */ typedef struct { - // The maximum and minimum allowed partition size + //! Maximum partition size for the sb. BLOCK_SIZE min_partition_size; + //! Minimum partition size for the sb. BLOCK_SIZE max_partition_size; - // Below are information gathered from tpl_model used to speed up the encoding - // process. + /***************************************************************************** + * \name TPL Info + * + * Information gathered from tpl_model at MC_FLOW_BSIZE_1D precision for the + * superblock to speed up the encoding process.. + ****************************************************************************/ + /**@{*/ + //! Number of TPL blocks in this superblock. int tpl_data_count; + //! TPL's estimate of inter cost for each tpl block. int64_t tpl_inter_cost[MAX_MC_FLOW_BLK_IN_SB * MAX_MC_FLOW_BLK_IN_SB]; + //! TPL's estimate of tpl cost for each tpl block. int64_t tpl_intra_cost[MAX_MC_FLOW_BLK_IN_SB * MAX_MC_FLOW_BLK_IN_SB]; + //! Motion vectors found by TPL model for each tpl block. int_mv tpl_mv[MAX_MC_FLOW_BLK_IN_SB * MAX_MC_FLOW_BLK_IN_SB] [INTER_REFS_PER_FRAME]; + //! TPL's stride for the arrays in this struct. int tpl_stride; + /**@}*/ } SuperBlockEnc; +/*! \brief Stores the best performing modes. + */ typedef struct { + //! The mbmi used to reconstruct the winner mode. MB_MODE_INFO mbmi; + //! Rdstats of the winner mode. RD_STATS rd_cost; + //! Rdcost of the winner mode int64_t rd; + //! Luma rate of the winner mode. int rate_y; + //! Chroma rate of the winner mode. int rate_uv; - uint8_t color_index_map[64 * 64]; + //! The color map needed to reconstruct palette mode. + uint8_t color_index_map[MAX_SB_SQUARE]; + //! The current winner mode. THR_MODES mode_index; } WinnerModeStats; -typedef struct { - unsigned int sse; - int sum; - unsigned int var; -} DIFF; - -enum { - NO_TRELLIS_OPT, // No trellis optimization - FULL_TRELLIS_OPT, // Trellis optimization in all stages - FINAL_PASS_TRELLIS_OPT, // Trellis optimization in only the final encode pass - NO_ESTIMATE_YRD_TRELLIS_OPT // Disable trellis in estimate_yrd_for_sb -} UENUM1BYTE(TRELLIS_OPT_TYPE); - -enum { - FULL_TXFM_RD, - LOW_TXFM_RD, -} UENUM1BYTE(TXFM_RD_MODEL); - -enum { - USE_FULL_RD = 0, - USE_FAST_RD, - USE_LARGESTALL, -} UENUM1BYTE(TX_SIZE_SEARCH_METHOD); - +/*! \brief Each source plane of the current macroblock + * + * This struct also stores the txfm buffers and quantizer settings. + */ typedef struct macroblock_plane { + //! Stores source - pred so the txfm can be computed later DECLARE_ALIGNED(32, int16_t, src_diff[MAX_SB_SQUARE]); + //! Dequantized coefficients tran_low_t *dqcoeff; + //! Quantized coefficients tran_low_t *qcoeff; + //! Transformed coefficients tran_low_t *coeff; + //! Location of the end of qcoeff (end of block). uint16_t *eobs; + //! Contexts used to code the transform coefficients. uint8_t *txb_entropy_ctx; + //! A buffer containing the source frame. struct buf_2d src; - // Quantizer setings - // These are used/accessed only in the quantization process - // RDO does not / must not depend on any of these values - // All values below share the coefficient scale/shift used in TX + /*! \name Quantizer Settings + * + * \attention These are used/accessed only in the quantization process. + * RDO does not and *must not* depend on any of these values. + * All values below share the coefficient scale/shift used in TX. + */ + /**@{*/ + //! Quantization step size used by AV1_XFORM_QUANT_FP. const int16_t *quant_fp_QTX; + //! Offset used for rounding in the quantizer process by AV1_XFORM_QUANT_FP. const int16_t *round_fp_QTX; + //! Quantization step size used by AV1_XFORM_QUANT_B. const int16_t *quant_QTX; - const int16_t *quant_shift_QTX; - const int16_t *zbin_QTX; + //! Offset used for rounding in the quantizer process by AV1_XFORM_QUANT_B. const int16_t *round_QTX; + //! Scale factor to shift coefficients toward zero. Only used by QUANT_B. + const int16_t *quant_shift_QTX; + //! Size of the quantization bin around 0. Only Used by QUANT_B + const int16_t *zbin_QTX; + //! Dequantizer const int16_t *dequant_QTX; + /**@}*/ } MACROBLOCK_PLANE; +/*! \brief Costs for encoding the coefficients within a level. + * + * Covers everything including txb_skip, eob, dc_sign, + */ typedef struct { + //! Cost to skip txfm for the current txfm block. int txb_skip_cost[TXB_SKIP_CONTEXTS][2]; + /*! \brief Cost for encoding the base_eob of a level. + * + * Decoder uses base_eob to derive the base_level as base_eob := base_eob+1. + */ int base_eob_cost[SIG_COEF_CONTEXTS_EOB][3]; + /*! \brief Cost for encoding the base level of a coefficient. + * + * Decoder derives coeff_base as coeff_base := base_eob + 1. + */ int base_cost[SIG_COEF_CONTEXTS][8]; + /*! \brief Cost for encoding the last non-zero coefficient. + * + * Eob is derived from eob_extra at the decoder as eob := eob_extra + 1 + */ int eob_extra_cost[EOB_COEF_CONTEXTS][2]; + //! Cost for encoding the dc_sign int dc_sign_cost[DC_SIGN_CONTEXTS][2]; + //! Cost for encoding an increment to the coefficient int lps_cost[LEVEL_CONTEXTS][COEFF_BASE_RANGE + 1 + COEFF_BASE_RANGE + 1]; } LV_MAP_COEFF_COST; +/*! \brief Costs for encoding the eob. + */ typedef struct { + //! eob_cost. int eob_cost[2][11]; } LV_MAP_EOB_COST; +/*! \brief Stores the transforms coefficients for the whole superblock. + */ typedef struct { + //! The transformed coefficients. tran_low_t tcoeff[MAX_MB_PLANE][MAX_SB_SQUARE]; + //! Where the transformed coefficients end. uint16_t eobs[MAX_MB_PLANE][MAX_SB_SQUARE / (TX_SIZE_W_MIN * TX_SIZE_H_MIN)]; - // Transform block entropy contexts. - // Bits 0~3: txb_skip_ctx; bits 4~5: dc_sign_ctx. + /*! \brief Transform block entropy contexts. + * + * Each element is used as a bit field. + * - Bits 0~3: txb_skip_ctx + * - Bits 4~5: dc_sign_ctx. + */ uint8_t entropy_ctx[MAX_MB_PLANE] [MAX_SB_SQUARE / (TX_SIZE_W_MIN * TX_SIZE_H_MIN)]; } CB_COEFF_BUFFER; +/*! \brief Extended mode info derived from mbmi. + */ typedef struct { // TODO(angiebird): Reduce the buffer size according to sb_type + //! The reference mv list for the current block. CANDIDATE_MV ref_mv_stack[MODE_CTX_REF_FRAMES][USABLE_REF_MV_STACK_SIZE]; + //! The weights used to compute the ref mvs. uint16_t weight[MODE_CTX_REF_FRAMES][USABLE_REF_MV_STACK_SIZE]; - int_mv global_mvs[REF_FRAMES]; - int16_t mode_context[MODE_CTX_REF_FRAMES]; + //! Number of ref mvs in the drl. uint8_t ref_mv_count[MODE_CTX_REF_FRAMES]; + //! Global mvs + int_mv global_mvs[REF_FRAMES]; + //! Context used to encode the current mode. + int16_t mode_context[MODE_CTX_REF_FRAMES]; } MB_MODE_INFO_EXT; -// Structure to store best mode information at frame level. This -// frame level information will be used during bitstream preparation stage. +/*! \brief Stores best extended mode information at frame level. + * + * The frame level in here is used in bitstream preparation stage. The + * information in \ref MB_MODE_INFO_EXT are copied to this struct to save + * memory. + */ typedef struct { + //! \copydoc MB_MODE_INFO_EXT::ref_mv_stack CANDIDATE_MV ref_mv_stack[USABLE_REF_MV_STACK_SIZE]; + //! \copydoc MB_MODE_INFO_EXT::weight uint16_t weight[USABLE_REF_MV_STACK_SIZE]; - // TODO(Ravi/Remya): Reduce the buffer size of global_mvs - int_mv global_mvs[REF_FRAMES]; - int cb_offset; - int16_t mode_context; + //! \copydoc MB_MODE_INFO_EXT::ref_mv_count uint8_t ref_mv_count; + // TODO(Ravi/Remya): Reduce the buffer size of global_mvs + //! \copydoc MB_MODE_INFO_EXT::global_mvs + int_mv global_mvs[REF_FRAMES]; + //! \copydoc MB_MODE_INFO_EXT::mode_context + int16_t mode_context; + //! Offset of current coding block's coeff buffer relative to the sb. + int cb_offset; } MB_MODE_INFO_EXT_FRAME; +/*! \brief Txfm search results for a partition + */ typedef struct { - uint8_t best_palette_color_map[MAX_PALETTE_SQUARE]; - int kmeans_data_buf[2 * MAX_PALETTE_SQUARE]; -} PALETTE_BUFFER; - -typedef struct { + //! Txfm size used if the current mode is intra mode. TX_SIZE tx_size; + //! Txfm sizes used if the current mode is inter mode. TX_SIZE inter_tx_size[INTER_TX_SIZE_BUF_LEN]; + //! Map showing which txfm block skips the txfm process. uint8_t blk_skip[MAX_MIB_SIZE * MAX_MIB_SIZE]; + //! Map showing the txfm types for each blcok. uint8_t tx_type_map[MAX_MIB_SIZE * MAX_MIB_SIZE]; + //! Rd_stats for the whole partition block. RD_STATS rd_stats; + //! Hash value of the current record. uint32_t hash_value; } MB_RD_INFO; -#define RD_RECORD_BUFFER_LEN 8 +/*! \brief Hash records of txfm search results for the partition block. + */ typedef struct { + //! Circular buffer that stores the txfm search results. MB_RD_INFO tx_rd_info[RD_RECORD_BUFFER_LEN]; // Circular buffer. + //! Index to insert the newest \ref TXB_RD_INFO. int index_start; + //! Number of info stored in this record. int num; - CRC32C crc_calculator; // Hash function. + //! Hash function + CRC32C crc_calculator; } MB_RD_RECORD; +/*! \brief Txfm search results for a tx block. + */ typedef struct { + //! Distortion after the txfm process int64_t dist; + //! SSE of the prediction before the txfm process int64_t sse; + //! Rate used to encode the txfm. int rate; + //! Location of the end of non-zero entries. uint16_t eob; + //! Transform type used on the current block. TX_TYPE tx_type; + //! Unknown usage uint16_t entropy_context; + //! Context used to code the coefficients. uint8_t txb_entropy_ctx; + //! Whether the current info block contains valid info uint8_t valid; - uint8_t fast; // This is not being used now. + //! Unused + uint8_t fast; + //! Whether trellis optimization is done. uint8_t perform_block_coeff_opt; } TXB_RD_INFO; -#define TX_SIZE_RD_RECORD_BUFFER_LEN 256 +/*! \brief Hash records of txfm search result for each tx block. + */ typedef struct { + //! The hash values. uint32_t hash_vals[TX_SIZE_RD_RECORD_BUFFER_LEN]; + //! The txfm search results TXB_RD_INFO tx_rd_info[TX_SIZE_RD_RECORD_BUFFER_LEN]; + //! Index to insert the newest \ref TXB_RD_INFO. int index_start; + //! Number of info stored in this record. int num; } TXB_RD_RECORD; -typedef struct tx_size_rd_info_node { - TXB_RD_INFO *rd_info_array; // Points to array of size TX_TYPES. - struct tx_size_rd_info_node *children[4]; -} TXB_RD_INFO_NODE; - -// Simple translation rd state for prune_comp_search_by_single_result +/*! \brief Simple translation rd_stats for prune_comp_search_by_single_result(). + * + * This is only used by the rd-path of AV1 realtime. + */ typedef struct { + //! rd_stats for single_ref single_translation. RD_STATS rd_stats; + //! Luma rd_stats for single_ref single_translation. RD_STATS rd_stats_y; + //! Chroma rd_stats for single_ref single_translation. RD_STATS rd_stats_uv; + //! Txfm skip map of the txfm subblocks. uint8_t blk_skip[MAX_MIB_SIZE * MAX_MIB_SIZE]; + //! Txfm type map of the txfm subblocks. uint8_t tx_type_map[MAX_MIB_SIZE * MAX_MIB_SIZE]; + //! Whether to skip the txfm process. uint8_t skip_txfm; + //! Whether simple_ref single_trans result decides to prune the mode. uint8_t early_skipped; } SimpleRDState; -// 4: NEAREST, NEW, NEAR, GLOBAL -#define SINGLE_REF_MODES ((REF_FRAMES - 1) * 4) - +//! Number of compound rd stats #define MAX_COMP_RD_STATS 64 +/*! \brief Rdcost stats in compound mode. + */ typedef struct { + //! Rate of the compound modes. int32_t rate[COMPOUND_TYPES]; + //! Distortion of the compound modes. int64_t dist[COMPOUND_TYPES]; + //! Estimated rate of the compound modes. int32_t model_rate[COMPOUND_TYPES]; + //! Estimated distortion of the compound modes. int64_t model_dist[COMPOUND_TYPES]; + //! Rate need to send the mask type. int comp_rs2[COMPOUND_TYPES]; + //! Motion vector for each predictor. int_mv mv[2]; + //! Ref frame for each predictor. MV_REFERENCE_FRAME ref_frames[2]; + //! Current prediction mode. PREDICTION_MODE mode; + //! Current interpolation filter. int_interpfilters filter; + //! Refmv index in the drl. int ref_mv_idx; + //! Whether the predictors are GLOBALMV. int is_global[2]; + //! Current parameters for interinter mode. INTERINTER_COMPOUND_DATA interinter_comp; } COMP_RD_STATS; -// Struct for buffers used by av1_compound_type_rd() function. -// For sizes and alignment of these arrays, refer to -// alloc_compound_type_rd_buffers() function. +/*! \brief Contains buffers used to speed up rdopt for obmc. + * + * See the comments for calc_target_weighted_pred for details. + */ typedef struct { - uint8_t *pred0; - uint8_t *pred1; - int16_t *residual1; // src - pred1 - int16_t *diff10; // pred1 - pred0 - uint8_t *tmp_best_mask_buf; // backup of the best segmentation mask -} CompoundTypeRdBuffers; - -// Struct for buffers used to speed up rdopt for obmc. -// See the comments for calc_target_weighted_pred for details. -typedef struct { - // A new source weighted with the above and left predictors for efficient - // rdopt in obmc mode. + /*! \brief A new source weighted with the above and left predictors. + * + * Used to efficiently construct multiple obmc predictors during rdopt. + */ int32_t *wsrc; - // A new mask constructed from the original left and horizontal masks for - // fast obmc rdopt. + /*! \brief A new mask constructed from the original horz/vert mask. + * + * \copydetails wsrc + */ int32_t *mask; - // Holds a prediction using the above/left predictor. This is used to build - // the obmc predictor. + /*! \brief Prediction from the up predictor. + * + * Used to build the obmc predictor. + */ uint8_t *above_pred; + /*! \brief Prediction from the up predictor. + * + * \copydetails above_pred + */ uint8_t *left_pred; } OBMCBuffer; -// This struct holds some parameters related to partitioning schemes in av1. +/*! \brief Contains color maps used in palette mode. + */ +typedef struct { + //! The best color map found. + uint8_t best_palette_color_map[MAX_PALETTE_SQUARE]; + //! A temporary buffer used for k-means clustering. + int kmeans_data_buf[2 * MAX_PALETTE_SQUARE]; +} PALETTE_BUFFER; + +/*! \brief Contains buffers used by av1_compound_type_rd() + * + * For sizes and alignment of these arrays, refer to + * alloc_compound_type_rd_buffers() function. + */ +typedef struct { + //! First prediction. + uint8_t *pred0; + //! Second prediction. + uint8_t *pred1; + //! Source - first prediction. + int16_t *residual1; + //! Second prediction - first prediction. + int16_t *diff10; + //! Backup of the best segmentation mask. + uint8_t *tmp_best_mask_buf; +} CompoundTypeRdBuffers; + +/*! \brief Holds some parameters related to partitioning schemes in AV1. + */ // TODO(chiyotsai@google.com): Consolidate this with SIMPLE_MOTION_DATA_TREE typedef struct { #if !CONFIG_REALTIME_ONLY // The following 4 parameters are used for cnn-based partitioning on intra // frame. - // Where we are on the quad tree. Used to index into the cnn buffer for - // partition decision. + /*! \brief Current index on the partition block quad tree. + * + * Used to index into the cnn buffer for partition decision. + */ int quad_tree_idx; - // Whether the CNN buffer contains valid output + //! Whether the CNN buffer contains valid output. int cnn_output_valid; - // A buffer used by our segmentation CNN for intra-frame partitioning. + //! A buffer used by our segmentation CNN for intra-frame partitioning. float cnn_buffer[CNN_OUT_BUF_SIZE]; - // log of the quantization parameter of the current BLOCK_64X64 that includes - // the current block. Used as an input to the CNN. + //! log of the quantization parameter of the ancestor BLOCK_64X64. float log_q; #endif - // Holds the variable of various subblocks. This is used by rt mode for - // variance based partitioning. - // 0 - 128x128 | 1-2 - 128x64 | 3-4 - 64x128 - // 5-8 - 64x64 | 9-16 - 64x32 | 17-24 - 32x64 - // 25-40 - 32x32 - // 41-104 - 16x16 + /*! \brief Variance of the subblocks in the superblock. + * + * This is used by rt mode for variance based partitioning. + * The indices corresponds to the following block sizes: + * - 0 - 128x128 + * - 1-2 - 128x64 + * - 3-4 - 64x128 + * - 5-8 - 64x64 + * - 9-16 - 64x32 + * - 17-24 - 32x64 + * - 25-40 - 32x32 + * - 41-104 - 16x16 + */ uint8_t variance_low[105]; } PartitionSearchInfo; -// This struct stores the parameters used to perform the txfm search. For the -// most part, this determines how various speed features are used. +/*! \brief Defines the parameters used to perform txfm search. + * + * For the most part, this determines how various speed features are used. + */ typedef struct { - // Whether to limit the txfm search type to the default txfm during rdopt. - // This could either be a result of either sequence parameter or speed - // features. + /*! \brief Whether to limit the intra txfm search type to the default txfm. + * + * This could either be a result of either sequence parameter or speed + * features. + */ int use_default_intra_tx_type; + /*! \brief Whether to limit the inter txfm search type to the default txfm. + * + * \copydetails use_default_intra_tx_type + */ int use_default_inter_tx_type; - // Try to prune 2d transforms based on 1d transform results. + //! Whether to prune 2d transforms based on 1d transform results. int prune_2d_txfm_mode; - // The following six parameters are copied from WinnerModeParams based on the - // current evaluation mode. See the documentation for WinnerModeParams for - // more detail. + /*! \brief Variable from \ref WinnerModeParams based on current eval mode. + * + * See the documentation for \ref WinnerModeParams for more detail. + */ unsigned int coeff_opt_dist_threshold; + //! \copydoc coeff_opt_dist_threshold unsigned int coeff_opt_satd_threshold; + //! \copydoc coeff_opt_dist_threshold unsigned int tx_domain_dist_threshold; + //! \copydoc coeff_opt_dist_threshold TX_SIZE_SEARCH_METHOD tx_size_search_method; + //! \copydoc coeff_opt_dist_threshold unsigned int use_transform_domain_distortion; + //! \copydoc coeff_opt_dist_threshold unsigned int skip_txfm_level; - // Although this looks suspicious similar to a bitstream element, This - // tx_mode_search_type is used internally by the encoder, and is not - // written to the bitstream. It determines what kind of tx_mode should be - // searched. For example, we might set it to TX_MODE_LARGEST to find a good - // candidate, then use TX_MODE_SELECT on it + /*! \brief How to search for the optimal tx_size + * + * If ONLY_4X4, use TX_4X4; if TX_MODE_LARGEST, use the largest tx_size for + * the current partition block; if TX_MODE_SELECT, search through the whole + * tree. + * + * \attention + * Although this looks suspicious similar to a bitstream element, this + * tx_mode_search_type is only used internally by the encoder, and is *not* + * written to the bitstream. It determines what kind of tx_mode would be + * searched. For example, we might set it to TX_MODE_LARGEST to find a good + * candidate, then code it as TX_MODE_SELECT. + */ TX_MODE tx_mode_search_type; } TxfmSearchParams; +/*!\cond */ #define MAX_NUM_8X8_TXBS ((MAX_MIB_SIZE >> 1) * (MAX_MIB_SIZE >> 1)) #define MAX_NUM_16X16_TXBS ((MAX_MIB_SIZE >> 2) * (MAX_MIB_SIZE >> 2)) #define MAX_NUM_32X32_TXBS ((MAX_MIB_SIZE >> 3) * (MAX_MIB_SIZE >> 3)) #define MAX_NUM_64X64_TXBS ((MAX_MIB_SIZE >> 4) * (MAX_MIB_SIZE >> 4)) +/*!\endcond */ -// This struct stores various encoding/search decisions related to txfm search. -// This can include cache of previous txfm results, the current encoding -// decision, etc. +/*! \brief Stores various encoding/search decisions related to txfm search. + * + * This struct contains a cache of previous txfm results, and some buffers for + * the current txfm decision. + */ typedef struct { - // Skips transform and quantization on a partition block level. + //! Whether to skip transform and quantization on a partition block level. int skip_txfm; - // Skips transform and quantization on a transform block level inside the - // current partition block. Each element of this array is used as a bit-field. - // So for example, the we are skipping on the luma plane, then the last bit - // would be set to 1. + /*! \brief Whether to skip transform and quantization on a txfm block level. + * + * Skips transform and quantization on a transform block level inside the + * current partition block. Each element of this array is used as a bit-field. + * So for example, the we are skipping on the luma plane, then the last bit + * would be set to 1. + */ uint8_t blk_skip[MAX_MIB_SIZE * MAX_MIB_SIZE]; - // Keeps a record of what kind of transform to use for each of the transform - // block inside the partition block. A quick note here: the buffer here is - // NEVER directly used. Instead, this just allocates the memory for - // MACROBLOCKD::tx_type_map during rdopt on the partition block. So if we need - // to save memory, we could move the allocation to pick_sb_mode instead. + /*! \brief Transform types inside the partition block + * + * Keeps a record of what kind of transform to use for each of the transform + * block inside the partition block. + * \attention The buffer here is *never* directly used. Instead, this just + * allocates the memory for MACROBLOCKD::tx_type_map during rdopt on the + * partition block. So if we need to save memory, we could move the allocation + * to pick_sb_mode instead. + */ uint8_t tx_type_map_[MAX_MIB_SIZE * MAX_MIB_SIZE]; - // Records of a partition block's inter-mode txfm result hashed by its - // residue. This is similar to txb_rd_record_*, but this operates on the whole - // prediction block. + /** \name Txfm hash records + * Hash records of the transform search results based on the residue. There + * are two main types here: + * - MB_RD_RECORD: records a whole *partition block*'s inter-mode txfm result. + * Since this operates on the partition block level, this can give us a + * whole txfm partition tree. + * - TXB_RD_RECORD: records a txfm search result within a transform blcok + * itself. This operates on txb level only and onlyt appplies to square + * txfms. + */ + /**@{*/ + //! Txfm hash record for the whole coding block. MB_RD_RECORD mb_rd_record; - // Records of a transform block's result hashed by residue within the - // transform block. This operates on txb level only and only applies to square - // txfms. - // Inter transform block RD search + //! Inter mode txfm hash record for TX_8X8 blocks. TXB_RD_RECORD txb_rd_record_8X8[MAX_NUM_8X8_TXBS]; + //! Inter mode txfm hash record for TX_16X16 blocks. TXB_RD_RECORD txb_rd_record_16X16[MAX_NUM_16X16_TXBS]; + //! Inter mode txfm hash record for TX_32X32 blocks. TXB_RD_RECORD txb_rd_record_32X32[MAX_NUM_32X32_TXBS]; + //! Inter mode txfm hash record for TX_64X64 blocks. TXB_RD_RECORD txb_rd_record_64X64[MAX_NUM_64X64_TXBS]; - // Intra transform block RD search + //! Intra mode txfm hash record for square tx blocks. TXB_RD_RECORD txb_rd_record_intra; + /**@}*/ - // Keep track of how many times we've used split partition for transform - // blocks. Misleadingly, his parameter doesn't actually keep track of the - // count of the current block. Instead, it's a cumulative count across of the - // whole frame. The main usage is that if txb_split_count is zero, then we - // can signal TX_MODE_LARGEST at frame level. + /*! \brief Number of txb splits. + * + * Keep track of how many times we've used split tx partition for transform + * blocks. Somewhat misleadingly, this parameter doesn't actually keep track + * of the count of the current block. Instead, it's a cumulative count across + * of the whole frame. The main usage is that if txb_split_count is zero, then + * we can signal TX_MODE_LARGEST at frame level. + */ // TODO(chiyotsai@google.com): Move this to a more appropriate location such // as ThreadData. unsigned int txb_split_count; #if CONFIG_SPEED_STATS - // For debugging. Used to check how many txfm searches we are doing. + //! For debugging. Used to check how many txfm searches we are doing. unsigned int tx_search_count; #endif // CONFIG_SPEED_STATS } TxfmSearchInfo; +#undef MAX_NUM_8X8_TXBS +#undef MAX_NUM_16X16_TXBS +#undef MAX_NUM_32X32_TXBS +#undef MAX_NUM_64X64_TXBS -// This struct holds the entropy costs for various modes sent to the bitstream. -// This however does not include the costs for mv and transformed coefficients. +/*! \brief Holds the entropy costs for various modes sent to the bitstream. + * + * \attention This does not include the costs for mv and transformed + * coefficients. + */ typedef struct { - // ========================================================================== - // Partition Costs - // ========================================================================== + /***************************************************************************** + * \name Partition Costs + ****************************************************************************/ + /**@{*/ + //! Cost for coding the partition. int partition_cost[PARTITION_CONTEXTS][EXT_PARTITION_TYPES]; + /**@}*/ - // ========================================================================== - // Intra Mode Costs - // ========================================================================== - int mbmode_cost[BLOCK_SIZE_GROUPS][INTRA_MODES]; // Mode cost for inter frame - int y_mode_costs[INTRA_MODES][INTRA_MODES][INTRA_MODES]; // Mode cost for kf + /***************************************************************************** + * \name Intra Costs: General + ****************************************************************************/ + /**@{*/ + //! Luma mode cost for inter frame. + int mbmode_cost[BLOCK_SIZE_GROUPS][INTRA_MODES]; + //! Luma mode cost for intra frame. + int y_mode_costs[INTRA_MODES][INTRA_MODES][INTRA_MODES]; + //! Chroma mode cost int intra_uv_mode_cost[CFL_ALLOWED_TYPES][INTRA_MODES][UV_INTRA_MODES]; + //! filter_intra_cost int filter_intra_cost[BLOCK_SIZES_ALL][2]; + //! filter_intra_mode_cost int filter_intra_mode_cost[FILTER_INTRA_MODES]; + //! angle_delta_cost int angle_delta_cost[DIRECTIONAL_MODES][2 * MAX_ANGLE_DELTA + 1]; - // Screen Content Tools Costs + //! Rate rate associated with each alpha codeword + int cfl_cost[CFL_JOINT_SIGNS][CFL_PRED_PLANES][CFL_ALPHABET_SIZE]; + /**@}*/ + + /***************************************************************************** + * \name Intra Costs: Screen Contents + ****************************************************************************/ + /**@{*/ + //! intrabc_cost int intrabc_cost[2]; + //! palette_y_size_cost int palette_y_size_cost[PALATTE_BSIZE_CTXS][PALETTE_SIZES]; + //! palette_uv_size_cost int palette_uv_size_cost[PALATTE_BSIZE_CTXS][PALETTE_SIZES]; + //! palette_y_color_cost int palette_y_color_cost[PALETTE_SIZES][PALETTE_COLOR_INDEX_CONTEXTS] [PALETTE_COLORS]; + //! palette_uv_color_cost int palette_uv_color_cost[PALETTE_SIZES][PALETTE_COLOR_INDEX_CONTEXTS] [PALETTE_COLORS]; + //! palette_y_mode_cost int palette_y_mode_cost[PALATTE_BSIZE_CTXS][PALETTE_Y_MODE_CONTEXTS][2]; + //! palette_uv_mode_cost int palette_uv_mode_cost[PALETTE_UV_MODE_CONTEXTS][2]; + /**@}*/ - // The rate associated with each alpha codeword - int cfl_cost[CFL_JOINT_SIGNS][CFL_PRED_PLANES][CFL_ALPHABET_SIZE]; - - // ========================================================================== - // Inter Mode Costs - // ========================================================================== + /***************************************************************************** + * \name Inter Costs: MV Modes + ****************************************************************************/ + /**@{*/ + //! skip_mode_cost int skip_mode_cost[SKIP_MODE_CONTEXTS][2]; - - // MV Mode Costs + //! newmv_mode_cost int newmv_mode_cost[NEWMV_MODE_CONTEXTS][2]; + //! zeromv_mode_cost int zeromv_mode_cost[GLOBALMV_MODE_CONTEXTS][2]; + //! refmv_mode_cost int refmv_mode_cost[REFMV_MODE_CONTEXTS][2]; + //! drl_mode_cost0 int drl_mode_cost0[DRL_MODE_CONTEXTS][2]; + /**@}*/ - // Ref Costs + /***************************************************************************** + * \name Inter Costs: Ref Frame Types + ****************************************************************************/ + /**@{*/ + //! single_ref_cost int single_ref_cost[REF_CONTEXTS][SINGLE_REFS - 1][2]; + //! comp_inter_cost int comp_inter_cost[COMP_INTER_CONTEXTS][2]; + //! comp_ref_type_cost int comp_ref_type_cost[COMP_REF_TYPE_CONTEXTS] [CDF_SIZE(COMP_REFERENCE_TYPES)]; + //! uni_comp_ref_cost int uni_comp_ref_cost[UNI_COMP_REF_CONTEXTS][UNIDIR_COMP_REFS - 1] [CDF_SIZE(2)]; - // Cost for signaling ref_frame[0] (LAST_FRAME, LAST2_FRAME, LAST3_FRAME or - // GOLDEN_FRAME) in bidir-comp mode. + /*! \brief Cost for signaling ref_frame[0] in bidir-comp mode + * + * Includes LAST_FRAME, LAST2_FRAME, LAST3_FRAME, and GOLDEN_FRAME. + */ int comp_ref_cost[REF_CONTEXTS][FWD_REFS - 1][2]; - // Cost for signaling ref_frame[1] (ALTREF_FRAME, ALTREF2_FRAME, or - // BWDREF_FRAME) in bidir-comp mode. + /*! \brief Cost for signaling ref_frame[1] in bidir-comp mode + * + * Includes ALTREF_FRAME, ALTREF2_FRAME, and BWDREF_FRAME. + */ int comp_bwdref_cost[REF_CONTEXTS][BWD_REFS - 1][2]; + /**@}*/ - // Compound Costs + /***************************************************************************** + * \name Inter Costs: Compound Types + ****************************************************************************/ + /**@{*/ + //! intra_inter_cost int intra_inter_cost[INTRA_INTER_CONTEXTS][2]; + //! inter_compound_mode_cost int inter_compound_mode_cost[INTER_MODE_CONTEXTS][INTER_COMPOUND_MODES]; + //! compound_type_cost int compound_type_cost[BLOCK_SIZES_ALL][MASKED_COMPOUND_TYPES]; + //! wedge_idx_cost int wedge_idx_cost[BLOCK_SIZES_ALL][16]; + //! interintra_cost int interintra_cost[BLOCK_SIZE_GROUPS][2]; + //! wedge_interintra_cost int wedge_interintra_cost[BLOCK_SIZES_ALL][2]; + //! interintra_mode_cost int interintra_mode_cost[BLOCK_SIZE_GROUPS][INTERINTRA_MODES]; + /**@}*/ - // Masks + /***************************************************************************** + * \name Inter Costs: Compound Masks + ****************************************************************************/ + /**@{*/ + //! comp_idx_cost int comp_idx_cost[COMP_INDEX_CONTEXTS][2]; + //! comp_group_idx_cost int comp_group_idx_cost[COMP_GROUP_IDX_CONTEXTS][2]; + /**@}*/ - // Motion Mode/Filter Costs + /***************************************************************************** + * \name Inter Costs: Motion Modes/Filters + ****************************************************************************/ + /**@{*/ + //! motion_mode_cost int motion_mode_cost[BLOCK_SIZES_ALL][MOTION_MODES]; + //! motion_mode_cost1 int motion_mode_cost1[BLOCK_SIZES_ALL][2]; + //! switchable_interp_costs int switchable_interp_costs[SWITCHABLE_FILTER_CONTEXTS][SWITCHABLE_FILTERS]; + /**@}*/ - // ========================================================================== - // Txfm Mode Costs - // ========================================================================== + /***************************************************************************** + * \name Txfm Mode Costs + ****************************************************************************/ + /**@{*/ + //! skip_txfm_cost int skip_txfm_cost[SKIP_CONTEXTS][2]; + //! tx_size_cost int tx_size_cost[TX_SIZES - 1][TX_SIZE_CONTEXTS][TX_SIZES]; + //! txfm_partition_cost int txfm_partition_cost[TXFM_PARTITION_CONTEXTS][2]; + //! inter_tx_type_costs int inter_tx_type_costs[EXT_TX_SETS_INTER][EXT_TX_SIZES][TX_TYPES]; + //! intra_tx_type_costs int intra_tx_type_costs[EXT_TX_SETS_INTRA][EXT_TX_SIZES][INTRA_MODES] [TX_TYPES]; + /**@}*/ - // ========================================================================== - // Restoration Mode Costs - // ========================================================================== + /***************************************************************************** + * \name Restoration Mode Costs + ****************************************************************************/ + /**@{*/ + //! switchable_restore_cost int switchable_restore_cost[RESTORE_SWITCHABLE_TYPES]; + //! wiener_restore_cost int wiener_restore_cost[2]; + //! sgrproj_restore_cost int sgrproj_restore_cost[2]; + /**@}*/ } ModeCosts; -// This struct holds the rates needed to transmit a new mv and the cost -// multiplier that converts entropy cost to sad/sse/var during motion search. +/*! \brief Holds mv costs for encoding and motion search. + */ typedef struct { - // A multiplier that converts mv cost to l2 error. + /***************************************************************************** + * \name Rate to Distortion Multipliers + ****************************************************************************/ + /**@{*/ + //! A multiplier that converts mv cost to l2 error. int errorperbit; - // A multiplier that converts mv cost to l1 error. + //! A multiplier that converts mv cost to l1 error. int sadperbit; + /**@}*/ + /***************************************************************************** + * \name Encoding Costs + * Here are the entropy costs needed to encode a given mv. + * \ref nmv_cost_alloc and \ref nmv_cost_hp_alloc are two arrays that holds + * the memory for holding the mv cost. But since the motion vectors can be + * negative, we shift them to the middle and store the resulting pointer in + * \ref nmv_cost and \ref nmv_cost_hp for easier referencing. Finally, \ref + * mv_cost_stack points to the \ref nmv_cost with the mv precision we are + * currently working with. In essence, only \ref mv_cost_stack is needed for + * motion search, the other can be considered private. + ****************************************************************************/ + /**@{*/ + //! Costs for coding the zero components. int nmv_joint_cost[MV_JOINTS]; - // Below are the entropy costs needed to encode a given mv. - // nmv_costs_(hp_)alloc are two arrays that holds the memory - // for holding the mv cost. But since the motion vectors can be negative, we - // shift them to the middle and store the resulting pointer in nmvcost(_hp) - // for easier referencing. Finally, nmv_cost_stack points to the nmvcost array - // with the mv precision we are currently working with. In essence, only - // mv_cost_stack is needed for motion search, the other can be considered - // private. + //! Allocates memory for 1/4-pel motion vector costs. int nmv_cost_alloc[2][MV_VALS]; + //! Allocates memory for 1/8-pel motion vector costs. int nmv_cost_hp_alloc[2][MV_VALS]; + //! Points to the middle of \ref nmv_cost_alloc int *nmv_cost[2]; + //! Points to the middle of \ref nmv_cost_hp_alloc int *nmv_cost_hp[2]; + //! Points to the nmv_cost_hp in use. int **mv_cost_stack; + /**@}*/ } MvCosts; -// This struct holds the costs need to encode the coefficients +/*! \brief Holds the costs needed to encode the coefficients + */ typedef struct { + //! Costs for coding the coefficients. LV_MAP_COEFF_COST coeff_costs[TX_SIZES][PLANE_TYPES]; + //! Costs for coding the eobs. LV_MAP_EOB_COST eob_costs[7][2]; } CoeffCosts; +/*!\cond */ +// 4: NEAREST, NEW, NEAR, GLOBAL +#define SINGLE_REF_MODES ((REF_FRAMES - 1) * 4) +/*!\endcond */ struct inter_modes_info; -typedef struct macroblock MACROBLOCK; -struct macroblock { - // ========================================================================== - // Source, Buffers and Decoder - // ========================================================================== - // Holds the src buffer for each of plane of the current block. This - // also contains the txfm and quantized txfm coefficients. + +/*! \brief Encoder's parameters related to the current coding block. + * + * This struct contains most of the information the encoder needs to encode the + * current coding block. This includes the src and pred buffer, a copy of the + * decoder's view of the current block, the txfm coefficients. This struct also + * contains various buffers and data used to speed up the encoding process. + */ +typedef struct macroblock { + /***************************************************************************** + * \name Source, Buffers and Decoder + ****************************************************************************/ + /**@{*/ + /*! \brief Each of the encoding plane. + * + * An array holding the src buffer for each of plane of the current block. It + * also contains the txfm and quantized txfm coefficients. + */ struct macroblock_plane plane[MAX_MB_PLANE]; - // Contains the encoder's copy of what the decoder sees in the current block. - // Most importantly, this struct contains pointers to mbmi that is used in - // final bitstream packing. + /*! \brief Decoder's view of current coding block. + * + * Contains the encoder's copy of what the decoder sees in the current block. + * Most importantly, this struct contains pointers to mbmi that is used in + * final bitstream packing. + */ MACROBLOCKD e_mbd; - // Contains extra information not transmitted in the bitstream but are - // derived. For example, this contains the stack of ref_mvs. + /*! \brief Derived coding information. + * + * Contains extra information not transmitted in the bitstream but are + * derived. For example, this contains the stack of ref_mvs. + */ MB_MODE_INFO_EXT *mbmi_ext; - // Contains the finalized info in mbmi_ext that gets used at the frame level - // for bitstream packing. + /*! \brief Finalized mbmi_ext for the whole frame. + * + * Contains the finalized info in mbmi_ext that gets used at the frame level + * for bitstream packing. + */ MB_MODE_INFO_EXT_FRAME *mbmi_ext_frame; + //! Entropy context for the current row. FRAME_CONTEXT *row_ctx; - // This context will be used to update color_map_cdf pointer which would be - // used during pack bitstream. For single thread and tile-multithreading case - // this pointer will be same as xd->tile_ctx, but for the case of row-mt: - // xd->tile_ctx will point to a temporary context while tile_pb_ctx will point - // to the accurate tile context. + /*! \brief Entropy context for the current tile. + * + * This context will be used to update color_map_cdf pointer which would be + * used during pack bitstream. For single thread and tile-multithreading case + * this pointer will be same as xd->tile_ctx, but for the case of row-mt: + * xd->tile_ctx will point to a temporary context while tile_pb_ctx will point + * to the accurate tile context. + */ FRAME_CONTEXT *tile_pb_ctx; - // Points to cb_coef_buff in the AV1_COMP struct, which contains the finalized - // coefficients. This is here to conveniently copy the best coefficients to - // frame level for bitstream packing. Since CB_COEFF_BUFFER is allocated on a - // superblock level, we need to combine it with cb_offset to get the proper - // position for the current coding block. + /*! \brief Buffer of transformed coefficients + * + * Points to cb_coef_buff in the AV1_COMP struct, which contains the finalized + * coefficients. This is here to conveniently copy the best coefficients to + * frame level for bitstream packing. Since CB_COEFF_BUFFER is allocated on a + * superblock level, we need to combine it with cb_offset to get the proper + * position for the current coding block. + */ CB_COEFF_BUFFER *cb_coef_buff; + //! Offset of current coding block's coeff buffer relative to the sb. uint16_t cb_offset; - // Stores some modified source and masks used for fast OBMC search. + //! Modified source and masks used for fast OBMC search. OBMCBuffer obmc_buffer; - // Stores the best palette map. + //! Buffer to store the best palette map. PALETTE_BUFFER *palette_buffer; - // Stores buffers used to perform compound_type_rd. + //! Buffer used for compound_type_rd(). CompoundTypeRdBuffers comp_rd_buffer; - // Stores convolution during the averaging prediction in compound/ mode. + //! Buffer to store convolution during averaging process in compound mode. CONV_BUF_TYPE *tmp_conv_dst; - // Points to a buffer that is used to hold temporary prediction results. This - // is used in two ways: - // 1. This is a temporary buffer used to pingpong the prediction in - // handle_inter_mode. - // 2. xd->tmp_obmc_bufs also points to this buffer, and is used in ombc - // prediction. + /*! \brief Temporary buffer to hold prediction. + * + * Points to a buffer that is used to hold temporary prediction results. This + * is used in two ways: + * - This is a temporary buffer used to pingpong the prediction in + * handle_inter_mode. + * - xd->tmp_obmc_bufs also points to this buffer, and is used in ombc + * prediction. + */ uint8_t *tmp_pred_bufs[2]; + /**@}*/ - // ========================================================================== - // Costs for Rdopt - // ========================================================================== - // The quantization index for the current partition block. This is used to - // as the index to find quantization parameter for luma and chroma transformed - // coefficients. + /***************************************************************************** + * \name Rdopt Costs + ****************************************************************************/ + /**@{*/ + /*! \brief Quantization index for the current partition block. + * + * This is used to as the index to find quantization parameter for luma and + * chroma transformed coefficients. + */ int qindex; - // The difference between the frame-level base qindex and the qindex used for - // the current superblock. This is used to track whether a non-zero delta for - // qindex is used at least once in the current frame. + /*! \brief Difference between frame-level qindex and current qindex. + * + * This is used to track whether a non-zero delta for qindex is used at least + * once in the current frame. + */ int delta_qindex; - // The rd multiplier used to determine the rate-distortion trade-off. This is - // roughly proportional to the inverse of q-index for a given frame, but this - // can be manipulated to for better rate-control. For example, in tune_ssim - // mode, this is scaled by a factor related to the variance of the current - // block. + /*! \brief Rate-distortion multiplier. + * + * The rd multiplier used to determine the rate-distortion trade-off. This is + * roughly proportional to the inverse of q-index for a given frame, but this + * can be manipulated for better rate-control. For example, in tune_ssim + * mode, this is scaled by a factor related to the variance of the current + * block. + */ int rdmult; - // These are measure of the energy in the current source mb/sb. They are used - // to determine the rdmult to facilitate better rdopt. + //! Energy in the current source coding block. Used to calculate \ref rdmult int mb_energy; + //! Energy in the current source superblock. Used to calculate \ref rdmult int sb_energy_level; - // Stores the rate needed to signal a mode to the bitstream. + //! The rate needed to signal a mode to the bitstream. ModeCosts mode_costs; - // Stores the rate needed to encode a new motion vector to the bitstream - // and some multipliers for motion search. + //! The rate needed to encode a new motion vector to the bitstream and some + //! multipliers for motion search. MvCosts mv_costs; - // Stores the rate needed to signal the txfm coefficients to the bitstream. + //! The rate needed to signal the txfm coefficients to the bitstream. CoeffCosts coeff_costs; + /**@}*/ - // ========================================================================== - // Segmentation - // ========================================================================== - // Part of the segmentation mode. In skip_block mode, all mvs are set 0 and - // all txfms are skipped. + /****************************************************************************** + * \name Segmentation + *****************************************************************************/ + /**@{*/ + /*! \brief Skip mode for the segment + * + * A syntax element of the segmentation mode. In skip_block mode, all mvs are + * set 0 and all txfms are skipped. + */ int seg_skip_block; + /**@}*/ - // ========================================================================== - // Superblock - // ========================================================================== - // Stores information on a whole superblock level. + /***************************************************************************** + * \name Superblock + ****************************************************************************/ + /**@{*/ + //! Information on a whole superblock level. // TODO(chiyotsai@google.com): Refactor this out of macroblock SuperBlockEnc sb_enc; - // The characteristic of the current superblock. e.g., it can have high sad, - // low sad, etc. Only used by realtime mode. + /*! \brief Characteristics of the current superblock. + * + * Characteristics like whether the block has high sad, low sad, etc. This is + * only used by av1 realtime mode. + */ uint8_t content_state_sb; + /**@}*/ - // ========================================================================== - // Reference Frame Search - // ========================================================================== - // The sad of the predicted mv for each of the reference frame. This is used - // to measure how viable a reference frames. + /***************************************************************************** + * \name Reference Frame Searc + ****************************************************************************/ + /**@{*/ + /*! \brief Sum absolute distortion of the predicted mv for each ref frame. + * + * This is used to measure how viable a reference frame is. + */ int pred_mv_sad[REF_FRAMES]; - // Contains min(pred_mv_sad). + //! The minimum of \ref pred_mv_sad. int best_pred_mv_sad; - // Determines whether a given ref frame is "good" based on data from the TPL - // model. If so, this stops selective_ref frame from pruning the given ref - // frame at block level. + /*! \brief Disables certain ref frame pruning based on tpl. + * + * Determines whether a given ref frame is "good" based on data from the TPL + * model. If so, this stops selective_ref frame from pruning the given ref + * frame at block level. + */ uint8_t tpl_keep_ref_frame[REF_FRAMES]; - // Keeps track of ref frames that are selected by square partition blocks - // within a superblock, in MI resolution. They can be used to prune ref frames - // for rectangular blocks. + /*! \brief Reference frames picked by the square subblocks in a superblock. + * + * Keeps track of ref frames that are selected by square partition blocks + * within a superblock, in MI resolution. They can be used to prune ref frames + * for rectangular blocks. + */ int picked_ref_frames_mask[MAX_MIB_SIZE * MAX_MIB_SIZE]; - // Determines whether to prune reference frames in real-time mode. For the - // most part, this is the same as nonrd_prune_ref_frame_search in - // cpi->sf.rt_sf.nonrd_prune_ref_frame_search, but this can be selectively - // turned off if the only frame available is GOLDEN_FRAME. + /*! \brief Prune ref frames in real-time mode. + * + * Determines whether to prune reference frames in real-time mode. For the + * most part, this is the same as nonrd_prune_ref_frame_search in + * cpi->sf.rt_sf.nonrd_prune_ref_frame_search, but this can be selectively + * turned off if the only frame available is GOLDEN_FRAME. + */ int nonrd_prune_ref_frame_search; + /**@}*/ - // ========================================================================== - // Partition Search - // ========================================================================== - // Stores some partition-search related buffers. + /***************************************************************************** + * \name Partition Search + ****************************************************************************/ + /**@{*/ + //! Stores some partition-search related buffers. PartitionSearchInfo part_search_info; - // In some cases, our speed features can be overly aggressive and remove all - // modes search in the superblock. In this case, we set - // must_find_valid_partition to 1 to reduce the number of speed features, and - // recode the superblock again. + /*! \brief Whether to disable some features to force a mode in current block. + * + * In some cases, our speed features can be overly aggressive and remove all + * modes search in the superblock. When this happens, we set + * must_find_valid_partition to 1 to reduce the number of speed features, and + * recode the superblock again. + */ int must_find_valid_partition; + /**@}*/ - // ========================================================================== - // Prediction Mode Search - // ========================================================================== - // Skip mode tries to use the closest forward and backward references for - // inter prediction. Skip here means to skip transmitting the reference - // frames, not to be confused with skip_txfm. + /***************************************************************************** + * \name Prediction Mode Search + ****************************************************************************/ + /**@{*/ + /*! \brief Inter skip mode. + * + * Skip mode tries to use the closest forward and backward references for + * inter prediction. Skip here means to skip transmitting the reference + * frames, not to be confused with skip_txfm. + */ int skip_mode; - // Determines a rd threshold to determine whether to continue searching the - // current mode. If the current best rd is already <= threshold, then we skip - // the current mode. + /*! \brief Factors used for rd-thresholding. + * + * Determines a rd threshold to determine whether to continue searching the + * current mode. If the current best rd is already <= threshold, then we skip + * the current mode. + */ int thresh_freq_fact[BLOCK_SIZES_ALL][MAX_MODES]; - // Winner mode is a two-pass strategy to find the best prediction mode. In the - // first pass, we search the prediction modes with a limited set of txfm - // options, and keep the top modes. These modes are called the winner modes. - // In the second pass, we retry the winner modes with more thorough txfm - // options. - // Stores the winner modes. + /*! \brief Tracks the winner modes in the current coding block. + * + * Winner mode is a two-pass strategy to find the best prediction mode. In the + * first pass, we search the prediction modes with a limited set of txfm + * options, and keep the top modes. These modes are called the winner modes. + * In the second pass, we retry the winner modes with more thorough txfm + * options. + */ WinnerModeStats winner_mode_stats[AOMMAX(MAX_WINNER_MODE_COUNT_INTRA, MAX_WINNER_MODE_COUNT_INTER)]; - // Tracks how many winner modes there are. + //! Tracks how many winner modes there are. int winner_mode_count; - // These are for inter_mode_rd_model_estimation, which is another two pass - // approach. In this speed feature, we collect data in the first couple frames - // to build an rd model to estimate the rdcost of a prediction model based on - // the residue error. Once enough data is collected, this speed feature uses - // the estimated rdcost to find the most performant prediction mode. Then we - // follow up with a second pass find the best transform for the mode. - // Determines if one would go with reduced complexity transform block - // search model to select prediction modes, or full complexity model - // to select transform kernel. + /*! \brief The model used for rd-estimation to avoid txfm + * + * These are for inter_mode_rd_model_estimation, which is another two pass + * approach. In this speed feature, we collect data in the first couple frames + * to build an rd model to estimate the rdcost of a prediction model based on + * the residue error. Once enough data is collected, this speed feature uses + * the estimated rdcost to find the most performant prediction mode. Then we + * follow up with a second pass find the best transform for the mode. + * Determines if one would go with reduced complexity transform block + * search model to select prediction modes, or full complexity model + * to select transform kernel. + */ TXFM_RD_MODEL rd_model; - // Stores the inter mode information needed to build an rd model. + /*! \brief Stores the inter mode information needed to build an rd model. + * + * These are for inter_mode_rd_model_estimation, which is another two pass + * approach. In this speed feature, we collect data in the first couple frames + * to build an rd model to estimate the rdcost of a prediction model based on + * the residue error. Once enough data is collected, this speed feature uses + * the estimated rdcost to find the most performant prediction mode. Then we + * follow up with a second pass find the best transform for the mode. + */ // TODO(any): try to consolidate this speed feature with winner mode // processing. struct inter_modes_info *inter_modes_info; - // Yet another 2-pass approach that tries to prune compound mode by first - // doing a simple_translational search on single ref modes. This however does - // not have good trade-off so it is only used by real-time mode. + /*! \brief Store the cost of single ref simple_translation predictor. + * + * This is used in another 2-pass approach that tries to prune compound mode + * by first doing a simple_translational search on single ref modes. This + * however does not have good trade-off so it is only used by real-time mode. + */ SimpleRDState simple_rd_state[SINGLE_REF_MODES][3]; - // Determines how to blend the compound predictions + //! How to blend the compound predictions. uint8_t compound_idx; - // Caches the results of compound type search so they can be reused later. + //! A caches of results of compound type search so they can be reused later. COMP_RD_STATS comp_rd_stats[MAX_COMP_RD_STATS]; + //! The idx for the latest compound mode in the cache \ref comp_rd_stats. int comp_rd_stats_idx; - // The edge strengths are used in wedge_search. - // The likelihood of an edge existing in the block (using partial Canny edge - // detection). For reference, 556 is the value returned for a solid - // vertical black/white edge. - uint16_t edge_strength; - // The strongest edge strength seen along the x/y axis. - uint16_t edge_strength_x; - uint16_t edge_strength_y; - - // Contains the hash table, hash function, and buffer used for intrabc. - IntraBCHashInfo intrabc_hash_info; - - // ========================================================================== - // MV Search - // ========================================================================== - // The l_\inf norm of the best ref_mv for each frame. This is used to - // determine the initial step size during motion search. - unsigned int max_mv_context[REF_FRAMES]; - - // These define limits to motion vector components to prevent them - // from extending outside the UMV borders - FullMvLimits mv_limits; - - // In interpolation search, we can usually skip recalculating the luma - // prediction because it is already calculated by a previous predictor. This - // flag signifies that some modes might have been skipped, so we need to redo - // the motion compensation. + /*! \brief Whether to recompute the luma prediction. + * + * In interpolation search, we can usually skip recalculating the luma + * prediction because it is already calculated by a previous predictor. This + * flag signifies that some modes might have been skipped, so we need to + * rebuild the prediction. + */ int recalc_luma_mc_data; - // ========================================================================== - // Txfm Search - // ========================================================================== - // Stores various txfm search related parameters such as txfm_type, txfm_size, - // trellis eob search, etc. + /*! \brief Likelihood of an edge existing in the current coding block. + * + * The likelihood of an edge existing in the block (using partial Canny edge + * detection). For reference, 556 is the value returned for a solid + * vertical black/white edge. + * The edge strengths are used in wedge_search. + */ + uint16_t edge_strength; + //! The strongest edge strength seen along the x axis. + uint16_t edge_strength_x; + //! The strongest edge strength seen along the y axis. + uint16_t edge_strength_y; + + /*! \brief Data structure to speed up intrabc search. + * + * Contains the hash table, hash function, and buffer used for intrabc. + */ + IntraBCHashInfo intrabc_hash_info; + /**@}*/ + + /***************************************************************************** + * \name MV Search + ****************************************************************************/ + /**@{*/ + /*! \brief Context used to determine the initial step size in motion search. + * + * This context is defined as the \f$l_\inf\f$ norm of the best ref_mvs for + * each frame. + */ + unsigned int max_mv_context[REF_FRAMES]; + + /*! \brief Limit for the range of motion vectors. + * + * These define limits to motion vector components to prevent them from + * extending outside the UMV borders + */ + FullMvLimits mv_limits; + /**@}*/ + + /***************************************************************************** + * \name Txfm Search + ****************************************************************************/ + /**@{*/ + /*! \brief Parameters that control how motion search is done. + * + * Stores various txfm search related parameters such as txfm_type, txfm_size, + * trellis eob search, etc. + */ TxfmSearchParams txfm_search_params; - // Caches old txfm search results and keeps the current txfm decisions. + /*! \brief Results of the txfm searches that have been done. + * + * Caches old txfm search results and keeps the current txfm decisions to + * facilitate rdopt. + */ TxfmSearchInfo txfm_search_info; - // Strong color activity detection. Used in REALTIME coding mode to enhance - // the visual quality at the boundary of moving color objects. + /*! \brief Whether there is a strong color activity. + * + * Used in REALTIME coding mode to enhance the visual quality at the boundary + * of moving color objects. + */ uint8_t color_sensitivity[2]; + /**@}*/ - // ========================================================================== - // Misc - // ========================================================================== - // Variance on the source frame. + /***************************************************************************** + * \name Misc + ****************************************************************************/ + /**@{*/ + //! Variance of the source frame. unsigned int source_variance; - // The sse of the current predictor. + //! SSE of the current predictor. unsigned int pred_sse[REF_FRAMES]; + /**@}*/ - // ========================================================================== - // Unused - // ========================================================================== - // Some of these are not currently used by the codec so they should probably - // be removed. + /***************************************************************************** + * \name Unused + ****************************************************************************/ + /**@{*/ + //! To be removed. unsigned int simple_motion_pred_sse; -}; + /**@}*/ +} MACROBLOCK; +#undef SINGLE_REF_MODES -// Only consider full SB, MC_FLOW_BSIZE_1D = 16. +/*!\cond */ + static INLINE int tpl_blocks_in_sb(BLOCK_SIZE bsize) { switch (bsize) { case BLOCK_64X64: return 16; @@ -834,6 +1275,8 @@ return (txb_skip[blk_idx] >> plane) & 1; } +/*!\endcond */ + #ifdef __cplusplus } // extern "C" #endif
diff --git a/av1/encoder/enc_enums.h b/av1/encoder/enc_enums.h index 5a06514..ff191ff 100644 --- a/av1/encoder/enc_enums.h +++ b/av1/encoder/enc_enums.h
@@ -248,6 +248,17 @@ MAX_REFS } UENUM1BYTE(THR_MODES_SUB8X8); +enum { + FULL_TXFM_RD, + LOW_TXFM_RD, +} UENUM1BYTE(TXFM_RD_MODEL); + +enum { + USE_FULL_RD = 0, + USE_FAST_RD, + USE_LARGESTALL, +} UENUM1BYTE(TX_SIZE_SEARCH_METHOD); + #ifdef __cplusplus } // extern "C" #endif
diff --git a/av1/encoder/encodeframe.c b/av1/encoder/encodeframe.c index fc5ff85..ae64e95 100644 --- a/av1/encoder/encodeframe.c +++ b/av1/encoder/encodeframe.c
@@ -3470,8 +3470,8 @@ * * \return A bool value is returned indicating if a valid partition is found. * The pc_tree struct is modified to store the picked partition and modes. - * The rd_cost struct is also updated with the RD stats orresponding to the best - * partition found. + * The rd_cost struct is also updated with the RD stats corresponding to the + * best partition found. */ static bool rd_pick_partition(AV1_COMP *const cpi, ThreadData *td, TileDataEnc *tile_data, TokenExtra **tp,
diff --git a/av1/encoder/encodemb.h b/av1/encoder/encodemb.h index 4160f82..fea51f0 100644 --- a/av1/encoder/encodemb.h +++ b/av1/encoder/encodemb.h
@@ -22,6 +22,30 @@ extern "C" { #endif +enum { + AV1_XFORM_QUANT_FP = 0, + AV1_XFORM_QUANT_B = 1, + AV1_XFORM_QUANT_DC = 2, + AV1_XFORM_QUANT_SKIP_QUANT, + AV1_XFORM_QUANT_TYPES, +} UENUM1BYTE(AV1_XFORM_QUANT); + +// TODO(any): Merge OPT_TYPe and TRELLLIS_OPT_TYPE +// Available optimization types to optimize the quantized coefficients. +enum { + NONE_OPT = 0, // No optimization. + TRELLIS_OPT = 1, // Trellis optimization. See `av1_optimize_b()`. + DROPOUT_OPT = 2, // Dropout optimization. See `av1_dropout_qcoeff()`. + TRELLIS_DROPOUT_OPT = 3 // Perform dropout after trellis optimization. +} UENUM1BYTE(OPT_TYPE); + +enum { + NO_TRELLIS_OPT, // No trellis optimization + FULL_TRELLIS_OPT, // Trellis optimization in all stages + FINAL_PASS_TRELLIS_OPT, // Trellis optimization in only the final encode pass + NO_ESTIMATE_YRD_TRELLIS_OPT // Disable trellis in estimate_yrd_for_sb +} UENUM1BYTE(TRELLIS_OPT_TYPE); + struct optimize_ctx { ENTROPY_CONTEXT ta[MAX_MB_PLANE][MAX_MIB_SIZE]; ENTROPY_CONTEXT tl[MAX_MB_PLANE][MAX_MIB_SIZE]; @@ -38,22 +62,6 @@ TRELLIS_OPT_TYPE enable_optimize_b; }; -enum { - AV1_XFORM_QUANT_FP = 0, - AV1_XFORM_QUANT_B = 1, - AV1_XFORM_QUANT_DC = 2, - AV1_XFORM_QUANT_SKIP_QUANT, - AV1_XFORM_QUANT_TYPES, -} UENUM1BYTE(AV1_XFORM_QUANT); - -// Available optimization types to optimize the quantized coefficients. -enum { - NONE_OPT = 0, // No optimization. - TRELLIS_OPT = 1, // Trellis optimization. See `av1_optimize_b()`. - DROPOUT_OPT = 2, // Dropout optimization. See `av1_dropout_qcoeff()`. - TRELLIS_DROPOUT_OPT = 3 // Perform dropout after trellis optimization. -} UENUM1BYTE(OPT_TYPE); - void av1_encode_sb(const struct AV1_COMP *cpi, MACROBLOCK *x, BLOCK_SIZE bsize, RUN_TYPE dry_run);
diff --git a/av1/encoder/tx_search.c b/av1/encoder/tx_search.c index b77dd3f..344d370 100644 --- a/av1/encoder/tx_search.c +++ b/av1/encoder/tx_search.c
@@ -47,6 +47,11 @@ int8_t children[4]; } RD_RECORD_IDX_NODE; +typedef struct tx_size_rd_info_node { + TXB_RD_INFO *rd_info_array; // Points to array of size TX_TYPES. + struct tx_size_rd_info_node *children[4]; +} TXB_RD_INFO_NODE; + // origin_threshold * 128 / 100 static const uint32_t skip_pred_threshold[3][BLOCK_SIZES_ALL] = { {
diff --git a/docs.cmake b/docs.cmake index 6286990..8ead019 100644 --- a/docs.cmake +++ b/docs.cmake
@@ -108,6 +108,7 @@ "${AOM_ROOT}/doc/dev_guide/av1_encoder.dox") set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} + "${AOM_ROOT}/av1/encoder/block.h" "${AOM_ROOT}/av1/encoder/encode_strategy.c" "${AOM_ROOT}/av1/encoder/encode_strategy.h" "${AOM_ROOT}/av1/encoder/encodeframe.c" @@ -293,6 +294,9 @@ # Add image path. file(APPEND "${AOM_DOXYFILE}" "IMAGE_PATH += ${AOM_ROOT}/doc/dev_guide\n") + # Allow banner style comments + file(APPEND "${AOM_DOXYFILE}" "JAVADOC_BANNER = YES") + # Add the doxygen generation rule. add_custom_target(docs ALL COMMAND "${DOXYGEN_EXECUTABLE}" "${AOM_DOXYFILE}"