vpx_ext_ratectrl.h File Reference

Defines structs and callbacks needed for external rate control. More...

`#include "./vpx_integer.h"`
`#include "./vpx_tpl.h"`

Go to the source code of this file.

## Data Structures

struct | vpx_rc_encodeframe_decision
| Encode frame decision made by the external rate control model. More...
struct | vpx_rc_encodeframe_info
| Information for the frame to be encoded. More...
struct | vpx_rc_encodeframe_result
| Frame coding result. More...
struct | vpx_rc_frame_stats
| First pass frame stats This is a mirror of vp9's FIRSTPASS_STATS except that spatial_layer_id is omitted. More...
struct | vpx_rc_firstpass_stats
| Collection of first pass frame stats. More...
struct | vpx_rc_config
| Encode config sent to external rate control model. More...
struct | vpx_rc_ref_frame
| Control what ref frame to use and its index. More...
struct | vpx_rc_gop_decision
| The decision made by the external rate control model to set the group of picture. More...
struct | vpx_rc_key_frame_decision
| The decision made by the external rate control model to set the key frame location and the show frame count in the key frame group. More...
struct | vpx_rc_funcs
| Callback function set for external rate control. More...

## Macros

#define | VPX_EXT_RATECTRL_ABI_VERSION (5 + VPX_TPL_ABI_VERSION)
| Current ABI version number.
#define | VPX_RC_MAX_STATIC_GF_GROUP_LENGTH 250
| Corresponds to MAX_STATIC_GF_GROUP_LENGTH defined in vp9_ratectrl.h.
#define | VPX_RC_MAX_REF_FRAMES 4
| Max number of ref frames returned by the external RC.
#define | VPX_DEFAULT_Q -1
| A reserved value for the q index. If the external rate control model returns this value, the encoder will use the default q selected by libvpx's rate control system.
#define | VPX_DEFAULT_RDMULT -1
| A reserved value for the rdmult. If the external rate control model returns this value, the encoder will use the default rdmult selected by libvpx's rate control system.

## Typedefs

typedef enum vpx_rc_type | vpx_rc_type_t
| The type of the external rate control.
typedef enum vpx_ext_rc_mode | vpx_ext_rc_mode_t
| The rate control mode for the external rate control model.
typedef enum vpx_rc_frame_update_type | vpx_rc_frame_update_type_t
| Corresponds to FRAME_UPDATE_TYPE defined in vp9_firstpass.h.
typedef enum vpx_rc_ref_name | vpx_rc_ref_name_t
| Name for the ref frames returned by the external RC.
typedef void * | vpx_rc_model_t
| Abstract rate control model handler.
typedef struct vpx_rc_encodeframe_decision | vpx_rc_encodeframe_decision_t
| Encode frame decision made by the external rate control model.
typedef struct vpx_rc_encodeframe_info | vpx_rc_encodeframe_info_t
| Information for the frame to be encoded.
typedef struct vpx_rc_encodeframe_result | vpx_rc_encodeframe_result_t
| Frame coding result.
typedef enum vpx_rc_status | vpx_rc_status_t
| Status returned by rate control callback functions.
typedef struct vpx_rc_frame_stats | vpx_rc_frame_stats_t
| First pass frame stats This is a mirror of vp9's FIRSTPASS_STATS except that spatial_layer_id is omitted.
typedef struct vpx_rc_firstpass_stats | vpx_rc_firstpass_stats_t
| Collection of first pass frame stats.
typedef struct vpx_rc_config | vpx_rc_config_t
| Encode config sent to external rate control model.
typedef struct vpx_rc_ref_frame | vpx_rc_ref_frame_t
| Control what ref frame to use and its index.
typedef struct vpx_rc_gop_decision | vpx_rc_gop_decision_t
| The decision made by the external rate control model to set the group of picture.
typedef struct vpx_rc_key_frame_decision | vpx_rc_key_frame_decision_t
| The decision made by the external rate control model to set the key frame location and the show frame count in the key frame group.
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_ptr)
| Create an external rate control model callback prototype.
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)
| Send first pass stats to the external rate control model callback prototype.
typedef vpx_rc_status_t(* | vpx_rc_send_tpl_gop_stats_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const VpxTplGopStats *tpl_gop_stats)
| Send TPL stats for the current GOP to the external rate control model callback prototype.
typedef vpx_rc_status_t(* | vpx_rc_get_encodeframe_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const int frame_gop_index, vpx_rc_encodeframe_decision_t *frame_decision)
| Receive encode frame decision callback prototype.
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)
| Update encode frame result callback prototype.
typedef vpx_rc_status_t(* | vpx_rc_get_key_frame_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, vpx_rc_key_frame_decision_t *key_frame_decision)
| Get the key frame decision from the external rate control model.
typedef vpx_rc_status_t(* | vpx_rc_get_gop_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, vpx_rc_gop_decision_t *gop_decision)
| Get the GOP structure from the external rate control model.
typedef vpx_rc_status_t(* | vpx_rc_get_frame_rdmult_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const vpx_rc_encodeframe_info_t *frame_info, int *rdmult)
| Get the frame rdmult from the external rate control model.
typedef vpx_rc_status_t(* | vpx_rc_delete_model_cb_fn_t) (vpx_rc_model_t rate_ctrl_model)
| Delete the external rate control model callback prototype.
typedef struct vpx_rc_funcs | vpx_rc_funcs_t
| Callback function set for external rate control.

