1 /* 2 * Copyright (c) 2023, Alliance for Open Media. All rights reserved 3 * 4 * This source code is subject to the terms of the BSD 3-Clause Clear License 5 * and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear 6 * License was not distributed with this source code in the LICENSE file, you 7 * can obtain it at www.aomedia.org/license/software-license/bsd-3-c-c. If the 8 * Alliance for Open Media Patent License 1.0 was not distributed with this 9 * source code in the PATENTS file, you can obtain it at 10 * www.aomedia.org/license/patent. 11 */ 12 #ifndef OBU_PARAM_DEFINITIONS_H_ 13 #define OBU_PARAM_DEFINITIONS_H_ 14 15 #include <cstdint> 16 #include <limits> 17 #include <memory> 18 #include <optional> 19 #include <vector> 20 21 #include "absl/log/check.h" 22 #include "absl/status/status.h" 23 #include "iamf/common/read_bit_buffer.h" 24 #include "iamf/common/write_bit_buffer.h" 25 #include "iamf/obu/param_definitions.h" 26 #include "iamf/obu/types.h" 27 28 namespace iamf_tools { 29 30 /* !\brief Forward declarartion of `ParameterData`. */ 31 struct ParameterData; 32 33 /* !\brief Common part of the parameter definitions. 34 * 35 * Extended by `MixGainParamDefinition`, `DemixingParamDefinition`, and 36 * `ReconGainParamDefinition`. 37 */ 38 class ParamDefinition { 39 public: 40 /*!\brief A `DecodedUleb128` enum for the type of parameter. */ 41 enum ParameterDefinitionType : DecodedUleb128 { 42 kParameterDefinitionMixGain = 0, 43 kParameterDefinitionDemixing = 1, 44 kParameterDefinitionReconGain = 2, 45 // Values in the range of [3, (1 << 32) - 1] are reserved. 46 kParameterDefinitionReservedStart = 3, 47 kParameterDefinitionReservedEnd = std::numeric_limits<DecodedUleb128>::max() 48 }; 49 50 /*!\brief Default constructor. 51 * 52 * After constructing `InitializeSubblockDurations()` MUST be called 53 * before using most functionality. 54 */ 55 ParamDefinition() = default; 56 57 /*!\brief Default destructor. 58 */ 59 virtual ~ParamDefinition() = default; 60 61 /*!\brief Gets the number of subblocks. 62 * 63 * \return Number of subblocks. 64 */ 65 DecodedUleb128 GetNumSubblocks() const; 66 67 /*!\brief Initializes the subblock durations. 68 * 69 * This must be called before calling `SetSubblockDuration()` and 70 * `GetSubblockDuration()`. 71 * 72 * \param num_subblocks Number of subblocks. 73 */ 74 void InitializeSubblockDurations(DecodedUleb128 num_subblocks); 75 76 /*!\brief Gets the subblock duration. 77 * 78 * \param subblock_index Index of the subblock to get the duration. 79 * \return Duration of the subblock. 80 */ 81 DecodedUleb128 GetSubblockDuration(int subblock_index) const; 82 83 /*!\brief Sets the subblock duration. 84 * 85 * \param subblock_index Index of the subblock to set the duration. 86 * \param duration Duration to set. 87 * \return `absl::OkStatus()` if successful. A specific status on failure. 88 */ 89 absl::Status SetSubblockDuration(int subblock_index, DecodedUleb128 duration); 90 91 /*!\brief Validates the parameter definition called by `ValidateAndWrite()`. 92 * 93 * \return `absl::OkStatus()` if successful. A specific status on failure. 94 */ 95 absl::Status Validate() const; 96 97 /*!\brief Validates and writes the parameter definition. 98 * 99 * This function defines the validating and writing of the common parts, 100 * and the sub-classes's overridden ones shall define their specific parts. 101 * 102 * \param wb Buffer to write to. 103 * \return `absl::OkStatus()` if successful. A specific status on failure. 104 */ 105 virtual absl::Status ValidateAndWrite(WriteBitBuffer& wb) const; 106 107 /*!\brief Reads and validates the parameter definition. 108 * 109 * This function defines the validating and reading of the common parts, 110 * and the sub-classes's overridden ones shall define their specific parts. 111 * 112 * \param rb Buffer to read from. 113 * \return `absl::OkStatus()` if successful. A specific status on failure. 114 */ 115 virtual absl::Status ReadAndValidate(ReadBitBuffer& rb); 116 117 /*!\brief Gets the `ParameterDefinitionType`. 118 * 119 * \return Type of this parameter definition. 120 */ GetType()121 std::optional<ParameterDefinitionType> GetType() const { return type_; } 122 123 /*!\brief Creates a parameter data. 124 * 125 * The created instance will one of the subclassees of `ParameterData`, 126 * depending on the specific subclass implementing this function. 127 * 128 * \return Unique pointer to the created parameter data. 129 */ 130 virtual std::unique_ptr<ParameterData> CreateParameterData() const = 0; 131 132 /*!\brief Prints the parameter definition. 133 */ 134 virtual void Print() const; 135 136 friend bool operator==(const ParamDefinition& lhs, 137 const ParamDefinition& rhs) = default; 138 139 DecodedUleb128 parameter_id_ = 0; 140 DecodedUleb128 parameter_rate_ = 0; 141 uint8_t param_definition_mode_ = 0; // 1 bit. 142 uint8_t reserved_ = 0; // 7 bits. 143 144 // All fields below are only included if `param_definition_mode_ == 0`. 145 DecodedUleb128 duration_ = 0; 146 DecodedUleb128 constant_subblock_duration_ = 0; 147 148 protected: 149 /*!\brief Constructor with a passed-in type used by sub-classes. 150 * 151 * \param type Type of the specific parameter definition. 152 */ ParamDefinition(ParameterDefinitionType type)153 ParamDefinition(ParameterDefinitionType type) : type_(type) {} 154 155 private: 156 /*!\brief Whether the subblock durations are included in this object. 157 * 158 * \return True if the subblock durations are included. 159 */ 160 bool IncludeSubblockDurationArray() const; 161 162 // Type of this parameter definition. 163 std::optional<ParameterDefinitionType> type_ = std::nullopt; 164 165 // `num_subblocks` is only included if `param_definition_mode_ == 0` and 166 // `constant_subblock_duration == 0`. 167 DecodedUleb128 num_subblocks_ = 0; 168 169 // Vector of length `num_subblocks`. 170 std::vector<DecodedUleb128> subblock_durations_ = {}; 171 }; 172 173 /* !\brief Parameter definition of mix gains to be applied to a signal. 174 */ 175 class MixGainParamDefinition : public ParamDefinition { 176 public: 177 /*!\brief Default constructor. 178 */ MixGainParamDefinition()179 MixGainParamDefinition() : ParamDefinition(kParameterDefinitionMixGain) {} 180 181 /*!\brief Default destructor. 182 */ 183 ~MixGainParamDefinition() override = default; 184 185 /*!\brief Validates and writes to a buffer. 186 * 187 * \param wb Buffer to write to. 188 * \return `absl::OkStatus()` if successful. A specific status on failure. 189 */ 190 absl::Status ValidateAndWrite(WriteBitBuffer& wb) const override; 191 192 /*!\brief Reads from a buffer and validates the resulting output. 193 * 194 * \param rb Buffer to read from. 195 * \return `absl::OkStatus()` if successful. A specific status on failure. 196 */ 197 absl::Status ReadAndValidate(ReadBitBuffer& rb) override; 198 /*!\brief Creates a parameter data. 199 * 200 * The created instance will be of type `MixGainParameterData`. 201 * 202 * \return Unique pointer to the created parameter data. 203 */ 204 std::unique_ptr<ParameterData> CreateParameterData() const override; 205 206 /*!\brief Prints the parameter definition. 207 */ 208 void Print() const override; 209 210 friend bool operator==(const MixGainParamDefinition& lhs, 211 const MixGainParamDefinition& rhs) = default; 212 213 int16_t default_mix_gain_; 214 }; 215 216 struct ChannelNumbers { 217 friend bool operator==(const ChannelNumbers& lhs, 218 const ChannelNumbers& rhs) = default; 219 // Number of surround channels. 220 int surround; 221 // Number of low-frequency effects channels. 222 int lfe; 223 // Number of height channels. 224 int height; 225 }; 226 227 /* !\brief Parameter definition for recon gain. 228 */ 229 class ReconGainParamDefinition : public ParamDefinition { 230 public: 231 /* Additional data useful for creating parameter (sub)blocks. 232 * 233 * Present only in some intermediate stages of encoder, decoder, and 234 * transcoder and are will not be read from/written to bitstreams. 235 */ 236 struct ReconGainAuxiliaryData { 237 bool recon_gain_is_present_flag; 238 ChannelNumbers channel_numbers_for_layer; 239 friend bool operator==(const ReconGainAuxiliaryData& lhs, 240 const ReconGainAuxiliaryData& rhs) = default; 241 }; 242 243 /*!\brief Constructor. 244 * 245 * \param audio_element_id ID of the Audio Element OBU that uses this 246 * recon gain parameter. 247 */ ReconGainParamDefinition(uint32_t audio_element_id)248 ReconGainParamDefinition(uint32_t audio_element_id) 249 : ParamDefinition(kParameterDefinitionReconGain), 250 audio_element_id_(audio_element_id) {} 251 252 /*!\brief Default destructor. 253 */ 254 ~ReconGainParamDefinition() override = default; 255 256 /*!\brief Validates and writes to a buffer. 257 * 258 * \param wb Buffer to write to. 259 * \return `absl::OkStatus()` if successful. A specific status on failure. 260 */ 261 absl::Status ValidateAndWrite(WriteBitBuffer& wb) const override; 262 263 /*!\brief Reads from a buffer and validates the resulting output. 264 * 265 * \param rb Buffer to read from. 266 * \return `absl::OkStatus()` if successful. A specific status on failure. 267 */ 268 absl::Status ReadAndValidate(ReadBitBuffer& rb) override; 269 270 /*!\brief Creates a parameter data. 271 * 272 * The created instance will be of type `ReconGainInfoParameterData`. 273 * 274 * \return Unique pointer to the created parameter data. 275 */ 276 std::unique_ptr<ParameterData> CreateParameterData() const override; 277 278 /*!\brief Prints the parameter definition. 279 */ 280 void Print() const override; 281 282 friend bool operator==(const ReconGainParamDefinition& lhs, 283 const ReconGainParamDefinition& rhs) = default; 284 285 /*!\brief ID of the Audio Element OBU that uses this recon gain parameter. 286 */ 287 const uint32_t audio_element_id_; 288 289 // Vector of size equal to the number of layers in the corresponding 290 // audio element. 291 std::vector<ReconGainAuxiliaryData> aux_data_; 292 }; 293 294 /* !\brief Parameter definition reserved for future use; should be ignored. 295 */ 296 class ExtendedParamDefinition : public ParamDefinition { 297 public: 298 /*!\brief Default constructor. 299 */ ExtendedParamDefinition(ParamDefinition::ParameterDefinitionType type)300 explicit ExtendedParamDefinition( 301 ParamDefinition::ParameterDefinitionType type) 302 : ParamDefinition(type) {} 303 304 /*!\brief Default destructor. 305 */ 306 ~ExtendedParamDefinition() override = default; 307 308 /*!\brief Validates and writes a `ExtendedParamDefinition` to a buffer. 309 * 310 * \param wb Buffer to write to. 311 * \return `absl::OkStatus()` if successful. A specific status on failure. 312 */ 313 absl::Status ValidateAndWrite(WriteBitBuffer& wb) const override; 314 315 /*!\brief Reads from a buffer and validates the resulting output. 316 * 317 * \param rb Buffer to read from. 318 * \return `absl::OkStatus()` if successful. A specific status on failure. 319 */ 320 absl::Status ReadAndValidate(ReadBitBuffer& rb) override; 321 322 /*!\brief Creates a parameter data. 323 * 324 * The created instance will be of type `ExtensionParameterData`. 325 * 326 * \return Unique pointer to the created parameter data. 327 */ 328 std::unique_ptr<ParameterData> CreateParameterData() const override; 329 330 /*!\brief Prints the parameter definition. 331 */ 332 void Print() const override; 333 334 friend bool operator==(const ExtendedParamDefinition& lhs, 335 const ExtendedParamDefinition& rhs) = default; 336 337 // Size and vector of the bytes the OBU parser should ignore. 338 DecodedUleb128 param_definition_size_ = 0; 339 std::vector<uint8_t> param_definition_bytes_ = {}; 340 }; 341 342 } // namespace iamf_tools 343 344 #endif // OBU_PARAM_DEFINITIONS_H_ 345