path: root/libvideoeditor/vss/common/inc/M4VE_API.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.
 */

/**
 ******************************************************************************
 * @file   M4VE_API.h
 * @note   This file declares the generic shell interface retrieving function
 *         of any external encoder.
******************************************************************************
*/

#ifndef __M4VE_API_H__
#define __M4VE_API_H__

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 *    OSAL types definition */
#include "M4OSA_Types.h"
#include "M4OSA_Time.h"
#include "M4OSA_Memory.h"
#include "M4OSA_CoreID.h"
#include "M4OSA_OptionID.h"

/**
 *    Include Video filters interface definition (for the M4VIFI_ImagePlane type) */
#include "M4VIFI_FiltersAPI.h"


/**
 ************************************************************************
 * VE Errors & Warnings definition
 ************************************************************************
*/
#define    M4ERR_VE_FATAL        ((M4OSA_ERR)M4OSA_ERR_CREATE(M4_ERR, M4VE_EXTERNAL, 0x000000))


/**
 *********************************************************************************************
 * enum        M4VE_EncoderMode
 * @brief    This enum defines in which mode the external encoder will be used
 *            ("Standalone encoder" or "Encoder + Grabber").
 *********************************************************************************************
 */
typedef enum
{
    M4VE_kSEMode,        /**< "Standalone Encoder" mode */
    M4VE_kEGMode        /**< "Encoder + Grabber" mode */
} M4VE_EncoderMode;


/**
 *********************************************************************************************
 * enum        M4VE_EncoderType
 * @brief    This enum defines the supported encoder types.
 *********************************************************************************************
 */
typedef enum
{
    M4VE_kMpeg4VideoEnc,     /**< MPEG-4 */
    M4VE_kH263VideoEnc,      /**< H263 */
    M4VE_kH264VideoEnc,      /**< H264 */
    M4VE_kMJPEGEnc,            /**< MJPEG */
    M4VE_kEncoderType_NB
} M4VE_EncoderType;


/**
 *********************************************************************************************
 * struct    M4VE_ImageSize
 * @brief    This structure defines video frame size (for both grabbing and encoding).
 *********************************************************************************************
 */
typedef struct
{
    M4OSA_UInt32     width;     /**< Width of the Image */
    M4OSA_UInt32     height;    /**< Height of the Image */
} M4VE_ImageSize;


/**
 *********************************************************************************************
 * enum        M4VE_FormatConfig
 * @brief    This enum defines the frame format we have in input for the grabbing
 *            part of the external encoder.
 *********************************************************************************************
*/
typedef enum
{
    M4VE_kYUV420=0,    /**< YUV 4:2:0 planar (standard input for mpeg-4 video) */
    M4VE_kYUV422,    /**< YUV422 planar */
    M4VE_kYUYV,        /**< YUV422 interlaced, luma first */
    M4VE_kUYVY,        /**< YUV422 interlaced, chroma first */
    M4VE_kJPEG,        /**< JPEG compressed frames */
    M4VE_kRGB444,    /**< RGB 12 bits 4:4:4 */
    M4VE_kRGB555,    /**< RGB 15 bits 5:5:5 */
    M4VE_kRGB565,    /**< RGB 16 bits 5:6:5 */
    M4VE_kRGB24,    /**< RGB 24 bits 8:8:8 */
    M4VE_kRGB32,    /**< RGB 32 bits  */
    M4VE_kBGR444,    /**< BGR 12 bits 4:4:4 */
    M4VE_kBGR555,    /**< BGR 15 bits 5:5:5 */
    M4VE_kBGR565,    /**< BGR 16 bits 5:6:5 */
    M4VE_kBGR24,    /**< BGR 24 bits 8:8:8 */
    M4VE_kBGR32        /**< BGR 32 bits  */
} M4VE_FormatConfig;


/**
 *********************************************************************************************
 * struct    M4VE_Framerate
 * @brief    This structure defines the maximum framerate the encoder will have
 *            at input and will generate at output (in frames per second).
 *********************************************************************************************
*/
typedef struct
{
    M4OSA_UInt32     framerateNum;    /**< Framerate numerator */
    M4OSA_UInt32     framerateDen;    /**< Framrate denominator */
} M4VE_Framerate;
/**<     For example, a framerate of 29.97 fps for H263 encoding will be expressed as:
    FramerateNum = 30000
    FramerateDen = 1001 */


