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

/*
 * 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.
 */
/**
 ************************************************************************
 * @file   M4DECODER_Common.h
 * @brief  Shell Decoder common interface declaration
 * @note   This file declares the common interfaces that decoder shells must implement
 *
 ************************************************************************
*/
#ifndef __M4DECODER_COMMON_H__
#define __M4DECODER_COMMON_H__

#include "M4OSA_Types.h"
#include "M4OSA_Error.h"
#include "M4OSA_OptionID.h"
#include "M4OSA_CoreID.h"

#include "M4READER_Common.h"
#include "M4VIFI_FiltersAPI.h"

#include "M4_Utils.h"

/* ----- Errors and Warnings ----- */

/**
 * Warning: there is no new decoded frame to render since the last rendering
 */
#define M4WAR_VIDEORENDERER_NO_NEW_FRAME M4OSA_ERR_CREATE(M4_WAR, M4DECODER_COMMON, 0x0001)
/**
 * Warning: the deblocking filter is not implemented
 */
#define M4WAR_DEBLOCKING_FILTER_NOT_IMPLEMENTED M4OSA_ERR_CREATE(M4_WAR, M4DECODER_COMMON,\
                                                                     0x000002)


/* Error: Stream H263 profiles (other than  0) are not supported */
#define M4ERR_DECODER_H263_PROFILE_NOT_SUPPORTED            M4OSA_ERR_CREATE(M4_ERR,\
                                                                 M4DECODER_MPEG4, 0x0001)
/* Error: Stream H263 not baseline not supported (Supported sizes are CIF, QCIF or SQCIF) */
#define M4ERR_DECODER_H263_NOT_BASELINE                        M4OSA_ERR_CREATE(M4_ERR,\
                                                                 M4DECODER_MPEG4, 0x0002)

/**
 ************************************************************************
 * enum     M4DECODER_AVCProfileLevel
 * @brief    This enum defines the AVC decoder profile and level for the current instance
 * @note    This options can be read from decoder via M4DECODER_getOption_fct
 ************************************************************************
*/
typedef enum
{
    M4DECODER_AVC_kProfile_0_Level_1 = 0,
    M4DECODER_AVC_kProfile_0_Level_1b,
    M4DECODER_AVC_kProfile_0_Level_1_1,
    M4DECODER_AVC_kProfile_0_Level_1_2,
    M4DECODER_AVC_kProfile_0_Level_1_3,
    M4DECODER_AVC_kProfile_0_Level_2,
    M4DECODER_AVC_kProfile_0_Level_2_1,
    M4DECODER_AVC_kProfile_0_Level_2_2,
    M4DECODER_AVC_kProfile_0_Level_3,
    M4DECODER_AVC_kProfile_0_Level_3_1,
    M4DECODER_AVC_kProfile_0_Level_3_2,
    M4DECODER_AVC_kProfile_0_Level_4,
    M4DECODER_AVC_kProfile_0_Level_4_1,
    M4DECODER_AVC_kProfile_0_Level_4_2,
    M4DECODER_AVC_kProfile_0_Level_5,
    M4DECODER_AVC_kProfile_0_Level_5_1,
    M4DECODER_AVC_kProfile_and_Level_Out_Of_Range = 255
} M4DECODER_AVCProfileLevel;

/**
 ************************************************************************
 * enum     M4DECODER_OptionID
 * @brief    This enum defines the decoder options
 * @note    These options can be read from or written to a decoder via M4DECODER_getOption_fct
 ************************************************************************
*/
typedef enum
{
    /**
    Get the version of the core decoder
    */
    M4DECODER_kOptionID_Version        = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x01),
    /**
    Get the size of the currently decoded video
    */
    M4DECODER_kOptionID_VideoSize    = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x02),
    /**
    Set the conversion filter to use at rendering
    */
    M4DECODER_kOptionID_OutputFilter = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x03),
    /**
    Activate the Deblocking filter
    */
    M4DECODER_kOptionID_DeblockingFilter = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x04),
    /**
    Get nex rendered frame CTS
    */
    M4DECODER_kOptionID_NextRenderedFrameCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON,\
                                                                         0x05),

    /**
    Set the YUV data to the dummy video decoder
    */
    M4DECODER_kOptionID_DecYuvData =
        M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x06),
    /**
    Set the YUV data with color effect applied to the dummy video decoder
    */
    M4DECODER_kOptionID_YuvWithEffectNonContiguous =
        M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x07),

    M4DECODER_kOptionID_YuvWithEffectContiguous =
        M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x08),

    M4DECODER_kOptionID_EnableYuvWithEffect =
        M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x09),

    /**
     * Get the supported video decoders and capabilities */
    M4DECODER_kOptionID_VideoDecodersAndCapabilities =
        M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x10),

    /* common to MPEG4 decoders */
    /**
     * Get the DecoderConfigInfo */
    M4DECODER_MPEG4_kOptionID_DecoderConfigInfo = M4OSA_OPTION_ID_CREATE(M4_READ,\
                                                         M4DECODER_MPEG4, 0x01),

    /* last decoded cts */
    M4DECODER_kOptionID_AVCLastDecodedFrameCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AVC,\
                                                                             0x01)
