linux-arkmicro/buildroot-external/package/hx280enc/software/inc/h264encapi.h

/*------------------------------------------------------------------------------
--                                                                            --
--       This software is confidential and proprietary and may be used        --
--        only as expressly authorized by a licensing agreement from          --
--                                                                            --
--                            Hantro Products Oy.                             --
--                                                                            --
--                   (C) COPYRIGHT 2006 HANTRO PRODUCTS OY                    --
--                            ALL RIGHTS RESERVED                             --
--                                                                            --
--                 The entire notice above must be reproduced                 --
--                  on all copies and should not be removed.                  --
--                                                                            --
--------------------------------------------------------------------------------
--
--  Abstract : Hantro 8290 H.264 Encoder API
--
------------------------------------------------------------------------------*/

#ifndef __H264ENCAPI_H__
#define __H264ENCAPI_H__

#include "basetype.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*------------------------------------------------------------------------------
    1. Type definition for encoder instance
------------------------------------------------------------------------------*/

    typedef const void *H264EncInst;

/*------------------------------------------------------------------------------
    2. Enumerations for API parameters
------------------------------------------------------------------------------*/

/* Function return values */
    typedef enum
    {
        H264ENC_OK = 0,
        H264ENC_FRAME_READY = 1,

        H264ENC_ERROR = -1,
        H264ENC_NULL_ARGUMENT = -2,
        H264ENC_INVALID_ARGUMENT = -3,
        H264ENC_MEMORY_ERROR = -4,
        H264ENC_EWL_ERROR = -5,
        H264ENC_EWL_MEMORY_ERROR = -6,
        H264ENC_INVALID_STATUS = -7,
        H264ENC_OUTPUT_BUFFER_OVERFLOW = -8,
        H264ENC_HW_BUS_ERROR = -9,
        H264ENC_HW_DATA_ERROR = -10,
        H264ENC_HW_TIMEOUT = -11,
        H264ENC_HW_RESERVED = -12,
        H264ENC_SYSTEM_ERROR = -13,
        H264ENC_INSTANCE_ERROR = -14,
        H264ENC_HRD_ERROR = -15,
        H264ENC_HW_RESET = -16
    } H264EncRet;

/* Stream type for initialization */
    typedef enum
    {
        H264ENC_BYTE_STREAM = 0,    /* H.264 annex B: NAL unit starts with
                                     * hex bytes '00 00 00 01' */
        H264ENC_NAL_UNIT_STREAM = 1 /* Plain NAL units without startcode */
    } H264EncStreamType;

/* Stream view mode and buffer requirement for initialization */
    typedef enum
    {
        H264ENC_BASE_VIEW_DOUBLE_BUFFER = 0,    /* H.264 stream using
                                                   two reference frame buffers */
        H264ENC_BASE_VIEW_SINGLE_BUFFER = 1,    /* H.264 stream using
                                                   one reference frame buffers,
                                                   HRD frame discard not possible */
        H264ENC_MVC_STEREO_INTER_VIEW_PRED = 2, /* H.264 MVC Stereo stream using
                                                   one reference frame buffer,
                                                   no HRD frame discard,
                                                   second view is always
                                                   inter-view predicted */
        H264ENC_MVC_STEREO_INTER_PRED = 3       /* H.264 MVC Stereo stream using
                                                   two reference frame buffers,
                                                   no HRD frame discard,
                                                   second view can be inter
                                                   predicted */
    } H264EncViewMode;

/* Level for initialization */
    typedef enum
    {
        H264ENC_LEVEL_1 = 10,
        H264ENC_LEVEL_1_b = 99,
        H264ENC_LEVEL_1_1 = 11,
        H264ENC_LEVEL_1_2 = 12,
        H264ENC_LEVEL_1_3 = 13,
        H264ENC_LEVEL_2 = 20,
        H264ENC_LEVEL_2_1 = 21,
        H264ENC_LEVEL_2_2 = 22,
        H264ENC_LEVEL_3 = 30,
        H264ENC_LEVEL_3_1 = 31,
        H264ENC_LEVEL_3_2 = 32,
        H264ENC_LEVEL_4 = 40,
        H264ENC_LEVEL_4_1 = 41,
        H264ENC_LEVEL_4_2 = 42,
        H264ENC_LEVEL_5 = 50,
        H264ENC_LEVEL_5_1 = 51
    } H264EncLevel;

