FFmpeg coverage


Directory: ../../../ffmpeg/
File: src/libavutil/dovi_meta.h
Date: 2024-12-12 01:08:13
Exec Total Coverage
Lines: 9 9 100.0%
Functions: 4 4 100.0%
Branches: 0 0 -%

Line Branch Exec Source
1 /*
2 * Copyright (c) 2020 Vacing Fang <vacingfang@tencent.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 /**
22 * @file
23 * DOVI configuration
24 */
25
26
27 #ifndef AVUTIL_DOVI_META_H
28 #define AVUTIL_DOVI_META_H
29
30 #include <stdint.h>
31 #include <stddef.h>
32
33 #include "rational.h"
34 #include "csp.h"
35
36 /*
37 * DOVI configuration
38 * ref: dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2
39 dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2
40 * @code
41 * uint8_t dv_version_major, the major version number that the stream complies with
42 * uint8_t dv_version_minor, the minor version number that the stream complies with
43 * uint8_t dv_profile, the Dolby Vision profile
44 * uint8_t dv_level, the Dolby Vision level
45 * uint8_t rpu_present_flag
46 * uint8_t el_present_flag
47 * uint8_t bl_present_flag
48 * uint8_t dv_bl_signal_compatibility_id
49 * uint8_t dv_md_compression, the compression method in use
50 * @endcode
51 *
52 * @note The struct must be allocated with av_dovi_alloc() and
53 * its size is not a part of the public ABI.
54 */
55 typedef struct AVDOVIDecoderConfigurationRecord {
56 uint8_t dv_version_major;
57 uint8_t dv_version_minor;
58 uint8_t dv_profile;
59 uint8_t dv_level;
60 uint8_t rpu_present_flag;
61 uint8_t el_present_flag;
62 uint8_t bl_present_flag;
63 uint8_t dv_bl_signal_compatibility_id;
64 uint8_t dv_md_compression;
65 } AVDOVIDecoderConfigurationRecord;
66
67 enum AVDOVICompression {
68 AV_DOVI_COMPRESSION_NONE = 0,
69 AV_DOVI_COMPRESSION_LIMITED = 1,
70 AV_DOVI_COMPRESSION_RESERVED = 2,
71 AV_DOVI_COMPRESSION_EXTENDED = 3,
72 };
73
74 /**
75 * Allocate a AVDOVIDecoderConfigurationRecord structure and initialize its
76 * fields to default values.
77 *
78 * @return the newly allocated struct or NULL on failure
79 */
80 AVDOVIDecoderConfigurationRecord *av_dovi_alloc(size_t *size);
81
82 /**
83 * Dolby Vision RPU data header.
84 *
85 * @note sizeof(AVDOVIRpuDataHeader) is not part of the public ABI.
86 */
87 typedef struct AVDOVIRpuDataHeader {
88 uint8_t rpu_type;
89 uint16_t rpu_format;
90 uint8_t vdr_rpu_profile;
91 uint8_t vdr_rpu_level;
92 uint8_t chroma_resampling_explicit_filter_flag;
93 uint8_t coef_data_type; /* informative, lavc always converts to fixed */
94 uint8_t coef_log2_denom;
95 uint8_t vdr_rpu_normalized_idc;
96 uint8_t bl_video_full_range_flag;
97 uint8_t bl_bit_depth; /* [8, 16] */
98 uint8_t el_bit_depth; /* [8, 16] */
99 uint8_t vdr_bit_depth; /* [8, 16] */
100 uint8_t spatial_resampling_filter_flag;
101 uint8_t el_spatial_resampling_filter_flag;
102 uint8_t disable_residual_flag;
103 uint8_t ext_mapping_idc_0_4; /* extended base layer inverse mapping indicator */
104 uint8_t ext_mapping_idc_5_7; /* reserved */
105 } AVDOVIRpuDataHeader;
106
107 enum AVDOVIMappingMethod {
108 AV_DOVI_MAPPING_POLYNOMIAL = 0,
109 AV_DOVI_MAPPING_MMR = 1,
110 };
111
112 /**
113 * Coefficients of a piece-wise function. The pieces of the function span the
114 * value ranges between two adjacent pivot values.
115 */
116 #define AV_DOVI_MAX_PIECES 8
117 typedef struct AVDOVIReshapingCurve {
118 uint8_t num_pivots; /* [2, 9] */
119 uint16_t pivots[AV_DOVI_MAX_PIECES + 1]; /* sorted ascending */
120 enum AVDOVIMappingMethod mapping_idc[AV_DOVI_MAX_PIECES];
121 /* AV_DOVI_MAPPING_POLYNOMIAL */
122 uint8_t poly_order[AV_DOVI_MAX_PIECES]; /* [1, 2] */
123 int64_t poly_coef[AV_DOVI_MAX_PIECES][3]; /* x^0, x^1, x^2 */
124 /* AV_DOVI_MAPPING_MMR */
125 uint8_t mmr_order[AV_DOVI_MAX_PIECES]; /* [1, 3] */
126 int64_t mmr_constant[AV_DOVI_MAX_PIECES];
127 int64_t mmr_coef[AV_DOVI_MAX_PIECES][3/* order - 1 */][7];
128 } AVDOVIReshapingCurve;
129
130 enum AVDOVINLQMethod {
131 AV_DOVI_NLQ_NONE = -1,
132 AV_DOVI_NLQ_LINEAR_DZ = 0,
133 };
134
135 /**
136 * Coefficients of the non-linear inverse quantization. For the interpretation
137 * of these, see ETSI GS CCM 001.
138 */
139 typedef struct AVDOVINLQParams {
140 uint16_t nlq_offset;
141 uint64_t vdr_in_max;
142 /* AV_DOVI_NLQ_LINEAR_DZ */
143 uint64_t linear_deadzone_slope;
144 uint64_t linear_deadzone_threshold;
145 } AVDOVINLQParams;
146
147 /**
148 * Dolby Vision RPU data mapping parameters.
149 *
150 * @note sizeof(AVDOVIDataMapping) is not part of the public ABI.
151 */
152 typedef struct AVDOVIDataMapping {
153 uint8_t vdr_rpu_id;
154 uint8_t mapping_color_space;
155 uint8_t mapping_chroma_format_idc;
156 AVDOVIReshapingCurve curves[3]; /* per component */
157
158 /* Non-linear inverse quantization */
159 enum AVDOVINLQMethod nlq_method_idc;
160 uint32_t num_x_partitions;
161 uint32_t num_y_partitions;
162 AVDOVINLQParams nlq[3]; /* per component */
163 uint16_t nlq_pivots[2];
164 } AVDOVIDataMapping;
165
166 /**
167 * Dolby Vision RPU colorspace metadata parameters.
168 *
169 * @note sizeof(AVDOVIColorMetadata) is not part of the public ABI.
170 */
171 typedef struct AVDOVIColorMetadata {
172 uint8_t dm_metadata_id;
173 uint8_t scene_refresh_flag;
174
175 /**
176 * Coefficients of the custom Dolby Vision IPT-PQ matrices. These are to be
177 * used instead of the matrices indicated by the frame's colorspace tags.
178 * The output of rgb_to_lms_matrix is to be fed into a BT.2020 LMS->RGB
179 * matrix based on a Hunt-Pointer-Estevez transform, but without any
180 * crosstalk. (See the definition of the ICtCp colorspace for more
181 * information.)
182 */
183 AVRational ycc_to_rgb_matrix[9]; /* before PQ linearization */
184 AVRational ycc_to_rgb_offset[3]; /* input offset of neutral value */
185 AVRational rgb_to_lms_matrix[9]; /* after PQ linearization */
186
187 /**
188 * Extra signal metadata (see Dolby patents for more info).
189 */
190 uint16_t signal_eotf;
191 uint16_t signal_eotf_param0;
192 uint16_t signal_eotf_param1;
193 uint32_t signal_eotf_param2;
194 uint8_t signal_bit_depth;
195 uint8_t signal_color_space;
196 uint8_t signal_chroma_format;
197 uint8_t signal_full_range_flag; /* [0, 3] */
198 uint16_t source_min_pq;
199 uint16_t source_max_pq;
200 uint16_t source_diagonal;
201 } AVDOVIColorMetadata;
202
203 typedef struct AVDOVIDmLevel1 {
204 /* Per-frame brightness metadata */
205 uint16_t min_pq;
206 uint16_t max_pq;
207 uint16_t avg_pq;
208 } AVDOVIDmLevel1;
209
210 typedef struct AVDOVIDmLevel2 {
211 /* Usually derived from level 8 (at different levels) */
212 uint16_t target_max_pq;
213 uint16_t trim_slope;
214 uint16_t trim_offset;
215 uint16_t trim_power;
216 uint16_t trim_chroma_weight;
217 uint16_t trim_saturation_gain;
218 int16_t ms_weight;
219 } AVDOVIDmLevel2;
220
221 typedef struct AVDOVIDmLevel3 {
222 uint16_t min_pq_offset;
223 uint16_t max_pq_offset;
224 uint16_t avg_pq_offset;
225 } AVDOVIDmLevel3;
226
227 typedef struct AVDOVIDmLevel4 {
228 uint16_t anchor_pq;
229 uint16_t anchor_power;
230 } AVDOVIDmLevel4;
231
232 typedef struct AVDOVIDmLevel5 {
233 /* Active area definition */
234 uint16_t left_offset;
235 uint16_t right_offset;
236 uint16_t top_offset;
237 uint16_t bottom_offset;
238 } AVDOVIDmLevel5;
239
240 typedef struct AVDOVIDmLevel6 {
241 /* Static HDR10 metadata */
242 uint16_t max_luminance;
243 uint16_t min_luminance;
244 uint16_t max_cll;
245 uint16_t max_fall;
246 } AVDOVIDmLevel6;
247
248 typedef struct AVDOVIDmLevel8 {
249 /* Extended version of level 2 */
250 uint8_t target_display_index;
251 uint16_t trim_slope;
252 uint16_t trim_offset;
253 uint16_t trim_power;
254 uint16_t trim_chroma_weight;
255 uint16_t trim_saturation_gain;
256 uint16_t ms_weight;
257 uint16_t target_mid_contrast;
258 uint16_t clip_trim;
259 uint8_t saturation_vector_field[6];
260 uint8_t hue_vector_field[6];
261 } AVDOVIDmLevel8;
262
263 typedef struct AVDOVIDmLevel9 {
264 /* Source display characteristics */
265 uint8_t source_primary_index;
266 AVColorPrimariesDesc source_display_primaries;
267 } AVDOVIDmLevel9;
268
269 typedef struct AVDOVIDmLevel10 {
270 /* Target display characteristics */
271 uint8_t target_display_index;
272 uint16_t target_max_pq;
273 uint16_t target_min_pq;
274 uint8_t target_primary_index;
275 AVColorPrimariesDesc target_display_primaries;
276 } AVDOVIDmLevel10;
277
278 typedef struct AVDOVIDmLevel11 {
279 uint8_t content_type;
280 uint8_t whitepoint;
281 uint8_t reference_mode_flag;
282 uint8_t sharpness;
283 uint8_t noise_reduction;
284 uint8_t mpeg_noise_reduction;
285 uint8_t frame_rate_conversion;
286 uint8_t brightness;
287 uint8_t color;
288 } AVDOVIDmLevel11;
289
290 typedef struct AVDOVIDmLevel254 {
291 /* DMv2 info block, always present in samples with DMv2 metadata */
292 uint8_t dm_mode;
293 uint8_t dm_version_index;
294 } AVDOVIDmLevel254;
295
296 typedef struct AVDOVIDmLevel255 {
297 /* Debug block, not really used in samples */
298 uint8_t dm_run_mode;
299 uint8_t dm_run_version;
300 uint8_t dm_debug[4];
301 } AVDOVIDmLevel255;
302
303 /**
304 * Dolby Vision metadata extension block. Dynamic extension blocks may change
305 * from frame to frame, while static blocks are constant throughout the entire
306 * sequence.
307 *
308 * @note sizeof(AVDOVIDmData) is not part of the public API.
309 */
310 typedef struct AVDOVIDmData {
311 uint8_t level; /* [1, 255] */
312 union {
313 AVDOVIDmLevel1 l1; /* dynamic */
314 AVDOVIDmLevel2 l2; /* dynamic, may appear multiple times */
315 AVDOVIDmLevel3 l3; /* dynamic */
316 AVDOVIDmLevel4 l4; /* dynamic */
317 AVDOVIDmLevel5 l5; /* dynamic */
318 AVDOVIDmLevel6 l6; /* static */
319 /* level 7 is currently unused */
320 AVDOVIDmLevel8 l8; /* dynamic, may appear multiple times */
321 AVDOVIDmLevel9 l9; /* dynamic */
322 AVDOVIDmLevel10 l10; /* static, may appear multiple times */
323 AVDOVIDmLevel11 l11; /* dynamic */
324 AVDOVIDmLevel254 l254; /* static */
325 AVDOVIDmLevel255 l255; /* static */
326 };
327 } AVDOVIDmData;
328
329 /**
330 * Combined struct representing a combination of header, mapping and color
331 * metadata, for attaching to frames as side data.
332 *
333 * @note The struct must be allocated with av_dovi_metadata_alloc() and
334 * its size is not a part of the public ABI.
335 */
336
337 typedef struct AVDOVIMetadata {
338 /**
339 * Offset in bytes from the beginning of this structure at which the
340 * respective structs start.
341 */
342 size_t header_offset; /* AVDOVIRpuDataHeader */
343 size_t mapping_offset; /* AVDOVIDataMapping */
344 size_t color_offset; /* AVDOVIColorMetadata */
345
346 size_t ext_block_offset; /* offset to start of ext blocks array */
347 size_t ext_block_size; /* size per element */
348 int num_ext_blocks; /* number of extension blocks */
349
350 /* static limit on num_ext_blocks, derived from bitstream limitations */
351 #define AV_DOVI_MAX_EXT_BLOCKS 32
352 } AVDOVIMetadata;
353
354 static av_always_inline AVDOVIRpuDataHeader *
355 4 av_dovi_get_header(const AVDOVIMetadata *data)
356 {
357 4 return (AVDOVIRpuDataHeader *)((uint8_t *) data + data->header_offset);
358 }
359
360 static av_always_inline AVDOVIDataMapping *
361 4 av_dovi_get_mapping(const AVDOVIMetadata *data)
362 {
363 4 return (AVDOVIDataMapping *)((uint8_t *) data + data->mapping_offset);
364 }
365
366 static av_always_inline AVDOVIColorMetadata *
367 4 av_dovi_get_color(const AVDOVIMetadata *data)
368 {
369 4 return (AVDOVIColorMetadata *)((uint8_t *) data + data->color_offset);
370 }
371
372 static av_always_inline AVDOVIDmData *
373 2 av_dovi_get_ext(const AVDOVIMetadata *data, int index)
374 {
375 4 return (AVDOVIDmData *)((uint8_t *) data + data->ext_block_offset +
376 2 data->ext_block_size * index);
377 }
378
379 /**
380 * Find an extension block with a given level, or NULL. In the case of
381 * multiple extension blocks, only the first is returned.
382 */
383 AVDOVIDmData *av_dovi_find_level(const AVDOVIMetadata *data, uint8_t level);
384
385 /**
386 * Allocate an AVDOVIMetadata structure and initialize its
387 * fields to default values.
388 *
389 * @param size If this parameter is non-NULL, the size in bytes of the
390 * allocated struct will be written here on success
391 *
392 * @return the newly allocated struct or NULL on failure
393 */
394 AVDOVIMetadata *av_dovi_metadata_alloc(size_t *size);
395
396 #endif /* AVUTIL_DOVI_META_H */
397