/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
************************************************************************
* @fil M4AD_Common.h
* @brief Audio Shell Decoder common interface declaration
* @note This file declares the common interfaces that audio decoder shells must implement
************************************************************************
*/
#ifndef __M4AD_COMMON_H__
#define __M4AD_COMMON_H__
#include "M4OSA_Types.h"
#include "M4OSA_Error.h"
#include "M4OSA_OptionID.h"
#include "M4OSA_CoreID.h"
#include "M4DA_Types.h"
#include "M4TOOL_VersionInfo.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef M4OSA_Void* M4AD_Context;
/**
************************************************************************
* enum M4AD_OptionID
* @brief This enum defines the Audio decoder options.
* @note These options can be read from or written to a decoder via
* M4AD_getOption_fct/M4AD_setOption_fct
************************************************************************
*/
typedef enum
{
/**
* Set the flag of presence of protection */
M4AD_kOptionID_ProtectionAbsent = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x01),
/**
* Set the number of frames per bloc */
M4AD_kOptionID_NbFramePerBloc = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x02),
/**
* Set the AAC decoder user parameters */
M4AD_kOptionID_UserParam = M4OSA_OPTION_ID_CREATE(M4_WRITE, M4DECODER_AUDIO, 0x03),
/**
* Get the AAC steam type */
M4AD_kOptionID_StreamType = M4OSA_OPTION_ID_CREATE(M4_READ , M4DECODER_AUDIO, 0x10),
/**
* Get the number of used bytes in the latest decode
(used only when decoding AAC from ADIF file) */
M4AD_kOptionID_UsedBytes = M4OSA_OPTION_ID_CREATE(M4_READ , M4DECODER_AUDIO, 0x11),
/* Reader Interface */
M4AD_kOptionID_3gpReaderInterface = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x012),
/* Audio Access Unit */
M4AD_kOptionID_AudioAU = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x13),
/* Reader error code */
M4AD_kOptionID_GetAudioAUErrCode = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x14),
/* Number of channels */
M4AD_kOptionID_AudioNbChannels = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x15),
/* Sampling frequency */
M4AD_kOptionID_AudioSampFrequency = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x16),
/* Audio AU CTS */
M4AD_kOptionID_AuCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AUDIO, 0x17)
} M4AD_OptionID;
typedef enum
{
M4_kUnknown = 0, /* Unknown stream type */
M4_kAAC, /* M4_kAAC_MAIN or M4_kAAC_LC or M4_kAAC_SSR or M4_kAAC_LTP */
M4_kAACplus, /* Decoder type is AAC plus */
M4_keAACplus /* Decoder type is enhanced AAC plus */
} M4_AACType;
/**
************************************************************************
* enum M4AD_Type
* @brief This enum defines the audio types used to create decoders
* @note This enum is used internally by the VPS to identify a currently supported
* audio decoder interface. Each decoder is registered with one of this type associated.
* When a decoder instance is needed, this type is used to identify
* and retrieve its interface.
************************************************************************
*/
typedef enum
{
M4AD_kTypeAMRNB = 0,
M4AD_kTypeAMRWB,
M4AD_kTypeAAC,
M4AD_kTypeMP3,
M4AD_kTypePCM,
M4AD_kTypeBBMusicEngine,
M4AD_kTypeWMA,
M4AD_kTypeRMA,
M4AD_kTypeADPCM,
M4AD_kType_NB /* number of decoders, keep it as last enum entry */
} M4AD_Type ;
/**
************************************************************************
* structure M4AD_Buffer
* @brief Structure to describe a buffer
************************************************************************
*/
typedef struct
{
M4OSA_MemAddr8 m_dataAddress;
M4OSA_UInt32 m_bufferSize;
int64_t m_timeStampUs;
} M4AD_Buffer;
/**
************************************************************************
* @brief Creates an instance of the decoder
* @note Allocates the context
*
* @param pContext: (OUT) Context of the decoder
* @param pStreamHandler: (IN) Pointer to an audio stream description
* @param pUserData: (IN) Pointer to User data
*
* @return M4NO_ERROR there is no error
* @return M4ERR_STATE State automaton is not applied
* @return M4ERR_ALLOC a memory allocation has failed
* @return M4ERR_PARAMETER at least one parameter is not properly set (in DEBUG only)
************************************************************************
*/
typedef M4OSA_ERR (M4AD_create_fct)(M4AD_Context *pContext,
M4_AudioStreamHandler *pStreamHandler, void* pUserData);
/**
************************************************************************
* @brief Destroys the instance of the decoder
* @note After this call the context is invalid
*
* @param context: (IN) Context of the decoder
*
* @return M4NO_ERROR There is no error
* @return M4ERR_PARAMETER The context is invalid (in DEBUG only)
************************************************************************
*/
typedef M4OSA_ERR (M4AD_destroy_fct) (M4AD_Context context);
/**
************************************************************************
* @brief Decodes the given audio data
* @note Parses and decodes the next audio frame, from the given buffer.
* This function changes pInputBufferSize value according to the amount
* of data actually read.
*
* @param context: (IN) Context of the decoder
* @param inputBuffer: (IN/OUT)Input Data buffer. It contains at least one audio frame.
* The size of the buffer must be updated inside the
* function to reflect the size of the actually decoded data.
* (e.g. the first frame in pInputBuffer)
* @param decodedPCMBuffer: (OUT) Output PCM buffer (decoded data).
* @param jumping: (IN) M4OSA_TRUE if a jump was just done, M4OSA_FALSE otherwise.
* @return M4NO_ERROR there is no error
* @return M4ERR_PARAMETER at least one parameter is not properly set
************************************************************************
*/
typedef M4OSA_ERR (M4AD_step_fct) (M4AD_Context context, M4AD_Buffer *pInputBuffer,
M4AD_Buffer *pDecodedPCMBuffer, M4OSA_Bool jumping);
/**
************************************************************************
* @brief Gets the decoder version
* @note The version is given in a M4_VersionInfo structure
*
* @param pValue: (OUT) Pointer to the version structure
*
* @return M4NO_ERROR there is no error
* @return M4ERR_PARAMETER The given pointer is null (in DEBUG only)
************************************************************************
*/
typedef M4OSA_ERR (M4AD_getVersion_fct)(M4_VersionInfo* pVersionInfo);
/**
************************************************************************
* @brief This function creates the AAC core decoder according to
* the stream properties and to the options that may
* have been set using M4AD_setOption_fct
* @note Creates an instance of the AAC decoder
* @note This function is used especially by the AAC decoder
*
* @param pContext: (IN/OUT) Context of the decoder
* @param pStreamHandler: (IN) Pointer to an audio stream description
*
* @return M4NO_ERROR there is no error
* @return M4ERR_STATE State automaton is not applied
* @return M4ERR_ALLOC a memory allocation has failed
* @return M4ERR_PARAMETER at least one parameter is not properly set (in DEBUG only)
************************************************************************
*/
typedef M4OSA_ERR (M4AD_start_fct) (M4AD_Context pContext);
/**
************************************************************************
* @brief Reset the instance of the decoder
*
* @param context: (IN) Context of the decoder
*
* @return M4NO_ERROR There is no error
* @return M4ERR_PARAMETER The context is invalid (in DEBUG only)
************************************************************************
*/
typedef M4OSA_ERR (M4AD_reset_fct) (M4AD_Context context);
/**
************************************************************************
* @brief set en option value of the audio decoder
*
* @param context: (IN) Context of the decoder
* @param optionId: (IN) indicates the option to set
* @param pValue: (IN) pointer to structure or value (allocated by user)
* where option is stored
* @return M4NO_ERROR there is no error
* @return M4ERR_BAD_CONTEXT provided context is not a valid one
* @return M4ERR_PARAMETER at least one parameter is not properly set
* @return M4ERR_BAD_OPTION_ID when the option ID is not a valid one
************************************************************************
*/
typedef M4OSA_ERR (M4AD_setOption_fct) (M4AD_Context context,
M4OSA_OptionID optionId, M4OSA_DataOption pValue);
/**
************************************************************************
* @brief Get en option value of the audio decoder
*
* @param context: (IN) Context of the decoder
* @param optionId: (IN) indicates the option to set
* @param pValue: (OUT) pointer to structure or value (allocated by user)
* where option is stored
* @return M4NO_ERROR there is no error
* @return M4ERR_BAD_CONTEXT provided context is not a valid one
* @return M4ERR_PARAMETER at least one parameter is not properly set
* @return M4ERR_BAD_OPTION_ID when the option ID is not a valid one
************************************************************************
*/
typedef M4OSA_ERR (M4AD_getOption_fct) (M4AD_Context context, M4OSA_OptionID optionId,
M4OSA_DataOption pValue);
/**
************************************************************************
* structure M4AD_Interface
* @brief This structure defines the generic audio decoder interface
* @note This structure stores the pointers to functions of one audio decoder type.
* The decoder type is one of the M4AD_Type
************************************************************************
*/
typedef struct _M4AD_Interface
{
M4AD_create_fct* m_pFctCreateAudioDec;
M4AD_start_fct* m_pFctStartAudioDec;
M4AD_step_fct* m_pFctStepAudioDec;
M4AD_getVersion_fct* m_pFctGetVersionAudioDec;
M4AD_destroy_fct* m_pFctDestroyAudioDec;
M4AD_reset_fct* m_pFctResetAudioDec;
M4AD_setOption_fct* m_pFctSetOptionAudioDec;
M4AD_getOption_fct* m_pFctGetOptionAudioDec;
} M4AD_Interface;
#ifdef __cplusplus
}
#endif
#endif /*__M4AD_COMMON_H__*/