FFmpeg
hdr_dynamic_metadata.h
Go to the documentation of this file.
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  */
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  */
54 
55 /**
56  * Color transform parameters at a processing window in a dynamic metadata for
57  * SMPTE 2094-40.
58  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
171 
172  /**
173  * The linearized maxRGB values at given percentiles in the
174  * processing window in the scene.
175  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
248 
249  /**
250  * Application version in the application defining document in ST-2094
251  * suite. The value shall be set to 0.
252  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 */
AVHDRPlusColorTransformParams::average_maxrgb
AVRational average_maxrgb
The average of linearized maxRGB values in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:164
AVDynamicHDRPlus::params
AVHDRPlusColorTransformParams params[3]
The color transform parameters for every processing window.
Definition: hdr_dynamic_metadata.h:264
AVHDRPlusColorTransformParams::rotation_angle
uint8_t rotation_angle
The clockwise rotation angle in degree of arc with respect to the positive direction of the x-axis of...
Definition: hdr_dynamic_metadata.h:118
AVHDRPlusPercentile::percentile
AVRational percentile
The linearized maxRGB value at a specific percentile in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:52
rational.h
AVHDRPlusColorTransformParams::semimajor_axis_external_ellipse
uint16_t semimajor_axis_external_ellipse
The semi-major axis value of the external ellipse of the elliptical pixel selector in amount of pixel...
Definition: hdr_dynamic_metadata.h:134
AVHDRPlusColorTransformParams
Color transform parameters at a processing window in a dynamic metadata for SMPTE 2094-40.
Definition: hdr_dynamic_metadata.h:59
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:344
AVDynamicHDRPlus::num_cols_targeted_system_display_actual_peak_luminance
uint8_t num_cols_targeted_system_display_actual_peak_luminance
The number of columns in the targeted_system_display_actual_peak_luminance array.
Definition: hdr_dynamic_metadata.h:290
data
const char data[16]
Definition: mxf.c:148
AVHDRPlusColorTransformParams::tone_mapping_flag
uint8_t tone_mapping_flag
This flag indicates that the metadata for the tone mapping function in the processing window is prese...
Definition: hdr_dynamic_metadata.h:189
AVHDRPlusColorTransformParams::distribution_maxrgb
AVHDRPlusPercentile distribution_maxrgb[15]
The linearized maxRGB values at given percentiles in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:176
AVHDRPlusColorTransformParams::knee_point_x
AVRational knee_point_x
The x coordinate of the separation point between the linear part and the curved part of the tone mapp...
Definition: hdr_dynamic_metadata.h:196
av_dynamic_hdr_plus_from_t35
int av_dynamic_hdr_plus_from_t35(AVDynamicHDRPlus *s, const uint8_t *data, size_t size)
Parse the user data registered ITU-T T.35 to AVbuffer (AVDynamicHDRPlus).
Definition: hdr_dynamic_metadata.c:61
AVHDRPlusColorTransformParams::color_saturation_mapping_flag
uint8_t color_saturation_mapping_flag
This flag shall be equal to 0 in bitstreams conforming to this version of this Specification.
Definition: hdr_dynamic_metadata.h:222
AVHDRPlusColorTransformParams::center_of_ellipse_x
uint16_t center_of_ellipse_x
The x coordinate of the center position of the concentric internal and external ellipses of the ellip...
Definition: hdr_dynamic_metadata.h:102
AVHDRPlusColorTransformParams::knee_point_y
AVRational knee_point_y
The y coordinate of the separation point between the linear part and the curved part of the tone mapp...
Definition: hdr_dynamic_metadata.h:203
AVHDRPlusColorTransformParams::num_bezier_curve_anchors
uint8_t num_bezier_curve_anchors
The number of the intermediate anchor parameters of the tone mapping function in the processing windo...
Definition: hdr_dynamic_metadata.h:209
AV_HDR_PLUS_OVERLAP_PROCESS_WEIGHTED_AVERAGING
@ AV_HDR_PLUS_OVERLAP_PROCESS_WEIGHTED_AVERAGING
Definition: hdr_dynamic_metadata.h:31
s
#define s(width, name)
Definition: cbs_vp9.c:198
AVHDRPlusColorTransformParams::semiminor_axis_external_ellipse
uint16_t semiminor_axis_external_ellipse
The semi-minor axis value of the external ellipse of the elliptical pixel selector in amount of pixel...
Definition: hdr_dynamic_metadata.h:141
av_dynamic_hdr_plus_to_t35
int av_dynamic_hdr_plus_to_t35(const AVDynamicHDRPlus *s, uint8_t **data, size_t *size)
Serialize dynamic HDR10+ metadata to a user data registered ITU-T T.35 buffer, excluding the first 48...
Definition: hdr_dynamic_metadata.c:239
AVHDRPlusColorTransformParams::window_upper_left_corner_y
AVRational window_upper_left_corner_y
The relative y coordinate of the top left pixel of the processing window.
Definition: hdr_dynamic_metadata.h:76
AVHDRPlusColorTransformParams::window_lower_right_corner_x
AVRational window_lower_right_corner_x
The relative x coordinate of the bottom right pixel of the processing window.
Definition: hdr_dynamic_metadata.h:85
AVDynamicHDRPlus::targeted_system_display_maximum_luminance
AVRational targeted_system_display_maximum_luminance
The nominal maximum display luminance of the targeted system display, in units of 0....
Definition: hdr_dynamic_metadata.h:271
AVDynamicHDRPlus::mastering_display_actual_peak_luminance_flag
uint8_t mastering_display_actual_peak_luminance_flag
This flag shall be equal to 0 in bitstreams conforming to this version of this Specification.
Definition: hdr_dynamic_metadata.h:303
frame
static AVFrame * frame
Definition: demux_decode.c:54
av_dynamic_hdr_plus_create_side_data
AVDynamicHDRPlus * av_dynamic_hdr_plus_create_side_data(AVFrame *frame)
Allocate a complete AVDynamicHDRPlus and add it to the frame.
Definition: hdr_dynamic_metadata.c:48
AVHDRPlusPercentile::percentage
uint8_t percentage
The percentage value corresponding to a specific percentile linearized RGB value in the processing wi...
Definition: hdr_dynamic_metadata.h:45
AVHDRPlusPercentile
Represents the percentile at a specific percentage in a distribution.
Definition: hdr_dynamic_metadata.h:39
AVDynamicHDRPlus::application_version
uint8_t application_version
Application version in the application defining document in ST-2094 suite.
Definition: hdr_dynamic_metadata.h:253
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVHDRPlusColorTransformParams::fraction_bright_pixels
AVRational fraction_bright_pixels
The fraction of selected pixels in the image that contains the brightest pixel in the scene.
Definition: hdr_dynamic_metadata.h:183
AVHDRPlusColorTransformParams::color_saturation_weight
AVRational color_saturation_weight
The color saturation gain in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:229
av_dynamic_hdr_plus_alloc
AVDynamicHDRPlus * av_dynamic_hdr_plus_alloc(size_t *size)
Allocate an AVDynamicHDRPlus structure and set its fields to default values.
Definition: hdr_dynamic_metadata.c:36
AVDynamicHDRPlus::num_rows_mastering_display_actual_peak_luminance
uint8_t num_rows_mastering_display_actual_peak_luminance
The number of rows in the mastering_display_actual_peak_luminance array.
Definition: hdr_dynamic_metadata.h:309
AVDynamicHDRPlus::num_windows
uint8_t num_windows
The number of processing windows.
Definition: hdr_dynamic_metadata.h:259
size
int size
Definition: twinvq_data.h:10344
AVDynamicHDRPlus::mastering_display_actual_peak_luminance
AVRational mastering_display_actual_peak_luminance[25][25]
The normalized actual peak luminance of the mastering display used for mastering the image essence.
Definition: hdr_dynamic_metadata.h:322
frame.h
AVHDRPlusColorTransformParams::window_lower_right_corner_y
AVRational window_lower_right_corner_y
The relative y coordinate of the bottom right pixel of the processing window.
Definition: hdr_dynamic_metadata.h:94
AVDynamicHDRPlus::num_rows_targeted_system_display_actual_peak_luminance
uint8_t num_rows_targeted_system_display_actual_peak_luminance
The number of rows in the targeted system_display_actual_peak_luminance array.
Definition: hdr_dynamic_metadata.h:283
AVHDRPlusColorTransformParams::window_upper_left_corner_x
AVRational window_upper_left_corner_x
The relative x coordinate of the top left pixel of the processing window.
Definition: hdr_dynamic_metadata.h:67
AVHDRPlusColorTransformParams::semimajor_axis_internal_ellipse
uint16_t semimajor_axis_internal_ellipse
The semi-major axis value of the internal ellipse of the elliptical pixel selector in amount of pixel...
Definition: hdr_dynamic_metadata.h:125
AV_HDR_PLUS_OVERLAP_PROCESS_LAYERING
@ AV_HDR_PLUS_OVERLAP_PROCESS_LAYERING
Definition: hdr_dynamic_metadata.h:32
AVHDRPlusColorTransformParams::overlap_process_option
enum AVHDRPlusOverlapProcessOption overlap_process_option
Overlap process option indicates one of the two methods of combining rendered pixels in the processin...
Definition: hdr_dynamic_metadata.h:149
AVDynamicHDRPlus
This struct represents dynamic metadata for color volume transform - application 4 of SMPTE 2094-40:2...
Definition: hdr_dynamic_metadata.h:243
AVHDRPlusOverlapProcessOption
AVHDRPlusOverlapProcessOption
Option for overlapping elliptical pixel selectors in an image.
Definition: hdr_dynamic_metadata.h:30
AVDynamicHDRPlus::targeted_system_display_actual_peak_luminance_flag
uint8_t targeted_system_display_actual_peak_luminance_flag
This flag shall be equal to 0 in bit streams conforming to this version of this Specification.
Definition: hdr_dynamic_metadata.h:277
AVHDRPlusColorTransformParams::num_distribution_maxrgb_percentiles
uint8_t num_distribution_maxrgb_percentiles
The number of linearized maxRGB values at given percentiles in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:170
AVHDRPlusColorTransformParams::maxscl
AVRational maxscl[3]
The maximum of the color components of linearized RGB values in the processing window in the scene.
Definition: hdr_dynamic_metadata.h:157
AVHDRPlusColorTransformParams::center_of_ellipse_y
uint16_t center_of_ellipse_y
The y coordinate of the center position of the concentric internal and external ellipses of the ellip...
Definition: hdr_dynamic_metadata.h:110
AVDynamicHDRPlus::targeted_system_display_actual_peak_luminance
AVRational targeted_system_display_actual_peak_luminance[25][25]
The normalized actual peak luminance of the targeted system display.
Definition: hdr_dynamic_metadata.h:297
AVDynamicHDRPlus::itu_t_t35_country_code
uint8_t itu_t_t35_country_code
Country code by Rec.
Definition: hdr_dynamic_metadata.h:247
AVHDRPlusColorTransformParams::bezier_curve_anchors
AVRational bezier_curve_anchors[15]
The intermediate anchor parameters of the tone mapping function in the processing window in the scene...
Definition: hdr_dynamic_metadata.h:216
AVDynamicHDRPlus::num_cols_mastering_display_actual_peak_luminance
uint8_t num_cols_mastering_display_actual_peak_luminance
The number of columns in the mastering_display_actual_peak_luminance array.
Definition: hdr_dynamic_metadata.h:315