/**
 *********************************************************************************************
 * struct    M4VE_GrabbingParameters
 * @brief    This structure defines the grabbing parameters set at open step.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_ImageSize        size;        /**< Size of grabbed frames */
    M4VE_FormatConfig    format;        /**< Format of the grabbed frames (YUV420, RGB565,etc.) */
} M4VE_GrabbingParameters;


/**
 *********************************************************************************************
 * struct    M4VE_EncodingParameters
 * @brief    This structure defines the encoding parameters set at open step.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_EncoderType  type;             /**< coding type (H263/H264/MPEG-4)*/
    M4VE_ImageSize    size;             /**< Size of frames to encode */
    M4OSA_Bool          bRateControlEnable; /**< Flag to enable/disable rate control */
    M4OSA_Bool          bLowDelay;        /**< force encoder in "low delay" mode */
    M4OSA_UInt32      bitrate;             /**< Average targeted bitrate in bit per sec */
    M4VE_Framerate    framerate;        /**< Maximum input framerate */
    M4OSA_UInt32      timescale;       /**< timescale of the video bitstream */
    M4OSA_Context     pUserSettings;   /**< Additionnal user settings passed by the
                                            application to the service at Codec registration */
} M4VE_EncodingParameters;


/**
 *********************************************************************************************
 * struct    M4VE_VideoBuffer
 * @brief    This structure defines the output buffer where the encoded data
 *            are stored by the encoder.
 *********************************************************************************************
*/
typedef struct
{
    M4OSA_MemAddr32 pBuffer;    /**< pointer to video buffer 32 bits aligned */
    M4OSA_UInt32    bufferSize; /**< the size in bytes of the buffer */
} M4VE_VideoBuffer;


/**
 *********************************************************************************************
 * struct    M4VE_ParameterSet
 * @brief    Parameter set structure used for H264 headers.
 *********************************************************************************************
*/
typedef struct
{
    M4OSA_UInt16    length;                /**< Number of items*/
    M4OSA_UInt8*    pParameterSetUnit;  /**< Array of items*/
} M4VE_ParameterSet;


/**
 *********************************************************************************************
 * struct    M4VE_H264HeaderBuffer
 * @brief    This structure defines the buffer where the stream header is stored
 *            by the encoder, in case of H264
 *********************************************************************************************
*/
typedef struct
{
    M4OSA_UInt8            NALUnitLength;             /**< length in bytes of a NAL access Unit */
    M4OSA_UInt8            nOfSequenceParametersSets; /**< Number of sequence parameter sets*/
    M4OSA_UInt8            nOfPictureParametersSets;  /**< Number of picture parameter sets*/
    M4VE_ParameterSet    *pSequenceParameterSets;    /**< Sequence parameter set array */
    M4VE_ParameterSet    *pPictureParameterSets;        /**< Picture parameter set array */
} M4VE_H264HeaderBuffer;



/**
 *********************************************************************************************
 * struct    M4VE_HeaderBuffer
 * @brief    This structure defines the buffer where the stream header is stored
 *            by the encoder.
 *********************************************************************************************
*/
typedef struct
{
    union
    {
        M4VE_VideoBuffer         header;     /**< MPEG-4, H263, MJPEG */
        M4VE_H264HeaderBuffer     H264Header; /**< H264 */
    }M4VE_SpecificHeader;
} M4VE_HeaderBuffer;


/**
 *********************************************************************************************
 * enum        M4VE_OptionID
 * @brief    This defines the supported options handled by the video encoder interface.
 *********************************************************************************************
*/
typedef enum
{
    dummy=0
} M4VE_OptionID;

/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalOpenEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the external encoder is opened.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalOpenEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalHeaderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode,
 *                                       M4VE_HeaderBuffer *pBuffer);
 * @brief    This function signals to the service that the stream header is ready.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @param    pBuffer :                (IN) Stream header.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_PARAMETER            pBuffer field is null or invalid.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalHeaderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode,
                     M4VE_HeaderBuffer *pBuffer);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalStartGrabberDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the grabbing part is started.
 *            This callback is unused in the "standalone encoder" mode.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalStartGrabberDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalStartEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the external encoder is started.
 *            This callback is unused in the "standalone encoder" mode.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalStartEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalEncodeDone)(M4OSA_Context pUserData, M4OSA_ERR    errCode,
                M4OSA_UInt32 cts, M4VE_VideoBuffer* pBuffer);
 * @brief    This function signals to the service that the encoding of a frame is done.
 *            The integrator must call this function when the encoding of the video
 *            frame is completed (for example in an interrupt callback).
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @param    cts :                    (IN) Time of the encoded frame (from stepEncode).
 * @param    pBuffer :                (IN) Encoded data Buffer.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_PARAMETER            At least one parameter is null or invalid.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalEncodeDone)(M4OSA_Context pUserData, M4OSA_ERR    errCode,
                         M4OSA_Time cts, M4VE_VideoBuffer* pBuffer);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalStopGrabberDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the grabbing part is stopped.
 *            This callback is unused in the "standalone encoder" mode.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalStopGrabberDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalStopEncoderDone)(M4OSA_Context    pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the external encoder is stopped.
 *            This callback is unused in the "standalone encoder" mode.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalStopEncoderDone)(M4OSA_Context    pUserData, M4OSA_ERR errCode);


