1 /* 2 * Copyright (c) 2020 The WebM project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 /*!\file 12 * \brief Defines structs and callbacks needed for external rate control. 13 * 14 */ 15 #ifndef VPX_VPX_VPX_EXT_RATECTRL_H_ 16 #define VPX_VPX_VPX_EXT_RATECTRL_H_ 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #include "./vpx_integer.h" 23 #include "./vpx_tpl.h" 24 25 /*!\brief Current ABI version number 26 * 27 * \internal 28 * If this file is altered in any way that changes the ABI, this value 29 * must be bumped. Examples include, but are not limited to, changing 30 * types, removing or reassigning enums, adding/removing/rearranging 31 * fields to structures. 32 */ 33 #define VPX_EXT_RATECTRL_ABI_VERSION (5 + VPX_TPL_ABI_VERSION) 34 35 /*!\brief Corresponds to MAX_STATIC_GF_GROUP_LENGTH defined in vp9_ratectrl.h 36 */ 37 #define VPX_RC_MAX_STATIC_GF_GROUP_LENGTH 250 38 39 /*!\brief Max number of ref frames returned by the external RC. 40 * 41 * Corresponds to MAX_REF_FRAMES defined in vp9_blockd.h. 42 */ 43 #define VPX_RC_MAX_REF_FRAMES 4 44 45 /*!\brief The type of the external rate control. 46 * 47 * This controls what encoder parameters are determined by the external rate 48 * control. 49 */ 50 typedef enum vpx_rc_type { 51 /*! 52 * The external rate control doesn't determine anything. 53 * This mode is used as baseline. 54 */ 55 VPX_RC_NONE = 0, 56 /*! 57 * The external rate control model determines the quantization parameter (QP) 58 * for each frame. 59 */ 60 VPX_RC_QP = 1 << 0, 61 /*! 62 * The external rate control model determines the group of picture (GOP) of 63 * the video sequence. 64 */ 65 VPX_RC_GOP = 1 << 1, 66 /*! 67 * The external rate control model determines the rate-distortion multiplier 68 * (rdmult) for the current frame. 69 */ 70 VPX_RC_RDMULT = 1 << 2, 71 /*! 72 * The external rate control model determines both QP and GOP. 73 */ 74 VPX_RC_GOP_QP = VPX_RC_QP | VPX_RC_GOP, 75 /*! 76 * The external rate control model determines the QP, GOP and the rdmult. 77 */ 78 VPX_RC_GOP_QP_RDMULT = VPX_RC_QP | VPX_RC_GOP | VPX_RC_RDMULT 79 } vpx_rc_type_t; 80 81 /*!\brief The rate control mode for the external rate control model. 82 */ 83 typedef enum vpx_ext_rc_mode { 84 VPX_RC_QMODE = 0, 85 VPX_RC_VBR = 1, 86 VPX_RC_CQ = 2, 87 } vpx_ext_rc_mode_t; 88 89 /*!\brief Corresponds to FRAME_UPDATE_TYPE defined in vp9_firstpass.h. 90 */ 91 typedef enum vpx_rc_frame_update_type { 92 VPX_RC_INVALID_UPDATE_TYPE = -1, 93 VPX_RC_KF_UPDATE = 0, 94 VPX_RC_LF_UPDATE = 1, 95 VPX_RC_GF_UPDATE = 2, 96 VPX_RC_ARF_UPDATE = 3, 97 VPX_RC_OVERLAY_UPDATE = 4, 98 VPX_RC_MID_OVERLAY_UPDATE = 5, 99 VPX_RC_USE_BUF_FRAME = 6, 100 } vpx_rc_frame_update_type_t; 101 102 /*!\brief Name for the ref frames returned by the external RC. 103 * 104 * Corresponds to the ref frames defined in vp9_blockd.h. 105 */ 106 typedef enum vpx_rc_ref_name { 107 VPX_RC_INVALID_REF_FRAME = -1, 108 VPX_RC_INTRA_FRAME = 0, 109 VPX_RC_LAST_FRAME = 1, 110 VPX_RC_GOLDEN_FRAME = 2, 111 VPX_RC_ALTREF_FRAME = 3, 112 } vpx_rc_ref_name_t; 113 114 /*!\brief Abstract rate control model handler 115 * 116 * The encoder will receive the model handler from 117 * vpx_rc_funcs_t::create_model(). 118 */ 119 typedef void *vpx_rc_model_t; 120 121 /*!\brief A reserved value for the q index. 122 * If the external rate control model returns this value, 123 * the encoder will use the default q selected by libvpx's rate control 124 * system. 125 */ 126 #define VPX_DEFAULT_Q -1 127 128 /*!\brief A reserved value for the rdmult. 129 * If the external rate control model returns this value, 130 * the encoder will use the default rdmult selected by libvpx's rate control 131 * system. 132 */ 133 #define VPX_DEFAULT_RDMULT -1 134 135 /*!\brief Encode frame decision made by the external rate control model 136 * 137 * The encoder will receive the decision from the external rate control model 138 * through vpx_rc_funcs_t::get_encodeframe_decision(). 139 */ 140 typedef struct vpx_rc_encodeframe_decision { 141 int q_index; /**< Quantizer step index [0..255]*/ 142 int rdmult; /**< Frame level Lagrangian multiplier*/ 143 } vpx_rc_encodeframe_decision_t; 144 145 /*!\brief Information for the frame to be encoded. 146 * 147 * The encoder will send the information to external rate control model through 148 * vpx_rc_funcs_t::get_encodeframe_decision(). 149 * 150 */ 151 typedef struct vpx_rc_encodeframe_info { 152 /*! 153 * 0: Key frame 154 * 1: Inter frame 155 * 2: Alternate reference frame 156 * 3: Overlay frame 157 * 4: Golden frame 158 */ 159 int frame_type; 160 int show_index; /**< display index, starts from zero*/ 161 int coding_index; /**< coding index, starts from zero*/ 162 /*! 163 * index of the current frame in this group of picture, starts from zero. 164 */ 165 int gop_index; 166 int ref_frame_coding_indexes[3]; /**< three reference frames' coding indices*/ 167 /*! 168 * The validity of the three reference frames. 169 * 0: Invalid 170 * 1: Valid 171 */ 172 int ref_frame_valid_list[3]; 173 /*! 174 * The length of the current GOP. 175 */ 176 int gop_size; 177 /*! 178 * Whether the current GOP uses an alt ref. 179 */ 180 int use_alt_ref; 181 } vpx_rc_encodeframe_info_t; 182 183 /*!\brief Frame coding result 184 * 185 * The encoder will send the result to the external rate control model through 186 * vpx_rc_funcs_t::update_encodeframe_result(). 187 */ 188 typedef struct vpx_rc_encodeframe_result { 189 int64_t bit_count; /**< number of bits spent on coding the frame*/ 190 int actual_encoding_qindex; /**< the actual qindex used to encode the frame*/ 191 } vpx_rc_encodeframe_result_t; 192 193 /*!\brief Status returned by rate control callback functions. 194 */ 195 typedef enum vpx_rc_status { 196 VPX_RC_OK = 0, 197 VPX_RC_ERROR = 1, 198 } vpx_rc_status_t; 199 200 /*!\brief First pass frame stats 201 * This is a mirror of vp9's FIRSTPASS_STATS except that spatial_layer_id is 202 * omitted 203 */ 204 typedef struct vpx_rc_frame_stats { 205 /*! 206 * Frame number in display order, if stats are for a single frame. 207 * No real meaning for a collection of frames. 208 */ 209 double frame; 210 /*! 211 * Weight assigned to this frame (or total weight for the collection of 212 * frames) currently based on intra factor and brightness factor. This is used 213 * to distribute bits between easier and harder frames. 214 */ 215 double weight; 216 /*! 217 * Intra prediction error. 218 */ 219 double intra_error; 220 /*! 221 * Best of intra pred error and inter pred error using last frame as ref. 222 */ 223 double coded_error; 224 /*! 225 * Best of intra pred error and inter pred error using golden frame as ref. 226 */ 227 double sr_coded_error; 228 /*! 229 * Estimate the noise energy of the current frame. 230 */ 231 double frame_noise_energy; 232 /*! 233 * Percentage of blocks with inter pred error < intra pred error. 234 */ 235 double pcnt_inter; 236 /*! 237 * Percentage of blocks using (inter prediction and) non-zero motion vectors. 238 */ 239 double pcnt_motion; 240 /*! 241 * Percentage of blocks where golden frame was better than last or intra: 242 * inter pred error using golden frame < inter pred error using last frame and 243 * inter pred error using golden frame < intra pred error 244 */ 245 double pcnt_second_ref; 246 /*! 247 * Percentage of blocks where intra and inter prediction errors were very 248 * close. 249 */ 250 double pcnt_neutral; 251 /*! 252 * Percentage of blocks that have intra error < inter error and inter error < 253 * LOW_I_THRESH 254 * - bit_depth 8: LOW_I_THRESH = 24000 255 * - bit_depth 10: LOW_I_THRESH = 24000 << 4 256 * - bit_depth 12: LOW_I_THRESH = 24000 << 8 257 */ 258 double pcnt_intra_low; 259 /*! 260 * Percentage of blocks that have intra error < inter error and intra error < 261 * LOW_I_THRESH but inter error >= LOW_I_THRESH LOW_I_THRESH 262 * - bit_depth 8: LOW_I_THRESH = 24000 263 * - bit_depth 10: LOW_I_THRESH = 24000 << 4 264 * - bit_depth 12: LOW_I_THRESH = 24000 << 8 265 */ 266 double pcnt_intra_high; 267 /*! 268 * Percentage of blocks that have almost no intra error residual 269 * (i.e. are in effect completely flat and untextured in the intra 270 * domain). In natural videos this is uncommon, but it is much more 271 * common in animations, graphics and screen content, so may be used 272 * as a signal to detect these types of content. 273 */ 274 double intra_skip_pct; 275 /*! 276 * Percentage of blocks that have intra error < SMOOTH_INTRA_THRESH 277 * - bit_depth 8: SMOOTH_INTRA_THRESH = 4000 278 * - bit_depth 10: SMOOTH_INTRA_THRESH = 4000 << 4 279 * - bit_depth 12: SMOOTH_INTRA_THRESH = 4000 << 8 280 */ 281 double intra_smooth_pct; 282 /*! 283 * Image mask rows top and bottom. 284 */ 285 double inactive_zone_rows; 286 /*! 287 * Image mask columns at left and right edges. 288 */ 289 double inactive_zone_cols; 290 /*! 291 * Mean of row motion vectors. 292 */ 293 double MVr; 294 /*! 295 * Mean of absolute value of row motion vectors. 296 */ 297 double mvr_abs; 298 /*! 299 * Mean of column motion vectors. 300 */ 301 double MVc; 302 /*! 303 * Mean of absolute value of column motion vectors. 304 */ 305 double mvc_abs; 306 /*! 307 * Variance of row motion vectors. 308 */ 309 double MVrv; 310 /*! 311 * Variance of column motion vectors. 312 */ 313 double MVcv; 314 /*! 315 * Value in range [-1,1] indicating fraction of row and column motion vectors 316 * that point inwards (negative MV value) or outwards (positive MV value). 317 * For example, value of 1 indicates, all row/column MVs are inwards. 318 */ 319 double mv_in_out_count; 320 /*! 321 * Duration of the frame / collection of frames. 322 */ 323 double duration; 324 /*! 325 * 1.0 if stats are for a single frame, or 326 * number of frames whose stats are accumulated. 327 */ 328 double count; 329 /*! 330 * Number of new mv in a frame. 331 */ 332 double new_mv_count; 333 } vpx_rc_frame_stats_t; 334 335 /*!\brief Collection of first pass frame stats 336 */ 337 typedef struct vpx_rc_firstpass_stats { 338 /*! 339 * Pointer to first pass frame stats. 340 * The pointed array of vpx_rc_frame_stats_t should have length equal to 341 * number of show frames in the video. 342 */ 343 vpx_rc_frame_stats_t *frame_stats; 344 /*! 345 * Number of show frames in the video. 346 */ 347 int num_frames; 348 } vpx_rc_firstpass_stats_t; 349 350 /*!\brief Encode config sent to external rate control model 351 */ 352 typedef struct vpx_rc_config { 353 int frame_width; /**< frame width */ 354 int frame_height; /**< frame height */ 355 int show_frame_count; /**< number of visible frames in the video */ 356 int max_gf_interval; /**< max GOP size in number of show frames */ 357 int min_gf_interval; /**< min GOP size in number of show frames */ 358 /*! 359 * Target bitrate in kilobytes per second 360 */ 361 int target_bitrate_kbps; 362 int frame_rate_num; /**< numerator of frame rate */ 363 int frame_rate_den; /**< denominator of frame rate */ 364 /*! 365 * The following fields are only for external rate control models that support 366 * different rate control modes. 367 */ 368 vpx_ext_rc_mode_t rc_mode; /**< Q mode or VBR mode */ 369 int overshoot_percent; /**< for VBR mode only */ 370 int undershoot_percent; /**< for VBR mode only */ 371 int min_base_q_index; /**< for VBR mode only */ 372 int max_base_q_index; /**< for VBR mode only */ 373 int base_qp; /**< base QP for leaf frames, 0-255 */ 374 } vpx_rc_config_t; 375 376 /*!\brief Control what ref frame to use and its index. 377 */ 378 typedef struct vpx_rc_ref_frame { 379 /*! 380 * Ref frame index. Corresponding to |lst_fb_idx|, |gld_fb_idx| or 381 * |alt_fb_idx| in VP9_COMP depending on the ref frame #name. 382 */ 383 int index[VPX_RC_MAX_REF_FRAMES]; 384 /*! 385 * Ref frame name. This decides whether the #index is used as 386 * |lst_fb_idx|, |gld_fb_idx| or |alt_fb_idx| in VP9_COMP. 387 * 388 */ 389 vpx_rc_ref_name_t name[VPX_RC_MAX_REF_FRAMES]; 390 } vpx_rc_ref_frame_t; 391 392 /*!\brief The decision made by the external rate control model to set the 393 * group of picture. 394 */ 395 typedef struct vpx_rc_gop_decision { 396 int gop_coding_frames; /**< The number of frames of this GOP */ 397 int use_alt_ref; /**< Whether to use alt ref for this GOP */ 398 int use_key_frame; /**< Whether to set key frame for this GOP */ 399 /*! 400 * Frame type for each frame in this GOP. 401 * This will be populated to |update_type| in GF_GROUP defined in 402 * vp9_firstpass.h 403 */ 404 vpx_rc_frame_update_type_t update_type[VPX_RC_MAX_STATIC_GF_GROUP_LENGTH + 2]; 405 /*! Ref frame buffer index to be updated for each frame in this GOP. */ 406 int update_ref_index[VPX_RC_MAX_STATIC_GF_GROUP_LENGTH + 2]; 407 /*! Ref frame list to be used for each frame in this GOP. */ 408 vpx_rc_ref_frame_t ref_frame_list[VPX_RC_MAX_STATIC_GF_GROUP_LENGTH + 2]; 409 } vpx_rc_gop_decision_t; 410 411 /*!\brief The decision made by the external rate control model to set the 412 * key frame location and the show frame count in the key frame group 413 */ 414 typedef struct vpx_rc_key_frame_decision { 415 int key_frame_show_index; /**< This key frame's show index in the video */ 416 int key_frame_group_size; /**< Show frame count of this key frame group */ 417 } vpx_rc_key_frame_decision_t; 418 419 /*!\brief Create an external rate control model callback prototype 420 * 421 * This callback is invoked by the encoder to create an external rate control 422 * model. 423 * 424 * \param[in] priv Callback's private data 425 * \param[in] ratectrl_config Pointer to vpx_rc_config_t 426 * \param[out] rate_ctrl_model_ptr Pointer to vpx_rc_model_t 427 */ 428 typedef vpx_rc_status_t (*vpx_rc_create_model_cb_fn_t)( 429 void *priv, const vpx_rc_config_t *ratectrl_config, 430 vpx_rc_model_t *rate_ctrl_model_ptr); 431 432 /*!\brief Send first pass stats to the external rate control model callback 433 * prototype 434 * 435 * This callback is invoked by the encoder to send first pass stats to the 436 * external rate control model. 437 * 438 * \param[in] rate_ctrl_model rate control model 439 * \param[in] first_pass_stats first pass stats 440 */ 441 typedef vpx_rc_status_t (*vpx_rc_send_firstpass_stats_cb_fn_t)( 442 vpx_rc_model_t rate_ctrl_model, 443 const vpx_rc_firstpass_stats_t *first_pass_stats); 444 445 /*!\brief Send TPL stats for the current GOP to the external rate control model 446 * callback prototype 447 * 448 * This callback is invoked by the encoder to send TPL stats for the GOP to the 449 * external rate control model. 450 * 451 * \param[in] rate_ctrl_model rate control model 452 * \param[in] tpl_gop_stats TPL stats for current GOP 453 */ 454 typedef vpx_rc_status_t (*vpx_rc_send_tpl_gop_stats_cb_fn_t)( 455 vpx_rc_model_t rate_ctrl_model, const VpxTplGopStats *tpl_gop_stats); 456 457 /*!\brief Receive encode frame decision callback prototype 458 * 459 * This callback is invoked by the encoder to receive encode frame decision from 460 * the external rate control model. 461 * 462 * \param[in] rate_ctrl_model rate control model 463 * \param[in] frame_gop_index index of the frame in current gop 464 * \param[out] frame_decision encode decision of the coding frame 465 */ 466 typedef vpx_rc_status_t (*vpx_rc_get_encodeframe_decision_cb_fn_t)( 467 vpx_rc_model_t rate_ctrl_model, const int frame_gop_index, 468 vpx_rc_encodeframe_decision_t *frame_decision); 469 470 /*!\brief Update encode frame result callback prototype 471 * 472 * This callback is invoked by the encoder to update encode frame result to the 473 * external rate control model. 474 * 475 * \param[in] rate_ctrl_model rate control model 476 * \param[out] encode_frame_result encode result of the coding frame 477 */ 478 typedef vpx_rc_status_t (*vpx_rc_update_encodeframe_result_cb_fn_t)( 479 vpx_rc_model_t rate_ctrl_model, 480 const vpx_rc_encodeframe_result_t *encode_frame_result); 481 482 /*!\brief Get the key frame decision from the external rate control model. 483 * 484 * This callback is invoked by the encoder to get key frame decision from 485 * the external rate control model. 486 * 487 * \param[in] rate_ctrl_model rate control model 488 * \param[out] key_frame_decision key frame decision from the model 489 */ 490 typedef vpx_rc_status_t (*vpx_rc_get_key_frame_decision_cb_fn_t)( 491 vpx_rc_model_t rate_ctrl_model, 492 vpx_rc_key_frame_decision_t *key_frame_decision); 493 494 /*!\brief Get the GOP structure from the external rate control model. 495 * 496 * This callback is invoked by the encoder to get GOP decisions from 497 * the external rate control model. 498 * 499 * \param[in] rate_ctrl_model rate control model 500 * \param[out] gop_decision GOP decision from the model 501 */ 502 typedef vpx_rc_status_t (*vpx_rc_get_gop_decision_cb_fn_t)( 503 vpx_rc_model_t rate_ctrl_model, vpx_rc_gop_decision_t *gop_decision); 504 505 /*!\brief Get the frame rdmult from the external rate control model. 506 * 507 * This callback is invoked by the encoder to get rdmult from 508 * the external rate control model. 509 * 510 * \param[in] rate_ctrl_model rate control model 511 * \param[in] frame_info information collected from the encoder 512 * \param[out] rdmult frame rate-distortion multiplier from the model 513 */ 514 typedef vpx_rc_status_t (*vpx_rc_get_frame_rdmult_cb_fn_t)( 515 vpx_rc_model_t rate_ctrl_model, const vpx_rc_encodeframe_info_t *frame_info, 516 int *rdmult); 517 518 /*!\brief Delete the external rate control model callback prototype 519 * 520 * This callback is invoked by the encoder to delete the external rate control 521 * model. 522 * 523 * \param[in] rate_ctrl_model rate control model 524 */ 525 typedef vpx_rc_status_t (*vpx_rc_delete_model_cb_fn_t)( 526 vpx_rc_model_t rate_ctrl_model); 527 528 /*!\brief Callback function set for external rate control. 529 * 530 * The user can enable external rate control by registering 531 * a set of callback functions with the codec control flag 532 * #VP9E_SET_EXTERNAL_RATE_CONTROL. 533 */ 534 typedef struct vpx_rc_funcs { 535 /*! 536 * The rate control type of this API. 537 */ 538 vpx_rc_type_t rc_type; 539 /*! 540 * Create an external rate control model. 541 */ 542 vpx_rc_create_model_cb_fn_t create_model; 543 /*! 544 * Send first pass stats to the external rate control model. 545 */ 546 vpx_rc_send_firstpass_stats_cb_fn_t send_firstpass_stats; 547 /*! 548 * Send TPL stats for current GOP to the external rate control model. 549 */ 550 vpx_rc_send_tpl_gop_stats_cb_fn_t send_tpl_gop_stats; 551 /*! 552 * Get encodeframe decision from the external rate control model. 553 */ 554 vpx_rc_get_encodeframe_decision_cb_fn_t get_encodeframe_decision; 555 /*! 556 * Update encodeframe result to the external rate control model. 557 */ 558 vpx_rc_update_encodeframe_result_cb_fn_t update_encodeframe_result; 559 /*! 560 * Get key frame decision from the external rate control model. 561 */ 562 vpx_rc_get_key_frame_decision_cb_fn_t get_key_frame_decision; 563 /*! 564 * Get GOP decisions from the external rate control model. 565 */ 566 vpx_rc_get_gop_decision_cb_fn_t get_gop_decision; 567 /*! 568 * Get rdmult for the frame from the external rate control model. 569 */ 570 vpx_rc_get_frame_rdmult_cb_fn_t get_frame_rdmult; 571 /*! 572 * Delete the external rate control model. 573 */ 574 vpx_rc_delete_model_cb_fn_t delete_model; 575 576 /*! 577 * Rate control log path. 578 */ 579 const char *rate_ctrl_log_path; 580 /*! 581 * Private data for the external rate control model. 582 */ 583 void *priv; 584 } vpx_rc_funcs_t; 585 586 #ifdef __cplusplus 587 } // extern "C" 588 #endif 589 590 #endif // VPX_VPX_VPX_EXT_RATECTRL_H_ 591