## Enumerations

enum | vpx_rc_type { VPX_RC_NONE = 0 , VPX_RC_QP = 1 << 0 , VPX_RC_GOP = 1 << 1 , VPX_RC_RDMULT = 1 << 2 , VPX_RC_GOP_QP = VPX_RC_QP | VPX_RC_GOP , VPX_RC_GOP_QP_RDMULT = VPX_RC_QP | VPX_RC_GOP | VPX_RC_RDMULT }
| The type of the external rate control. More...
enum | vpx_ext_rc_mode { VPX_RC_QMODE = 0 , VPX_RC_VBR = 1 , VPX_RC_CQ = 2 }
| The rate control mode for the external rate control model.
enum | vpx_rc_frame_update_type { VPX_RC_INVALID_UPDATE_TYPE = -1 , VPX_RC_KF_UPDATE = 0 , VPX_RC_LF_UPDATE = 1 , VPX_RC_GF_UPDATE = 2 , VPX_RC_ARF_UPDATE = 3 , VPX_RC_OVERLAY_UPDATE = 4 , VPX_RC_MID_OVERLAY_UPDATE = 5 , VPX_RC_USE_BUF_FRAME = 6 }
| Corresponds to FRAME_UPDATE_TYPE defined in vp9_firstpass.h.
enum | vpx_rc_ref_name { VPX_RC_INVALID_REF_FRAME = -1 , VPX_RC_INTRA_FRAME = 0 , VPX_RC_LAST_FRAME = 1 , VPX_RC_GOLDEN_FRAME = 2 , VPX_RC_ALTREF_FRAME = 3 }
| Name for the ref frames returned by the external RC. More...
enum | vpx_rc_status { VPX_RC_OK = 0 , VPX_RC_ERROR = 1 }
| Status returned by rate control callback functions.

## Detailed Description

Defines structs and callbacks needed for external rate control.

## Macro Definition Documentation

## VPX_RC_MAX_REF_FRAMES

#define VPX_RC_MAX_REF_FRAMES 4

Max number of ref frames returned by the external RC.

Corresponds to MAX_REF_FRAMES defined in vp9_blockd.h.

## Typedef Documentation

## vpx_rc_type_t

typedef enum vpx_rc_type vpx_rc_type_t

The type of the external rate control.

This controls what encoder parameters are determined by the external rate control.

## vpx_rc_ref_name_t

typedef enum vpx_rc_ref_name vpx_rc_ref_name_t

Name for the ref frames returned by the external RC.

Corresponds to the ref frames defined in vp9_blockd.h.

## vpx_rc_model_t

typedef void* vpx_rc_model_t

Abstract rate control model handler.

The encoder will receive the model handler from vpx_rc_funcs_t::create_model().

## vpx_rc_encodeframe_decision_t

typedef struct vpx_rc_encodeframe_decision vpx_rc_encodeframe_decision_t

Encode frame decision made by the external rate control model.

The encoder will receive the decision from the external rate control model through vpx_rc_funcs_t::get_encodeframe_decision().

## vpx_rc_encodeframe_info_t

typedef struct vpx_rc_encodeframe_info vpx_rc_encodeframe_info_t

