enc/include/cvei.h

/* ------------------------------------------------------------------
 * Copyright (C) 1998-2009 PacketVideo
 *
 * 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: cvei.h                                                                */
/*  Purpose:                                                                    */
/*  Date:                                                                       */
/*  Revision History:                                                           */
/** @introduction   Common Video Encoder Interface (CVEI) is intended to be used by
    application developers who want to create a multimedia application with video
    encoding feature. CVEI is designed such that new video encoder algorithms or
    modules can be plugged in seamlessly without user interaction. In other words,
    any changes to the CVEI library are transparent to the users. Users can still
    use the same set of APIs for new encoding tools.

    @requirement    CVEI will take an input frame in one of several format supported
    by PV and encode it to an MPEG4 bitstream. It will also return a reconstructed
    image in YUV 4:2:0 format. Currently the input format supported are YUV 4:2:0,
    RGB24 and UYVY 4:2:2.

    CVEI is designed such that it is simple to use. It should hides implementation
    dependency  from the users. In this version, we decided that the operation will
    be synchronous, i.e., the encoding will be a blocked call. Asynchronous operation
    will be in the level above CVEI, i.e., in Author Engine Video Module which will
    take care of capturing device as well.

    @brief  The following classes are used to interface with codecs. Their names
    are CPVxxxVideoEncoder where xxx is codec specific such as MPEG4, H263, H26L,
    etc. All of them are subclasses of CPVCommonVideoEncoder.
*/
/*********************************************************************************/

#ifndef __CVEI_H
#define __CVEI_H

#include "oscl_scheduler_ao.h"
#include "oscl_base.h"
#include "mp4enc_api.h" /* for MP4HintTrack */

#define MAX_LAYER 2

/** General returned values. */
enum TCVEI_RETVAL
{
    ECVEI_SUCCESS,
    ECVEI_FAIL,
    ECVEI_FLUSH,
    ECVEI_MORE_OUTPUT
} ;

/** Returned events with the callback function. */
enum TCVEI_EVENT
{
    /** Called when a packet or a frame of output bitstream is ready. */
    ECVEI_BUFFER_READY,

    /** Called when the last packet of a frame of output bitstream is ready. */
    ECVEI_FRAME_DONE,

    /** Called when no buffers is available for output bitstream. A buffer can be added thru AddBuffer API. */
    ECVEI_NO_BUFFERS,

    /** Called when there is an error with the encoding operation. */
    ECVEI_ERROR
};

/** Contains supported input format */
enum TPVVideoFormat
{
    ECVEI_RGB24,
    ECVEI_RGB12,
    ECVEI_YUV420,
    ECVEI_UYVY,
    ECVEI_YUV420SEMIPLANAR
};

/** Type of contents for optimal encoding mode. */
enum TPVContentType
{
    /** Content is to be streamed in real-time. */
    ECVEI_STREAMING,

    /** Content is to be downloaded and playbacked later.*/
    ECVEI_DOWNLOAD,

    /** Content is to be 3gpp baseline compliant. */
    ECVEI_H263
};

/** Rate control type. */
enum TMP4RateControlType
{
    /** Constant quality, variable bit rate, fixed quantization level. */
    ECONSTANT_Q,

    /** Short-term constant bit rate control. */
    ECBR_1,

    /** Long-term constant bit rate control. */
    EVBR_1
};

/** Targeted profile and level to encode. */
enum TPVM4VProfileLevel
{
    /* Non-scalable profile */
    ECVEI_SIMPLE_LEVEL0 = 0,
    ECVEI_SIMPLE_LEVEL1,
    ECVEI_SIMPLE_LEVEL2,
    ECVEI_SIMPLE_LEVEL3,
    ECVEI_CORE_LEVEL1,
    ECVEI_CORE_LEVEL2,

    /* Scalable profile */
    ECVEI_SIMPLE_SCALABLE_LEVEL0 = 6,
    ECVEI_SIMPLE_SCALABLE_LEVEL1,
    ECVEI_SIMPLE_SCALABLE_LEVEL2,

    ECVEI_CORE_SCALABLE_LEVEL1 = 10,
    ECVEI_CORE_SCALABLE_LEVEL2,
    ECVEI_CORE_SCALABLE_LEVEL3
};