/**
 *********************************************************************************************
 * M4OSA_Int32 (*M4VE_SignalCloseEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);
 * @brief    This function signals to the service that the external encoder is closed.
 * @note    The external encoder returns one of the following codes in the errCode parameter:
 *            M4NO_ERROR    There is no error
 *            M4ERR_VE_FATAL    a fatal error occurred
 * @param    pUserData:                (IN) User data provided by the service at init step.
 * @param    errCode :                (IN) Error code returned to the service internal layers.
 * @return    M4NO_ERROR:                there is no error.
 * @return    M4ERR_VE_FATAL:        a fatal error occurred.
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SignalCloseEncoderDone)(M4OSA_Context pUserData, M4OSA_ERR errCode);




/**
 *********************************************************************************************
 * struct    M4VE_GenericCallback
 * @brief    This structure is used to pass the generic callbacks, i.e. the ones that are used
 *            in both "Standalone Encoder" and "Encoder + Grabber" modes.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_SignalOpenEncoderDone        pOpenEncoderDone; /**< Callback to use at open completion */
    M4VE_SignalHeaderDone             pHeaderDone;         /**< Callback to use when the stream
                                                                 header is ready */
    M4VE_SignalEncodeDone             pEncodeDone;         /**< Callback to use for any frame
                                                                    encoding completion */
    M4VE_SignalCloseEncoderDone       pCloseEncoderDone;/**< Callback to use at close completion */
} M4VE_GenericCallback;    /**< Callbacks used in all encoder modes */

/**
 *********************************************************************************************
 * struct    M4VE_EGModeCallback
 * @brief    This structure is used to pass the callbacks used in the "Encoder + Grabber" mode
 *********************************************************************************************
*/
typedef struct
{
    M4VE_SignalStartGrabberDone     pStartGrabberDone;/**< Callback to use at start
                                                            completion of the grabber part*/
    M4VE_SignalStartEncoderDone     pStartEncoderDone;/**< Callback to use at start
                                                            completion of the encoder part*/
    M4VE_SignalStopGrabberDone      pStopGrabberDone; /**< Callback to use at stop
                                                            completion of the grabber part*/
    M4VE_SignalStopEncoderDone      pStopEncoderDone; /**< Callback to use at stop
                                                            completion of the encoder part*/
} M4VE_EGModeCallback; /**< Callbacks used in "Encoder + Grabber" mode */

/**
 *********************************************************************************************
 * struct    M4VE_SEModeCallback
 * @brief    This structure is used to pass the callbacks used in the "Standalone Encoder" mode
 * @note    There's no specific callback for the standalone encoder mode,
 *               but we have to declare one
 * @note        for some compilers
 *********************************************************************************************
*/
typedef M4OSA_Int32 (*M4VE_SEDummyCB)  (M4OSA_Context pUserData, M4OSA_ERR errCode);

typedef struct
{
    M4VE_SEDummyCB                  pDummySECB; /**< No specific callback for
                                                        Standalone encoder mode */
} M4VE_SEModeCallback; /**< Callbacks used in "Standalone Encoder" mode */


/**
 *********************************************************************************************
 * struct    M4VE_CallbackInterface
 * @brief    This structure is the container for the whole set of callback used by external encoder
  *********************************************************************************************
*/