/* Last decoded cts */

} M4DECODER_OptionID;


/**
 ************************************************************************
 * struct    M4DECODER_MPEG4_DecoderConfigInfo
 * @brief    Contains info read from the MPEG-4 VideoObjectLayer.
 ************************************************************************
*/
typedef struct
{
    M4OSA_UInt8        uiProfile;                /**< profile and level as defined in the Visual
                                                         Object Sequence header, if present */
    M4OSA_UInt32    uiTimeScale;            /**< time scale as parsed in VOL header */
    M4OSA_UInt8        uiUseOfResynchMarker;    /**< Usage of resynchronization marker */
    M4OSA_Bool        bDataPartition;            /**< If 1 data partitioning is used. */
    M4OSA_Bool        bUseOfRVLC;                /**< Usage of RVLC for the stream */

} M4DECODER_MPEG4_DecoderConfigInfo;


/**
 ***********************************************************************
 * structure    M4DECODER_VideoSize
 * @brief        This structure defines the video size (width and height)
 * @note        This structure is used to retrieve via the M4DECODER_getOption_fct
 *                function the size of the current decoded video
 ************************************************************************
*/
typedef struct _M4DECODER_VideoSize
{
    M4OSA_UInt32   m_uiWidth;    /**< video width  in pixels */
    M4OSA_UInt32   m_uiHeight;    /**< video height in pixels */

} M4DECODER_VideoSize;

/**
 ************************************************************************
 * structure    M4DECODER_OutputFilter
 * @brief        This structure defines the conversion filter
 * @note        This structure is used to retrieve the filter function
 *                pointer and its user data via the function
 *                M4DECODER_getOption_fct    with the option
 *                M4DECODER_kOptionID_OutputFilter
 ************************************************************************
*/
typedef struct _M4DECODER_OutputFilter
{
    M4OSA_Void   *m_pFilterFunction;    /**< pointer to the filter function */
    M4OSA_Void   *m_pFilterUserData;    /**< user data of the filter        */

} M4DECODER_OutputFilter;

/**
 ************************************************************************
 * enum     M4DECODER_VideoType
 * @brief    This enum defines the video types used to create decoders
 * @note    This enum is used internally by the VPS to identify a currently supported
 *            video 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
 *            and retrieve its interface.
 ************************************************************************
*/
typedef enum
{
    M4DECODER_kVideoTypeMPEG4 = 0,
    M4DECODER_kVideoTypeMJPEG,
    M4DECODER_kVideoTypeAVC,
    M4DECODER_kVideoTypeWMV,
    M4DECODER_kVideoTypeREAL,
    M4DECODER_kVideoTypeYUV420P,

    M4DECODER_kVideoType_NB  /* number of decoders, keep it as last enum entry */

} M4DECODER_VideoType ;

typedef struct {
    M4OSA_UInt32 mProfile;
    M4OSA_UInt32 mLevel;
} VideoProfileLevel;

typedef struct {
    VideoProfileLevel *profileLevel;
    M4OSA_UInt32 profileNumber;
} VideoComponentCapabilities;

typedef struct {
    M4_StreamType codec;
    VideoComponentCapabilities *component;
    M4OSA_UInt32 componentNumber;
} VideoDecoder;

typedef struct {
    VideoDecoder *decoder;
    M4OSA_UInt32 decoderNumber;
} M4DECODER_VideoDecoders;
/**
 ************************************************************************
 * @brief    creates an instance of the decoder
 * @note    allocates the context
 *
 * @param    pContext:        (OUT)    Context of the decoder
 * @param    pStreamHandler:    (IN)    Pointer to a video stream description
 * @param    pGlobalInterface:  (IN)    Pointer to the M4READER_GlobalInterface structure that must
 *                                       be used by the decoder to read data from the stream
 * @param    pDataInterface:    (IN)    Pointer to the M4READER_DataInterface structure that must
 *                                       be used by the decoder to read data from the stream
 * @param    pAccessUnit        (IN)    Pointer to an access unit (allocated by the caller)
 *                                      where the decoded data are stored
 *
 * @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  (M4DECODER_create_fct)    (M4OSA_Context *pContext,
                                                 M4_StreamHandler *pStreamHandler,
                                                 M4READER_GlobalInterface *pGlobalInterface,
                                                 M4READER_DataInterface *pDataInterface,
                                                 M4_AccessUnit *pAccessUnit,
                                                 M4OSA_Void* pUserData);

/**
 ************************************************************************
 * @brief    destroy 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  (M4DECODER_destroy_fct)    (M4OSA_Context context);

/**
 ************************************************************************
 * @brief    get an option value from the decoder
 * @note    this function follows the set/get option mechanism described in OSAL 3.0
 *          it allows the caller to retrieve a property value:
 *          -the version number of the decoder
 *          -the size (widthxheight) of the image
 *
 * @param    context:    (IN)        Context of the decoder
 * @param    optionId:    (IN)        indicates the option to set
 * @param    pValue:        (IN/OUT)    pointer to structure or value (allocated by user) where
 *                                      option is stored
 * @return    M4NO_ERROR                 there is no error
 * @return  M4ERR_PARAMETER         The context is invalid (in DEBUG only)
 * @return    M4ERR_BAD_OPTION_ID        when the option ID is not a valid one
 * @return  M4ERR_STATE             State automaton is not applied
 ************************************************************************
*/
typedef M4OSA_ERR  (M4DECODER_getOption_fct)(M4OSA_Context context, M4OSA_OptionID optionId,
                                             M4OSA_DataOption pValue);

