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

   1 /*
   2  * Copyright (c) 2018 Mohammad Izadi <moh.izadi 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_METADATA_H
  22 #define AVUTIL_HDR_DYNAMIC_METADATA_H
  23
  24 #include "frame.h"
  25 #include "rational.h"
  26
  27 /**
  28  * Option for overlapping elliptical pixel selectors in an image.
  29  */
  30 enum AVHDRPlusOverlapProcessOption {
  31     AV_HDR_PLUS_OVERLAP_PROCESS_WEIGHTED_AVERAGING = 0,
  32     AV_HDR_PLUS_OVERLAP_PROCESS_LAYERING = 1,
  33 };
  34
  35 /**
  36  * Represents the percentile at a specific percentage in
  37  * a distribution.
  38  */
  39 typedef struct AVHDRPlusPercentile {
  40     /**
  41      * The percentage value corresponding to a specific percentile linearized
  42      * RGB value in the processing window in the scene. The value shall be in
  43      * the range of 0 to100, inclusive.
  44      */
  45     uint8_t percentage;
  46
  47     /**
  48      * The linearized maxRGB value at a specific percentile in the processing
  49      * window in the scene. The value shall be in the range of 0 to 1, inclusive
  50      * and in multiples of 0.00001.
  51      */
  52     AVRational percentile;
  53 } AVHDRPlusPercentile;
  54
  55 /**
  56  * Color transform parameters at a processing window in a dynamic metadata for
  57  * SMPTE 2094-40.
  58  */
  59 typedef struct AVHDRPlusColorTransformParams {
  60     /**
  61      * The relative x coordinate of the top left pixel of the processing
  62      * window. The value shall be in the range of 0 and 1, inclusive and
  63      * in multiples of 1/(width of Picture - 1). The value 1 corresponds
  64      * to the absolute coordinate of width of Picture - 1. The value for
  65      * first processing window shall be 0.
  66      */
  67     AVRational window_upper_left_corner_x;
  68
  69     /**
  70      * The relative y coordinate of the top left pixel of the processing
  71      * window. The value shall be in the range of 0 and 1, inclusive and
  72      * in multiples of 1/(height of Picture - 1). The value 1 corresponds
  73      * to the absolute coordinate of height of Picture - 1. The value for
  74      * first processing window shall be 0.
  75      */
  76     AVRational window_upper_left_corner_y;
  77
  78     /**
  79      * The relative x coordinate of the bottom right pixel of the processing
  80      * window. The value shall be in the range of 0 and 1, inclusive and
  81      * in multiples of 1/(width of Picture - 1). The value 1 corresponds
  82      * to the absolute coordinate of width of Picture - 1. The value for
  83      * first processing window shall be 1.
  84      */
  85     AVRational window_lower_right_corner_x;
  86
  87     /**
  88      * The relative y coordinate of the bottom right pixel of the processing
  89      * window. The value shall be in the range of 0 and 1, inclusive and
  90      * in multiples of 1/(height of Picture - 1). The value 1 corresponds
  91      * to the absolute coordinate of height of Picture - 1. The value for
  92      * first processing window shall be 1.
  93      */
  94     AVRational window_lower_right_corner_y;
  95
  96     /**
  97      * The x coordinate of the center position of the concentric internal and
  98      * external ellipses of the elliptical pixel selector in the processing
  99      * window. The value shall be in the range of 0 to (width of Picture - 1),
 100      * inclusive and in multiples of 1 pixel.
 101      */
 102     uint16_t center_of_ellipse_x;
 103
 104     /**
 105      * The y coordinate of the center position of the concentric internal and
 106      * external ellipses of the elliptical pixel selector in the processing
 107      * window. The value shall be in the range of 0 to (height of Picture - 1),
 108      * inclusive and in multiples of 1 pixel.
 109      */
 110     uint16_t center_of_ellipse_y;
 111
 112     /**
 113      * The clockwise rotation angle in degree of arc with respect to the
 114      * positive direction of the x-axis of the concentric internal and external
 115      * ellipses of the elliptical pixel selector in the processing window. The
 116      * value shall be in the range of 0 to 180, inclusive and in multiples of 1.
 117      */
 118     uint8_t rotation_angle;
 119
 120     /**
 121      * The semi-major axis value of the internal ellipse of the elliptical pixel
 122      * selector in amount of pixels in the processing window. The value shall be
 123      * in the range of 1 to 65535, inclusive and in multiples of 1 pixel.
 124      */
 125     uint16_t semimajor_axis_internal_ellipse;
 126
 127     /**
 128      * The semi-major axis value of the external ellipse of the elliptical pixel
 129      * selector in amount of pixels in the processing window. The value
 130      * shall not be less than semimajor_axis_internal_ellipse of the current
 131      * processing window. The value shall be in the range of 1 to 65535,
 132      * inclusive and in multiples of 1 pixel.
 133      */
 134     uint16_t semimajor_axis_external_ellipse;
 135
 136     /**
 137      * The semi-minor axis value of the external ellipse of the elliptical pixel
 138      * selector in amount of pixels in the processing window. The value shall be
 139      * in the range of 1 to 65535, inclusive and in multiples of 1 pixel.
 140      */
 141     uint16_t semiminor_axis_external_ellipse;
 142
 143     /**
 144      * Overlap process option indicates one of the two methods of combining
 145      * rendered pixels in the processing window in an image with at least one
 146      * elliptical pixel selector. For overlapping elliptical pixel selectors
 147      * in an image, overlap_process_option shall have the same value.
 148      */
 149     enum AVHDRPlusOverlapProcessOption overlap_process_option;
 150
 151     /**
 152      * The maximum of the color components of linearized RGB values in the
 153      * processing window in the scene. The values should be in the range of 0 to
 154      * 1, inclusive and in multiples of 0.00001. maxscl[ 0 ], maxscl[ 1 ], and
 155      * maxscl[ 2 ] are corresponding to R, G, B color components respectively.
 156      */
 157     AVRational maxscl[3];
 158
 159     /**
 160      * The average of linearized maxRGB values in the processing window in the
 161      * scene. The value should be in the range of 0 to 1, inclusive and in
 162      * multiples of 0.00001.
 163      */
 164     AVRational average_maxrgb;
 165
 166     /**
 167      * The number of linearized maxRGB values at given percentiles in the
 168      * processing window in the scene. The maximum value shall be 15.
 169      */
 170     uint8_t num_distribution_maxrgb_percentiles;
 171
 172     /**
 173      * The linearized maxRGB values at given percentiles in the
 174      * processing window in the scene.
 175      */
 176     AVHDRPlusPercentile distribution_maxrgb[15];
 177
 178     /**
 179      * The fraction of selected pixels in the image that contains the brightest
 180      * pixel in the scene. The value shall be in the range of 0 to 1, inclusive
 181      * and in multiples of 0.001.
 182      */
 183     AVRational fraction_bright_pixels;
 184
 185     /**
 186      * This flag indicates that the metadata for the tone mapping function in
 187      * the processing window is present (for value of 1).
 188      */
 189     uint8_t tone_mapping_flag;
 190
 191     /**
 192      * The x coordinate of the separation point between the linear part and the
 193      * curved part of the tone mapping function. The value shall be in the range
 194      * of 0 to 1, excluding 0 and in multiples of 1/4095.
 195      */
 196     AVRational knee_point_x;
 197
 198     /**
 199      * The y coordinate of the separation point between the linear part and the
 200      * curved part of the tone mapping function. The value shall be in the range
 201      * of 0 to 1, excluding 0 and in multiples of 1/4095.
 202      */
 203     AVRational knee_point_y;
 204
 205     /**
 206      * The number of the intermediate anchor parameters of the tone mapping
 207      * function in the processing window. The maximum value shall be 15.
 208      */
 209     uint8_t num_bezier_curve_anchors;
 210
 211     /**
 212      * The intermediate anchor parameters of the tone mapping function in the
 213      * processing window in the scene. The values should be in the range of 0
 214      * to 1, inclusive and in multiples of 1/1023.
 215      */
 216     AVRational bezier_curve_anchors[15];
 217
 218     /**
 219      * This flag shall be equal to 0 in bitstreams conforming to this version of
 220      * this Specification. Other values are reserved for future use.
 221      */
 222     uint8_t color_saturation_mapping_flag;
 223
 224     /**
 225      * The color saturation gain in the processing window in the scene. The
 226      * value shall be in the range of 0 to 63/8, inclusive and in multiples of
 227      * 1/8. The default value shall be 1.
 228      */
 229     AVRational color_saturation_weight;
 230 } AVHDRPlusColorTransformParams;
 231
 232 /**
 233  * This struct represents dynamic metadata for color volume transform -
 234  * application 4 of SMPTE 2094-40:2016 standard.
 235  *
 236  * To be used as payload of a AVFrameSideData or AVPacketSideData with the
 237  * appropriate type.
 238  *
 239  * @note The struct should be allocated with
 240  * av_dynamic_hdr_plus_alloc() and its size is not a part of
 241  * the public ABI.
 242  */
 243 typedef struct AVDynamicHDRPlus {
 244     /**
 245      * Country code by Rec. ITU-T T.35 Annex A. The value shall be 0xB5.
 246      */
 247     uint8_t itu_t_t35_country_code;
 248
 249     /**
 250      * Application version in the application defining document in ST-2094
 251      * suite. The value shall be set to 0.
 252      */
 253     uint8_t application_version;
 254
 255     /**
 256      * The number of processing windows. The value shall be in the range
 257      * of 1 to 3, inclusive.
 258      */
 259     uint8_t num_windows;
 260
 261     /**
 262      * The color transform parameters for every processing window.
 263      */
 264     AVHDRPlusColorTransformParams params[3];
 265
 266     /**
 267      * The nominal maximum display luminance of the targeted system display,
 268      * in units of 0.0001 candelas per square metre. The value shall be in
 269      * the range of 0 to 10000, inclusive.
 270      */
 271     AVRational targeted_system_display_maximum_luminance;
 272
 273     /**
 274      * This flag shall be equal to 0 in bit streams conforming to this version
 275      * of this Specification. The value 1 is reserved for future use.
 276      */
 277     uint8_t targeted_system_display_actual_peak_luminance_flag;
 278
 279     /**
 280      * The number of rows in the targeted system_display_actual_peak_luminance
 281      * array. The value shall be in the range of 2 to 25, inclusive.
 282      */
 283     uint8_t num_rows_targeted_system_display_actual_peak_luminance;
 284
 285     /**
 286      * The number of columns in the
 287      * targeted_system_display_actual_peak_luminance array. The value shall be
 288      * in the range of 2 to 25, inclusive.
 289      */
 290     uint8_t num_cols_targeted_system_display_actual_peak_luminance;
 291
 292     /**
 293      * The normalized actual peak luminance of the targeted system display. The
 294      * values should be in the range of 0 to 1, inclusive and in multiples of
 295      * 1/15.
 296      */
 297     AVRational targeted_system_display_actual_peak_luminance[25][25];
 298
 299     /**
 300      * This flag shall be equal to 0 in bitstreams conforming to this version of
 301      * this Specification. The value 1 is reserved for future use.
 302      */
 303     uint8_t mastering_display_actual_peak_luminance_flag;
 304
 305     /**
 306      * The number of rows in the mastering_display_actual_peak_luminance array.
 307      * The value shall be in the range of 2 to 25, inclusive.
 308      */
 309     uint8_t num_rows_mastering_display_actual_peak_luminance;
 310
 311     /**
 312      * The number of columns in the mastering_display_actual_peak_luminance
 313      * array. The value shall be in the range of 2 to 25, inclusive.
 314      */
 315     uint8_t num_cols_mastering_display_actual_peak_luminance;
 316
 317     /**
 318      * The normalized actual peak luminance of the mastering display used for
 319      * mastering the image essence. The values should be in the range of 0 to 1,
 320      * inclusive and in multiples of 1/15.
 321      */
 322     AVRational mastering_display_actual_peak_luminance[25][25];
 323 } AVDynamicHDRPlus;
 324
 325 /**
 326  * Allocate an AVDynamicHDRPlus structure and set its fields to
 327  * default values. The resulting struct can be freed using av_freep().
 328  *
 329  * @return An AVDynamicHDRPlus filled with default values or NULL
 330  *         on failure.
 331  */
 332 AVDynamicHDRPlus *av_dynamic_hdr_plus_alloc(size_t *size);
 333
 334 /**
 335  * Allocate a complete AVDynamicHDRPlus and add it to the frame.
 336  * @param frame The frame which side data is added to.
 337  *
 338  * @return The AVDynamicHDRPlus structure to be filled by caller or NULL
 339  *         on failure.
 340  */
 341 AVDynamicHDRPlus *av_dynamic_hdr_plus_create_side_data(AVFrame *frame);
 342
 343 #endif /* AVUTIL_HDR_DYNAMIC_METADATA_H */