1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 /** 17 ************************************************************************ 18 * @fil M4AD_Common.h 19 * @brief Audio Shell Decoder common interface declaration 20 * @note This file declares the common interfaces that audio decoder shells must implement 21 ************************************************************************ 22 */ 23 #ifndef __M4AD_COMMON_H__ 24 #define __M4AD_COMMON_H__ 25 26 #include "M4OSA_Types.h" 27 #include "M4OSA_Error.h" 28 #include "M4OSA_OptionID.h" 29 #include "M4OSA_CoreID.h" 30 #include "M4DA_Types.h" 31 #include "M4TOOL_VersionInfo.h" 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 38 typedef M4OSA_Void* M4AD_Context; 39 40 /** 41 ************************************************************************ 42 * enum M4AD_OptionID 43 * @brief This enum defines the Audio decoder options. 44 * @note These options can be read from or written to a decoder via 45 * M4AD_getOption_fct/M4AD_setOption_fct 46 ************************************************************************ 47 */ 48 typedef enum 49 { 50 /** 51 * Set the flag of presence of protection */ 52 M4AD_kOptionID_ProtectionAbsent = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x01), 53 54 /** 55 * Set the number of frames per bloc */ 56 M4AD_kOptionID_NbFramePerBloc = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x02), 57 58 /** 59 * Set the AAC decoder user parameters */ 60 M4AD_kOptionID_UserParam = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x03), 61 62 63 /** 64 * Get the AAC steam type */ 65 M4AD_kOptionID_StreamType = M4OSA_OPTION_ID_CREATE(M4_READ , M4DECODER_AUDIO, 0x10), 66 67 /** 68 * Get the number of used bytes in the latest decode 69 (used only when decoding AAC from ADIF file) */ 70 M4AD_kOptionID_UsedBytes = M4OSA_OPTION_ID_CREATE(M4_READ , M4DECODER_AUDIO, 0x11), 71 72 /* Reader Interface */ 73 M4AD_kOptionID_3gpReaderInterface = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x012), 74 75 /* Audio Access Unit */ 76 M4AD_kOptionID_AudioAU = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x13), 77 78 /* Reader error code */ 79 M4AD_kOptionID_GetAudioAUErrCode = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x14), 80 81 /* Number of channels */ 82 M4AD_kOptionID_AudioNbChannels = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x15), 83 84 /* Sampling frequency */ 85 M4AD_kOptionID_AudioSampFrequency = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x16), 86 87 /* Audio AU CTS */ 88 M4AD_kOptionID_AuCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x17) 89 90 } M4AD_OptionID; 91 92 93 94 typedef enum 95 { 96 M4_kUnknown = 0, /* Unknown stream type */ 97 M4_kAAC, /* M4_kAAC_MAIN or M4_kAAC_LC or M4_kAAC_SSR or M4_kAAC_LTP */ 98 M4_kAACplus, /* Decoder type is AAC plus */ 99 M4_keAACplus /* Decoder type is enhanced AAC plus */ 100 } M4_AACType; 101 102 /** 103 ************************************************************************ 104 * enum M4AD_Type 105 * @brief This enum defines the audio types used to create decoders 106 * @note This enum is used internally by the VPS to identify a currently supported 107 * audio decoder interface. Each decoder is registered with one of this type associated. 108 * When a decoder instance is needed, this type is used to identify 109 * and retrieve its interface. 110 ************************************************************************ 111 */ 112 typedef enum 113 { 114 M4AD_kTypeAMRNB = 0, 115 M4AD_kTypeAMRWB, 116 M4AD_kTypeAAC, 117 M4AD_kTypeMP3, 118 M4AD_kTypePCM, 119 M4AD_kTypeBBMusicEngine, 120 M4AD_kTypeWMA, 121 M4AD_kTypeRMA, 122 M4AD_kTypeADPCM, 123 M4AD_kType_NB /* number of decoders, keep it as last enum entry */ 124 125 } M4AD_Type ; 126 127 128 129 /** 130 ************************************************************************ 131 * structure M4AD_Buffer 132 * @brief Structure to describe a buffer 133 ************************************************************************ 134 */ 135 typedef struct 136 { 137 M4OSA_MemAddr8 m_dataAddress; 138 M4OSA_UInt32 m_bufferSize; 139 int64_t m_timeStampUs; 140 } M4AD_Buffer; 141 142 /** 143 ************************************************************************ 144 * @brief Creates an instance of the decoder 145 * @note Allocates the context 146 * 147 * @param pContext: (OUT) Context of the decoder 148 * @param pStreamHandler: (IN) Pointer to an audio stream description 149 * @param pUserData: (IN) Pointer to User data 150 * 151 * @return M4NO_ERROR there is no error 152 * @return M4ERR_STATE State automaton is not applied 153 * @return M4ERR_ALLOC a memory allocation has failed 154 * @return M4ERR_PARAMETER at least one parameter is not properly set (in DEBUG only) 155 ************************************************************************ 156 */ 157 158 typedef M4OSA_ERR (M4AD_create_fct)(M4AD_Context *pContext, 159 M4_AudioStreamHandler *pStreamHandler, void* pUserData); 160 161 162 /** 163 ************************************************************************ 164 * @brief Destroys the instance of the decoder 165 * @note After this call the context is invalid 166 * 167 * @param context: (IN) Context of the decoder 168 * 169 * @return M4NO_ERROR There is no error 170 * @return M4ERR_PARAMETER The context is invalid (in DEBUG only) 171 ************************************************************************ 172 */ 173 typedef M4OSA_ERR (M4AD_destroy_fct) (M4AD_Context context); 174 175 /** 176 ************************************************************************ 177 * @brief Decodes the given audio data 178 * @note Parses and decodes the next audio frame, from the given buffer. 179 * This function changes pInputBufferSize value according to the amount 180 * of data actually read. 181 * 182 * @param context: (IN) Context of the decoder 183 * @param inputBuffer: (IN/OUT)Input Data buffer. It contains at least one audio frame. 184 * The size of the buffer must be updated inside the 185 * function to reflect the size of the actually decoded data. 186 * (e.g. the first frame in pInputBuffer) 187 * @param decodedPCMBuffer: (OUT) Output PCM buffer (decoded data). 188 * @param jumping: (IN) M4OSA_TRUE if a jump was just done, M4OSA_FALSE otherwise. 189 * @return M4NO_ERROR there is no error 190 * @return M4ERR_PARAMETER at least one parameter is not properly set 191 ************************************************************************ 192 */ 193 typedef M4OSA_ERR (M4AD_step_fct) (M4AD_Context context, M4AD_Buffer *pInputBuffer, 194 M4AD_Buffer *pDecodedPCMBuffer, M4OSA_Bool jumping); 195 196 /** 197 ************************************************************************ 198 * @brief Gets the decoder version 199 * @note The version is given in a M4_VersionInfo structure 200 * 201 * @param pValue: (OUT) Pointer to the version structure 202 * 203 * @return M4NO_ERROR there is no error 204 * @return M4ERR_PARAMETER The given pointer is null (in DEBUG only) 205 ************************************************************************ 206 */ 207 typedef M4OSA_ERR (M4AD_getVersion_fct)(M4_VersionInfo* pVersionInfo); 208 209 210 /** 211 ************************************************************************ 212 * @brief This function creates the AAC core decoder according to 213 * the stream properties and to the options that may 214 * have been set using M4AD_setOption_fct 215 * @note Creates an instance of the AAC decoder 216 * @note This function is used especially by the AAC decoder 217 * 218 * @param pContext: (IN/OUT) Context of the decoder 219 * @param pStreamHandler: (IN) Pointer to an audio stream description 220 * 221 * @return M4NO_ERROR there is no error 222 * @return M4ERR_STATE State automaton is not applied 223 * @return M4ERR_ALLOC a memory allocation has failed 224 * @return M4ERR_PARAMETER at least one parameter is not properly set (in DEBUG only) 225 ************************************************************************ 226 */ 227 typedef M4OSA_ERR (M4AD_start_fct) (M4AD_Context pContext); 228 229 /** 230 ************************************************************************ 231 * @brief Reset the instance of the decoder 232 * 233 * @param context: (IN) Context of the decoder 234 * 235 * @return M4NO_ERROR There is no error 236 * @return M4ERR_PARAMETER The context is invalid (in DEBUG only) 237 ************************************************************************ 238 */ 239 typedef M4OSA_ERR (M4AD_reset_fct) (M4AD_Context context); 240 241 242 /** 243 ************************************************************************ 244 * @brief set en option value of the audio decoder 245 * 246 * @param context: (IN) Context of the decoder 247 * @param optionId: (IN) indicates the option to set 248 * @param pValue: (IN) pointer to structure or value (allocated by user) 249 * where option is stored 250 * @return M4NO_ERROR there is no error 251 * @return M4ERR_BAD_CONTEXT provided context is not a valid one 252 * @return M4ERR_PARAMETER at least one parameter is not properly set 253 * @return M4ERR_BAD_OPTION_ID when the option ID is not a valid one 254 ************************************************************************ 255 */ 256 typedef M4OSA_ERR (M4AD_setOption_fct) (M4AD_Context context, 257 M4OSA_OptionID optionId, M4OSA_DataOption pValue); 258 259 /** 260 ************************************************************************ 261 * @brief Get en option value of the audio decoder 262 * 263 * @param context: (IN) Context of the decoder 264 * @param optionId: (IN) indicates the option to set 265 * @param pValue: (OUT) pointer to structure or value (allocated by user) 266 * where option is stored 267 * @return M4NO_ERROR there is no error 268 * @return M4ERR_BAD_CONTEXT provided context is not a valid one 269 * @return M4ERR_PARAMETER at least one parameter is not properly set 270 * @return M4ERR_BAD_OPTION_ID when the option ID is not a valid one 271 ************************************************************************ 272 */ 273 typedef M4OSA_ERR (M4AD_getOption_fct) (M4AD_Context context, M4OSA_OptionID optionId, 274 M4OSA_DataOption pValue); 275 /** 276 ************************************************************************ 277 * structure M4AD_Interface 278 * @brief This structure defines the generic audio decoder interface 279 * @note This structure stores the pointers to functions of one audio decoder type. 280 * The decoder type is one of the M4AD_Type 281 ************************************************************************ 282 */ 283 typedef struct _M4AD_Interface 284 { 285 286 M4AD_create_fct* m_pFctCreateAudioDec; 287 M4AD_start_fct* m_pFctStartAudioDec; 288 M4AD_step_fct* m_pFctStepAudioDec; 289 M4AD_getVersion_fct* m_pFctGetVersionAudioDec; 290 M4AD_destroy_fct* m_pFctDestroyAudioDec; 291 M4AD_reset_fct* m_pFctResetAudioDec; 292 M4AD_setOption_fct* m_pFctSetOptionAudioDec; 293 M4AD_getOption_fct* m_pFctGetOptionAudioDec; 294 295 } M4AD_Interface; 296 297 #ifdef __cplusplus 298 } 299 #endif 300 301 #endif /*__M4AD_COMMON_H__*/ 302 303