git.sesse.net Git - ffmpeg/blob - libavutil/film_grain_params.h

   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
  24 enum 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 /**
  34  * This structure describes how to handle film grain synthesis for AOM codecs.
  35  *
  36  * @note The struct must be allocated as part of AVFilmGrainParams using
  37  *       av_film_grain_params_alloc(). Its size is not a part of the public ABI.
  38  */
  39 typedef struct AVFilmGrainAOMParams {
  40     /**
  41      * Number of points, and the scale and value for each point of the
  42      * piecewise linear scaling function for the uma plane.
  43      */
  44     int num_y_points;
  45     uint8_t y_points[14][2 /* value, scaling */];
  46
  47     /**
  48      * Signals whether to derive the chroma scaling function from the luma.
  49      * Not equivalent to copying the luma values and scales.
  50      */
  51     int chroma_scaling_from_luma;
  52
  53     /**
  54      * If chroma_scaling_from_luma is set to 0, signals the chroma scaling
  55      * function parameters.
  56      */
  57     int num_uv_points[2 /* cb, cr */];
  58     uint8_t uv_points[2 /* cb, cr */][10][2 /* value, scaling */];
  59
  60     /**
  61      * Specifies the shift applied to the chroma components. For AV1, its within
  62      * [8; 11] and determines the range and quantization of the film grain.
  63      */
  64     int scaling_shift;
  65
  66     /**
  67      * Specifies the auto-regression lag.
  68      */
  69     int ar_coeff_lag;
  70
  71     /**
  72      * Luma auto-regression coefficients. The number of coefficients is given by
  73      * 2 * ar_coeff_lag * (ar_coeff_lag + 1).
  74      */
  75     int8_t ar_coeffs_y[24];
  76
  77     /**
  78      * Chroma auto-regression coefficients. The number of coefficients is given by
  79      * 2 * ar_coeff_lag * (ar_coeff_lag + 1) + !!num_y_points.
  80      */
  81     int8_t ar_coeffs_uv[2 /* cb, cr */][25];
  82
  83     /**
  84      * Specifies the range of the auto-regressive coefficients. Values of 6,
  85      * 7, 8 and so on represent a range of [-2, 2), [-1, 1), [-0.5, 0.5) and
  86      * so on. For AV1 must be between 6 and 9.
  87      */
  88     int ar_coeff_shift;
  89
  90     /**
  91      * Signals the down shift applied to the generated gaussian numbers during
  92      * synthesis.
  93      */
  94     int grain_scale_shift;
  95
  96     /**
  97      * Specifies the luma/chroma multipliers for the index to the component
  98      * scaling function.
  99      */
 100     int uv_mult[2 /* cb, cr */];
 101     int uv_mult_luma[2 /* cb, cr */];
 102
 103     /**
 104      * Offset used for component scaling function. For AV1 its a 9-bit value
 105      * with a range [-256, 255]
 106      */
 107     int uv_offset[2 /* cb, cr */];
 108
 109     /**
 110      * Signals whether to overlap film grain blocks.
 111      */
 112     int overlap_flag;
 113
 114     /**
 115      * Signals to clip to limited color levels after film grain application.
 116      */
 117     int limit_output_range;
 118 } AVFilmGrainAOMParams;
 119
 120 /**
 121  * This structure describes how to handle film grain synthesis in video
 122  * for specific codecs. Must be present on every frame where film grain is
 123  * meant to be synthesised for correct presentation.
 124  *
 125  * @note The struct must be allocated with av_film_grain_params_alloc() and
 126  *       its size is not a part of the public ABI.
 127  */
 128 typedef struct AVFilmGrainParams {
 129     /**
 130      * Specifies the codec for which this structure is valid.
 131      */
 132     enum AVFilmGrainParamsType type;
 133
 134     /**
 135      * Seed to use for the synthesis process, if the codec allows for it.
 136      */
 137     uint64_t seed;
 138
 139     /**
 140      * Additional fields may be added both here and in any structure included.
 141      * If a codec's film grain structure differs slightly over another
 142      * codec's, fields within may change meaning depending on the type.
 143      */
 144     union {
 145         AVFilmGrainAOMParams aom;
 146     } codec;
 147 } AVFilmGrainParams;
 148
 149 /**
 150  * Allocate an AVFilmGrainParams structure and set its fields to
 151  * default values. The resulting struct can be freed using av_freep().
 152  * If size is not NULL it will be set to the number of bytes allocated.
 153  *
 154  * @return An AVFilmGrainParams filled with default values or NULL
 155  *         on failure.
 156  */
 157 AVFilmGrainParams *av_film_grain_params_alloc(size_t *size);
 158
 159 /**
 160  * Allocate a complete AVFilmGrainParams and add it to the frame.
 161  *
 162  * @param frame The frame which side data is added to.
 163  *
 164  * @return The AVFilmGrainParams structure to be filled by caller.
 165  */
 166 AVFilmGrainParams *av_film_grain_params_create_side_data(AVFrame *frame);
 167
 168 #endif /* AVUTIL_FILM_GRAIN_PARAMS_H */