xref: /frameworks/av/libvideoeditor/vss/common/inc/M4AD_Common.h

/*
 * Copyright (C) 2004-2011 NXP Software
 * 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)

} 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;
} 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__*/