FFmpeg
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  */
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  */
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  */
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  */
152 
153  /**
154  * Specifies the bit depth used for the chroma components.
155  *
156  * @deprecated use AVFilmGrainParams.bit_depth_chroma.
157  */
160 
161  /**
162  * Specifies the video signal characteristics.
163  *
164  * @deprecated use AVFilmGrainParams.color_{range,primaries,trc,space}.
165  */
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  */
238 typedef 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 {
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  */
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 */
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:580
AVFilmGrainParams::bit_depth_luma
int bit_depth_luma
Intended bit depth, or 0 for unknown/unspecified.
Definition: film_grain_params.h:287
AVFilmGrainH274Params::color_range
attribute_deprecated enum AVColorRange color_range
Specifies the video signal characteristics.
Definition: film_grain_params.h:167
AVFilmGrainAOMParams::uv_points
uint8_t uv_points[2][10][2]
Definition: film_grain_params.h:63
AVFilmGrainH274Params::blending_mode_id
int blending_mode_id
Specifies the blending mode used to blend the simulated film grain with the decoded images.
Definition: film_grain_params.h:182
AVFilmGrainParams::aom
AVFilmGrainAOMParams aom
Definition: film_grain_params.h:260
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:375
av_film_grain_params_alloc
AVFilmGrainParams * av_film_grain_params_alloc(size_t *size)
Allocate an AVFilmGrainParams structure and set its fields to default values.
Definition: film_grain_params.c:22
AVFilmGrainParams::codec
union AVFilmGrainParams::@356 codec
Additional fields may be added both here and in any structure included.
av_film_grain_params_select
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 ...
Definition: film_grain_params.c:52
AVFilmGrainParams::color_space
enum AVColorSpace color_space
Definition: film_grain_params.h:282
AVColorPrimaries
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:555
AVFilmGrainParams::color_trc
enum AVColorTransferCharacteristic color_trc
Definition: film_grain_params.h:281
AVFilmGrainParams::seed
uint64_t seed
Seed to use for the synthesis process, if the codec allows for it.
Definition: film_grain_params.h:250
AVFilmGrainAOMParams::grain_scale_shift
int grain_scale_shift
Signals the down shift applied to the generated gaussian numbers during synthesis.
Definition: film_grain_params.h:99
AVFilmGrainH274Params::bit_depth_chroma
attribute_deprecated int bit_depth_chroma
Specifies the bit depth used for the chroma components.
Definition: film_grain_params.h:159
AVFilmGrainAOMParams::limit_output_range
int limit_output_range
Signals to clip to limited color levels after film grain application.
Definition: film_grain_params.h:122
AVFilmGrainAOMParams::num_y_points
int num_y_points
Number of points, and the scale and value for each point of the piecewise linear scaling function for...
Definition: film_grain_params.h:49
AVFilmGrainAOMParams
This structure describes how to handle film grain synthesis for AOM codecs.
Definition: film_grain_params.h:44
AVFilmGrainH274Params::intensity_interval_upper_bound
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...
Definition: film_grain_params.h:216
AVFilmGrainParams::bit_depth_chroma
int bit_depth_chroma
Definition: film_grain_params.h:288
av_film_grain_params_create_side_data
AVFilmGrainParams * av_film_grain_params_create_side_data(AVFrame *frame)
Allocate a complete AVFilmGrainParams and add it to the frame.
Definition: film_grain_params.c:32
AVFilmGrainParams::width
int width
Intended display resolution.
Definition: film_grain_params.h:269
AVFilmGrainH274Params::comp_model_value
int16_t comp_model_value[3][256][6]
Specifies the model values for the component for each intensity interval.
Definition: film_grain_params.h:227
AV_FILM_GRAIN_PARAMS_NONE
@ AV_FILM_GRAIN_PARAMS_NONE
Definition: film_grain_params.h:25
AVFilmGrainH274Params::model_id
int model_id
Specifies the film grain simulation mode.
Definition: film_grain_params.h:137
AVFilmGrainAOMParams::uv_mult_luma
int uv_mult_luma[2]
Definition: film_grain_params.h:106
AVFilmGrainH274Params::color_trc
attribute_deprecated enum AVColorTransferCharacteristic color_trc
Definition: film_grain_params.h:171
AVFilmGrainParams::subsampling_x
int subsampling_x
Intended subsampling ratio, or 0 for luma-only streams.
Definition: film_grain_params.h:274
AVFilmGrainAOMParams::num_uv_points
int num_uv_points[2]
If chroma_scaling_from_luma is set to 0, signals the chroma scaling function parameters.
Definition: film_grain_params.h:62
AVFilmGrainH274Params::color_primaries
attribute_deprecated enum AVColorPrimaries color_primaries
Definition: film_grain_params.h:169
AVFilmGrainH274Params::component_model_present
int component_model_present[3]
Indicates if the modelling of film grain for a given component is present.
Definition: film_grain_params.h:192
size
int size
Definition: twinvq_data.h:10344
AVFilmGrainParams
This structure describes how to handle film grain synthesis in video for specific codecs.
Definition: film_grain_params.h:238
frame.h
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
AVFilmGrainParams::h274
AVFilmGrainH274Params h274
Definition: film_grain_params.h:261
AVFilmGrainAOMParams::ar_coeffs_y
int8_t ar_coeffs_y[24]
Luma auto-regression coefficients.
Definition: film_grain_params.h:80
AVFilmGrainParams::color_primaries
enum AVColorPrimaries color_primaries
Definition: film_grain_params.h:280
AVFilmGrainH274Params
This structure describes how to handle film grain synthesis for codecs using the ITU-T H....
Definition: film_grain_params.h:132
AVFilmGrainH274Params::num_intensity_intervals
uint16_t num_intensity_intervals[3]
Specifies the number of intensity intervals for which a specific set of model values has been estimat...
Definition: film_grain_params.h:198
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:609
AVFilmGrainParams::subsampling_y
int subsampling_y
Definition: film_grain_params.h:274
AVFilmGrainParamsType
AVFilmGrainParamsType
Definition: film_grain_params.h:24
AVFilmGrainAOMParams::scaling_shift
int scaling_shift
Specifies the shift applied to the chroma components.
Definition: film_grain_params.h:69
AVFilmGrainH274Params::intensity_interval_lower_bound
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...
Definition: film_grain_params.h:210
AVFilmGrainParams::height
int height
Definition: film_grain_params.h:269
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
AVFilmGrainH274Params::color_space
attribute_deprecated enum AVColorSpace color_space
Definition: film_grain_params.h:173
AVFilmGrainAOMParams::ar_coeff_lag
int ar_coeff_lag
Specifies the auto-regression lag.
Definition: film_grain_params.h:74
AV_FILM_GRAIN_PARAMS_H274
@ AV_FILM_GRAIN_PARAMS_H274
The union is valid when interpreted as AVFilmGrainH274Params (codec.h274)
Definition: film_grain_params.h:35
AVFilmGrainAOMParams::y_points
uint8_t y_points[14][2]
Definition: film_grain_params.h:50
AVFilmGrainAOMParams::uv_offset
int uv_offset[2]
Offset used for component scaling function.
Definition: film_grain_params.h:112
AVFilmGrainH274Params::log2_scale_factor
int log2_scale_factor
Specifies a scale factor used in the film grain characterization equations.
Definition: film_grain_params.h:187
AVFilmGrainAOMParams::uv_mult
int uv_mult[2]
Specifies the luma/chroma multipliers for the index to the component scaling function.
Definition: film_grain_params.h:105
AVFilmGrainH274Params::bit_depth_luma
attribute_deprecated int bit_depth_luma
TODO: On this ABI bump, please also re-order the fields in AVFilmGrainParams (see below)
Definition: film_grain_params.h:151
AVFilmGrainH274Params::num_model_values
uint8_t num_model_values[3]
Specifies the number of model values present for each intensity interval in which the film grain has ...
Definition: film_grain_params.h:204
AVFilmGrainParams::color_range
enum AVColorRange color_range
Intended video signal characteristics.
Definition: film_grain_params.h:279
AVFilmGrainAOMParams::overlap_flag
int overlap_flag
Signals whether to overlap film grain blocks.
Definition: film_grain_params.h:117
AVFilmGrainAOMParams::chroma_scaling_from_luma
int chroma_scaling_from_luma
Signals whether to derive the chroma scaling function from the luma.
Definition: film_grain_params.h:56
AVColorRange
AVColorRange
Visual content value range.
Definition: pixfmt.h:648
AV_FILM_GRAIN_PARAMS_AV1
@ AV_FILM_GRAIN_PARAMS_AV1
The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom)
Definition: film_grain_params.h:30
AVFilmGrainParams::type
enum AVFilmGrainParamsType type
Specifies the codec for which this structure is valid.
Definition: film_grain_params.h:242
AVFilmGrainAOMParams::ar_coeff_shift
int ar_coeff_shift
Specifies the range of the auto-regressive coefficients.
Definition: film_grain_params.h:93
AVFilmGrainAOMParams::ar_coeffs_uv
int8_t ar_coeffs_uv[2][25]
Chroma auto-regression coefficients.
Definition: film_grain_params.h:86