typedef struct
{
    M4VE_GenericCallback    genericCallback;/**< Callbacks used in all modes */
    union
    {
        M4VE_EGModeCallback    EGModeCallback; /**< Callbacks used in "Encoder + Grabber" mode */
        M4VE_SEModeCallback    SEModeCallback; /**< Callbacks used in "Standalone Encoder" mode */
    } M4VE_SpecificModeCallBack;
    M4OSA_Context            pUserData;      /**< Internal user data to be retrieved in each
                                                    callbach above */
} M4VE_CallbackInterface;


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_initEncoder_fct)(M4OSA_Context* pContext,
 *                                       M4VE_CallbackInterface* pCallbackInterface);
 * @brief    This function initializes the external video encoder API.
 * @note    This function typically allocates the user context that will be provided
 *            to the other functions as their first argument. The second argument is
 *            the callback interface given by the service. Encoder implementation is supposed
 *            to use these callbacks in response to each asynchronous API function.
 *            All these callbacks must be called with the pUserData field specified
 *            by the service inside the M4VE_CallbackInterface structure.
 * @param    pContext:            (OUT) Execution context of the encoder.
 * @param    pCallbackInterface:    (IN) Callback interface.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    At least one parameter is not correct (NULL or invalid).
 * @return    M4ERR_ALLOC:        there is no more available memory.
 *********************************************************************************************
