multilayer_metadata.h (5402B)
1 /* 2 * Copyright (c) 2024, Alliance for Open Media. All rights reserved. 3 * 4 * This source code is subject to the terms of the BSD 2 Clause License and 5 * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License 6 * was not distributed with this source code in the LICENSE file, you can 7 * obtain it at www.aomedia.org/license/software. If the Alliance for Open 8 * Media Patent License 1.0 was not distributed with this source code in the 9 * PATENTS file, you can obtain it at www.aomedia.org/license/patent. 10 */ 11 12 // Experimental multilayer metadata defined in CWG-E050. 13 14 #ifndef AOM_EXAMPLES_MULTILAYER_METADATA_H_ 15 #define AOM_EXAMPLES_MULTILAYER_METADATA_H_ 16 17 #include <cstdint> 18 #include <utility> 19 #include <vector> 20 21 namespace libaom_examples { 22 23 // std::pair<T, bool> is used to indicate presence of a field, 24 // like an std::optional (which cannot be used because it's C++17). 25 // If the boolean is true, then the value is present. 26 27 struct ColorProperties { 28 bool color_range; // true for full range values 29 uint8_t color_primaries; 30 uint8_t transfer_characteristics; 31 uint8_t matrix_coefficients; 32 }; 33 34 enum AlphaUse { 35 ALPHA_STRAIGHT = 0, 36 ALPHA_PREMULTIPLIED = 1, 37 ALPHA_UNSPECIFIED = 2, 38 // 3 is reserved. 39 }; 40 41 struct AlphaInformation { 42 AlphaUse alpha_use_idc; // [0, 3] 43 bool alpha_simple_flag; // If true, all fields below are ignored. 44 uint8_t alpha_bit_depth; // [8, 15] 45 uint8_t alpha_clip_idc; // [0, 3] 46 bool alpha_incr_flag; 47 uint16_t alpha_transparent_value; // [0, 1<<(alpha_bit_depth+1)) 48 uint16_t alpha_opaque_value; // [0, 1<<(alpha_bit_depth+1)) 49 std::pair<ColorProperties, bool> alpha_color_description; 50 }; 51 52 struct DepthRepresentationElement { 53 bool sign_flag; 54 uint8_t exponent; // [0, 126] (biased exponent) 55 uint8_t mantissa_len; // [1, 32] 56 uint32_t mantissa; 57 }; 58 59 struct DepthInformation { 60 std::pair<DepthRepresentationElement, bool> z_near; 61 std::pair<DepthRepresentationElement, bool> z_far; 62 std::pair<DepthRepresentationElement, bool> d_min; 63 std::pair<DepthRepresentationElement, bool> d_max; 64 uint8_t depth_representation_type; // [0, 2]. Values 3 to 15 are reserved. 65 // Only relevant if d_min or d_max are present. 66 uint8_t disparity_ref_view_id; // [0, 3] 67 }; 68 69 enum MultilayerUseCase { 70 MULTILAYER_USE_CASE_UNSPECIFIED = 0, 71 MULTILAYER_USE_CASE_GLOBAL_ALPHA = 1, 72 MULTILAYER_USE_CASE_GLOBAL_DEPTH = 2, 73 MULTILAYER_USE_CASE_ALPHA = 3, 74 MULTILAYER_USE_CASE_DEPTH = 4, 75 MULTILAYER_USE_CASE_STEREO = 5, 76 MULTILAYER_USE_CASE_STEREO_GLOBAL_ALPHA = 6, 77 MULTILAYER_USE_CASE_STEREO_GLOBAL_DEPTH = 7, 78 MULTILAYER_USE_CASE_STEREO_ALPHA = 8, 79 MULTILAYER_USE_CASE_STEREO_DEPTH = 9, 80 MULTILAYER_USE_CASE_444_GLOBAL_ALPHA = 10, 81 MULTILAYER_USE_CASE_444_GLOBAL_DEPTH = 11, 82 MULTILAYER_USE_CASE_444 = 12, 83 MULTILAYER_USE_CASE_420_444 = 13, 84 // 14 to 63 are reserved. 85 }; 86 87 enum LayerType { 88 MULTILAYER_LAYER_TYPE_UNSPECIFIED = 0, 89 MULTILAYER_LAYER_TYPE_TEXTURE = 1, 90 MULTILAYER_LAYER_TYPE_TEXTURE_1 = 2, 91 MULTILAYER_LAYER_TYPE_TEXTURE_2 = 3, 92 MULTILAYER_LAYER_TYPE_TEXTURE_3 = 4, 93 MULTILAYER_LAYER_TYPE_ALPHA = 5, 94 MULTILAYER_LAYER_TYPE_DEPTH = 6, 95 // 7 to 31 are reserved. 96 }; 97 98 enum MultilayerMetadataScope { 99 SCOPE_UNSPECIFIED = 0, 100 SCOPE_LOCAL = 1, 101 SCOPE_GLOBAL = 2, 102 SCOPE_MIXED = 3, 103 }; 104 105 enum MultilayerViewType { 106 VIEW_UNSPECIFIED = 0, 107 VIEW_CENTER = 1, 108 VIEW_LEFT = 2, 109 VIEW_RIGHT = 3, 110 // 4 to 7 are reserved. 111 }; 112 113 struct FrameLocalMetadata { 114 long frame_idx; 115 // Relevant for MULTILAYER_LAYER_TYPE_ALPHA with scope != SCOPE_GLOBAL. 116 AlphaInformation alpha; 117 // Relevant for MULTILAYER_LAYER_TYPE_DEPTH with scope != SCOPE_GLOBAL. 118 DepthInformation depth; 119 }; 120 121 struct LayerMetadata { 122 LayerType layer_type; // [0, 31] 123 bool luma_plane_only_flag; 124 MultilayerViewType layer_view_type; // [0, 7] 125 uint8_t group_id; // [0, 3] 126 uint8_t layer_dependency_idc; // [0, 7] 127 MultilayerMetadataScope layer_metadata_scope; // [0, 3] 128 129 std::pair<ColorProperties, bool> layer_color_description; 130 131 // Relevant for MULTILAYER_LAYER_TYPE_ALPHA with scope >= SCOPE_GLOBAL. 132 AlphaInformation alpha; 133 // Relevant for MULTILAYER_LAYER_TYPE_DEPTH with scope >= SCOPE_GLOBAL. 134 DepthInformation depth; 135 136 // Relevant when scope != SCOPE_GLOBAL. 137 std::vector<FrameLocalMetadata> local_metadata; 138 }; 139 140 struct MultilayerMetadata { 141 MultilayerUseCase use_case; // [0, 63] 142 std::vector<LayerMetadata> layers; // max size 4 143 }; 144 145 // Parses a multilayer metadata file. 146 // The metadata is expected to be in a subset of the YAML format supporting 147 // simple lists and maps with integer values, and comments. 148 // Checks that the metadata is valid and terminates the process in case of 149 // error. 150 bool parse_multilayer_file(const char *metadata_path, 151 MultilayerMetadata *multilayer); 152 153 // Prints the multilayer metadata to stdout for debugging. 154 void print_multilayer_metadata(const MultilayerMetadata &multilayer); 155 156 // Converts a double value to a DepthRepresentationElement struct. 157 bool double_to_depth_representation_element( 158 double v, DepthRepresentationElement *element); 159 // Converts a DepthRepresentationElement struct to a double value. 160 double depth_representation_element_to_double( 161 const DepthRepresentationElement &e); 162 163 } // namespace libaom_examples 164 165 #endif // AOM_EXAMPLES_MULTILAYER_METADATA_H_