ref: 3ccbd4803bcc75be860dd67bb3a56b114251433b
dir: libvpx/vpx/vpx_ext_ratectrl.h
/*
* Copyright (c) 2020 The WebM project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef VPX_VPX_VPX_EXT_RATECTRL_H_
#define VPX_VPX_VPX_EXT_RATECTRL_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "./vpx_integer.h"
/*!\brief Current ABI version number
*
* \internal
* If this file is altered in any way that changes the ABI, this value
* must be bumped. Examples include, but are not limited to, changing
* types, removing or reassigning enums, adding/removing/rearranging
* fields to structures.
*/
#define VPX_EXT_RATECTRL_ABI_VERSION (1)
/*!\brief Abstract rate control model handler
*
* The encoder will receive the model handler from create_model() defined in
* vpx_rc_funcs_t.
*/
typedef void *vpx_rc_model_t;
/*!\brief Encode frame decision made by the external rate control model
*
* The encoder will receive the decision from the external rate control model
* through get_encodeframe_decision() defined in vpx_rc_funcs_t.
*
* If max_frame_size = 0, the encoding ignores max frame size limit.
* If max_frame_size = -1, the encoding uses VP9's max frame size as the limit.
* If the encoded frame size is larger than max_frame_size, the frame is
* recoded to meet the size limit, following VP9's recoding principles.
*/
typedef struct vpx_rc_encodeframe_decision {
int q_index; /**< Quantizer step index [0..255]*/
int max_frame_size; /**< Maximal frame size allowed to encode a frame*/
} vpx_rc_encodeframe_decision_t;
/*!\brief Information for the frame to be encoded.
*
* The encoder will send the information to external rate control model through
* get_encodeframe_decision() defined in vpx_rc_funcs_t.
*
*/
typedef struct vpx_rc_encodeframe_info {
/*!
* 0: Key frame
* 1: Inter frame
* 2: Alternate reference frame
* 3: Overlay frame
* 4: Golden frame
*/
int frame_type;
int show_index; /**< display index, starts from zero*/
int coding_index; /**< coding index, starts from zero*/
/*!
* index in group of picture, starts from zero.
*/
int gop_index;
int ref_frame_coding_indexes[3]; /**< three reference frames' coding indices*/
/*!
* The validity of the three reference frames.
* 0: Invalid
* 1: Valid
*/
int ref_frame_valid_list[3];
} vpx_rc_encodeframe_info_t;
/*!\brief Frame coding result
*
* The encoder will send the result to the external rate control model through
* update_encodeframe_result() defined in vpx_rc_funcs_t.
*/
typedef struct vpx_rc_encodeframe_result {
int64_t sse; /**< sum of squared error of the reconstructed frame */
int64_t bit_count; /**< number of bits spent on coding the frame*/
int64_t pixel_count; /**< number of pixels in YUV planes of the frame*/
int actual_encoding_qindex; /**< the actual qindex used to encode the frame*/
} vpx_rc_encodeframe_result_t;
/*!\brief Status returned by rate control callback functions.
*/
typedef enum vpx_rc_status {
VPX_RC_OK = 0,
VPX_RC_ERROR = 1,
} vpx_rc_status_t;
/*!\brief First pass frame stats
* This is a mirror of vp9's FIRSTPASS_STATS except that spatial_layer_id is
* omitted
*/
typedef struct vpx_rc_frame_stats {
/*!
* Frame number in display order, if stats are for a single frame.
* No real meaning for a collection of frames.
*/
double frame;
/*!
* Weight assigned to this frame (or total weight for the collection of
* frames) currently based on intra factor and brightness factor. This is used
* to distribute bits between easier and harder frames.
*/
double weight;
/*!
* Intra prediction error.
*/
double intra_error;
/*!
* Best of intra pred error and inter pred error using last frame as ref.
*/
double coded_error;
/*!
* Best of intra pred error and inter pred error using golden frame as ref.
*/
double sr_coded_error;
/*!
* Estimate the noise energy of the current frame.
*/
double frame_noise_energy;
/*!
* Percentage of blocks with inter pred error < intra pred error.
*/
double pcnt_inter;
/*!
* Percentage of blocks using (inter prediction and) non-zero motion vectors.
*/
double pcnt_motion;
/*!
* Percentage of blocks where golden frame was better than last or intra:
* inter pred error using golden frame < inter pred error using last frame and
* inter pred error using golden frame < intra pred error
*/
double pcnt_second_ref;
/*!
* Percentage of blocks where intra and inter prediction errors were very
* close.
*/
double pcnt_neutral;
/*!
* Percentage of blocks that have intra error < inter error and inter error <
* LOW_I_THRESH
* - bit_depth 8: LOW_I_THRESH = 24000
* - bit_depth 10: LOW_I_THRESH = 24000 << 4
* - bit_depth 12: LOW_I_THRESH = 24000 << 8
*/
double pcnt_intra_low;
/*!
* Percentage of blocks that have intra error < inter error and intra error <
* LOW_I_THRESH but inter error >= LOW_I_THRESH LOW_I_THRESH
* - bit_depth 8: LOW_I_THRESH = 24000
* - bit_depth 10: LOW_I_THRESH = 24000 << 4
* - bit_depth 12: LOW_I_THRESH = 24000 << 8
*/
double pcnt_intra_high;
/*!
* Percentage of blocks that have almost no intra error residual
* (i.e. are in effect completely flat and untextured in the intra
* domain). In natural videos this is uncommon, but it is much more
* common in animations, graphics and screen content, so may be used
* as a signal to detect these types of content.
*/
double intra_skip_pct;
/*!
* Percentage of blocks that have intra error < SMOOTH_INTRA_THRESH
* - bit_depth 8: SMOOTH_INTRA_THRESH = 4000
* - bit_depth 10: SMOOTH_INTRA_THRESH = 4000 << 4
* - bit_depth 12: SMOOTH_INTRA_THRESH = 4000 << 8
*/
double intra_smooth_pct;
/*!
* Image mask rows top and bottom.
*/
double inactive_zone_rows;
/*!
* Image mask columns at left and right edges.
*/
double inactive_zone_cols;
/*!
* Mean of row motion vectors.
*/
double MVr;
/*!
* Mean of absolute value of row motion vectors.
*/
double mvr_abs;
/*!
* Mean of column motion vectors.
*/
double MVc;
/*!
* Mean of absolute value of column motion vectors.
*/
double mvc_abs;
/*!
* Variance of row motion vectors.
*/
double MVrv;
/*!
* Variance of column motion vectors.
*/
double MVcv;
/*!
* Value in range [-1,1] indicating fraction of row and column motion vectors
* that point inwards (negative MV value) or outwards (positive MV value).
* For example, value of 1 indicates, all row/column MVs are inwards.
*/
double mv_in_out_count;
/*!
* Duration of the frame / collection of frames.
*/
double duration;
/*!
* 1.0 if stats are for a single frame, or
* number of frames whose stats are accumulated.
*/
double count;
} vpx_rc_frame_stats_t;
/*!\brief Collection of first pass frame stats
*/
typedef struct vpx_rc_firstpass_stats {
/*!
* Pointer to first pass frame stats.
* The pointed array of vpx_rc_frame_stats_t should have length equal to
* number of show frames in the video.
*/
vpx_rc_frame_stats_t *frame_stats;
/*!
* Number of show frames in the video.
*/
int num_frames;
} vpx_rc_firstpass_stats_t;
/*!\brief Encode config sent to external rate control model
*/
typedef struct vpx_rc_config {
int frame_width; /**< frame width */
int frame_height; /**< frame height */
int show_frame_count; /**< number of visible frames in the video */
/*!
* Target bitrate in kilobytes per second
*/
int target_bitrate_kbps;
int frame_rate_num; /**< numerator of frame rate */
int frame_rate_den; /**< denominator of frame rate */
} vpx_rc_config_t;
/*!\brief Create an external rate control model callback prototype
*
* This callback is invoked by the encoder to create an external rate control
* model.
*
* \param[in] priv Callback's private data
* \param[in] ratectrl_config Pointer to vpx_rc_config_t
* \param[out] rate_ctrl_model_pt Pointer to vpx_rc_model_t
*/
typedef vpx_rc_status_t (*vpx_rc_create_model_cb_fn_t)(
void *priv, const vpx_rc_config_t *ratectrl_config,
vpx_rc_model_t *rate_ctrl_model_pt);
/*!\brief Send first pass stats to the external rate control model callback
* prototype
*
* This callback is invoked by the encoder to send first pass stats to the
* external rate control model.
*
* \param[in] rate_ctrl_model rate control model
* \param[in] first_pass_stats first pass stats
*/
typedef vpx_rc_status_t (*vpx_rc_send_firstpass_stats_cb_fn_t)(
vpx_rc_model_t rate_ctrl_model,
const vpx_rc_firstpass_stats_t *first_pass_stats);
/*!\brief Receive encode frame decision callback prototype
*
* This callback is invoked by the encoder to receive encode frame decision from
* the external rate control model.
*
* \param[in] rate_ctrl_model rate control model
* \param[in] encode_frame_info information of the coding frame
* \param[out] frame_decision encode decision of the coding frame
*/
typedef vpx_rc_status_t (*vpx_rc_get_encodeframe_decision_cb_fn_t)(
vpx_rc_model_t rate_ctrl_model,
const vpx_rc_encodeframe_info_t *encode_frame_info,
vpx_rc_encodeframe_decision_t *frame_decision);
/*!\brief Update encode frame result callback prototype
*
* This callback is invoked by the encoder to update encode frame result to the
* external rate control model.
*
* \param[in] rate_ctrl_model rate control model
* \param[out] encode_frame_result encode result of the coding frame
*/
typedef vpx_rc_status_t (*vpx_rc_update_encodeframe_result_cb_fn_t)(
vpx_rc_model_t rate_ctrl_model,
const vpx_rc_encodeframe_result_t *encode_frame_result);
/*!\brief Delete the external rate control model callback prototype
*
* This callback is invoked by the encoder to delete the external rate control
* model.
*
* \param[in] rate_ctrl_model rate control model
*/
typedef vpx_rc_status_t (*vpx_rc_delete_model_cb_fn_t)(
vpx_rc_model_t rate_ctrl_model);
/*!\brief Callback function set for external rate control.
*
* The user can enable external rate control by registering
* a set of callback functions with the codec control flag
* VP9E_SET_EXTERNAL_RATE_CONTROL.
*/
typedef struct vpx_rc_funcs {
/*!
* Create an external rate control model.
*/
vpx_rc_create_model_cb_fn_t create_model;
/*!
* Send first pass stats to the external rate control model.
*/
vpx_rc_send_firstpass_stats_cb_fn_t send_firstpass_stats;
/*!
* Get encodeframe decision from the external rate control model.
*/
vpx_rc_get_encodeframe_decision_cb_fn_t get_encodeframe_decision;
/*!
* Update encodeframe result to the external rate control model.
*/
vpx_rc_update_encodeframe_result_cb_fn_t update_encodeframe_result;
/*!
* Delete the external rate control model.
*/
vpx_rc_delete_model_cb_fn_t delete_model;
/*!
* Private data for the external rate control model.
*/
void *priv;
} vpx_rc_funcs_t;
#ifdef __cplusplus
} // extern "C"
#endif
#endif // VPX_VPX_VPX_EXT_RATECTRL_H_