/** This structure contains encoder settings. */
struct TPVVideoEncodeParam
{
    /** Specifies an  ID that will be used to specify this encoder while returning
    the bitstream in asynchronous mode. */
    uint32              iEncodeID;

    /** Specifies whether base only (iNumLayer = 1) or base + enhancement layer
    (iNumLayer =2 ) is to be used. */
    int32               iNumLayer;

    /** Specifies the width in pixels of the encoded frames. IFrameWidth[0] is for
    base layer and iFrameWidth[1] is for enhanced layer. */
    int                 iFrameWidth[MAX_LAYER];

    /** Specifies the height in pixels of the encoded frames. IFrameHeight[0] is for
    base layer and iFrameHeight[1] is for enhanced layer. */
    int                 iFrameHeight[MAX_LAYER];

    /** Specifies the cumulative bit rate in bit per second. IBitRate[0] is for base
    layer and iBitRate[1] is for base+enhanced layer.*/
    int                 iBitRate[MAX_LAYER];

    /** Specifies the cumulative frame rate in frame per second. IFrameRate[0] is for
    base layer and iFrameRate[1] is for base+enhanced layer. */
    float               iFrameRate[MAX_LAYER];

    /** Specifies the picture quality factor on the scale of 1 to 10. It trades off
    the picture quality with the frame rate. Higher frame quality means lower frame rate.
    Lower frame quality for higher frame rate.*/
    int32               iFrameQuality;

    /** Enable the use of iFrameQuality to determine the frame rate. If it is false,
    the encoder will try to meet the specified frame rate regardless of the frame quality.*/
    bool                iEnableFrameQuality;

    /** Specifies the maximum number of P-frames between 2 INTRA frames. An INTRA mode is
    forced to a frame once this interval is reached. When there is only one I-frame is present
    at the beginning of the clip, iIFrameInterval should be set to -1. */
    int32               iIFrameInterval;

    /** According to iIFrameInterval setting, the minimum number of intra MB per frame is
    optimally calculated for error resiliency. However, when iIFrameInterval is set to -1,
    iNumIntraMBRefresh must be specified to guarantee the minimum number of intra
    macroblocks per frame.*/
    uint32              iNumIntraMBRefresh;

    /** Specifies the VBV buffer size which determines the end-to-end delay between the
    encoder and the decoder.  The size is in unit of seconds. For download application,
    the buffer size can be larger than the streaming application. For 2-way application,
    this buffer shall be kept minimal. For a special case, in VBR mode, iBufferDelay will
    be set to -1 to allow buffer underflow. */
    float               iBufferDelay;

    /** Specifies the type of the access whether it is streaming, CVEI_STREAMING
    (data partitioning mode) or download, CVEI_DOWNLOAD (combined mode).*/
    TPVContentType      iContentType;

    /** Specifies the rate control algorithm among one of the following constant Q,
    CBR and VBR.  The structure TMP4RateControlType is defined below.*/
    TMP4RateControlType iRateControlType;

    /** Specifies high quality but also high complexity mode for rate control. */
    bool                iRDOptimal;

    /** Specifies the initial quantization parameter for the first I-frame. If constant Q
    rate control is used, this QP will be used for all the I-frames. This number must be
    set between 1 and 31, otherwise, Initialize() will fail. */
    int                 iIquant[2];

    /** Specifies the initial quantization parameter for the first P-frame. If constant Q
    rate control is used, this QP will be used for all the P-frames. This number must be
    set between 1 and 31, otherwise, Initialize() will fail. */
    int                 iPquant[2];

    /** Specifies the initial quantization parameter for the first B-frame. If constant Q
    rate control is used, this QP will be used for all the B-frames. This number must be
    set between 1 and 31, otherwise, Initialize() will fail. */
    int                 iBquant[2];

    /** Specifies the search range in pixel unit for motion vector. The range of the
    motion vector will be of dimension [-iSearchRange.5, +iSearchRange.0]. */
    int32               iSearchRange;

    /** Specifies the use of 8x8 motion vectors. */
    bool                iMV8x8;

    /** Specifies the use of half-pel motion vectors. */
    bool                iMVHalfPel;

    /** Specifies automatic scene detection where I-frame will be used the the first frame
    in a new scene. */
    bool                iSceneDetection;

