M4AD_Common.h revision bc8e52dadeb078c45e62ebda17fd95e67f689654 
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
34extern "C" {
35#endif
36
37
38typedef 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*/
48typedef 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
94typedef 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*/
112typedef 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*/
135typedef 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
158typedef 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*/
173typedef 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*/
193typedef 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*/
207typedef 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*/
227typedef 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*/
239typedef 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*/
256typedef 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*/
273typedef 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*/
283typedef 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