Add more documentation and references.
Further changes to the architecture overview document.
Add additional sections and references.
Remove some callgraph and callerfgraph references for now for speed.
Change-Id: Ib99cb5d8e73dd3d0d2b60d05f3f452331fd309ca
diff --git a/av1/encoder/encoder.h b/av1/encoder/encoder.h
index ce53991..1915e47 100644
--- a/av1/encoder/encoder.h
+++ b/av1/encoder/encoder.h
@@ -630,7 +630,17 @@
int speed;
MODE mode;
+
+ /*!\endcond */
+ /*!
+ * Indicates the current encoder pass :
+ * 0 = 1 Pass encode,
+ * 1 = First pass of two pass,
+ * 2 = Second pass of two pass.
+ *
+ */
int pass;
+ /*!\cond */
// Configuration related to key-frame.
KeyFrameCfg kf_cfg;
diff --git a/av1/encoder/firstpass.h b/av1/encoder/firstpass.h
index 622a1e2..11a9f90 100644
--- a/av1/encoder/firstpass.h
+++ b/av1/encoder/firstpass.h
@@ -167,7 +167,13 @@
FRAME_CONTENT_TYPES = 2
} UENUM1BYTE(FRAME_CONTENT_TYPE);
+/*!\endcond */
+/*!
+ * \brief Data relating to the current GF/ARF group and the
+ * individual frames within the group
+ */
typedef struct {
+ /*!\cond */
unsigned char index;
FRAME_UPDATE_TYPE update_type[MAX_STATIC_GF_GROUP_LENGTH];
unsigned char arf_src_offset[MAX_STATIC_GF_GROUP_LENGTH];
@@ -186,7 +192,9 @@
unsigned char q_val[MAX_STATIC_GF_GROUP_LENGTH];
int bit_allocation[MAX_STATIC_GF_GROUP_LENGTH];
int size;
+ /*!\endcond */
} GF_GROUP;
+/*!\cond */
typedef struct {
FIRSTPASS_STATS *stats_in_start;
diff --git a/av1/encoder/ratectrl.h b/av1/encoder/ratectrl.h
index 0c1a4c7..c1da2da 100644
--- a/av1/encoder/ratectrl.h
+++ b/av1/encoder/ratectrl.h
@@ -81,29 +81,80 @@
FRAME_UPDATE_TYPES
} UENUM1BYTE(FRAME_UPDATE_TYPE);
+/*!\endcond */
+/*!
+ * \brief Rate Control parameters and status
+ */
typedef struct {
// Rate targetting variables
- int base_frame_target; // A baseline frame target before adjustment
- // for previous under or over shoot.
+
+ /*!
+ * Baseline target rate for frame before adjustment for previous under or
+ * over shoot.
+ */
+ int base_frame_target;
+ /*!
+ * Target rate for frame after adjustment for previous under or over shoot.
+ */
int this_frame_target; // Actual frame target after rc adjustment.
- // gop bit budget
+ /*!
+ * Target bit budget for the current GF / ARF group of frame.
+ */
int64_t gf_group_bits;
+ /*!
+ * Projected size for current frame
+ */
int projected_frame_size;
- int sb64_target_rate;
- int last_q[FRAME_TYPES]; // Separate values for Intra/Inter
- int last_boosted_qindex; // Last boosted GF/KF/ARF q
- int last_kf_qindex; // Q index of the last key frame coded.
+ /*!
+ * Super block rate target used with some adaptive quantization strategies.
+ */
+ int sb64_target_rate;
+
+ /*!
+ * Q used on last encoded frame of the given type.
+ */
+ int last_q[FRAME_TYPES];
+
+ /*!
+ * Q used for last boosted (non leaf) frame (GF/KF/ARF)
+ */
+ int last_boosted_qindex;
+
+ /*!
+ * Q used for last boosted (non leaf) frame
+ */
+ int last_kf_qindex;
+
+ /*!
+ * Boost factor used to calculate the extra bits allocated to ARFs and GFs
+ */
int gfu_boost;
+ /*!
+ * Boost factor used to calculate the extra bits allocated to the key frame
+ */
int kf_boost;
+ /*!
+ * Correction factors used to adjust the q estimate for a given target rate
+ * in the encode loop.
+ */
double rate_correction_factors[RATE_FACTOR_LEVELS];
+ /*!
+ * Number of frames since the last ARF / GF.
+ */
int frames_since_golden;
+
+ /*!
+ * Number of frames till the next ARF / GF is due.
+ */
int frames_till_gf_update_due;
+ /*!\cond */
+
// number of determined gf group length left
int intervals_till_gf_calculate_due;
// stores gf group length intervals
@@ -160,12 +211,29 @@
int64_t total_target_bits;
int64_t total_target_vs_actual;
+ /*!\endcond */
+ /*!
+ * User specified maximum Q allowed for current frame
+ */
int worst_quality;
+ /*!
+ * User specified minimum Q allowed for current frame
+ */
int best_quality;
+ /*!
+ * Initial buffuer level in ms for CBR / low delay encoding
+ */
int64_t starting_buffer_level;
+ /*!
+ * Optimum / target buffuer level in ms for CBR / low delay encoding
+ */
int64_t optimal_buffer_level;
+ /*!
+ * Maximum target buffuer level in ms for CBR / low delay encoding
+ */
int64_t maximum_buffer_size;
+ /*!\cond */
// rate control history for last frame(1) and the frame before(2).
// -1: undershot
@@ -177,10 +245,22 @@
int q_2_frame;
float_t arf_boost_factor;
- // Q index used for ALT frame
+
+ /*!\endcond */
+ /*!
+ * Q index used for ALT frame
+ */
int arf_q;
+ /*!
+ * Proposed maximum alloed Q for current frame
+ */
int active_worst_quality;
+ /*!
+ * Proposed minimum allowed Q different layers in a coding pyramid
+ */
int active_best_quality[MAX_ARF_LAYERS + 1];
+
+ /*!\cond */
int base_layer_qp;
// Total number of stats used only for kf_boost calculation.
@@ -194,8 +274,11 @@
int use_arf_in_this_kf_group;
// Track amount of low motion in scene
int avg_frame_low_motion;
+ /*!\endcond */
} RATE_CONTROL;
+/*!\cond */
+
struct AV1_COMP;
struct AV1EncoderConfig;
diff --git a/doc/dev_guide/av1_encoder.dox b/doc/dev_guide/av1_encoder.dox
index 32b27db..fadf0ee 100644
--- a/doc/dev_guide/av1_encoder.dox
+++ b/doc/dev_guide/av1_encoder.dox
@@ -102,24 +102,21 @@
The following are the main high level data structures used by the libaom AV1
encoder and referenced elsewhere in this overview document:
-The following are the main libaom encoder data structures referenced
-in this overview document:
-
- \ref AV1_COMP
- - \ref AV1_COMP.rc ((TODO REF) RATE_CONTROL)
+ - \ref AV1_COMP.rc (\ref RATE_CONTROL)
- \ref AV1_COMP.oxcf (\ref AV1EncoderConfig)
- \ref AV1_COMP.twopass (\ref TWO_PASS)
- - \ref AV1_COMP.gf_group ((TODO REF) GF_GROUP)
+ - \ref AV1_COMP.gf_group (\ref GF_GROUP)
- \ref AV1_COMP.speed
- \ref AV1_COMP.sf (\ref SPEED_FEATURES)
- - AV1EncoderConfig (Encoder configuration parameters)
- - AV1EncoderConfig.rc_cfg (RateControlCfg)
+ - \ref AV1EncoderConfig (Encoder configuration parameters)
+ - \ref AV1EncoderConfig.rc_cfg (\ref RateControlCfg)
- - (TODO REF) RATE_CONTROL (Rate control status)
+ - \ref RATE_CONTROL (Rate control status)
- \ref RateControlCfg (Rate control configuration)
- \ref TWO_PASS (Two pass status and control data)
- - (TODO REF) GF_GROUP (Data relating to the current GF/ARF group)
+ - \ref GF_GROUP (Data relating to the current GF/ARF group)
- \ref FIRSTPASS_STATS (Defines entries in the first pass stats buffer)
- \ref SPEED_FEATURES (Encode speed / quality tradeoff parameters)
@@ -151,7 +148,7 @@
in real time and to avoid any coding tools that could increase latency, such
as frame look ahead.
-<b>Live Streams:</b> In cases such as live streaming of games or events it
+<b>Live Streams:</b> In cases such as live streaming of games or events, it
may be possible to allow some limited buffering of the video and use of
lookahead coding tools to improve encoding quality. However, whilst a lag of
a second or two may be fine given the one way nature of this type of video,
@@ -222,7 +219,7 @@
- <b>VBR</b> (Variable Bitrate)
- <b>CBR</b> (Constant Bitrate)
- <b>CQ</b> (Constrained Quality mode ; A constrained variant of VBR)
-- <b>Fixed Q</b> (Constant quality of Q mode)
+- <b>Fixed Q</b> (Constant quality of Q mode)
The value of \ref aom_codec_enc_cfg_t.rc_end_usage is in turn copied over
into the encoder rate control configuration data structure as
@@ -319,33 +316,31 @@
entirely in volatile memory. This has some disadvantages when compared to a
full first pass encode, but avoids the need for file I/O and improves speed.
-In what follows I will refer to the following key data structures.
+In this section I will refer to the following key data structures.
(see also \ref architecture_enc_data_structures)
- \ref AV1_COMP cpi (the main compressor instance data structure)
- \ref AV1_COMP.oxcf (\ref AV1EncoderConfig)
- - \ref AV1_COMP.rc ((TODO REF) RATE_CONTROL)
+ - \ref AV1_COMP.rc (\ref RATE_CONTROL)
- \ref AV1_COMP.twopass (\ref TWO_PASS)
- \ref AV1EncoderConfig (Encoder configuration parameters)
- - (TODO REF) AV1EncoderConfig.pass
+ - \ref AV1EncoderConfig.pass
-- (TODO REF) RATE_CONTROL (Rate control status)
+- \ref RATE_CONTROL (Rate control status)
- \ref TWO_PASS (Two pass status and control data)
- \ref FIRSTPASS_STATS *frame_stats_buf (used to store per frame first
pass stats)
-
For two pass encoding, the function \ref av1_encode() in encoder.c will first
-be called for each frame in the video with the value (TODO REF)
-cpi->oxcf.pass=1. This will result in calls to \ref av1_first_pass() in
-firspass.c
+be called for each frame in the video with the value \ref AV1EncoderConfig.pass
+= 1. This will result in calls to \ref av1_first_pass() in firspass.c
-Statistics about each frame are stored in (TODO REF) frame_stats_buf.
+Statistics for each frame are stored in \ref FIRSTPASS_STATS frame_stats_buf.
After completion of the first pass, \ref av1_encode() will be called again for
-each frame with (TODO REF) cpi->oxcf.pass=2. The frames are then encoded in
+each frame with \ref AV1EncoderConfig.pass = 2. The frames are then encoded in
accordance with the statistics gathered during the first pass by calls to
\ref encode_frame_to_data_rate() in encoder.c.
@@ -362,7 +357,7 @@
frame, golden frame or normal leaf frame).
- Suggests a maximum Q (quantizer value) for each ARF/GF group, based on
estimated complexity and recent rate control compliance
- (TODO REF) (rc->active_worst_quality)
+ (\ref RATE_CONTROL.active_worst_quality)
- Tracks adherence to the overall rate control objectives and adjusts
heuristics.
@@ -378,20 +373,32 @@
- (TODO REF) av1_twopass_postencode_update()
For each frame, the two pass algorithm defines a target number of bits
-(TODO REF) rc->base_frame_target, which is then adjusted if necessary to
+\ref RATE_CONTROL.base_frame_target, which is then adjusted if necessary to
reflect any undershoot or overshoot on previous frames to give
-(TODO REF) rc->this_frame_target.
+\ref RATE_CONTROL.this_frame_target.
-As well as (TODO REF) rc->active_worst_quality, the two pass code also
+As well as \ref RATE_CONTROL.active_worst_quality, the two pass code also
maintains a record of the actual Q value used to encode previous frames
at each level in the current pyramid hierarchy
-((TODO REF)rc->active_best_quality[level]). The function
+(\ref RATE_CONTROL.active_best_quality). The function
\ref rc_pick_q_and_bounds(), defined in rate_ctrl.c, uses these values
to set a permitted Q range for each frame.
\subsubsection architecture_enc_1pass_lagged 1 Pass Lagged VBR Encoding
- Add details here.
+1 pass lagged encode falls between simple 1 pass encoding and full two pass
+encoding and is used for cases where it is not possible to do a full first
+pass through the entire video clip, but where some delay is permissible. For
+example near live streaming where there is a delay of up to a few seconds. In
+this case the first pass and second pass are in effect combined such that the
+first pass starts encoding the clip and the second pass lags behind it by a
+few frames. When using this method, full sequence level statistics are not
+available, but it is possible to collect and use frame or group of frame level
+data to help in the allocation of bits and in defining ARF/GF coding
+hierarchies. The reader is referred to the data value
+(TODO REF) cpi->lap_enabled (where <b>lap</b> stands for
+<b>look ahead processing</b>). This encoding mode for the most part uses the
+same rate control pathways as two pass VBR encoding.
\subsection architecture_enc_rc_loop The Main Rate Control Loop