    /** Specifies the packet size in bytes which represents the number of bytes between two resync markers.
    For ECVEI_DOWNLOAD and ECVEI_H263, if iPacketSize is set to 0, there will be no resync markers in the bitstream.
    For ECVEI_STREAMING is parameter must be set to a value greater than 0.*/
    uint32              iPacketSize;

    /** Specifies whether the current frame skipping decision is allowed after encoding
    the current frame. If there is no memory of what has been coded for the current frame,
    iNoCurrentSkip has to be on. */
    bool                iNoCurrentSkip;

    /** Specifies that no frame skipping is allowed. Frame skipping is a tool used to
    control the average number of bits spent to meet the target bit rate. */
    bool                iNoFrameSkip;

    /** Specifies the duration of the clip in millisecond.*/
    int32               iClipDuration;

    /** Specifies the profile and level used to encode the bitstream. When present,
    other settings will be checked against the range allowable by this target profile
    and level. Fail may be returned from the Initialize call. */
    TPVM4VProfileLevel  iProfileLevel;

    /** Specifies FSI Buffer input */
    uint8*              iFSIBuff;

    /** Specifies FSI Buffer Length */
    int             iFSIBuffLength;


};


/** Structure for input format information */
struct TPVVideoInputFormat
{
    /** Contains the width in pixels of the input frame. */
    int32           iFrameWidth;

    /** Contains the height in pixels of the input frame. */
    int32           iFrameHeight;

    /** Contains the input frame rate in the unit of frame per second. */
    float           iFrameRate;

    /** Contains Frame Orientation. Used for RGB input. 1 means Bottom_UP RGB, 0 means Top_Down RGB, -1 for video formats other than RGB*/
    int             iFrameOrientation;

    /** Contains the format of the input video, e.g., YUV 4:2:0, UYVY, RGB24, etc. */
    TPVVideoFormat  iVideoFormat;
};


/** Contains the input data information */
struct TPVVideoInputData
{
    /** Pointer to an input frame buffer in input source format.*/
    uint8       *iSource;

    /** The corresponding time stamp of the input frame. */
    uint32      iTimeStamp;
};

/** Contains the output data information */
struct TPVVideoOutputData
{
    /** Pointer to the reconstructed frame buffer in YUV 4:2:0 domain. */
    uint8           *iFrame;

    /** The number of layer encoded, 0 for base, 1 for enhanced. */
    int32           iLayerNumber;

    /** Pointer to the encoded bitstream buffer. */
    uint8           *iBitStream;

    /** The size in bytes of iBStream. */
    int32           iBitStreamSize;

    /** The time stamp of the encoded frame according to the bitstream. */
    uint32          iVideoTimeStamp;

    /** The time stamp of the encoded frame as given before the encoding. */
    uint32          iExternalTimeStamp;

    /** The hint track information. */
    MP4HintTrack    iHintTrack;
};

/** An observer class for callbacks to report the status of the CVEI */
class MPVCVEIObserver
{
    public:
        /** The callback funtion with aEvent being one of TCVEIEvent enumeration. */
        virtual void HandlePVCVEIEvent
        (uint32 aId, uint32 aEvent, uint32 aParam1 = 0) = 0;
        virtual ~MPVCVEIObserver() {}
};

/** This class is the base class for codec specific interface class.
The users must maintain an instance of the codec specific class throughout
the encoding session.
*/
class CommonVideoEncoder : public OsclTimerObject
{
    public:
        /** Constructor for CVEI class. */
        CommonVideoEncoder() : OsclTimerObject(OsclActiveObject::EPriorityNominal, "PVEncoder") {};

        /** Initialization function to set the input video format and the
        encoding parameters. This function returns CVEI_ERROR if there is
        any errors. Otherwise, the function returns CVEI_SUCCESS.*/
        virtual  TCVEI_RETVAL Initialize(TPVVideoInputFormat *aVidInFormat, TPVVideoEncodeParam *aEncParam) = 0;

        /** Set the observer for asynchronous encoding mode. */
        virtual  TCVEI_RETVAL SetObserver(MPVCVEIObserver *aObserver) = 0;

        /** Add a buffer to the queue of output buffers for output bitstream in
        asynchronous encoding mode. */
        virtual  TCVEI_RETVAL AddBuffer(TPVVideoOutputData *aVidOut) = 0;

