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