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  /**
140  * Specifies the bit depth used for the luma component.
141  */
143 
144  /**
145  * Specifies the bit depth used for the chroma components.
146  */
148 
153 
154  /**
155  * Specifies the blending mode used to blend the simulated film grain
156  * with the decoded images.
157  *
158  * 0 = Additive, 1 = Multiplicative
159  */
161 
162  /**
163  * Specifies a scale factor used in the film grain characterization equations.
164  */
166 
167  /**
168  * Indicates if the modelling of film grain for a given component is present.
169  */
170  int component_model_present[3 /* y, cb, cr */];
171 
172  /**
173  * Specifies the number of intensity intervals for which a specific set of
174  * model values has been estimated, with a range of [1, 256].
175  */
176  uint16_t num_intensity_intervals[3 /* y, cb, cr */];
177 
178  /**
179  * Specifies the number of model values present for each intensity interval
180  * in which the film grain has been modelled, with a range of [1, 6].
181  */
182  uint8_t num_model_values[3 /* y, cb, cr */];
183 
184  /**
185  * Specifies the lower ounds of each intensity interval for whichthe set of
186  * model values applies for the component.
187  */
188  uint8_t intensity_interval_lower_bound[3 /* y, cb, cr */][256 /* intensity interval */];
189 
190  /**
191  * Specifies the upper bound of each intensity interval for which the set of
192  * model values applies for the component.
193  */
194  uint8_t intensity_interval_upper_bound[3 /* y, cb, cr */][256 /* intensity interval */];
195 
196  /**
197  * Specifies the model values for the component for each intensity interval.
198  * - When model_id == 0, the following applies:
199  * For comp_model_value[y], the range of values is [0, 2^bit_depth_luma - 1]
200  * For comp_model_value[cb..cr], the range of values is [0, 2^bit_depth_chroma - 1]
201  * - Otherwise, the following applies:
202  * For comp_model_value[y], the range of values is [-2^(bit_depth_luma - 1), 2^(bit_depth_luma - 1) - 1]
203  * For comp_model_value[cb..cr], the range of values is [-2^(bit_depth_chroma - 1), 2^(bit_depth_chroma - 1) - 1]
204  */
205  int16_t comp_model_value[3 /* y, cb, cr */][256 /* intensity interval */][6 /* model value */];
207 
208 /**
209  * This structure describes how to handle film grain synthesis in video
210  * for specific codecs. Must be present on every frame where film grain is
211  * meant to be synthesised for correct presentation.
212  *
213  * @note The struct must be allocated with av_film_grain_params_alloc() and
214  * its size is not a part of the public ABI.
215  */
216 typedef struct AVFilmGrainParams {
217  /**
218  * Specifies the codec for which this structure is valid.
219  */
221 
222  /**
223  * Seed to use for the synthesis process, if the codec allows for it.
224  *
225  * @note For H.264, this refers to `pic_offset` as defined in
226  * SMPTE RDD 5-2006.
227  */
228  uint64_t seed;
229 
230  /**
231  * Additional fields may be added both here and in any structure included.
232  * If a codec's film grain structure differs slightly over another
233  * codec's, fields within may change meaning depending on the type.
234  */
235  union {
238  } codec;
240 
241 /**
242  * Allocate an AVFilmGrainParams structure and set its fields to
243  * default values. The resulting struct can be freed using av_freep().
244  * If size is not NULL it will be set to the number of bytes allocated.
245  *
246  * @return An AVFilmGrainParams filled with default values or NULL
247  * on failure.
248  */
250 
251 /**
252  * Allocate a complete AVFilmGrainParams and add it to the frame.
253  *
254  * @param frame The frame which side data is added to.
255  *
256  * @return The AVFilmGrainParams structure to be filled by caller.
257  */
259 
260 #endif /* AVUTIL_FILM_GRAIN_PARAMS_H */
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:496
AVFilmGrainH274Params::color_space
enum AVColorSpace color_space
Definition: film_grain_params.h:152
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:160
AVFilmGrainParams::aom
AVFilmGrainAOMParams aom
Definition: film_grain_params.h:236
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:325
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:21
AVFilmGrainH274Params::color_range
enum AVColorRange color_range
Definition: film_grain_params.h:149
AVColorPrimaries
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:471
AVFilmGrainParams::seed
uint64_t seed
Seed to use for the synthesis process, if the codec allows for it.
Definition: film_grain_params.h:228
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
AVFilmGrainParams::codec
union AVFilmGrainParams::@301 codec
Additional fields may be added both here and in any structure included.
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:194
AVFilmGrainH274Params::bit_depth_luma
int bit_depth_luma
Specifies the bit depth used for the luma component.
Definition: film_grain_params.h:142
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:31
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:205
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
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::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:170
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:216
frame.h
AVFilmGrainParams::h274
AVFilmGrainH274Params h274
Definition: film_grain_params.h:237
AVFilmGrainAOMParams::ar_coeffs_y
int8_t ar_coeffs_y[24]
Luma auto-regression coefficients.
Definition: film_grain_params.h:80
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:176
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:525
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::color_primaries
enum AVColorPrimaries color_primaries
Definition: film_grain_params.h:150
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:188
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
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:165
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::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:182
AVFilmGrainAOMParams::overlap_flag
int overlap_flag
Signals whether to overlap film grain blocks.
Definition: film_grain_params.h:117
AVFilmGrainH274Params::color_trc
enum AVColorTransferCharacteristic color_trc
Definition: film_grain_params.h:151
AVFilmGrainH274Params::bit_depth_chroma
int bit_depth_chroma
Specifies the bit depth used for the chroma components.
Definition: film_grain_params.h:147
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:564
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:220
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