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