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 */
30enum 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 */
39typedef 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 */
59typedef 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 */
243typedef 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 */
332AVDynamicHDRPlus *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 */
341AVDynamicHDRPlus *av_dynamic_hdr_plus_create_side_data(AVFrame *frame);
342
343#endif /* AVUTIL_HDR_DYNAMIC_METADATA_H */
344