FFmpeg
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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 blending mode used to blend the simulated film grain
141  * with the decoded images.
142  *
143  * 0 = Additive, 1 = Multiplicative
144  */
146 
147  /**
148  * Specifies a scale factor used in the film grain characterization equations.
149  */
151 
152  /**
153  * Indicates if the modelling of film grain for a given component is present.
154  */
155  int component_model_present[3 /* y, cb, cr */];
156 
157  /**
158  * Specifies the number of intensity intervals for which a specific set of
159  * model values has been estimated, with a range of [1, 256].
160  */
161  uint16_t num_intensity_intervals[3 /* y, cb, cr */];
162 
163  /**
164  * Specifies the number of model values present for each intensity interval
165  * in which the film grain has been modelled, with a range of [1, 6].
166  */
167  uint8_t num_model_values[3 /* y, cb, cr */];
168 
169  /**
170  * Specifies the lower ounds of each intensity interval for whichthe set of
171  * model values applies for the component.
172  */
173  uint8_t intensity_interval_lower_bound[3 /* y, cb, cr */][256 /* intensity interval */];
174 
175  /**
176  * Specifies the upper bound of each intensity interval for which the set of
177  * model values applies for the component.
178  */
179  uint8_t intensity_interval_upper_bound[3 /* y, cb, cr */][256 /* intensity interval */];
180 
181  /**
182  * Specifies the model values for the component for each intensity interval.
183  * - When model_id == 0, the following applies:
184  * For comp_model_value[y], the range of values is [0, 2^bit_depth_luma - 1]
185  * For comp_model_value[cb..cr], the range of values is [0, 2^bit_depth_chroma - 1]
186  * - Otherwise, the following applies:
187  * For comp_model_value[y], the range of values is [-2^(bit_depth_luma - 1), 2^(bit_depth_luma - 1) - 1]
188  * For comp_model_value[cb..cr], the range of values is [-2^(bit_depth_chroma - 1), 2^(bit_depth_chroma - 1) - 1]
189  */
190  int16_t comp_model_value[3 /* y, cb, cr */][256 /* intensity interval */][6 /* model value */];
192 
193 /**
194  * This structure describes how to handle film grain synthesis in video
195  * for specific codecs. Must be present on every frame where film grain is
196  * meant to be synthesised for correct presentation.
197  *
198  * @note The struct must be allocated with av_film_grain_params_alloc() and
199  * its size is not a part of the public ABI.
200  */
201 typedef struct AVFilmGrainParams {
202  /**
203  * Specifies the codec for which this structure is valid.
204  */
206 
207  /**
208  * Seed to use for the synthesis process, if the codec allows for it.
209  *
210  * @note For H.264, this refers to `pic_offset` as defined in
211  * SMPTE RDD 5-2006.
212  */
213  uint64_t seed;
214 
215  /**
216  * Intended display resolution. May be 0 if the codec does not specify
217  * any restrictions.
218  */
219 
220  int width, height;
221 
222  /**
223  * Intended subsampling ratio, or 0 for luma-only streams.
224  */
226 
227  /**
228  * Intended video signal characteristics.
229  */
234 
235  /**
236  * Intended bit depth, or 0 for unknown/unspecified.
237  */
240 
241  /**
242  * Additional fields may be added both here and in any structure included.
243  * If a codec's film grain structure differs slightly over another
244  * codec's, fields within may change meaning depending on the type.
245  */
246  union {
249  } codec;
251 
252 /**
253  * Allocate an AVFilmGrainParams structure and set its fields to
254  * default values. The resulting struct can be freed using av_freep().
255  * If size is not NULL it will be set to the number of bytes allocated.
256  *
257  * @return An AVFilmGrainParams filled with default values or NULL
258  * on failure.
259  */
261 
262 /**
263  * Allocate a complete AVFilmGrainParams and add it to the frame.
264  *
265  * @param frame The frame which side data is added to.
266  *
267  * @return The AVFilmGrainParams structure to be filled by caller.
268  */
270 
271 /**
272  * Select the most appropriate film grain parameters set for the frame,
273  * taking into account the frame's format, resolution and video signal
274  * characteristics.
275  *
276  * @note, for H.274, this may select a film grain parameter set with
277  * greater chroma resolution than the frame. Users should take care to
278  * correctly adjust the chroma grain frequency to the frame.
279  */
281 
282 #endif /* AVUTIL_FILM_GRAIN_PARAMS_H */
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:644
AVFilmGrainParams::bit_depth_luma
int bit_depth_luma
Intended bit depth, or 0 for unknown/unspecified.
Definition: film_grain_params.h:238
AVFilmGrainParams::codec
union AVFilmGrainParams::@455 codec
Additional fields may be added both here and in any structure included.
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:145
AVFilmGrainParams::aom
AVFilmGrainAOMParams aom
Definition: film_grain_params.h:247
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:410
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:23
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:53
AVFilmGrainParams::color_space
enum AVColorSpace color_space
Definition: film_grain_params.h:233
AVColorPrimaries
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:619
AVFilmGrainParams::color_trc
enum AVColorTransferCharacteristic color_trc
Definition: film_grain_params.h:232
AVFilmGrainParams::seed
uint64_t seed
Seed to use for the synthesis process, if the codec allows for it.
Definition: film_grain_params.h:213
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:179
AVFilmGrainParams::bit_depth_chroma
int bit_depth_chroma
Definition: film_grain_params.h:239
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:33
AVFilmGrainParams::width
int width
Intended display resolution.
Definition: film_grain_params.h:220
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:190
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
AVFilmGrainParams::subsampling_x
int subsampling_x
Intended subsampling ratio, or 0 for luma-only streams.
Definition: film_grain_params.h:225
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:155
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:201
frame.h
AVFilmGrainParams::h274
AVFilmGrainH274Params h274
Definition: film_grain_params.h:248
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:231
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:161
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:673
AVFilmGrainParams::subsampling_y
int subsampling_y
Definition: film_grain_params.h:225
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:173
AVFilmGrainParams::height
int height
Definition: film_grain_params.h:220
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:150
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:167
AVFilmGrainParams::color_range
enum AVColorRange color_range
Intended video signal characteristics.
Definition: film_grain_params.h:230
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:715
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:205
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