film_grain_params.h (10259B)
1 /* 2 * This file is part of FFmpeg. 3 * 4 * FFmpeg is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * FFmpeg is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with FFmpeg; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 17 */ 18 19 #ifndef AVUTIL_FILM_GRAIN_PARAMS_H 20 #define AVUTIL_FILM_GRAIN_PARAMS_H 21 22 #include "frame.h" 23 24 enum AVFilmGrainParamsType { 25 AV_FILM_GRAIN_PARAMS_NONE = 0, 26 27 /** 28 * The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom) 29 */ 30 AV_FILM_GRAIN_PARAMS_AV1, 31 32 /** 33 * The union is valid when interpreted as AVFilmGrainH274Params (codec.h274) 34 */ 35 AV_FILM_GRAIN_PARAMS_H274, 36 }; 37 38 /** 39 * This structure describes how to handle film grain synthesis for AOM codecs. 40 * 41 * @note The struct must be allocated as part of AVFilmGrainParams using 42 * av_film_grain_params_alloc(). Its size is not a part of the public ABI. 43 */ 44 typedef struct AVFilmGrainAOMParams { 45 /** 46 * Number of points, and the scale and value for each point of the 47 * piecewise linear scaling function for the uma plane. 48 */ 49 int num_y_points; 50 uint8_t y_points[14][2 /* value, scaling */]; 51 52 /** 53 * Signals whether to derive the chroma scaling function from the luma. 54 * Not equivalent to copying the luma values and scales. 55 */ 56 int chroma_scaling_from_luma; 57 58 /** 59 * If chroma_scaling_from_luma is set to 0, signals the chroma scaling 60 * function parameters. 61 */ 62 int num_uv_points[2 /* cb, cr */]; 63 uint8_t uv_points[2 /* cb, cr */][10][2 /* value, scaling */]; 64 65 /** 66 * Specifies the shift applied to the chroma components. For AV1, its within 67 * [8; 11] and determines the range and quantization of the film grain. 68 */ 69 int scaling_shift; 70 71 /** 72 * Specifies the auto-regression lag. 73 */ 74 int ar_coeff_lag; 75 76 /** 77 * Luma auto-regression coefficients. The number of coefficients is given by 78 * 2 * ar_coeff_lag * (ar_coeff_lag + 1). 79 */ 80 int8_t ar_coeffs_y[24]; 81 82 /** 83 * Chroma auto-regression coefficients. The number of coefficients is given by 84 * 2 * ar_coeff_lag * (ar_coeff_lag + 1) + !!num_y_points. 85 */ 86 int8_t ar_coeffs_uv[2 /* cb, cr */][25]; 87 88 /** 89 * Specifies the range of the auto-regressive coefficients. Values of 6, 90 * 7, 8 and so on represent a range of [-2, 2), [-1, 1), [-0.5, 0.5) and 91 * so on. For AV1 must be between 6 and 9. 92 */ 93 int ar_coeff_shift; 94 95 /** 96 * Signals the down shift applied to the generated gaussian numbers during 97 * synthesis. 98 */ 99 int grain_scale_shift; 100 101 /** 102 * Specifies the luma/chroma multipliers for the index to the component 103 * scaling function. 104 */ 105 int uv_mult[2 /* cb, cr */]; 106 int uv_mult_luma[2 /* cb, cr */]; 107 108 /** 109 * Offset used for component scaling function. For AV1 its a 9-bit value 110 * with a range [-256, 255] 111 */ 112 int uv_offset[2 /* cb, cr */]; 113 114 /** 115 * Signals whether to overlap film grain blocks. 116 */ 117 int overlap_flag; 118 119 /** 120 * Signals to clip to limited color levels after film grain application. 121 */ 122 int limit_output_range; 123 } AVFilmGrainAOMParams; 124 125 /** 126 * This structure describes how to handle film grain synthesis for codecs using 127 * the ITU-T H.274 Versatile suplemental enhancement information message. 128 * 129 * @note The struct must be allocated as part of AVFilmGrainParams using 130 * av_film_grain_params_alloc(). Its size is not a part of the public ABI. 131 */ 132 typedef struct AVFilmGrainH274Params { 133 /** 134 * Specifies the film grain simulation mode. 135 * 0 = Frequency filtering, 1 = Auto-regression 136 */ 137 int model_id; 138 139 #if FF_API_H274_FILM_GRAIN_VCS 140 /** 141 * TODO: On this ABI bump, please also re-order the fields in 142 * AVFilmGrainParams (see below) 143 */ 144 145 /** 146 * Specifies the bit depth used for the luma component. 147 * 148 * @deprecated use AVFilmGrainParams.bit_depth_luma. 149 */ 150 attribute_deprecated 151 int bit_depth_luma; 152 153 /** 154 * Specifies the bit depth used for the chroma components. 155 * 156 * @deprecated use AVFilmGrainParams.bit_depth_chroma. 157 */ 158 attribute_deprecated 159 int bit_depth_chroma; 160 161 /** 162 * Specifies the video signal characteristics. 163 * 164 * @deprecated use AVFilmGrainParams.color_{range,primaries,trc,space}. 165 */ 166 attribute_deprecated 167 enum AVColorRange color_range; 168 attribute_deprecated 169 enum AVColorPrimaries color_primaries; 170 attribute_deprecated 171 enum AVColorTransferCharacteristic color_trc; 172 attribute_deprecated 173 enum AVColorSpace color_space; 174 #endif 175 176 /** 177 * Specifies the blending mode used to blend the simulated film grain 178 * with the decoded images. 179 * 180 * 0 = Additive, 1 = Multiplicative 181 */ 182 int blending_mode_id; 183 184 /** 185 * Specifies a scale factor used in the film grain characterization equations. 186 */ 187 int log2_scale_factor; 188 189 /** 190 * Indicates if the modelling of film grain for a given component is present. 191 */ 192 int component_model_present[3 /* y, cb, cr */]; 193 194 /** 195 * Specifies the number of intensity intervals for which a specific set of 196 * model values has been estimated, with a range of [1, 256]. 197 */ 198 uint16_t num_intensity_intervals[3 /* y, cb, cr */]; 199 200 /** 201 * Specifies the number of model values present for each intensity interval 202 * in which the film grain has been modelled, with a range of [1, 6]. 203 */ 204 uint8_t num_model_values[3 /* y, cb, cr */]; 205 206 /** 207 * Specifies the lower ounds of each intensity interval for whichthe set of 208 * model values applies for the component. 209 */ 210 uint8_t intensity_interval_lower_bound[3 /* y, cb, cr */][256 /* intensity interval */]; 211 212 /** 213 * Specifies the upper bound of each intensity interval for which the set of 214 * model values applies for the component. 215 */ 216 uint8_t intensity_interval_upper_bound[3 /* y, cb, cr */][256 /* intensity interval */]; 217 218 /** 219 * Specifies the model values for the component for each intensity interval. 220 * - When model_id == 0, the following applies: 221 * For comp_model_value[y], the range of values is [0, 2^bit_depth_luma - 1] 222 * For comp_model_value[cb..cr], the range of values is [0, 2^bit_depth_chroma - 1] 223 * - Otherwise, the following applies: 224 * For comp_model_value[y], the range of values is [-2^(bit_depth_luma - 1), 2^(bit_depth_luma - 1) - 1] 225 * For comp_model_value[cb..cr], the range of values is [-2^(bit_depth_chroma - 1), 2^(bit_depth_chroma - 1) - 1] 226 */ 227 int16_t comp_model_value[3 /* y, cb, cr */][256 /* intensity interval */][6 /* model value */]; 228 } AVFilmGrainH274Params; 229 230 /** 231 * This structure describes how to handle film grain synthesis in video 232 * for specific codecs. Must be present on every frame where film grain is 233 * meant to be synthesised for correct presentation. 234 * 235 * @note The struct must be allocated with av_film_grain_params_alloc() and 236 * its size is not a part of the public ABI. 237 */ 238 typedef struct AVFilmGrainParams { 239 /** 240 * Specifies the codec for which this structure is valid. 241 */ 242 enum AVFilmGrainParamsType type; 243 244 /** 245 * Seed to use for the synthesis process, if the codec allows for it. 246 * 247 * @note For H.264, this refers to `pic_offset` as defined in 248 * SMPTE RDD 5-2006. 249 */ 250 uint64_t seed; 251 252 /** 253 * Additional fields may be added both here and in any structure included. 254 * If a codec's film grain structure differs slightly over another 255 * codec's, fields within may change meaning depending on the type. 256 * 257 * TODO: Move this to the end of the structure, at the next ABI bump. 258 */ 259 union { 260 AVFilmGrainAOMParams aom; 261 AVFilmGrainH274Params h274; 262 } codec; 263 264 /** 265 * Intended display resolution. May be 0 if the codec does not specify 266 * any restrictions. 267 */ 268 269 int width, height; 270 271 /** 272 * Intended subsampling ratio, or 0 for luma-only streams. 273 */ 274 int subsampling_x, subsampling_y; 275 276 /** 277 * Intended video signal characteristics. 278 */ 279 enum AVColorRange color_range; 280 enum AVColorPrimaries color_primaries; 281 enum AVColorTransferCharacteristic color_trc; 282 enum AVColorSpace color_space; 283 284 /** 285 * Intended bit depth, or 0 for unknown/unspecified. 286 */ 287 int bit_depth_luma; 288 int bit_depth_chroma; 289 290 } AVFilmGrainParams; 291 292 /** 293 * Allocate an AVFilmGrainParams structure and set its fields to 294 * default values. The resulting struct can be freed using av_freep(). 295 * If size is not NULL it will be set to the number of bytes allocated. 296 * 297 * @return An AVFilmGrainParams filled with default values or NULL 298 * on failure. 299 */ 300 AVFilmGrainParams *av_film_grain_params_alloc(size_t *size); 301 302 /** 303 * Allocate a complete AVFilmGrainParams and add it to the frame. 304 * 305 * @param frame The frame which side data is added to. 306 * 307 * @return The AVFilmGrainParams structure to be filled by caller. 308 */ 309 AVFilmGrainParams *av_film_grain_params_create_side_data(AVFrame *frame); 310 311 /** 312 * Select the most appropriate film grain parameters set for the frame, 313 * taking into account the frame's format, resolution and video signal 314 * characteristics. 315 * 316 * @note, for H.274, this may select a film grain parameter set with 317 * greater chroma resolution than the frame. Users should take care to 318 * correctly adjust the chroma grain frequency to the frame. 319 */ 320 const AVFilmGrainParams *av_film_grain_params_select(const AVFrame *frame); 321 322 #endif /* AVUTIL_FILM_GRAIN_PARAMS_H */