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:584
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:340
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:559
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
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
frame
static AVFrame * frame
Definition: demux_decode.c:54
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
AVFilmGrainParams::codec
union AVFilmGrainParams::@351 codec
Additional fields may be added both here and in any structure included.
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:613
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
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:652
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