/* Picture YUV type for initialization */
    typedef enum
    {
        H264ENC_YUV420_PLANAR = 0,  /* YYYY... UUUU... VVVV */
        H264ENC_YUV420_SEMIPLANAR = 1,  /* YYYY... UVUVUV...    */
        H264ENC_YUV422_INTERLEAVED_YUYV = 2,    /* YUYVYUYV...          */
        H264ENC_YUV422_INTERLEAVED_UYVY = 3,    /* UYVYUYVY...          */
        H264ENC_RGB565 = 4, /* 16-bit RGB           */
        H264ENC_BGR565 = 5, /* 16-bit RGB           */
        H264ENC_RGB555 = 6, /* 15-bit RGB           */
        H264ENC_BGR555 = 7, /* 15-bit RGB           */
        H264ENC_RGB444 = 8, /* 12-bit RGB           */
        H264ENC_BGR444 = 9, /* 12-bit RGB           */
        H264ENC_RGB888 = 10,    /* 24-bit RGB           */
        H264ENC_BGR888 = 11,    /* 24-bit RGB           */
        H264ENC_RGB101010 = 12, /* 30-bit RGB           */
        H264ENC_BGR101010 = 13  /* 30-bit RGB           */
    } H264EncPictureType;

/* Picture rotation for pre-processing */
    typedef enum
    {
        H264ENC_ROTATE_0 = 0,
        H264ENC_ROTATE_90R = 1, /* Rotate 90 degrees clockwise */
        H264ENC_ROTATE_90L = 2  /* Rotate 90 degrees counter-clockwise */
    } H264EncPictureRotation;

/* Picture color space conversion (RGB input) for pre-processing */
    typedef enum
    {
        H264ENC_RGBTOYUV_BT601 = 0, /* Color conversion according to BT.601 */
        H264ENC_RGBTOYUV_BT709 = 1, /* Color conversion according to BT.709 */
        H264ENC_RGBTOYUV_USER_DEFINED = 2   /* User defined color conversion */
    } H264EncColorConversionType;

/* Picture type for encoding */
    typedef enum
    {
        H264ENC_INTRA_FRAME = 0,
        H264ENC_PREDICTED_FRAME = 1,
        H264ENC_NOTCODED_FRAME  /* Used just as a return value */
    } H264EncPictureCodingType;

/*------------------------------------------------------------------------------
    3. Structures for API function parameters
------------------------------------------------------------------------------*/

/* Configuration info for initialization
 * Width and height are picture dimensions after rotation
 * Width and height are restricted by level limitations
 */
    typedef struct
    {
        H264EncStreamType streamType;   /* Byte stream / Plain NAL units */
        H264EncViewMode viewMode;       /* Mode of stream to be generated and
                                           the corresponding amount of encoder
                                           internal frame buffers required */
        /* Stream Profile will be automatically decided based on parameters:
         * CABAC            -> Main/High Profile,
         * 8x8-transform    -> High Profile,
         * MVC              -> Stereo High Profile */
        H264EncLevel level;
        u32 width;           /* Encoded picture width in pixels, multiple of 4 */
        u32 height;          /* Encoded picture height in pixels, multiple of 2 */
        u32 frameRateNum;    /* The stream time scale, [1..1048575] */
        u32 frameRateDenom;  /* Maximum frame rate is frameRateNum/frameRateDenom
                              * in frames/second. The actual frame rate will be
                              * defined by timeIncrement of encoded pictures,
                              * [1..frameRateNum] */
    } H264EncConfig;

/* Defining rectangular macroblock area in encoder picture */
    typedef struct
    {
        u32 enable;         /* [0,1] Enables this area */
        u32 top;            /* Top macroblock row inside area [0..heightMbs-1] */
        u32 left;           /* Left macroblock row inside area [0..widthMbs-1] */
        u32 bottom;         /* Bottom macroblock row inside area [top..heightMbs-1] */
        u32 right;          /* Right macroblock row inside area [left..widthMbs-1] */
    } H264EncPictureArea;

