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 (1) 29 30 /*!\brief Abstract rate control model handler 31 * 32 * The encoder will receive the model handler from create_model() defined in 33 * vpx_rc_funcs_t. 34 */ 35 typedef void *vpx_rc_model_t; 36 37 /*!\brief Encode frame decision made by the external rate control model 38 * 39 * The encoder will receive the decision from the external rate control model 40 * through get_encodeframe_decision() defined in vpx_rc_funcs_t. 41 * 42 * If max_frame_size = 0, the encoding ignores max frame size limit. 43 * If max_frame_size = -1, the encoding uses VP9's max frame size as the limit. 44 * If the encoded frame size is larger than max_frame_size, the frame is 45 * recoded to meet the size limit, following VP9's recoding principles. 46 */ 47 typedef struct vpx_rc_encodeframe_decision { 48 int q_index; /**< Quantizer step index [0..255]*/ 49 int max_frame_size; /**< Maximal frame size allowed to encode a frame*/ 50 } vpx_rc_encodeframe_decision_t; 51 52 /*!\brief Information for the frame to be encoded. 53 * 54 * The encoder will send the information to external rate control model through 55 * get_encodeframe_decision() defined in vpx_rc_funcs_t. 56 * 57 */ 58 typedef struct vpx_rc_encodeframe_info { 59 /*! 60 * 0: Key frame 61 * 1: Inter frame 62 * 2: Alternate reference frame 63 * 3: Overlay frame 64 * 4: Golden frame 65 */ 66 int frame_type; 67 int show_index; /**< display index, starts from zero*/ 68 int coding_index; /**< coding index, starts from zero*/ 69 /*! 70 * index in group of picture, starts from zero. 71 */ 72 int gop_index; 73 int ref_frame_coding_indexes[3]; /**< three reference frames' coding indices*/ 74 /*! 75 * The validity of the three reference frames. 76 * 0: Invalid 77 * 1: Valid 78 */ 79 int ref_frame_valid_list[3]; 80 } vpx_rc_encodeframe_info_t; 81 82 /*!\brief Frame coding result 83 * 84 * The encoder will send the result to the external rate control model through 85 * update_encodeframe_result() defined in vpx_rc_funcs_t. 86 */ 87 typedef struct vpx_rc_encodeframe_result { 88 int64_t sse; /**< sum of squared error of the reconstructed frame */ 89 int64_t bit_count; /**< number of bits spent on coding the frame*/ 90 int64_t pixel_count; /**< number of pixels in YUV planes of the frame*/ 91 int actual_encoding_qindex; /**< the actual qindex used to encode the frame*/ 92 } vpx_rc_encodeframe_result_t; 93 94 /*!\brief Status returned by rate control callback functions. 95 */ 96 typedef enum vpx_rc_status { 97 VPX_RC_OK = 0, 98 VPX_RC_ERROR = 1, 99 } vpx_rc_status_t; 100 101 /*!\brief First pass frame stats 102 * This is a mirror of vp9's FIRSTPASS_STATS except that spatial_layer_id is 103 * omitted 104 */ 105 typedef struct vpx_rc_frame_stats { 106 /*! 107 * Frame number in display order, if stats are for a single frame. 108 * No real meaning for a collection of frames. 109 */ 110 double frame; 111 /*! 112 * Weight assigned to this frame (or total weight for the collection of 113 * frames) currently based on intra factor and brightness factor. This is used 114 * to distribute bits between easier and harder frames. 115 */ 116 double weight; 117 /*! 118 * Intra prediction error. 119 */ 120 double intra_error; 121 /*! 122 * Best of intra pred error and inter pred error using last frame as ref. 123 */ 124 double coded_error; 125 /*! 126 * Best of intra pred error and inter pred error using golden frame as ref. 127 */ 128 double sr_coded_error; 129 /*! 130 * Estimate the noise energy of the current frame. 131 */ 132 double frame_noise_energy; 133 /*! 134 * Percentage of blocks with inter pred error < intra pred error. 135 */ 136 double pcnt_inter; 137 /*! 138 * Percentage of blocks using (inter prediction and) non-zero motion vectors. 139 */ 140 double pcnt_motion; 141 /*! 142 * Percentage of blocks where golden frame was better than last or intra: 143 * inter pred error using golden frame < inter pred error using last frame and 144 * inter pred error using golden frame < intra pred error 145 */ 146 double pcnt_second_ref; 147 /*! 148 * Percentage of blocks where intra and inter prediction errors were very 149 * close. 150 */ 151 double pcnt_neutral; 152 /*! 153 * Percentage of blocks that have intra error < inter error and inter error < 154 * LOW_I_THRESH 155 * - bit_depth 8: LOW_I_THRESH = 24000 156 * - bit_depth 10: LOW_I_THRESH = 24000 << 4 157 * - bit_depth 12: LOW_I_THRESH = 24000 << 8 158 */ 159 double pcnt_intra_low; 160 /*! 161 * Percentage of blocks that have intra error < inter error and intra error < 162 * LOW_I_THRESH but inter error >= LOW_I_THRESH LOW_I_THRESH 163 * - bit_depth 8: LOW_I_THRESH = 24000 164 * - bit_depth 10: LOW_I_THRESH = 24000 << 4 165 * - bit_depth 12: LOW_I_THRESH = 24000 << 8 166 */ 167 double pcnt_intra_high; 168 /*! 169 * Percentage of blocks that have almost no intra error residual 170 * (i.e. are in effect completely flat and untextured in the intra 171 * domain). In natural videos this is uncommon, but it is much more 172 * common in animations, graphics and screen content, so may be used 173 * as a signal to detect these types of content. 174 */ 175 double intra_skip_pct; 176 /*! 177 * Percentage of blocks that have intra error < SMOOTH_INTRA_THRESH 178 * - bit_depth 8: SMOOTH_INTRA_THRESH = 4000 179 * - bit_depth 10: SMOOTH_INTRA_THRESH = 4000 << 4 180 * - bit_depth 12: SMOOTH_INTRA_THRESH = 4000 << 8 181 */ 182 double intra_smooth_pct; 183 /*! 184 * Image mask rows top and bottom. 185 */ 186 double inactive_zone_rows; 187 /*! 188 * Image mask columns at left and right edges. 189 */ 190 double inactive_zone_cols; 191 /*! 192 * Mean of row motion vectors. 193 */ 194 double MVr; 195 /*! 196 * Mean of absolute value of row motion vectors. 197 */ 198 double mvr_abs; 199 /*! 200 * Mean of column motion vectors. 201 */ 202 double MVc; 203 /*! 204 * Mean of absolute value of column motion vectors. 205 */ 206 double mvc_abs; 207 /*! 208 * Variance of row motion vectors. 209 */ 210 double MVrv; 211 /*! 212 * Variance of column motion vectors. 213 */ 214 double MVcv; 215 /*! 216 * Value in range [-1,1] indicating fraction of row and column motion vectors 217 * that point inwards (negative MV value) or outwards (positive MV value). 218 * For example, value of 1 indicates, all row/column MVs are inwards. 219 */ 220 double mv_in_out_count; 221 /*! 222 * Duration of the frame / collection of frames. 223 */ 224 double duration; 225 /*! 226 * 1.0 if stats are for a single frame, or 227 * number of frames whose stats are accumulated. 228 */ 229 double count; 230 } vpx_rc_frame_stats_t; 231 232 /*!\brief Collection of first pass frame stats 233 */ 234 typedef struct vpx_rc_firstpass_stats { 235 /*! 236 * Pointer to first pass frame stats. 237 * The pointed array of vpx_rc_frame_stats_t should have length equal to 238 * number of show frames in the video. 239 */ 240 vpx_rc_frame_stats_t *frame_stats; 241 /*! 242 * Number of show frames in the video. 243 */ 244 int num_frames; 245 } vpx_rc_firstpass_stats_t; 246 247 /*!\brief Encode config sent to external rate control model 248 */ 249 typedef struct vpx_rc_config { 250 int frame_width; /**< frame width */ 251 int frame_height; /**< frame height */ 252 int show_frame_count; /**< number of visible frames in the video */ 253 /*! 254 * Target bitrate in kilobytes per second 255 */ 256 int target_bitrate_kbps; 257 int frame_rate_num; /**< numerator of frame rate */ 258 int frame_rate_den; /**< denominator of frame rate */ 259 } vpx_rc_config_t; 260 261 /*!\brief Create an external rate control model callback prototype 262 * 263 * This callback is invoked by the encoder to create an external rate control 264 * model. 265 * 266 * \param[in] priv Callback's private data 267 * \param[in] ratectrl_config Pointer to vpx_rc_config_t 268 * \param[out] rate_ctrl_model_pt Pointer to vpx_rc_model_t 269 */ 270 typedef vpx_rc_status_t (*vpx_rc_create_model_cb_fn_t)( 271 void *priv, const vpx_rc_config_t *ratectrl_config, 272 vpx_rc_model_t *rate_ctrl_model_pt); 273 274 /*!\brief Send first pass stats to the external rate control model callback 275 * prototype 276 * 277 * This callback is invoked by the encoder to send first pass stats to the 278 * external rate control model. 279 * 280 * \param[in] rate_ctrl_model rate control model 281 * \param[in] first_pass_stats first pass stats 282 */ 283 typedef vpx_rc_status_t (*vpx_rc_send_firstpass_stats_cb_fn_t)( 284 vpx_rc_model_t rate_ctrl_model, 285 const vpx_rc_firstpass_stats_t *first_pass_stats); 286 287 /*!\brief Receive encode frame decision callback prototype 288 * 289 * This callback is invoked by the encoder to receive encode frame decision from 290 * the external rate control model. 291 * 292 * \param[in] rate_ctrl_model rate control model 293 * \param[in] encode_frame_info information of the coding frame 294 * \param[out] frame_decision encode decision of the coding frame 295 */ 296 typedef vpx_rc_status_t (*vpx_rc_get_encodeframe_decision_cb_fn_t)( 297 vpx_rc_model_t rate_ctrl_model, 298 const vpx_rc_encodeframe_info_t *encode_frame_info, 299 vpx_rc_encodeframe_decision_t *frame_decision); 300 301 /*!\brief Update encode frame result callback prototype 302 * 303 * This callback is invoked by the encoder to update encode frame result to the 304 * external rate control model. 305 * 306 * \param[in] rate_ctrl_model rate control model 307 * \param[out] encode_frame_result encode result of the coding frame 308 */ 309 typedef vpx_rc_status_t (*vpx_rc_update_encodeframe_result_cb_fn_t)( 310 vpx_rc_model_t rate_ctrl_model, 311 const vpx_rc_encodeframe_result_t *encode_frame_result); 312 313 /*!\brief Delete the external rate control model callback prototype 314 * 315 * This callback is invoked by the encoder to delete the external rate control 316 * model. 317 * 318 * \param[in] rate_ctrl_model rate control model 319 */ 320 typedef vpx_rc_status_t (*vpx_rc_delete_model_cb_fn_t)( 321 vpx_rc_model_t rate_ctrl_model); 322 323 /*!\brief Callback function set for external rate control. 324 * 325 * The user can enable external rate control by registering 326 * a set of callback functions with the codec control flag 327 * VP9E_SET_EXTERNAL_RATE_CONTROL. 328 */ 329 typedef struct vpx_rc_funcs { 330 /*! 331 * Create an external rate control model. 332 */ 333 vpx_rc_create_model_cb_fn_t create_model; 334 /*! 335 * Send first pass stats to the external rate control model. 336 */ 337 vpx_rc_send_firstpass_stats_cb_fn_t send_firstpass_stats; 338 /*! 339 * Get encodeframe decision from the external rate control model. 340 */ 341 vpx_rc_get_encodeframe_decision_cb_fn_t get_encodeframe_decision; 342 /*! 343 * Update encodeframe result to the external rate control model. 344 */ 345 vpx_rc_update_encodeframe_result_cb_fn_t update_encodeframe_result; 346 /*! 347 * Delete the external rate control model. 348 */ 349 vpx_rc_delete_model_cb_fn_t delete_model; 350 /*! 351 * Private data for the external rate control model. 352 */ 353 void *priv; 354 } vpx_rc_funcs_t; 355 356 #ifdef __cplusplus 357 } // extern "C" 358 #endif 359 360 #endif // VPX_VPX_VPX_EXT_RATECTRL_H_ 361