FFmpeg 7.1.1
Loading...
Searching...
No Matches
film_grain_params.h
Go to the documentation of this file.
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
26
27 /**
28 * The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom)
29 */
31
32 /**
33 * The union is valid when interpreted as AVFilmGrainH274Params (codec.h274)
34 */
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 */
44typedef 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 */
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 */
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 */
70
71 /**
72 * Specifies the auto-regression lag.
73 */
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 */
94
95 /**
96 * Signals the down shift applied to the generated gaussian numbers during
97 * synthesis.
98 */
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 */
118
119 /**
120 * Signals to clip to limited color levels after film grain application.
121 */
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 */
132typedef struct AVFilmGrainH274Params {
133 /**
134 * Specifies the film grain simulation mode.
135 * 0 = Frequency filtering, 1 = Auto-regression
136 */
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 */
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 */
159 int bit_depth_chroma;
160
161 /**
162 * Specifies the video signal characteristics.
163 *
164 * @deprecated use AVFilmGrainParams.color_{range,primaries,trc,space}.
165 */
167 enum AVColorRange color_range;
169 enum AVColorPrimaries color_primaries;
171 enum AVColorTransferCharacteristic color_trc;
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 */
183
184 /**
185 * Specifies a scale factor used in the film grain characterization equations.
186 */
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 */];
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 */
238typedef struct AVFilmGrainParams {
239 /**
240 * Specifies the codec for which this structure is valid.
241 */
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 {
263
264 /**
265 * Intended display resolution. May be 0 if the codec does not specify
266 * any restrictions.
267 */
268
270
271 /**
272 * Intended subsampling ratio, or 0 for luma-only streams.
273 */
275
276 /**
277 * Intended video signal characteristics.
278 */
283
284 /**
285 * Intended bit depth, or 0 for unknown/unspecified.
286 */
289
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 */
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 */
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 */
321
322#endif /* AVUTIL_FILM_GRAIN_PARAMS_H */
#define attribute_deprecated
Definition attributes.h:100
static AVFrame * frame
AVFilmGrainParamsType
@ AV_FILM_GRAIN_PARAMS_H274
The union is valid when interpreted as AVFilmGrainH274Params (codec.h274)
@ AV_FILM_GRAIN_PARAMS_AV1
The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom)
@ AV_FILM_GRAIN_PARAMS_NONE
AVFilmGrainParams * av_film_grain_params_create_side_data(AVFrame *frame)
Allocate a complete AVFilmGrainParams and add it to the frame.
const AVFilmGrainParams * av_film_grain_params_select(const AVFrame *frame)
Select the most appropriate film grain parameters set for the frame, taking into account the frame's ...
AVFilmGrainParams * av_film_grain_params_alloc(size_t *size)
Allocate an AVFilmGrainParams structure and set its fields to default values.
reference-counted frame API
AVColorRange
Visual content value range.
Definition pixfmt.h:651
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition pixfmt.h:555
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition pixfmt.h:580
AVColorSpace
YUV colorspace type.
Definition pixfmt.h:609
This structure describes how to handle film grain synthesis for AOM codecs.
int chroma_scaling_from_luma
Signals whether to derive the chroma scaling function from the luma.
int limit_output_range
Signals to clip to limited color levels after film grain application.
int scaling_shift
Specifies the shift applied to the chroma components.
int grain_scale_shift
Signals the down shift applied to the generated gaussian numbers during synthesis.
int num_uv_points[2]
If chroma_scaling_from_luma is set to 0, signals the chroma scaling function parameters.
int overlap_flag
Signals whether to overlap film grain blocks.
int ar_coeff_lag
Specifies the auto-regression lag.
int uv_offset[2]
Offset used for component scaling function.
int ar_coeff_shift
Specifies the range of the auto-regressive coefficients.
uint8_t uv_points[2][10][2]
int8_t ar_coeffs_uv[2][25]
Chroma auto-regression coefficients.
int uv_mult[2]
Specifies the luma/chroma multipliers for the index to the component scaling function.
int8_t ar_coeffs_y[24]
Luma auto-regression coefficients.
int num_y_points
Number of points, and the scale and value for each point of the piecewise linear scaling function for...
This structure describes how to handle film grain synthesis for codecs using the ITU-T H....
uint8_t intensity_interval_upper_bound[3][256]
Specifies the upper bound of each intensity interval for which the set of model values applies for th...
int blending_mode_id
Specifies the blending mode used to blend the simulated film grain with the decoded images.
uint8_t intensity_interval_lower_bound[3][256]
Specifies the lower ounds of each intensity interval for whichthe set of model values applies for the...
int log2_scale_factor
Specifies a scale factor used in the film grain characterization equations.
int16_t comp_model_value[3][256][6]
Specifies the model values for the component for each intensity interval.
int model_id
Specifies the film grain simulation mode.
int component_model_present[3]
Indicates if the modelling of film grain for a given component is present.
uint16_t num_intensity_intervals[3]
Specifies the number of intensity intervals for which a specific set of model values has been estimat...
uint8_t num_model_values[3]
Specifies the number of model values present for each intensity interval in which the film grain has ...
This structure describes how to handle film grain synthesis in video for specific codecs.
enum AVColorPrimaries color_primaries
AVFilmGrainAOMParams aom
AVFilmGrainH274Params h274
enum AVColorRange color_range
Intended video signal characteristics.
int subsampling_x
Intended subsampling ratio, or 0 for luma-only streams.
int bit_depth_luma
Intended bit depth, or 0 for unknown/unspecified.
enum AVFilmGrainParamsType type
Specifies the codec for which this structure is valid.
int width
Intended display resolution.
uint64_t seed
Seed to use for the synthesis process, if the codec allows for it.
enum AVColorTransferCharacteristic color_trc
union AVFilmGrainParams::@15 codec
Additional fields may be added both here and in any structure included.
enum AVColorSpace color_space
This structure describes decoded (raw) audio or video data.
Definition frame.h:389