1/*
2 * Copyright (c) 2021 Limin Wang <lance.lmwang 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_VIVID_METADATA_H
22#define AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H
23
24#include "frame.h"
25#include "rational.h"
26
27/**
28 * Color tone mapping parameters at a processing window in a dynamic metadata for
29 * CUVA 005.1:2021.
30 */
31typedef struct AVHDRVividColorToneMappingParams {
32    /**
33     * The nominal maximum display luminance of the targeted system display,
34     * in multiples of 1.0/4095 candelas per square metre. The value shall be in
35     * the range of 0.0 to 1.0, inclusive.
36     */
37    AVRational targeted_system_display_maximum_luminance;
38
39    /**
40     * This flag indicates that transfer the base paramter(for value of 1)
41     */
42    int base_enable_flag;
43
44    /**
45     * base_param_m_p in the base parameter,
46     * in multiples of 1.0/16383. The value shall be in
47     * the range of 0.0 to 1.0, inclusive.
48     */
49    AVRational base_param_m_p;
50
51    /**
52     * base_param_m_m in the base parameter,
53     * in multiples of 1.0/10. The value shall be in
54     * the range of 0.0 to 6.3, inclusive.
55     */
56    AVRational base_param_m_m;
57
58    /**
59     * base_param_m_a in the base parameter,
60     * in multiples of 1.0/1023. The value shall be in
61     * the range of 0.0 to 1.0 inclusive.
62     */
63    AVRational base_param_m_a;
64
65    /**
66     * base_param_m_b in the base parameter,
67     * in multiples of 1/1023. The value shall be in
68     * the range of 0.0 to 1.0, inclusive.
69     */
70    AVRational base_param_m_b;
71
72    /**
73     * base_param_m_n in the base parameter,
74     * in multiples of 1.0/10. The value shall be in
75     * the range of 0.0 to 6.3, inclusive.
76     */
77    AVRational base_param_m_n;
78
79    /**
80     * indicates k1_0 in the base parameter,
81     * base_param_k1 <= 1: k1_0 = base_param_k1
82     * base_param_k1 > 1: reserved
83     */
84    int base_param_k1;
85
86    /**
87     * indicates k2_0 in the base parameter,
88     * base_param_k2 <= 1: k2_0 = base_param_k2
89     * base_param_k2 > 1: reserved
90     */
91    int base_param_k2;
92
93    /**
94     * indicates k3_0 in the base parameter,
95     * base_param_k3 == 1: k3_0 = base_param_k3
96     * base_param_k3 == 2: k3_0 = maximum_maxrgb
97     * base_param_k3 > 2: reserved
98     */
99    int base_param_k3;
100
101    /**
102     * This flag indicates that delta mode of base paramter(for value of 1)
103     */
104    int base_param_Delta_enable_mode;
105
106    /**
107     * base_param_Delta in the base parameter,
108     * in multiples of 1.0/127. The value shall be in
109     * the range of 0.0 to 1.0, inclusive.
110     */
111    AVRational base_param_Delta;
112
113    /**
114     * indicates 3Spline_enable_flag in the base parameter,
115     * This flag indicates that transfer three Spline of base paramter(for value of 1)
116     */
117    int three_Spline_enable_flag;
118
119    /**
120     * The number of three Spline. The value shall be in the range
121     * of 1 to 2, inclusive.
122     */
123    int three_Spline_num;
124
125    /**
126     * The mode of three Spline. the value shall be in the range
127     * of 0 to 3, inclusive.
128     */
129    int three_Spline_TH_mode;
130
131    /**
132     * three_Spline_TH_enable_MB is in the range of 0.0 to 1.0, inclusive
133     * and in multiples of 1.0/255.
134     *
135     */
136    AVRational three_Spline_TH_enable_MB;
137
138    /**
139     * 3Spline_TH_enable of three Spline.
140     * The value shall be in the range of 0.0 to 1.0, inclusive.
141     * and in multiples of 1.0/4095.
142     */
143    AVRational three_Spline_TH_enable;
144
145    /**
146     * 3Spline_TH_Delta1 of three Spline.
147     * The value shall be in the range of 0.0 to 0.25, inclusive,
148     * and in multiples of 0.25/1023.
149     */
150    AVRational three_Spline_TH_Delta1;
151
152    /**
153     * 3Spline_TH_Delta2 of three Spline.
154     * The value shall be in the range of 0.0 to 0.25, inclusive,
155     * and in multiples of 0.25/1023.
156     */
157    AVRational three_Spline_TH_Delta2;
158
159    /**
160     * 3Spline_enable_Strength of three Spline.
161     * The value shall be in the range of 0.0 to 1.0, inclusive,
162     * and in multiples of 1.0/255.
163     */
164    AVRational three_Spline_enable_Strength;
165} AVHDRVividColorToneMappingParams;
166
167
168/**
169 * Color transform parameters at a processing window in a dynamic metadata for
170 * CUVA 005.1:2021.
171 */
172typedef struct AVHDRVividColorTransformParams {
173    /**
174     * Indicates the minimum brightness of the displayed content.
175     * The values should be in the range of 0.0 to 1.0,
176     * inclusive and in multiples of 1/4095.
177     */
178    AVRational minimum_maxrgb;
179
180    /**
181     * Indicates the average brightness of the displayed content.
182     * The values should be in the range of 0.0 to 1.0,
183     * inclusive and in multiples of 1/4095.
184     */
185    AVRational average_maxrgb;
186
187    /**
188     * Indicates the variance brightness of the displayed content.
189     * The values should be in the range of 0.0 to 1.0,
190     * inclusive and in multiples of 1/4095.
191     */
192    AVRational variance_maxrgb;
193
194    /**
195     * Indicates the maximum brightness of the displayed content.
196     * The values should be in the range of 0.0 to 1.0, inclusive
197     * and in multiples of 1/4095.
198     */
199    AVRational maximum_maxrgb;
200
201    /**
202     * This flag indicates that the metadata for the tone mapping function in
203     * the processing window is present (for value of 1).
204     */
205    int tone_mapping_mode_flag;
206
207    /**
208     * The number of tone mapping param. The value shall be in the range
209     * of 1 to 2, inclusive.
210     */
211    int tone_mapping_param_num;
212
213    /**
214     * The color tone mapping parameters.
215     */
216    AVHDRVividColorToneMappingParams tm_params[2];
217
218    /**
219     * This flag indicates that the metadata for the color saturation mapping in
220     * the processing window is present (for value of 1).
221     */
222    int color_saturation_mapping_flag;
223
224    /**
225     * The number of color saturation param. The value shall be in the range
226     * of 0 to 7, inclusive.
227     */
228    int color_saturation_num;
229
230    /**
231     * Indicates the color correction strength parameter.
232     * The values should be in the range of 0.0 to 2.0, inclusive
233     * and in multiples of 1/128.
234     */
235    AVRational color_saturation_gain[8];
236} AVHDRVividColorTransformParams;
237
238/**
239 * This struct represents dynamic metadata for color volume transform -
240 * CUVA 005.1:2021 standard
241 *
242 * To be used as payload of a AVFrameSideData or AVPacketSideData with the
243 * appropriate type.
244 *
245 * @note The struct should be allocated with
246 * av_dynamic_hdr_vivid_alloc() and its size is not a part of
247 * the public ABI.
248 */
249typedef struct AVDynamicHDRVivid {
250    /**
251     * The system start code. The value shall be set to 0x01.
252     */
253    uint8_t system_start_code;
254
255    /**
256     * The number of processing windows. The value shall be set to 0x01
257     * if the system_start_code is 0x01.
258     */
259    uint8_t num_windows;
260
261    /**
262     * The color transform parameters for every processing window.
263     */
264    AVHDRVividColorTransformParams params[3];
265} AVDynamicHDRVivid;
266
267/**
268 * Allocate an AVDynamicHDRVivid structure and set its fields to
269 * default values. The resulting struct can be freed using av_freep().
270 *
271 * @return An AVDynamicHDRVivid filled with default values or NULL
272 *         on failure.
273 */
274AVDynamicHDRVivid *av_dynamic_hdr_vivid_alloc(size_t *size);
275
276/**
277 * Allocate a complete AVDynamicHDRVivid and add it to the frame.
278 * @param frame The frame which side data is added to.
279 *
280 * @return The AVDynamicHDRVivid structure to be filled by caller or NULL
281 *         on failure.
282 */
283AVDynamicHDRVivid *av_dynamic_hdr_vivid_create_side_data(AVFrame *frame);
284
285#endif /* AVUTIL_HDR_DYNAMIC_VIVID_METADATA_H */
286