/* Coding control parameters */
    typedef struct
    {
        u32 sliceSize;       /* Slice size in macroblock rows,
                              * 0 to encode each picture in one slice,
                              * [0..height/16]
                              */
        u32 seiMessages;     /* Insert picture timing and buffering
                              * period SEI messages into the stream,
                              * [0,1]
                              */
        u32 videoFullRange;  /* Input video signal sample range, [0,1]
                              * 0 = Y range in [16..235],
                              * Cb&Cr range in [16..240]
                              * 1 = Y, Cb and Cr range in [0..255]
                              */
        u32 constrainedIntraPrediction; /* 0 = No constrains,
                                         * 1 = Only use intra neighbours */
        u32 disableDeblockingFilter;    /* 0 = Filter enabled,
                                         * 1 = Filter disabled,
                                         * 2 = Filter disabled on slice edges */
        u32 sampleAspectRatioWidth; /* Horizontal size of the sample aspect
                                     * ratio (in arbitrary units), 0 for
                                     * unspecified, [0..65535]
                                     */
        u32 sampleAspectRatioHeight;    /* Vertical size of the sample aspect ratio
                                         * (in same units as sampleAspectRatioWidth)
                                         * 0 for unspecified, [0..65535]
                                         */
        u32 enableCabac;     /* 0 = CAVLC - Baseline profile,
                              * 1 = CABAC - Main profile,
                              * 2 = CABAC/CAVLC frame based -
                              *     Performance optimized Main profile with
                              *     Intra frames encoded using CAVLC and
                              *     Inter frames encoded using CABAC */
        u32 cabacInitIdc;    /* [0,2] CABAC table initial value */
        u32 transform8x8Mode;   /* Enable 8x8 transform mode, High profile
                                 * 0=disabled, 1=adaptive 8x8, 2=always 8x8 */
        u32 quarterPixelMv;     /* 1/4 pixel motion estimation
                                 * 0=disabled, 1=adaptive, 2=enabled */
        u32 cirStart;           /* [0..mbTotal] First macroblock for
                                   Cyclic Intra Refresh */
        u32 cirInterval;        /* [0..mbTotal] Macroblock interval for
                                   Cyclic Intra Refresh, 0=disabled */
        u32 intraSliceMap1;     /* Bitmap for forcing slices 0..31 to intra,
                                   LSB=slice 0, MSB=slice 31, 1=intra. */
        u32 intraSliceMap2;     /* Bitmap for forcing slices 32..63 to intra,
                                   LSB=slice 32, MSB=slice 63, 1=intra. */
        u32 intraSliceMap3;     /* Bitmap for forcing slices 64..95 to intra,
                                   LSB=slice 64, MSB=slice 95, 1=intra. */
        H264EncPictureArea intraArea;   /* Area for forcing intra macroblocks */
        H264EncPictureArea roi1Area;    /* Area for 1st Region-Of-Interest */
        H264EncPictureArea roi2Area;    /* Area for 2nd Region-Of-Interest */
        i32 roi1DeltaQp;                /* [-15..0] QP delta value for 1st ROI */
        i32 roi2DeltaQp;                /* [-15..0] QP delta value for 2nd ROI */
    } H264EncCodingCtrl;

