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 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 13 #ifndef CLI_PARAMETERS_MANAGER_H_ 14 #define CLI_PARAMETERS_MANAGER_H_ 15 16 #include <cstdint> 17 18 #include "absl/container/flat_hash_map.h" 19 #include "absl/status/status.h" 20 #include "iamf/cli/audio_element_with_data.h" 21 #include "iamf/cli/parameter_block_with_data.h" 22 #include "iamf/obu/demixing_info_parameter_data.h" 23 #include "iamf/obu/demixing_param_definition.h" 24 #include "iamf/obu/param_definitions.h" 25 #include "iamf/obu/recon_gain_info_parameter_data.h" 26 #include "iamf/obu/types.h" 27 28 namespace iamf_tools { 29 30 /*!\brief Manages parameters and supports easy query. 31 * 32 * The class operates iteratively; holding one set of parameter blocks 33 * corresponding to the same frame (with the same start/end timestamps). 34 * 35 * For each frame: 36 * - Parameter blocks are added via `AddDemixingParameterBlock()` or 37 * `AddReconGainParameterBlock()`. 38 * - Parameter values can be queried via `GetDownMixingParameters()` or 39 * `GetReconGainInfoParameterData()`. 40 * - Caller (usually the audio frame generator) is responsible to tell this 41 * manager to advance to the next frame via `UpdateDemixingState()` or 42 * `UpdateReconGainState()`. 43 */ 44 class ParametersManager { 45 public: 46 /*!\brief Constructor. 47 * 48 * \param audio_elements Input Audio Element OBUs with data. 49 * \param parameter_blocks Input Parameter Block OBUs with data. 50 */ 51 ParametersManager( 52 const absl::flat_hash_map<DecodedUleb128, AudioElementWithData>& 53 audio_elements); 54 55 /*!\brief Initializes some internal data. 56 * 57 * \return `absl::OkStatus()` on success. A specific status on failure. 58 */ 59 absl::Status Initialize(); 60 61 /*!\brief Checks if a `DemixingParamDefinition` exists for an audio element. 62 * 63 * \param audio_element_id ID of the audio element to query. 64 * \return True if a `DemixingParamDefinition` is available for the audio 65 * element queried. 66 */ 67 bool DemixingParamDefinitionAvailable(DecodedUleb128 audio_element_id); 68 69 /*!\brief Gets current down-mixing parameters for an audio element. 70 * 71 * \param audio_element_id ID of the audio element that the parameters are 72 * to be applied. 73 * \param down_mixing_params Output down mixing parameters. 74 * \return `absl::OkStatus()` on success. A specific status on failure. 75 */ 76 absl::Status GetDownMixingParameters(DecodedUleb128 audio_element_id, 77 DownMixingParams& down_mixing_params); 78 79 /*!\brief Gets current recon gain info parameter data for an audio element. 80 * 81 * \param audio_element_id ID of the audio element that the parameters are 82 * to be applied. 83 * \param num_layers Number of layers in the audio element. 84 * \param recon_gain_info_parameter_data Output recon gain info parameter 85 * data. 86 * \return `absl::OkStatus()` on success. A specific status on failure. 87 */ 88 absl::Status GetReconGainInfoParameterData( 89 DecodedUleb128 audio_element_id, int32_t num_layers, 90 ReconGainInfoParameterData& recon_gain_info_parameter_data); 91 92 /*!\brief Adds a new demixing parameter block. 93 * 94 * \param parameter_block Pointer to the new demixing parameter block to add. 95 */ 96 void AddDemixingParameterBlock(const ParameterBlockWithData* parameter_block); 97 98 /*!\brief Adds a new recon gain parameter block. 99 * 100 * \param parameter_block Pointer to the new recon gain parameter block to 101 * add. 102 */ 103 void AddReconGainParameterBlock( 104 const ParameterBlockWithData* parameter_block); 105 106 /*!\brief Updates the state of demixing parameters for an audio element. 107 * 108 * Also validates the timestamp is as expected. 109 * 110 * \param audio_element_id Audio Element ID whose corresponding demixing 111 * state are to be updated. 112 * \param expected_next_timestamp Expected timestamp of the upcoming set of 113 * demixing parameter blocks. 114 * \return `absl::OkStatus()` on success. A specific status on failure. 115 */ 116 absl::Status UpdateDemixingState(DecodedUleb128 audio_element_id, 117 InternalTimestamp expected_next_timestamp); 118 119 /*!\brief Updates the state of recon gain parameters for an audio element. 120 * 121 * Also validates the timestamp is as expected. 122 * 123 * \param audio_element_id Audio Element ID whose corresponding recon gain 124 * state are to be updated. 125 * \param expected_new_timestamp Expected timestamp of the upcoming set of 126 * recon gain parameter blocks. 127 * \return `absl::OkStatus()` on success. A specific status on failure. 128 */ 129 absl::Status UpdateReconGainState(DecodedUleb128 audio_element_id, 130 InternalTimestamp expected_next_timestamp); 131 132 private: 133 // State used when generating demixing parameters for an audio element. 134 struct DemixingState { 135 const DemixingParamDefinition* param_definition; 136 137 // `w_idx` for the frame just processed, i.e. `wIdx(k - 1)` in the Spec. 138 int previous_w_idx; 139 140 // `w_idx` used to process the current frame, i.e. `wIdx(k)` in the Spec. 141 int w_idx; 142 143 // Timestamp for the next frame to be processed. 144 InternalTimestamp next_timestamp; 145 146 // Update rule of the currently tracked demixing parameters, because the 147 // first frame needs some special treatment. 148 DemixingInfoParameterData::WIdxUpdateRule update_rule; 149 }; 150 151 struct ReconGainState { 152 const ReconGainParamDefinition* param_definition; 153 154 // Timestamp for the next frame to be processed. 155 InternalTimestamp next_timestamp; 156 }; 157 158 // Mapping from Audio Element ID to audio element data. 159 const absl::flat_hash_map<DecodedUleb128, AudioElementWithData>& 160 audio_elements_; 161 162 // Mapping from Parameter ID to demixing parameter blocks. 163 absl::flat_hash_map<DecodedUleb128, const ParameterBlockWithData*> 164 demixing_parameter_blocks_; 165 166 // Mapping from Parameter ID to recon gain parameter blocks. 167 absl::flat_hash_map<DecodedUleb128, const ParameterBlockWithData*> 168 recon_gain_parameter_blocks_; 169 170 // Mapping from Audio Element ID to the demixing state. 171 absl::flat_hash_map<DecodedUleb128, DemixingState> demixing_states_; 172 173 // Mapping from Audio Element ID to the recon gain state. 174 absl::flat_hash_map<DecodedUleb128, ReconGainState> recon_gain_states_; 175 }; 176 177 } // namespace iamf_tools 178 179 #endif // CLI_PARAMETERS_MANAGER_H_ 180