hdr_dynamic_metadata.h (14385B)
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 /** 344 * Parse the user data registered ITU-T T.35 to AVbuffer (AVDynamicHDRPlus). 345 * The T.35 buffer must begin with the application mode, skipping the 346 * country code, terminal provider codes, and application identifier. 347 * @param s A pointer containing the decoded AVDynamicHDRPlus structure. 348 * @param data The byte array containing the raw ITU-T T.35 data. 349 * @param size Size of the data array in bytes. 350 * 351 * @return >= 0 on success. Otherwise, returns the appropriate AVERROR. 352 */ 353 int av_dynamic_hdr_plus_from_t35(AVDynamicHDRPlus *s, const uint8_t *data, 354 size_t size); 355 356 #define AV_HDR_PLUS_MAX_PAYLOAD_SIZE 907 357 358 /** 359 * Serialize dynamic HDR10+ metadata to a user data registered ITU-T T.35 buffer, 360 * excluding the first 48 bytes of the header, and beginning with the application mode. 361 * @param s A pointer containing the decoded AVDynamicHDRPlus structure. 362 * @param[in,out] data A pointer to pointer to a byte buffer to be filled with the 363 * serialized metadata. 364 * If *data is NULL, a buffer be will be allocated and a pointer to 365 * it stored in its place. The caller assumes ownership of the buffer. 366 * May be NULL, in which case the function will only store the 367 * required buffer size in *size. 368 * @param[in,out] size A pointer to a size to be set to the returned buffer's size. 369 * If *data is not NULL, *size must contain the size of the input 370 * buffer. May be NULL only if *data is NULL. 371 * 372 * @return >= 0 on success. Otherwise, returns the appropriate AVERROR. 373 */ 374 int av_dynamic_hdr_plus_to_t35(const AVDynamicHDRPlus *s, uint8_t **data, size_t *size); 375 376 #endif /* AVUTIL_HDR_DYNAMIC_METADATA_H */