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
24enum AVFilmGrainParamsType {
25    AV_FILM_GRAIN_PARAMS_NONE = 0,
26
27    /**
28     * The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom)
29     */
30    AV_FILM_GRAIN_PARAMS_AV1,
31
32    /**
33     * The union is valid when interpreted as AVFilmGrainH274Params (codec.h274)
34     */
35    AV_FILM_GRAIN_PARAMS_H274,
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     */
49    int num_y_points;
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     */
56    int chroma_scaling_from_luma;
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     */
69    int scaling_shift;
70
71    /**
72     * Specifies the auto-regression lag.
73     */
74    int ar_coeff_lag;
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     */
93    int ar_coeff_shift;
94
95    /**
96     * Signals the down shift applied to the generated gaussian numbers during
97     * synthesis.
98     */
99    int grain_scale_shift;
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     */
117    int overlap_flag;
118
119    /**
120     * Signals to clip to limited color levels after film grain application.
121     */
122    int limit_output_range;
123} AVFilmGrainAOMParams;
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     */
137    int model_id;
138
139    /**
140     * Specifies the bit depth used for the luma component.
141     */
142    int bit_depth_luma;
143
144    /**
145     * Specifies the bit depth used for the chroma components.
146     */
147    int bit_depth_chroma;
148
149    enum AVColorRange                  color_range;
150    enum AVColorPrimaries              color_primaries;
151    enum AVColorTransferCharacteristic color_trc;
152    enum AVColorSpace                  color_space;
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     */
160    int blending_mode_id;
161
162    /**
163     * Specifies a scale factor used in the film grain characterization equations.
164     */
165    int log2_scale_factor;
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 */];
206} AVFilmGrainH274Params;
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 */
216typedef struct AVFilmGrainParams {
217    /**
218     * Specifies the codec for which this structure is valid.
219     */
220    enum AVFilmGrainParamsType type;
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 {
236        AVFilmGrainAOMParams aom;
237        AVFilmGrainH274Params h274;
238    } codec;
239} AVFilmGrainParams;
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 */
249AVFilmGrainParams *av_film_grain_params_alloc(size_t *size);
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 */
258AVFilmGrainParams *av_film_grain_params_create_side_data(AVFrame *frame);
259
260#endif /* AVUTIL_FILM_GRAIN_PARAMS_H */
261