libavutil/hdr_dynamic_vivid_metadata.h

   1 /*
   2  * Copyright (c) 2021 Limin Wang <lance.lmwang at gmail.com>
   3  *
   4  * This file is part of FFmpeg.
   5  *
   6  * FFmpeg is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * FFmpeg is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with FFmpeg; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H
  22 #define AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H
  23
  24 #include "frame.h"
  25 #include "rational.h"
  26
  27 /**
  28  * HDR Vivid three spline params.
  29  */
  30 typedef struct AVHDRVivid3SplineParams {
  31     /**
  32      * The mode of three Spline. the value shall be in the range
  33      * of 0 to 3, inclusive.
  34      */
  35     int th_mode;
  36
  37     /**
  38      * three_Spline_TH_enable_MB is in the range of 0.0 to 1.0, inclusive
  39      * and in multiples of 1.0/255.
  40      *
  41      */
  42     AVRational th_enable_mb;
  43
  44     /**
  45      * 3Spline_TH_enable of three Spline.
  46      * The value shall be in the range of 0.0 to 1.0, inclusive.
  47      * and in multiples of 1.0/4095.
  48      */
  49     AVRational th_enable;
  50
  51     /**
  52      * 3Spline_TH_Delta1 of three Spline.
  53      * The value shall be in the range of 0.0 to 0.25, inclusive,
  54      * and in multiples of 0.25/1023.
  55      */
  56     AVRational th_delta1;
  57
  58     /**
  59      * 3Spline_TH_Delta2 of three Spline.
  60      * The value shall be in the range of 0.0 to 0.25, inclusive,
  61      * and in multiples of 0.25/1023.
  62      */
  63     AVRational th_delta2;
  64
  65     /**
  66      * 3Spline_enable_Strength of three Spline.
  67      * The value shall be in the range of 0.0 to 1.0, inclusive,
  68      * and in multiples of 1.0/255.
  69      */
  70     AVRational enable_strength;
  71 } AVHDRVivid3SplineParams;
  72
  73 /**
  74  * Color tone mapping parameters at a processing window in a dynamic metadata for
  75  * CUVA 005.1:2021.
  76  */
  77 typedef struct AVHDRVividColorToneMappingParams {
  78     /**
  79      * The nominal maximum display luminance of the targeted system display,
  80      * in multiples of 1.0/4095 candelas per square metre. The value shall be in
  81      * the range of 0.0 to 1.0, inclusive.
  82      */
  83     AVRational targeted_system_display_maximum_luminance;
  84
  85     /**
  86      * This flag indicates that transfer the base paramter(for value of 1)
  87      */
  88     int base_enable_flag;
  89
  90     /**
  91      * base_param_m_p in the base parameter,
  92      * in multiples of 1.0/16383. The value shall be in
  93      * the range of 0.0 to 1.0, inclusive.
  94      */
  95     AVRational base_param_m_p;
  96
  97     /**
  98      * base_param_m_m in the base parameter,
  99      * in multiples of 1.0/10. The value shall be in
 100      * the range of 0.0 to 6.3, inclusive.
 101      */
 102     AVRational base_param_m_m;
 103
 104     /**
 105      * base_param_m_a in the base parameter,
 106      * in multiples of 1.0/1023. The value shall be in
 107      * the range of 0.0 to 1.0 inclusive.
 108      */
 109     AVRational base_param_m_a;
 110
 111     /**
 112      * base_param_m_b in the base parameter,
 113      * in multiples of 1/1023. The value shall be in
 114      * the range of 0.0 to 1.0, inclusive.
 115      */
 116     AVRational base_param_m_b;
 117
 118     /**
 119      * base_param_m_n in the base parameter,
 120      * in multiples of 1.0/10. The value shall be in
 121      * the range of 0.0 to 6.3, inclusive.
 122      */
 123     AVRational base_param_m_n;
 124
 125     /**
 126      * indicates k1_0 in the base parameter,
 127      * base_param_k1 <= 1: k1_0 = base_param_k1
 128      * base_param_k1 > 1: reserved
 129      */
 130     int base_param_k1;
 131
 132     /**
 133      * indicates k2_0 in the base parameter,
 134      * base_param_k2 <= 1: k2_0 = base_param_k2
 135      * base_param_k2 > 1: reserved
 136      */
 137     int base_param_k2;
 138
 139     /**
 140      * indicates k3_0 in the base parameter,
 141      * base_param_k3 == 1: k3_0 = base_param_k3
 142      * base_param_k3 == 2: k3_0 = maximum_maxrgb
 143      * base_param_k3 > 2: reserved
 144      */
 145     int base_param_k3;
 146
 147     /**
 148      * This flag indicates that delta mode of base paramter(for value of 1)
 149      */
 150     int base_param_Delta_enable_mode;
 151
 152     /**
 153      * base_param_Delta in the base parameter,
 154      * in multiples of 1.0/127. The value shall be in
 155      * the range of 0.0 to 1.0, inclusive.
 156      */
 157     AVRational base_param_Delta;
 158
 159     /**
 160      * indicates 3Spline_enable_flag in the base parameter,
 161      * This flag indicates that transfer three Spline of base paramter(for value of 1)
 162      */
 163     int three_Spline_enable_flag;
 164
 165     /**
 166      * The number of three Spline. The value shall be in the range
 167      * of 1 to 2, inclusive.
 168      */
 169     int three_Spline_num;
 170
 171 #if FF_API_HDR_VIVID_THREE_SPLINE
 172     /**
 173      * The mode of three Spline. the value shall be in the range
 174      * of 0 to 3, inclusive.
 175      * @deprecated Use three_spline instead
 176      */
 177     attribute_deprecated
 178     int three_Spline_TH_mode;
 179
 180     /**
 181      * three_Spline_TH_enable_MB is in the range of 0.0 to 1.0, inclusive
 182      * and in multiples of 1.0/255.
 183      * @deprecated Use three_spline instead
 184      */
 185     attribute_deprecated
 186     AVRational three_Spline_TH_enable_MB;
 187
 188     /**
 189      * 3Spline_TH_enable of three Spline.
 190      * The value shall be in the range of 0.0 to 1.0, inclusive.
 191      * and in multiples of 1.0/4095.
 192      * @deprecated Use three_spline instead
 193      */
 194     attribute_deprecated
 195     AVRational three_Spline_TH_enable;
 196
 197     /**
 198      * 3Spline_TH_Delta1 of three Spline.
 199      * The value shall be in the range of 0.0 to 0.25, inclusive,
 200      * and in multiples of 0.25/1023.
 201      * @deprecated Use three_spline instead
 202      */
 203     attribute_deprecated
 204     AVRational three_Spline_TH_Delta1;
 205
 206     /**
 207      * 3Spline_TH_Delta2 of three Spline.
 208      * The value shall be in the range of 0.0 to 0.25, inclusive,
 209      * and in multiples of 0.25/1023.
 210      * @deprecated Use three_spline instead
 211      */
 212     attribute_deprecated
 213     AVRational three_Spline_TH_Delta2;
 214
 215     /**
 216      * 3Spline_enable_Strength of three Spline.
 217      * The value shall be in the range of 0.0 to 1.0, inclusive,
 218      * and in multiples of 1.0/255.
 219      * @deprecated Use three_spline instead
 220      */
 221     attribute_deprecated
 222     AVRational three_Spline_enable_Strength;
 223 #endif
 224
 225     AVHDRVivid3SplineParams three_spline[2];
 226 } AVHDRVividColorToneMappingParams;
 227
 228
 229 /**
 230  * Color transform parameters at a processing window in a dynamic metadata for
 231  * CUVA 005.1:2021.
 232  */
 233 typedef struct AVHDRVividColorTransformParams {
 234     /**
 235      * Indicates the minimum brightness of the displayed content.
 236      * The values should be in the range of 0.0 to 1.0,
 237      * inclusive and in multiples of 1/4095.
 238      */
 239     AVRational minimum_maxrgb;
 240
 241     /**
 242      * Indicates the average brightness of the displayed content.
 243      * The values should be in the range of 0.0 to 1.0,
 244      * inclusive and in multiples of 1/4095.
 245      */
 246     AVRational average_maxrgb;
 247
 248     /**
 249      * Indicates the variance brightness of the displayed content.
 250      * The values should be in the range of 0.0 to 1.0,
 251      * inclusive and in multiples of 1/4095.
 252      */
 253     AVRational variance_maxrgb;
 254
 255     /**
 256      * Indicates the maximum brightness of the displayed content.
 257      * The values should be in the range of 0.0 to 1.0, inclusive
 258      * and in multiples of 1/4095.
 259      */
 260     AVRational maximum_maxrgb;
 261
 262     /**
 263      * This flag indicates that the metadata for the tone mapping function in
 264      * the processing window is present (for value of 1).
 265      */
 266     int tone_mapping_mode_flag;
 267
 268     /**
 269      * The number of tone mapping param. The value shall be in the range
 270      * of 1 to 2, inclusive.
 271      */
 272     int tone_mapping_param_num;
 273
 274     /**
 275      * The color tone mapping parameters.
 276      */
 277     AVHDRVividColorToneMappingParams tm_params[2];
 278
 279     /**
 280      * This flag indicates that the metadata for the color saturation mapping in
 281      * the processing window is present (for value of 1).
 282      */
 283     int color_saturation_mapping_flag;
 284
 285     /**
 286      * The number of color saturation param. The value shall be in the range
 287      * of 0 to 7, inclusive.
 288      */
 289     int color_saturation_num;
 290
 291     /**
 292      * Indicates the color correction strength parameter.
 293      * The values should be in the range of 0.0 to 2.0, inclusive
 294      * and in multiples of 1/128.
 295      */
 296     AVRational color_saturation_gain[8];
 297 } AVHDRVividColorTransformParams;
 298
 299 /**
 300  * This struct represents dynamic metadata for color volume transform -
 301  * CUVA 005.1:2021 standard
 302  *
 303  * To be used as payload of a AVFrameSideData or AVPacketSideData with the
 304  * appropriate type.
 305  *
 306  * @note The struct should be allocated with
 307  * av_dynamic_hdr_vivid_alloc() and its size is not a part of
 308  * the public ABI.
 309  */
 310 typedef struct AVDynamicHDRVivid {
 311     /**
 312      * The system start code. The value shall be set to 0x01.
 313      */
 314     uint8_t system_start_code;
 315
 316     /**
 317      * The number of processing windows. The value shall be set to 0x01
 318      * if the system_start_code is 0x01.
 319      */
 320     uint8_t num_windows;
 321
 322     /**
 323      * The color transform parameters for every processing window.
 324      */
 325     AVHDRVividColorTransformParams params[3];
 326 } AVDynamicHDRVivid;
 327
 328 /**
 329  * Allocate an AVDynamicHDRVivid structure and set its fields to
 330  * default values. The resulting struct can be freed using av_freep().
 331  *
 332  * @return An AVDynamicHDRVivid filled with default values or NULL
 333  *         on failure.
 334  */
 335 AVDynamicHDRVivid *av_dynamic_hdr_vivid_alloc(size_t *size);
 336
 337 /**
 338  * Allocate a complete AVDynamicHDRVivid and add it to the frame.
 339  * @param frame The frame which side data is added to.
 340  *
 341  * @return The AVDynamicHDRVivid structure to be filled by caller or NULL
 342  *         on failure.
 343  */
 344 AVDynamicHDRVivid *av_dynamic_hdr_vivid_create_side_data(AVFrame *frame);
 345
 346 #endif /* AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H */