        /** This function sends in an input video data structure containing a source
        frame and the associated timestamp. The encoded bitstream will be returned by
        observer callback.
        The above 3 APIs only replace EncodeFrame() API. Other APIs such as initialization
        and update parameters remain the same. */
        virtual  TCVEI_RETVAL Encode(TPVVideoInputData *aVidIn) = 0;

        /** This function returns the maximum VBV buffer size such that the
            application can allocate a buffer that guarantees to fit one frame.*/
        virtual  int32 GetBufferSize() = 0;

        /** This function returns the VOL header part (starting from the VOS header)
        of the encoded bitstream. This function must be called after Initialize.
        The output is written to the memory (volHeader) allocated by the users.*/
        virtual  TCVEI_RETVAL GetVolHeader(uint8 *volHeader, int32 *size, int32 layer) = 0;

        /** This function sends in an input video data structure containing a source
        frame and the associated timestamp. It returns an output video data structure
        containing coded bit stream, reconstructed frame in YUV 4:2:0 (can be changed
        to source format) and the timestamp associated with the coded frame.
        The input timestamp may not correspond to the output timestamp. User can send
        an input structure in without getting any encoded data back or getting an encoded
        frame in the past. This function returns ECVEI_ERROR if there is any errors.
        Otherwise, the function returns ECVEI_SUCCESS.
        In case of Overrun Buffer usage, it is possible that return value is ECVEI_MORE_OUTPUT
        which indicates that frame cannot fit in the current buffer*/
        virtual  TCVEI_RETVAL EncodeFrame(TPVVideoInputData  *aVidIn, TPVVideoOutputData *aVidOut, int *aRemainingBytes
#ifdef PVAUTHOR_PROFILING
                                          , void *aParam1 = 0
#endif
                                         ) = 0;

        /** Before the termination of the encoding process, the users have to query
        whether there are any encoded frame pending inside the CVEI. The returned value
        will indicate whether there are more frames to be flushed (ECVEI_FLUSH).
        FlushOutput has to be called until there are no more frames, i.e., it returns
        ECVEI_SUCCESS. This function may be called during the encoding operation if
        there is no input frame and the application does not want to waste the time
        waiting for input frame. It can call this function to flush encoded frame
        out of the memory. */
        virtual  TCVEI_RETVAL FlushOutput(TPVVideoOutputData *aVidOut) = 0;

        /** This function cleanup the CVEI allocated resources. */
        virtual  TCVEI_RETVAL Terminate() = 0;

        /**This function dynamically changes the target bit rate of the encoder
        while encoding. aBitRate[n] is the new accumulate target bit rate of layer n.
        Successful update is returned with ECVEI_SUCCESS.*/
        virtual  TCVEI_RETVAL UpdateBitRate(int32 aNumLayer, int32 *aBitRate) = 0;

        /** This function dynamically changes the target frame rate of the encoder
        while encoding. aFrameRate[n] is the new accumulate target frame rate of
        layer n. Successful update is returned with ECVEI_SUCCESS. */
        virtual  TCVEI_RETVAL UpdateFrameRate(int32 aNumLayer, float *aFrameRate) = 0;

        /** This function dynamically changes the I-Vop update interval while
        encoding to a new value, aIFrameInterval. */
        virtual  TCVEI_RETVAL UpdateIFrameInterval(int32 aIFrameInterval) = 0;

        /** This function forces an I-Vop mode to the next frame to be encoded. */
        virtual  TCVEI_RETVAL IFrameRequest() = 0;

        /** This function returns the input width of a specific layer
        (not necessarily multiple of 16). */
        virtual  int32 GetEncodeWidth(int32 aLayer) = 0;

        /** This function returns the input height of a specific layer
        (not necessarily multiple of 16). */
        virtual  int32 GetEncodeHeight(int32 aLayer) = 0;

        /** This function returns the target encoded frame rate of a specific layer. */
        virtual  float GetEncodeFrameRate(int32 aLayer) = 0;
    protected:
        virtual void Run(void) = 0;
        virtual void DoCancel(void) = 0;
        /* internal enum */
        enum TCVEIState
        {
            EIdle,
            EEncode
        };

        TCVEIState  iState;
        uint32      iId;
};

#endif