/**
 ************************************************************************
 * @brief   set an option value of the decoder
 * @note    this function follows the set/get option mechanism described in OSAL 3.0
 *          it allows the caller to set a property value:
 *          -the conversion filter to use at rendering
 *
 * @param   context:    (IN)        Context of the decoder
 * @param   optionId:   (IN)        Identifier indicating 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_OPTION_ID     The option ID is not a valid one
 * @return  M4ERR_STATE             State automaton is not applied
 * @return  M4ERR_PARAMETER         The option parameter is invalid
 ************************************************************************
*/
typedef M4OSA_ERR  (M4DECODER_setOption_fct)(M4OSA_Context context, M4OSA_OptionID optionId,
                                                 M4OSA_DataOption pValue);

/**
 ************************************************************************
 * @brief   Decode Access Units up to a target time
 * @note    Parse and decode the stream until it is possible to output a decoded image for which
 *            the composition time is equal or greater to the passed targeted time
 *          The data are read from the reader data interface
 *
 * @param    context:    (IN)        Context of the decoder
 * @param    pTime:        (IN/OUT)    IN: Time to decode up to (in milli secondes)
 *                                    OUT:Time of the last decoded frame (in ms)
 * @param   bJump:      (IN)        0 if no jump occured just before this call
 *                                  1 if a a jump has just been made
 * @param   tolerance:      (IN)        We may decode an earlier frame within the tolerance.
 *                                      The time difference is specified in milliseconds.
 *
 * @return    M4NO_ERROR                 there is no error
 * @return    M4ERR_PARAMETER            at least one parameter is not properly set
 * @return    M4WAR_NO_MORE_AU        there is no more access unit to decode (end of stream)
 ************************************************************************
*/
typedef M4OSA_ERR  (M4DECODER_decode_fct)    (M4OSA_Context context, M4_MediaTime* pTime,
                                                 M4OSA_Bool bJump, M4OSA_UInt32 tolerance);

/**
 ************************************************************************
 * @brief    Renders the video at the specified time.
 * @note
 * @param    context:     (IN)        Context of the decoder
 * @param   pTime:       (IN/OUT)   IN: Time to render to (in milli secondes)
 *                OUT:Time of the actually rendered frame (in ms)
 * @param    pOutputPlane:(OUT)        Output plane filled with decoded data (converted)
 * @param   bForceRender:(IN)       1 if the image must be rendered even it has already been
 *                                  0 if not (in which case the function can return
 *                                       M4WAR_VIDEORENDERER_NO_NEW_FRAME)
 * @return    M4NO_ERROR                 There is no error
 * @return    M4ERR_PARAMETER            At least one parameter is not properly set
 * @return  M4ERR_STATE             State automaton is not applied
 * @return  M4ERR_ALLOC             There is no more available memory
 * @return    M4WAR_VIDEORENDERER_NO_NEW_FRAME    If the frame to render has already been rendered
 ************************************************************************
*/
typedef M4OSA_ERR  (M4DECODER_render_fct)    (M4OSA_Context context, M4_MediaTime* pTime,
                                              M4VIFI_ImagePlane* pOutputPlane,
                                              M4OSA_Bool bForceRender);

/**
 ************************************************************************
 * structure    M4DECODER_VideoInterface
 * @brief        This structure defines the generic video decoder interface
 * @note        This structure stores the pointers to functions of one video decoder type.
 *                The decoder type is one of the M4DECODER_VideoType
 ************************************************************************
*/
typedef struct _M4DECODER_VideoInterface
{
    M4DECODER_create_fct*        m_pFctCreate;
    M4DECODER_destroy_fct*        m_pFctDestroy;
    M4DECODER_getOption_fct*    m_pFctGetOption;
    M4DECODER_setOption_fct*    m_pFctSetOption;
    M4DECODER_decode_fct*        m_pFctDecode;
    M4DECODER_render_fct*        m_pFctRender;
} M4DECODER_VideoInterface;

#endif /*__M4DECODER_COMMON_H__*/