Doxygen additions for tpl modelling
Added some further doxygen notes and references for
TPL modelling.
Change-Id: I77eb7f41288038c8cff8275987e6c01cca20ae28
diff --git a/av1/encoder/encodeframe.c b/av1/encoder/encodeframe.c
index 1d8b70c..1be87e5 100644
--- a/av1/encoder/encodeframe.c
+++ b/av1/encoder/encodeframe.c
@@ -217,6 +217,22 @@
}
#if !CONFIG_REALTIME_ONLY
+/*!\brief Assigns different quantization parameters to each super
+ * block based on its TPL weight.
+ *
+ * \ingroup tpl_modelling
+ *
+ * \param[in] cpi Top level encoder instance structure
+ * \param[in,out] td Thread data structure
+ * \param[in,out] x Macro block level data for this block.
+ * \param[in] tile_info Tile infromation / identification
+ * \param[in] mi_row Block row (in "MI_SIZE" units) index
+ * \param[in] mi_col Block column (in "MI_SIZE" units) index
+ * \param[out] num_planes Number of image planes (e.g. Y,U,V)
+ *
+ * \return No return value but updates macroblock and thread data
+ * relating to the q / q delta to be used.
+ */
static AOM_INLINE void setup_delta_q(AV1_COMP *const cpi, ThreadData *td,
MACROBLOCK *const x,
const TileInfo *const tile_info,
diff --git a/av1/encoder/encoder.h b/av1/encoder/encoder.h
index 5412fcc..dc970e2 100644
--- a/av1/encoder/encoder.h
+++ b/av1/encoder/encoder.h
@@ -2854,11 +2854,20 @@
cpi->lap_enabled));
}
-// Check if the current stage has statistics
+/*!\endcond */
+/*!\brief Check if the current stage has statistics
+ *
+ *\ingroup two_pass_algo
+ *
+ * \param[in] cpi Top - level encoder instance structure
+ *
+ * \return 0 if no stats for current stage else 1
+ */
static INLINE int has_no_stats_stage(const AV1_COMP *const cpi) {
assert(IMPLIES(!cpi->lap_enabled, cpi->compressor_stage == ENCODE_STAGE));
return (cpi->oxcf.pass == 0 && !cpi->lap_enabled);
}
+/*!\cond */
// Function return size of frame stats buffer
static INLINE int get_stats_buf_size(int num_lap_buffer, int num_lag_buffer) {
diff --git a/av1/encoder/tpl_model.h b/av1/encoder/tpl_model.h
index ff3d6ad..1407b1a 100644
--- a/av1/encoder/tpl_model.h
+++ b/av1/encoder/tpl_model.h
@@ -16,6 +16,8 @@
extern "C" {
#endif
+/*!\cond */
+
struct AV1_COMP;
struct EncodeFrameParams;
struct EncodeFrameInput;
@@ -111,7 +113,6 @@
} TplDepFrame;
/*!\endcond */
-
/*!
* \brief Params related to temporal dependency model.
*/
@@ -182,10 +183,24 @@
int border_in_pixels;
} TplParams;
+/*!\brief Implements temporal dependency modelling for a GOP (GF/ARF
+ * group) and selects between 16 and 32 frame GOP structure.
+ *
+ *\ingroup tpl_modelling
+ *
+ * \param[in] cpi Top - level encoder instance structure
+ * \param[in] gop_eval Flag if it is in the GOP length decision stage
+ * \param[in] frame_params Per frame encoding parameters
+ * \param[in] frame_input Input frame buffers
+ *
+ * \return Indicates whether or not we should use a longer GOP length.
+ */
int av1_tpl_setup_stats(struct AV1_COMP *cpi, int gop_eval,
const struct EncodeFrameParams *const frame_params,
const struct EncodeFrameInput *const frame_input);
+/*!\cond */
+
int av1_tpl_ptr_pos(int mi_row, int mi_col, int stride, uint8_t right_shift);
void av1_tpl_rdmult_setup(struct AV1_COMP *cpi);
@@ -195,7 +210,7 @@
void av1_mc_flow_dispenser_row(struct AV1_COMP *cpi, MACROBLOCK *x, int mi_row,
BLOCK_SIZE bsize, TX_SIZE tx_size);
-
+/*!\endcond */
#ifdef __cplusplus
} // extern "C"
#endif
diff --git a/doc/dev_guide/av1_encoder.dox b/doc/dev_guide/av1_encoder.dox
index 74a05d1..9c3055c 100644
--- a/doc/dev_guide/av1_encoder.dox
+++ b/doc/dev_guide/av1_encoder.dox
@@ -781,7 +781,7 @@
calculate_gf_length(). The following encoder use cases are supported:
<ul>
- <li><b>Single pass with look-ahead disabled((TODO REF)has_no_stats_stage()):
+ <li><b>Single pass with look-ahead disabled(\ref has_no_stats_stage()):
</b> in this case there is no information available on the following stream
of frames, therefore the function will set the GF group length for the
current and the following GF groups (a total number of MAX_NUM_GF_INTERVALS
@@ -837,7 +837,7 @@
enforce an extra layer to determine whether to use maximum GF length of 32
or 16 for every GF group. In such a case, \ref calculate_gf_length() is
first called with the original maximum length (>=32). Afterwards,
-(TODO REF) av1_tpl_setup_stats() is called to analyze the determined GF group
+\ref av1_tpl_setup_stats() is called to analyze the determined GF group
and compare the reference to the last frame and the middle frame. If it is
decided that we should use a maximum GF length of 16, the function
\ref calculate_gf_length() is called again with the updated maximum
@@ -1020,10 +1020,14 @@
64x64 block level QP is scaled according to the Lagrangian multiplier.
</ul>
-\subsection architecture_enc_tpl_keyfun Key Functions
+\subsection architecture_enc_tpl_keyfun Key Functions and data structures
-- The TPL model is built in (TODO REF) av1_tpl_setup_stats().
-- Its application to the QP offset is triggered in (TODO REF) setup_delta_q().
+The reader is also refered to the following functions and data structures:
+
+- \ref TplParams
+- \ref av1_tpl_setup_stats() builds the TPL model.
+- \ref setup_delta_q() Assign different quantization parameters to each super
+ block based on its TPL weight.
\section architecture_enc_partitions Block Partition Search
@@ -1119,6 +1123,14 @@
*/
/*! @} - end defgroup rate_control */
+/*!\defgroup tpl_modelling Temporal Dependency Modelling
+ * \ingroup high_level_algo
+ * This module includes algorithms to implement temporal dependency modelling.
+ * See also \ref architecture_enc_tpl
+ * @{
+ */
+/*! @} - end defgroup tpl_modelling */
+
/*!\defgroup two_pass_algo Two Pass Mode
\ingroup high_level_algo
diff --git a/docs.cmake b/docs.cmake
index 552f9e7..24299ec 100644
--- a/docs.cmake
+++ b/docs.cmake
@@ -148,6 +148,7 @@
"${AOM_ROOT}/av1/encoder/svc_layercontext.h"
"${AOM_ROOT}/av1/encoder/temporal_filter.h"
"${AOM_ROOT}/av1/encoder/temporal_filter.c"
+ "${AOM_ROOT}/av1/encoder/tpl_model.h"
"${AOM_ROOT}/av1/encoder/tx_search.h"
"${AOM_ROOT}/av1/encoder/var_based_part.h"
"${AOM_ROOT}/av1/encoder/nonrd_pickmode.c")