/* Rate control parameters */
    typedef struct
    {
        u32 pictureRc;       /* Adjust QP between pictures, [0,1] */
        u32 mbRc;            /* Adjust QP inside picture, [0,1] */
        u32 pictureSkip;     /* Allow rate control to skip pictures, [0,1] */
        i32 qpHdr;           /* QP for next encoded picture, [-1..51]
                              * -1 = Let rate control calculate initial QP
                              * This QP is used for all pictures if 
                              * HRD and pictureRc and mbRc are disabled
                              * If HRD is enabled it may override this QP
                              */
        u32 qpMin;           /* Minimum QP for any picture, [0..51] */
        u32 qpMax;           /* Maximum QP for any picture, [0..51] */
        u32 bitPerSecond;    /* Target bitrate in bits/second, this is
                              * needed if pictureRc, mbRc, pictureSkip or
                              * hrd is enabled [10000..60000000]
                              */
        u32 hrd;             /* Hypothetical Reference Decoder model, [0,1]
                              * restricts the instantaneous bitrate and
                              * total bit amount of every coded picture.
                              * Enabling HRD will cause tight constrains
                              * on the operation of the rate control
                              */
        u32 hrdCpbSize;      /* Size of Coded Picture Buffer in HRD (bits) */
        u32 gopLen;          /* Length for Group of Pictures, indicates
                              * the distance of two intra pictures,
                              * including first intra [1..300]
                              */
        i32 intraQpDelta;    /* Intra QP delta. intraQP = QP + intraQpDelta
                              * This can be used to change the relative quality
                              * of the Intra pictures or to lower the size
                              * of Intra pictures. [-12..12]
                              */
        u32 fixedIntraQp;    /* Fixed QP value for all Intra pictures, [0..51]
                              * 0 = Rate control calculates intra QP.
                              */
        i32 mbQpAdjustment;  /* Encoder uses MAD thresholding to recognize
                              * macroblocks with least details. This value is
                              * used to adjust the QP of these macroblocks
                              * increasing the subjective quality. [-8..7]
                              */
    } H264EncRateCtrl;

/* Encoder input structure */
    typedef struct
    {
        u32 busLuma;         /* Bus address for input picture
                              * planar format: luminance component
                              * semiplanar format: luminance component 
                              * interleaved format: whole picture
                              */
        u32 busChromaU;      /* Bus address for input chrominance
                              * planar format: cb component
                              * semiplanar format: both chrominance
                              * interleaved format: not used
                              */
        u32 busChromaV;      /* Bus address for input chrominance
                              * planar format: cr component
                              * semiplanar format: not used
                              * interleaved format: not used
                              */
        u32 timeIncrement;   /* The previous picture duration in units
                              * of 1/frameRateNum. 0 for the very first picture
                              * and typically equal to frameRateDenom for the rest.
                              */
        u32 *pOutBuf;        /* Pointer to output stream buffer */
        u32 busOutBuf;       /* Bus address of output stream buffer */
        u32 outBufSize;      /* Size of output stream buffer in bytes */
        H264EncPictureCodingType codingType;    /* Proposed picture coding type, 
                                                 * INTRA/PREDICTED
                                                 */
        u32 busLumaStab;     /* bus address of next picture to stabilize (luminance) */
    } H264EncIn;

/* Encoder output structure */
    typedef struct
    {
        H264EncPictureCodingType codingType;    /* Realized picture coding type,
                                                 * INTRA/PREDICTED/NOTCODED
                                                 */
        u32 streamSize;      /* Size of output stream in bytes */
        i8 *motionVectors;   /* One pixel motion vector x and y and corresponding
                                SAD value for every macroblock.
                                Format: mb0x mb0y mb0sadMsb mb0sadLsb mb1x .. */
        u32 *pNaluSizeBuf;   /* Output buffer for NAL unit sizes
                              * pNaluSizeBuf[0] = NALU 0 size in bytes
                              * pNaluSizeBuf[1] = NALU 1 size in bytes
                              * etc
                              * Zero value is written after last NALU.
                              */
        u32 numNalus;        /* Amount of NAL units */
    } H264EncOut;

/* Input pre-processing */
    typedef struct
    {
        H264EncColorConversionType type;
        u16 coeffA;          /* User defined color conversion coefficient */
        u16 coeffB;          /* User defined color conversion coefficient */
        u16 coeffC;          /* User defined color conversion coefficient */
        u16 coeffE;          /* User defined color conversion coefficient */
        u16 coeffF;          /* User defined color conversion coefficient */
    } H264EncColorConversion;

    typedef struct
    {
        u32 origWidth;
        u32 origHeight;
        u32 xOffset;
        u32 yOffset;
        H264EncPictureType inputType;
        H264EncPictureRotation rotation;
        u32 videoStabilization;
        H264EncColorConversion colorConversion;
    } H264EncPreProcessingCfg;