*/
typedef    M4OSA_ERR (*M4VE_initEncoder_fct)(M4OSA_Context* pContext,
                     M4VE_CallbackInterface*    pCallbackInterface);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_setOption_fct)(M4OSA_Context, M4VE_OptionID, M4OSA_DataOption);
 * @brief    This function is used to set an option in the video encoder interface.
 * @note    none
 * @param    pContext:        (IN) Execution context of the encoder.
 * @param    optionId:        (IN) Id of the option to set.
 * @param    pValue:            (IN) Pointer of the option data to set.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    At least one parameter is not correct (NULL or invalid).
 * @return    M4ERR_BAD_OPTION_ID:The requested option Id is invalid.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_setOption_fct)(M4OSA_Context pContext,    M4VE_OptionID optionId,
                                        M4OSA_DataOption pValue);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_getOption_fct)(M4OSA_Context, M4VE_OptionID, M4OSA_DataOption*);
 * @brief    This function is used to retrieve an option in the video interface.
 * @note    none
 * @param    pContext:        (IN) Execution context of the encoder.
 * @param    optionId:        (IN) Id of the option to set.
 * @param    pValue:            (OUT) Pointer to the location where the requested option will
 *                                      be stored.
 * @return    M4NO_ERROR:        there is no error.
 * @return    M4ERR_PARAMETER:    At least one parameter is not correct (NULL or invalid).
 * @return    M4ERR_BAD_OPTION_ID:The requested option Id is invalid.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_getOption_fct)(M4OSA_Context pContext, M4VE_OptionID optionId,
                             M4OSA_DataOption* pValue);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_openEncoder_fct)(M4OSA_Context pContext,
 *                                     M4VE_GrabbingParameters *pGrabbingParams,
 *                                     M4VE_EncodingParameters *pEncodingParams);
 * @brief    This function opens an instance of the video encoder.
 *            Both encoding and grabbing parameters are specified here.
 * @note    This function is asynchronous, thus the external encoder must call the corresponding
 *            M4VE_SignalOpenEncoderDone callback function when the opening step is internally
 *            completed.
 *            Please note that both grabber and encoder components are opened at this step in
 *            the "encoder + grabber" mode. In response to this open, the encoder must also return
 *            the stream header (including VOS, VO & VOL) using the M4VE_SignalHeaderDone callback
 *            function. Usually the service waits for this callback between the
 *            M4VE_SignalOpenEncoderDone
 *            callback and the M4VE_SignalCloseEncoderDone callback in order to handle it.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @param    pGrabbingParams:    (IN) Grabbing parameters (can be optional, in this case is
 *                                    must be NULL).
 * @param    pEncodingParams:    (IN) Encoding parameters.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    At least one parameter is not correct (NULL or invalid).
 * @return    M4ERR_ALLOC:        there is no more available memory.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not be opened
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_openEncoder_fct)(M4OSA_Context pContext,
                         M4VE_GrabbingParameters *pGrabbingParams,
                          M4VE_EncodingParameters *pEncodingParams);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_forceIFrame_fct)(M4OSA_Context pContext);
 * @brief    This function is used by the service to signal the external encoder that an Intra
 *           refresh frame must be encoded. This function is used in both "Standalone Encoder" and
 *            "Encoder + grabber" modes and can be called at any time during the encoding session.
 * @note    For the "Encoder + Grabber" mode, this function can be called between the reception
 *            of the M4VE_SignalStartEncoderDone callback and the call to M4VE_stopEncoder_fct.
 *            For the "Standalone Encoder" mode, this function can be called between the reception
 *            of the M4VE_SignalOpenEncoderDone callback and the call to M4VE_closeEncoder_fct.
 *            The expected behavior is that the external encoder encodes an intra refresh frame
 *            for one of the frames coming next to the call of M4VE_forceIFrame_fct.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not handle this call
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_forceIFrame_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_releaseOutputBuffer_fct)(M4OSA_Context pContext, M4VE_VideoBuffer *pBuffer);
 * @brief    This function is called by the service to signal that a particular output buffer,
 *           provided in the M4VE_SignalEncodeDone callback by the external encoder, is no more
 *           needed by the service and can be considered as free for any remaining data processing.
 * @note    none.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @param    pBuffer:            (IN) Encoded data Buffer.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    At least one parameter is not correct (NULL or invalid).
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not acknowledge the buffer release for any
 *                                other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_releaseOutputBuffer_fct)(M4OSA_Context pContext,
                                                    M4VE_VideoBuffer *pBuffer);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_closeEncoder_fct)(M4OSA_Context pContext);
 * @brief    This function closes the encoding session.
 * @note    This function is asynchronous, thus the external encoder must call the corresponding
 *            M4VE_SignalCloseEncoderDone callback function when the closing step is internally
 *            completed.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext pointer is null or invalid.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not be closed for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_closeEncoder_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_cleanUpEncoder_fct)(M4OSA_Context pContext);
 * @brief    The function cleans up the encoder context.
 * @note    none
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext pointer is null or invalid.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not be closed for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_cleanUpEncoder_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_stepEncode_fct)(M4OSA_Context pContext,M4VIFI_ImagePlane *pInputPlane,
 *                                  M4OSA_Time cts);
 * @brief    The function gives a video frame to the external encoder in the "Standalone encoder"
 *            mode. The input buffer consists of a raw YUV420 planar frame,
 *            allocated by the service.
 *            The time (cts) is the composition time stamp of the frame to encode and is unique
 *            for each frame. This time is expressed in milliseconds.
 * @note    This function is asynchronous and its completion is signaled by the
 *            M4VE_SignalEncodeDone callback. It applies that the input buffer is maintained valid
 *            by the service till the call of this callback. The encoded data are retrieved in
 *            this callback function in a dedicated structure, allocated by the external encoder.
 *            The input buffer (YUV raw frame) is considered by the service as free for any
 *             remaining data processing after receiving the M4VE_SignalEncodeDone callback.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @param    pInputPlane:        (IN) Input buffer where video frame is stored.
 * @param    cts:                (IN) Composition time stamp in milliseconds.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_ALLOC:        there is no more available memory.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    The encoder could not encode the frame for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_stepEncode_fct)(M4OSA_Context pContext,M4VIFI_ImagePlane *pInputPlane,
                                            M4OSA_Time cts);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_startGrabber_fct)(M4OSA_Context pContext);
 * @brief    This function starts the grabber sub-component of the external encoder, in the
 *            "encoder + grabber" mode. This function is asynchronous, thus the external
 *            encoder must call the corresponding M4VE_SignalStartGrabberDone callback function
 *            when this start is internally effective.
 * @note    During this step, the service waits for the grabber to launch any video preview if
 *            needed.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_ALLOC:        there is no more available memory.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    the encoder could not be started for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_startGrabber_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_startEncoder_fct)(M4OSA_Context pContext);
 * @brief    This function starts the video encoder in the "encoder + grabber" mode.
 * @note    This function is asynchronous, thus the external encoder must call the corresponding
 *            M4VE_SignalStartEncoderDone callback function when this start is internally
 *            effective.
 *            After the completion of this asynchronous function, the service waits for the
 *            external encoder to periodically call the M4VE_SignalEncodeDone callback each time
 *            a new frame has been encoded. The external encoder must expect to have several
 *            M4VE_startEncoder_fct calls before being closed. See the description of
 *            M4VE_stopEncoder_fct function for the expected behaviour.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_ALLOC:        there is no more available memory.
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    the encoder could not be started for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_startEncoder_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR M4OSA_ERR (*M4VE_stopGrabber_fct)(M4OSA_Context pContext);
 * @brief    This function stops the video grabber in the "encoder + grabber" mode.
 * @note    This function is asynchronous, thus the external encoder must call the corresponding
 *          M4VE_SignalStopGrabberDone callback function when this stop is internally effective.
 *          During this step, the service waits for the grabber to stop the video preview
 *          if needed.
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_FATAL:    the encoder could not be stopped for any other reason.
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_stopGrabber_fct)(M4OSA_Context pContext);


