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 #include "rational.h"
33
34 /*
35 * DOVI configuration
36 * ref: dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2
37 dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2
38 * @code
39 * uint8_t dv_version_major, the major version number that the stream complies with
40 * uint8_t dv_version_minor, the minor version number that the stream complies with
41 * uint8_t dv_profile, the Dolby Vision profile
42 * uint8_t dv_level, the Dolby Vision level
43 * uint8_t rpu_present_flag
44 * uint8_t el_present_flag
45 * uint8_t bl_present_flag
46 * uint8_t dv_bl_signal_compatibility_id
47 * @endcode
48 *
49 * @note The struct must be allocated with av_dovi_alloc() and
50 * its size is not a part of the public ABI.
51 */
52 typedef struct AVDOVIDecoderConfigurationRecord {
53 uint8_t dv_version_major;
54 uint8_t dv_version_minor;
55 uint8_t dv_profile;
56 uint8_t dv_level;
57 uint8_t rpu_present_flag;
58 uint8_t el_present_flag;
59 uint8_t bl_present_flag;
60 uint8_t dv_bl_signal_compatibility_id;
61 } AVDOVIDecoderConfigurationRecord;
62
63 /**
64 * Allocate a AVDOVIDecoderConfigurationRecord structure and initialize its
65 * fields to default values.
66 *
67 * @return the newly allocated struct or NULL on failure
68 */
69 AVDOVIDecoderConfigurationRecord *av_dovi_alloc(size_t *size);
70
71 /**
72 * Dolby Vision RPU data header.
73 *
74 * @note sizeof(AVDOVIRpuDataHeader) is not part of the public ABI.
75 */
76 typedef struct AVDOVIRpuDataHeader {
77 uint8_t rpu_type;
78 uint16_t rpu_format;
79 uint8_t vdr_rpu_profile;
80 uint8_t vdr_rpu_level;
81 uint8_t chroma_resampling_explicit_filter_flag;
82 uint8_t coef_data_type; /* informative, lavc always converts to fixed */
83 uint8_t coef_log2_denom;
84 uint8_t vdr_rpu_normalized_idc;
85 uint8_t bl_video_full_range_flag;
86 uint8_t bl_bit_depth; /* [8, 16] */
87 uint8_t el_bit_depth; /* [8, 16] */
88 uint8_t vdr_bit_depth; /* [8, 16] */
89 uint8_t spatial_resampling_filter_flag;
90 uint8_t el_spatial_resampling_filter_flag;
91 uint8_t disable_residual_flag;
92 } AVDOVIRpuDataHeader;
93
94 enum AVDOVIMappingMethod {
95 AV_DOVI_MAPPING_POLYNOMIAL = 0,
96 AV_DOVI_MAPPING_MMR = 1,
97 };
98
99 /**
100 * Coefficients of a piece-wise function. The pieces of the function span the
101 * value ranges between two adjacent pivot values.
102 */
103 #define AV_DOVI_MAX_PIECES 8
104 typedef struct AVDOVIReshapingCurve {
105 uint8_t num_pivots; /* [2, 9] */
106 uint16_t pivots[AV_DOVI_MAX_PIECES + 1]; /* sorted ascending */
107 enum AVDOVIMappingMethod mapping_idc[AV_DOVI_MAX_PIECES];
108 /* AV_DOVI_MAPPING_POLYNOMIAL */
109 uint8_t poly_order[AV_DOVI_MAX_PIECES]; /* [1, 2] */
110 int64_t poly_coef[AV_DOVI_MAX_PIECES][3]; /* x^0, x^1, x^2 */
111 /* AV_DOVI_MAPPING_MMR */
112 uint8_t mmr_order[AV_DOVI_MAX_PIECES]; /* [1, 3] */
113 int64_t mmr_constant[AV_DOVI_MAX_PIECES];
114 int64_t mmr_coef[AV_DOVI_MAX_PIECES][3/* order - 1 */][7];
115 } AVDOVIReshapingCurve;
116
117 enum AVDOVINLQMethod {
118 AV_DOVI_NLQ_NONE = -1,
119 AV_DOVI_NLQ_LINEAR_DZ = 0,
120 };
121
122 /**
123 * Coefficients of the non-linear inverse quantization. For the interpretation
124 * of these, see ETSI GS CCM 001.
125 */
126 typedef struct AVDOVINLQParams {
127 uint16_t nlq_offset;
128 uint64_t vdr_in_max;
129 /* AV_DOVI_NLQ_LINEAR_DZ */
130 uint64_t linear_deadzone_slope;
131 uint64_t linear_deadzone_threshold;
132 } AVDOVINLQParams;
133
134 /**
135 * Dolby Vision RPU data mapping parameters.
136 *
137 * @note sizeof(AVDOVIDataMapping) is not part of the public ABI.
138 */
139 typedef struct AVDOVIDataMapping {
140 uint8_t vdr_rpu_id;
141 uint8_t mapping_color_space;
142 uint8_t mapping_chroma_format_idc;
143 AVDOVIReshapingCurve curves[3]; /* per component */
144
145 /* Non-linear inverse quantization */
146 enum AVDOVINLQMethod nlq_method_idc;
147 uint32_t num_x_partitions;
148 uint32_t num_y_partitions;
149 AVDOVINLQParams nlq[3]; /* per component */
150 } AVDOVIDataMapping;
151
152 /**
153 * Dolby Vision RPU colorspace metadata parameters.
154 *
155 * @note sizeof(AVDOVIColorMetadata) is not part of the public ABI.
156 */
157 typedef struct AVDOVIColorMetadata {
158 uint8_t dm_metadata_id;
159 uint8_t scene_refresh_flag;
160
161 /**
162 * Coefficients of the custom Dolby Vision IPT-PQ matrices. These are to be
163 * used instead of the matrices indicated by the frame's colorspace tags.
164 * The output of rgb_to_lms_matrix is to be fed into a BT.2020 LMS->RGB
165 * matrix based on a Hunt-Pointer-Estevez transform, but without any
166 * crosstalk. (See the definition of the ICtCp colorspace for more
167 * information.)
168 */
169 AVRational ycc_to_rgb_matrix[9]; /* before PQ linearization */
170 AVRational ycc_to_rgb_offset[3]; /* input offset of neutral value */
171 AVRational rgb_to_lms_matrix[9]; /* after PQ linearization */
172
173 /**
174 * Extra signal metadata (see Dolby patents for more info).
175 */
176 uint16_t signal_eotf;
177 uint16_t signal_eotf_param0;
178 uint16_t signal_eotf_param1;
179 uint32_t signal_eotf_param2;
180 uint8_t signal_bit_depth;
181 uint8_t signal_color_space;
182 uint8_t signal_chroma_format;
183 uint8_t signal_full_range_flag; /* [0, 3] */
184 uint16_t source_min_pq;
185 uint16_t source_max_pq;
186 uint16_t source_diagonal;
187 } AVDOVIColorMetadata;
188
189 /**
190 * Combined struct representing a combination of header, mapping and color
191 * metadata, for attaching to frames as side data.
192 *
193 * @note The struct must be allocated with av_dovi_metadata_alloc() and
194 * its size is not a part of the public ABI.
195 */
196
197 typedef struct AVDOVIMetadata {
198 /**
199 * Offset in bytes from the beginning of this structure at which the
200 * respective structs start.
201 */
202 size_t header_offset; /* AVDOVIRpuDataHeader */
203 size_t mapping_offset; /* AVDOVIDataMapping */
204 size_t color_offset; /* AVDOVIColorMetadata */
205 } AVDOVIMetadata;
206
207 static av_always_inline AVDOVIRpuDataHeader *
av_dovi_get_header(const AVDOVIMetadata * data)208 av_dovi_get_header(const AVDOVIMetadata *data)
209 {
210 return (AVDOVIRpuDataHeader *)((uint8_t *) data + data->header_offset);
211 }
212
213 static av_always_inline AVDOVIDataMapping *
av_dovi_get_mapping(const AVDOVIMetadata * data)214 av_dovi_get_mapping(const AVDOVIMetadata *data)
215 {
216 return (AVDOVIDataMapping *)((uint8_t *) data + data->mapping_offset);
217 }
218
219 static av_always_inline AVDOVIColorMetadata *
av_dovi_get_color(const AVDOVIMetadata * data)220 av_dovi_get_color(const AVDOVIMetadata *data)
221 {
222 return (AVDOVIColorMetadata *)((uint8_t *) data + data->color_offset);
223 }
224
225 /**
226 * Allocate an AVDOVIMetadata structure and initialize its
227 * fields to default values.
228 *
229 * @param size If this parameter is non-NULL, the size in bytes of the
230 * allocated struct will be written here on success
231 *
232 * @return the newly allocated struct or NULL on failure
233 */
234 AVDOVIMetadata *av_dovi_metadata_alloc(size_t *size);
235
236 #endif /* AVUTIL_DOVI_META_H */
237