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_GRAM_PARAMS_NONE = 0,
  26
  27     /**
  28      * The union is valid when interpreted as AVFilmGrainAOMParams (codec.aom)
  29      */
  30     AV_FILM_GRAM_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];
  58     uint8_t uv_points[2][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. The number of coefficients is given by
  68      * 2*ar_coeff_lag(ar_coeff_lag - 1), with an extra one for the chroma.
  69      */
  70     int ar_coeff_lag;
  71
  72     /**
  73      * Luma auto-regression coefficients.
  74      */
  75     int8_t ar_coeffs_y[24];
  76
  77     /**
  78      * Chroma auto-regression coefficients.
  79      */
  80     int8_t ar_coeffs_uv[2][25];
  81
  82     /**
  83      * Specifies the range of the auto-regressive coefficients. Values of 6,
  84      * 7, 8 and so on represent a range of [-2, 2), [-1, 1), [-0.5, 0.5) and
  85      * so on. For AV1 must be between 6 and 9.
  86      */
  87     int ar_coeff_shift;
  88
  89     /**
  90      * Signals the down shift applied to the generated gaussian numbers during
  91      * synthesis.
  92      */
  93     int grain_scale_shift;
  94
  95     /**
  96      * Specifies the luma/chroma multipliers for the index to the component
  97      * scaling function.
  98      */
  99     int uv_mult[2];
 100     int uv_mult_luma[2];
 101
 102     /**
 103      * Offset used for component scaling function. For AV1 its a 9-bit value
 104      * with a range [-256, 255]
 105      */
 106     int uv_offset[2];
 107
 108     /**
 109      * Signals whether to overlap film grain blocks.
 110      */
 111     int overlap_flag;
 112
 113     /**
 114      * Signals to clip to limited color levels after film grain application.
 115      */
 116     int limit_output_range;
 117 } AVFilmGrainAOMParams;
 118
 119 /**
 120  * This structure describes how to handle film grain synthesis in video
 121  * for specific codecs. Must be present on every frame where film grain is
 122  * meant to be synthesised for correct presentation.
 123  *
 124  * @note The struct must be allocated with av_film_grain_params_alloc() and
 125  *       its size is not a part of the public ABI.
 126  */
 127 typedef struct AVFilmGrainParams {
 128     /**
 129      * Specifies the codec for which this structure is valid.
 130      */
 131     enum AVFilmGrainParamsType type;
 132
 133     /**
 134      * Seed to use for the synthesis process, if the codec allows for it.
 135      */
 136     uint64_t seed;
 137
 138     /**
 139      * Additional fields may be added both here and in any structure included.
 140      * If a codec's film grain structure differs slightly over another
 141      * codec's, fields within may change meaning depending on the type.
 142      */
 143     union {
 144         AVFilmGrainAOMParams aom;
 145     } codec;
 146 } AVFilmGrainParams;
 147
 148 /**
 149  * Allocate an AVFilmGrainParams structure and set its fields to
 150  * default values. The resulting struct can be freed using av_freep().
 151  * If size is not NULL it will be set to the number of bytes allocated.
 152  *
 153  * @return An AVFilmGrainParams filled with default values or NULL
 154  *         on failure.
 155  */
 156 AVFilmGrainParams *av_film_grain_params_alloc(size_t *size);
 157
 158 /**
 159  * Allocate a complete AVFilmGrainParams and add it to the frame.
 160  *
 161  * @param frame The frame which side data is added to.
 162  *
 163  * @return The AVFilmGrainParams structure to be filled by caller.
 164  */
 165 AVFilmGrainParams *av_film_grain_params_create_side_data(AVFrame *frame);
 166
 167 #endif /* AVUTIL_FILM_GRAIN_PARAMS_H */