Information for the frame to be encoded.

The encoder will send the information to external rate control model through vpx_rc_funcs_t::get_encodeframe_decision().

## vpx_rc_encodeframe_result_t

typedef struct vpx_rc_encodeframe_result vpx_rc_encodeframe_result_t

Frame coding result.

The encoder will send the result to the external rate control model through vpx_rc_funcs_t::update_encodeframe_result().

## vpx_rc_create_model_cb_fn_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_ptr)

Create an external rate control model callback prototype.

This callback is invoked by the encoder to create an external rate control model.

Parameters

  [in] | priv | Callback's private data
  [in] | ratectrl_config | Pointer to vpx_rc_config_t
  [out] | rate_ctrl_model_ptr | Pointer to vpx_rc_model_t

## vpx_rc_send_firstpass_stats_cb_fn_t

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)

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.

Parameters

  [in] | rate_ctrl_model | rate control model
  [in] | first_pass_stats | first pass stats

## vpx_rc_send_tpl_gop_stats_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_send_tpl_gop_stats_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const VpxTplGopStats *tpl_gop_stats)

Send TPL stats for the current GOP to the external rate control model callback prototype.

This callback is invoked by the encoder to send TPL stats for the GOP to the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [in] | tpl_gop_stats | TPL stats for current GOP

## vpx_rc_get_encodeframe_decision_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_get_encodeframe_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const int frame_gop_index, vpx_rc_encodeframe_decision_t *frame_decision)

Receive encode frame decision callback prototype.

This callback is invoked by the encoder to receive encode frame decision from the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [in] | frame_gop_index | index of the frame in current gop
  [out] | frame_decision | encode decision of the coding frame

## vpx_rc_update_encodeframe_result_cb_fn_t

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)

Update encode frame result callback prototype.

This callback is invoked by the encoder to update encode frame result to the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [out] | encode_frame_result | encode result of the coding frame

## vpx_rc_get_key_frame_decision_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_get_key_frame_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, vpx_rc_key_frame_decision_t *key_frame_decision)

Get the key frame decision from the external rate control model.

This callback is invoked by the encoder to get key frame decision from the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [out] | key_frame_decision | key frame decision from the model

## vpx_rc_get_gop_decision_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_get_gop_decision_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, vpx_rc_gop_decision_t *gop_decision)

Get the GOP structure from the external rate control model.

This callback is invoked by the encoder to get GOP decisions from the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [out] | gop_decision | GOP decision from the model

## vpx_rc_get_frame_rdmult_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_get_frame_rdmult_cb_fn_t) (vpx_rc_model_t rate_ctrl_model, const vpx_rc_encodeframe_info_t *frame_info, int *rdmult)

Get the frame rdmult from the external rate control model.

This callback is invoked by the encoder to get rdmult from the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model
  [in] | frame_info | information collected from the encoder
  [out] | rdmult | frame rate-distortion multiplier from the model

## vpx_rc_delete_model_cb_fn_t

typedef vpx_rc_status_t(* vpx_rc_delete_model_cb_fn_t) (vpx_rc_model_t rate_ctrl_model)

Delete the external rate control model callback prototype.

This callback is invoked by the encoder to delete the external rate control model.

Parameters

  [in] | rate_ctrl_model | rate control model

## vpx_rc_funcs_t

typedef struct vpx_rc_funcs vpx_rc_funcs_t

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.

## Enumeration Type Documentation

## vpx_rc_type

enum vpx_rc_type

The type of the external rate control.

This controls what encoder parameters are determined by the external rate control.

Enumerator
VPX_RC_NONE | The external rate control doesn't determine anything. This mode is used as baseline.
VPX_RC_QP | The external rate control model determines the quantization parameter (QP) for each frame.
VPX_RC_GOP | The external rate control model determines the group of picture (GOP) of the video sequence.
VPX_RC_RDMULT | The external rate control model determines the rate-distortion multiplier (rdmult) for the current frame.
VPX_RC_GOP_QP | The external rate control model determines both QP and GOP.
VPX_RC_GOP_QP_RDMULT | The external rate control model determines the QP, GOP and the rdmult.

## vpx_rc_ref_name

enum vpx_rc_ref_name

Name for the ref frames returned by the external RC.

Corresponds to the ref frames defined in vp9_blockd.h.