libavutil/dovi_meta.h

   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 av_dovi_get_header(const AVDOVIMetadata *data)
 356 {
 357     return (AVDOVIRpuDataHeader *)((uint8_t *) data + data->header_offset);
 358 }
 359
 360 static av_always_inline AVDOVIDataMapping *
 361 av_dovi_get_mapping(const AVDOVIMetadata *data)
 362 {
 363     return (AVDOVIDataMapping *)((uint8_t *) data + data->mapping_offset);
 364 }
 365
 366 static av_always_inline AVDOVIColorMetadata *
 367 av_dovi_get_color(const AVDOVIMetadata *data)
 368 {
 369     return (AVDOVIColorMetadata *)((uint8_t *) data + data->color_offset);
 370 }
 371
 372 static av_always_inline AVDOVIDmData *
 373 av_dovi_get_ext(const AVDOVIMetadata *data, int index)
 374 {
 375     return (AVDOVIDmData *)((uint8_t *) data + data->ext_block_offset +
 376                             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 */