/* Callback struct and function type. The callback is made by the encoder
 * when a slice is completed and available in the encoder stream output buffer. */

    typedef struct
    {
        u32 slicesReadyPrev;/* Indicates how many slices were completed at
                               previous callback. This is given because
                               several slices can be completed between
                               the callbacks. */
        u32 slicesReady;    /* Indicates how many slices are completed. */
        u32 *sliceSizes;    /* Holds the size (bytes) of every completed slice. */
        u32 *pOutBuf;       /* Pointer to beginning of output stream buffer. */
        void *pAppData;     /* Pointer to application data. */
    } H264EncSliceReady;

    typedef void (*H264EncSliceReadyCallBackFunc)(H264EncSliceReady *sliceReady);

/* Version information */
    typedef struct
    {
        u32 major;           /* Encoder API major version */
        u32 minor;           /* Encoder API minor version */
    } H264EncApiVersion;

    typedef struct
    {
        u32 swBuild;         /* Software build ID */
        u32 hwBuild;         /* Hardware build ID */
    } H264EncBuild;

/*------------------------------------------------------------------------------
    4. Encoder API function prototypes
------------------------------------------------------------------------------*/

/* Version information */
    H264EncApiVersion H264EncGetApiVersion(void);
    H264EncBuild H264EncGetBuild(void);

/* Initialization & release */
    H264EncRet H264EncInit(const H264EncConfig * pEncConfig,
                           H264EncInst * instAddr);
    H264EncRet H264EncRelease(H264EncInst inst);

/* Encoder configuration before stream generation */
    H264EncRet H264EncSetCodingCtrl(H264EncInst inst, const H264EncCodingCtrl *
                                    pCodingParams);
    H264EncRet H264EncGetCodingCtrl(H264EncInst inst, H264EncCodingCtrl *
                                    pCodingParams);

/* Encoder configuration before and during stream generation */
    H264EncRet H264EncSetRateCtrl(H264EncInst inst,
                                  const H264EncRateCtrl * pRateCtrl);
    H264EncRet H264EncGetRateCtrl(H264EncInst inst,
                                  H264EncRateCtrl * pRateCtrl);

    H264EncRet H264EncSetPreProcessing(H264EncInst inst,
                                       const H264EncPreProcessingCfg *
                                       pPreProcCfg);
    H264EncRet H264EncGetPreProcessing(H264EncInst inst,
                                       H264EncPreProcessingCfg * pPreProcCfg);

/* Encoder user data insertion during stream generation */
    H264EncRet H264EncSetSeiUserData(H264EncInst inst, const u8 * pUserData,
                                     u32 userDataSize);

/* Stream generation */

/* H264EncStrmStart generates the SPS and PPS. SPS is the first NAL unit and PPS
 * is the second NAL unit. NaluSizeBuf indicates the size of NAL units.
 */
    H264EncRet H264EncStrmStart(H264EncInst inst, const H264EncIn * pEncIn,
                                H264EncOut * pEncOut);

/* H264EncStrmEncode encodes one video frame. If SEI messages are enabled the
 * first NAL unit is a SEI message. When MVC mode is selected first encoded
 * frame belongs to view=0 and second encoded frame belongs to view=1 and so on.
 * When MVC mode is selected a prefix NAL unit is generated before view=0 frames.
 */
    H264EncRet H264EncStrmEncode(H264EncInst inst, const H264EncIn * pEncIn,
                                 H264EncOut * pEncOut,
                                 H264EncSliceReadyCallBackFunc cbFunc,
                                 void * pAppData);

/* H264EncStrmEnd ends a stream with an EOS code. */
    H264EncRet H264EncStrmEnd(H264EncInst inst, const H264EncIn * pEncIn,
                              H264EncOut * pEncOut);

/* Hantro internal encoder testing */
    H264EncRet H264EncSetTestId(H264EncInst inst, u32 testId);

/*------------------------------------------------------------------------------
    5. Encoder API tracing callback function
------------------------------------------------------------------------------*/

    void H264EncTrace(const char *msg);

#ifdef __cplusplus
}
#endif

#endif /*__H264ENCAPI_H__*/