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