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:375
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
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
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
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