/**
 *********************************************************************************************
 * M4OSA_ERR (*M4VE_stopEncoder_fct)(M4OSA_Context pContext);
 * @brief    This function stops the video encoder in the "encoder + grabber" mode.
 * @note    This function is asynchronous, thus the external encoder must call the corresponding
 *            M4VE_SignalStopEncoderDone callback function when this stop is internally effective.
 *            After the reception of this callback, the service considers that no new frame will be
 *            retrieved via the M4VE_SignalEncodeDone callback.
 *            The external encoder must expect to have a possible call to M4VE_startEncoder_fct
 *            after M4VE_stopEncoder_fct. In this case, the external encoder must consider that it
 *             has been paused/resumed. The expected behaviour is the following one:
 *            - The result from this two encoding sessions is a Standalone stream, no header is
 *            generated for this new session. The external encoder is free to encode a refresh
 *            frame (like I VOP) for this new session.
 *            - The time stamps of this new session must directly follow the time stamps of the
 *            previous one (ie: no time hole coming from the delay between the stop of the first
 *            session and the start of the new one).
 * @param    pContext:            (IN) Execution context of the encoder.
 * @return    M4NO_ERROR:            there is no error.
 * @return    M4ERR_PARAMETER:    pContext field is not valid
 * @return    M4ERR_STATE:        This call is not allowed in the current encoder state.
 * @return    M4ERR_VE_ERR_FATAL:    the encoder could not be stopped for any other reason
 *********************************************************************************************
*/
typedef M4OSA_ERR (*M4VE_stopEncoder_fct)(M4OSA_Context pContext);





/**
 *********************************************************************************************
 * struct    M4VE_GenericInterface
 * @brief    The M4VE_GenericInterface structure defines the set of functions used in
 *               both encoder modes.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_initEncoder_fct            m_pFctInitEncoder;
    M4VE_setOption_fct                m_pFctSetOption;
    M4VE_getOption_fct                m_pFctGetOption;
    M4VE_openEncoder_fct            m_pFctOpenEncoder;
    M4VE_forceIFrame_fct            m_pFctForceIFrame;
    M4VE_releaseOutputBuffer_fct    m_pFctReleaseOutputBuffer;
    M4VE_closeEncoder_fct            m_pFctCloseEncoder;
    M4VE_cleanUpEncoder_fct            m_pFctCleanUpEncoder;
} M4VE_GenericInterface;            /**< Functions used in both "Standalone Encoder" and
                                        "Encoder + Grabber" modes */


/**
 *********************************************************************************************
 * struct    M4VE_SEModeInterface
 * @brief    The M4VE_SEModeInterface structure defines the set of functions used in
 *              "Standalone Encoder" mode.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_stepEncode_fct            m_pFctStepEncode;
} M4VE_SEModeInterface;            /**< Functions used only in "Standalone Encoder" mode */


/**
 *********************************************************************************************
 * struct    M4VE_EGModeInterface
 * @brief    The M4VE_EGModeInterface structure defines the set of functions used in
 *              "Encoder + Grabber" mode.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_startGrabber_fct        m_pFctStartGrabber;
    M4VE_startEncoder_fct        m_pFctStartEncoder;
    M4VE_stopGrabber_fct        m_pFctStopGrabber;
    M4VE_stopEncoder_fct        m_pFctStopEncoder;
} M4VE_EGModeInterface;            /**< Functions used only in "Encoder + Grabber" mode */



/**
 *********************************************************************************************
 * struct    M4VE_Interface
 * @brief    The M4VE_Interface structure stores pointers to the video encoder functions.
 *********************************************************************************************
*/
typedef struct
{
    M4VE_GenericInterface        genericInterface;    /**< Functions used everytime */
    M4VE_EncoderMode            encoderMode;        /**< "Standalone Encoder"
                                                    or "Encoder + Grabber" */
    union
    {
        M4VE_SEModeInterface    SEModeInterface;    /**< Functions used only in
                                                    "Standalone Encoder" mode */
        M4VE_EGModeInterface    EGModeInterface;    /**< Functions used only in
                                                    "Encoder + Grabber" mode */
    }M4VE_SpecificInterface;
} M4VE_Interface;

#ifdef __cplusplus
}
#endif /* __cplusplus */


#endif /*__M4VE_API_H__*/