frameworks/base/media/libstagefright/codecs/avc/enc/src/avcenc_api.h

   1 /* ------------------------------------------------------------------
   2  * Copyright (C) 1998-2009 PacketVideo
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  13  * express or implied.
  14  * See the License for the specific language governing permissions
  15  * and limitations under the License.
  16  * -------------------------------------------------------------------
  17  */
  18 /**
  19 This file contains application function interfaces to the AVC encoder library
  20 and necessary type defitionitions and enumerations.
  21 @publishedAll
  22 */
  23
  24 #ifndef AVCENC_API_H_INCLUDED
  25 #define AVCENC_API_H_INCLUDED
  26
  27 #ifndef AVCAPI_COMMON_H_INCLUDED
  28 #include "avcapi_common.h"
  29 #endif
  30
  31 // For memset, etc
  32 #include <string.h>
  33
  34 /**
  35  This enumeration is used for the status returned from the library interface.
  36 */
  37 typedef enum
  38 {
  39     /**
  40     Fail information, need to add more error code for more specific info
  41     */
  42     AVCENC_TRAILINGONES_FAIL = -35,
  43     AVCENC_SLICE_EMPTY = -34,
  44     AVCENC_POC_FAIL = -33,
  45     AVCENC_CONSECUTIVE_NONREF = -32,
  46     AVCENC_CABAC_FAIL = -31,
  47     AVCENC_PRED_WEIGHT_TAB_FAIL = -30,
  48     AVCENC_DEC_REF_PIC_MARK_FAIL = -29,
  49     AVCENC_SPS_FAIL = -28,
  50     AVCENC_BITSTREAM_BUFFER_FULL    = -27,
  51     AVCENC_BITSTREAM_INIT_FAIL = -26,
  52     AVCENC_CHROMA_QP_FAIL = -25,
  53     AVCENC_INIT_QS_FAIL = -24,
  54     AVCENC_INIT_QP_FAIL = -23,
  55     AVCENC_WEIGHTED_BIPRED_FAIL = -22,
  56     AVCENC_INVALID_INTRA_PERIOD = -21,
  57     AVCENC_INVALID_CHANGE_RATE = -20,
  58     AVCENC_INVALID_BETA_OFFSET = -19,
  59     AVCENC_INVALID_ALPHA_OFFSET = -18,
  60     AVCENC_INVALID_DEBLOCK_IDC = -17,
  61     AVCENC_INVALID_REDUNDANT_PIC = -16,
  62     AVCENC_INVALID_FRAMERATE = -15,
  63     AVCENC_INVALID_NUM_SLICEGROUP = -14,
  64     AVCENC_INVALID_POC_LSB = -13,
  65     AVCENC_INVALID_NUM_REF = -12,
  66     AVCENC_INVALID_FMO_TYPE = -11,
  67     AVCENC_ENCPARAM_MEM_FAIL = -10,
  68     AVCENC_LEVEL_NOT_SUPPORTED = -9,
  69     AVCENC_LEVEL_FAIL = -8,
  70     AVCENC_PROFILE_NOT_SUPPORTED = -7,
  71     AVCENC_TOOLS_NOT_SUPPORTED = -6,
  72     AVCENC_WRONG_STATE = -5,
  73     AVCENC_UNINITIALIZED = -4,
  74     AVCENC_ALREADY_INITIALIZED = -3,
  75     AVCENC_NOT_SUPPORTED = -2,
  76     AVCENC_MEMORY_FAIL = AVC_MEMORY_FAIL,
  77     AVCENC_FAIL = AVC_FAIL,
  78     /**
  79     Generic success value
  80     */
  81     AVCENC_SUCCESS = AVC_SUCCESS,
  82     AVCENC_PICTURE_READY = 2,
  83     AVCENC_NEW_IDR = 3, /* upon getting this, users have to call PVAVCEncodeSPS and PVAVCEncodePPS to get a new SPS and PPS*/
  84     AVCENC_SKIPPED_PICTURE = 4 /* continuable error message */
  85
  86 } AVCEnc_Status;
  87
  88 #define MAX_NUM_SLICE_GROUP  8      /* maximum for all the profiles */
  89
  90 /**
  91 This structure contains the encoding parameters.
  92 */
  93 typedef struct tagAVCEncParam
  94 {
  95     /* if profile/level is set to zero, encoder will choose the closest one for you */
  96     AVCProfile profile; /* profile of the bitstream to be compliant with*/
  97     AVCLevel   level;   /* level of the bitstream to be compliant with*/
  98
  99     int width;      /* width of an input frame in pixel */
 100     int height;     /* height of an input frame in pixel */
 101
 102     int poc_type; /* picture order count mode, 0,1 or 2 */
 103     /* for poc_type == 0 */
 104     uint log2_max_poc_lsb_minus_4; /* specify maximum value of POC Lsb, range 0..12*/
 105     /* for poc_type == 1 */
 106     uint delta_poc_zero_flag; /* delta POC always zero */
 107     int offset_poc_non_ref; /* offset for non-reference pic */
 108     int offset_top_bottom; /* offset between top and bottom field */
 109     uint num_ref_in_cycle; /* number of reference frame in one cycle */
 110     int *offset_poc_ref; /* array of offset for ref pic, dimension [num_ref_in_cycle] */
 111
 112     int num_ref_frame;  /* number of reference frame used */
 113     int num_slice_group;  /* number of slice group */
 114     int fmo_type;   /* 0: interleave, 1: dispersed, 2: foreground with left-over
 115                     3: box-out, 4:raster scan, 5:wipe, 6:explicit */
 116     /* for fmo_type == 0 */
 117     uint run_length_minus1[MAX_NUM_SLICE_GROUP];   /* array of size num_slice_group, in round robin fasion */
 118     /* fmo_type == 2*/
 119     uint top_left[MAX_NUM_SLICE_GROUP-1];           /* array of co-ordinates of each slice_group */
 120     uint bottom_right[MAX_NUM_SLICE_GROUP-1];       /* except the last one which is the background. */
 121     /* fmo_type == 3,4,5 */
 122     AVCFlag change_dir_flag;  /* slice group change direction flag */
 123     uint change_rate_minus1;
 124     /* fmo_type == 6 */
 125     uint *slice_group; /* array of size MBWidth*MBHeight */
 126
 127     AVCFlag db_filter;  /* enable deblocking loop filter */
 128     int disable_db_idc;  /* 0: filter everywhere, 1: no filter, 2: no filter across slice boundary */
 129     int alpha_offset;   /* alpha offset range -6,...,6 */
 130     int beta_offset;    /* beta offset range -6,...,6 */
 131
 132     AVCFlag constrained_intra_pred; /* constrained intra prediction flag */
 133
 134     AVCFlag auto_scd;   /* scene change detection on or off */
 135     int idr_period; /* idr frame refresh rate in number of target encoded frame (no concept of actual time).*/
 136     int intramb_refresh;    /* minimum number of intra MB per frame */
 137     AVCFlag data_par;   /* enable data partitioning */
 138
 139     AVCFlag fullsearch; /* enable full-pel full-search mode */
 140     int search_range;   /* search range for motion vector in (-search_range,+search_range) pixels */
 141     AVCFlag sub_pel;    /* enable sub pel prediction */
 142     AVCFlag submb_pred; /* enable sub MB partition mode */
 143     AVCFlag rdopt_mode; /* RD optimal mode selection */
 144     AVCFlag bidir_pred; /* enable bi-directional for B-slice, this flag forces the encoder to encode
 145                         any frame with POC less than the previously encoded frame as a B-frame.
 146                         If it's off, then such frames will remain P-frame. */
 147
 148     AVCFlag rate_control; /* rate control enable, on: RC on, off: constant QP */
 149     int initQP;     /* initial QP */
 150     uint32 bitrate;    /* target encoding bit rate in bits/second */
 151     uint32 CPB_size;  /* coded picture buffer in number of bits */
 152     uint32 init_CBP_removal_delay; /* initial CBP removal delay in msec */
 153
 154     uint32 frame_rate;  /* frame rate in the unit of frames per 1000 second */
 155     /* note, frame rate is only needed by the rate control, AVC is timestamp agnostic. */
 156
 157     AVCFlag out_of_band_param_set; /* flag to set whether param sets are to be retrieved up front or not */
 158
 159     AVCFlag use_overrun_buffer;  /* do not throw away the frame if output buffer is not big enough.
 160                                     copy excess bits to the overrun buffer */
 161 } AVCEncParams;
 162
 163
 164 /**
 165 This structure contains current frame encoding statistics for debugging purpose.
 166 */
 167 typedef struct tagAVCEncFrameStats
 168 {
 169     int avgFrameQP;   /* average frame QP */
 170     int numIntraMBs;  /* number of intra MBs */
 171     int numFalseAlarm;
 172     int numMisDetected;
 173     int numDetected;
 174
 175 } AVCEncFrameStats;
 176
 177 #ifdef __cplusplus
 178 extern "C"
 179 {
 180 #endif
 181     /** THE FOLLOWINGS ARE APIS */
 182     /**
 183     This function initializes the encoder library. It verifies the validity of the
 184     encoding parameters against the specified profile/level and the list of supported
 185     tools by this library. It allocates necessary memories required to perform encoding.
 186     For re-encoding application, if users want to setup encoder in a more precise way,
 187     users can give the external SPS and PPS to the encoder to follow.
 188     \param "avcHandle"  "Handle to the AVC encoder library object."
 189     \param "encParam"   "Pointer to the encoding parameter structure."
 190     \param "extSPS"     "External SPS used for re-encoding purpose. NULL if not present"
 191     \param "extPPS"     "External PPS used for re-encoding purpose. NULL if not present"
 192     \return "AVCENC_SUCCESS for success,
 193              AVCENC_NOT_SUPPORTED for the use of unsupported tools,
 194              AVCENC_MEMORY_FAIL for memory allocation failure,
 195              AVCENC_FAIL for generic failure."
 196     */
 197     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncInitialize(AVCHandle *avcHandle, AVCEncParams *encParam, void* extSPS, void* extPPS);
 198
 199
 200     /**
 201     Since the output buffer size is not known prior to encoding a frame, users need to
 202     allocate big enough buffer otherwise, that frame will be dropped. This function returns
 203     the size of the output buffer to be allocated by the users that guarantees to hold one frame.
 204     It follows the CPB spec for a particular level.  However, when the users set use_overrun_buffer
 205     flag, this API is useless as excess output bits are saved in the overrun buffer waiting to be
 206     copied out in small chunks, i.e. users can allocate any size of output buffer.
 207     \param "avcHandle"  "Handle to the AVC encoder library object."
 208     \param "size"   "Pointer to the size to be modified."
 209     \return "AVCENC_SUCCESS for success, AVCENC_UNINITIALIZED when level is not known.
 210     */
 211
 212     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncGetMaxOutputBufferSize(AVCHandle *avcHandle, int* size);
 213
 214     /**
 215     Users call this function to provide an input structure to the encoder library which will keep
 216     a list of input structures it receives in case the users call this function many time before
 217     calling PVAVCEncodeSlice. The encoder library will encode them according to the frame_num order.
 218     Users should not modify the content of a particular frame until this frame is encoded and
 219     returned thru CBAVCEnc_ReturnInput() callback function.
 220     \param "avcHandle"  "Handle to the AVC encoder library object."
 221     \param "input"      "Pointer to the input structure."
 222     \return "AVCENC_SUCCESS for success,
 223             AVCENC_FAIL if the encoder is not in the right state to take a new input frame.
 224             AVCENC_NEW_IDR for the detection or determination of a new IDR, with this status,
 225             the returned NAL is an SPS NAL,
 226             AVCENC_NO_PICTURE if the input frame coding timestamp is too early, users must
 227             get next frame or adjust the coding timestamp."
 228     */
 229     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncSetInput(AVCHandle *avcHandle, AVCFrameIO *input);
 230
 231     /**
 232     This function is called to encode a NAL unit which can be an SPS NAL, a PPS NAL or
 233     a VCL (video coding layer) NAL which contains one slice of data. It could be a
 234     fixed number of macroblocks, as specified in the encoder parameters set, or the
 235     maximum number of macroblocks fitted into the given input argument "buffer". The
 236     input frame is taken from the oldest unencoded input frame retrieved by users by
 237     PVAVCEncGetInput API.
 238     \param "avcHandle"  "Handle to the AVC encoder library object."
 239     \param "buffer"     "Pointer to the output AVC bitstream buffer, the format will be EBSP,
 240                          not RBSP."
 241     \param "buf_nal_size"   "As input, the size of the buffer in bytes.
 242                         This is the physical limitation of the buffer. As output, the size of the EBSP."
 243     \param "nal_type"   "Pointer to the NAL type of the returned buffer."
 244     \return "AVCENC_SUCCESS for success of encoding one slice,
 245              AVCENC_PICTURE_READY for the completion of a frame encoding,
 246              AVCENC_FAIL for failure (this should not occur, though)."
 247     */
 248     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncodeNAL(AVCHandle *avcHandle, uint8 *buffer, uint *buf_nal_size, int *nal_type);
 249
 250     /**
 251     This function sniffs the nal_unit_type such that users can call corresponding APIs.
 252     This function is identical to PVAVCDecGetNALType() in the decoder.
 253     \param "bitstream"  "Pointer to the beginning of a NAL unit (start with forbidden_zero_bit, etc.)."
 254     \param "size"       "size of the bitstream (NumBytesInNALunit + 1)."
 255     \param "nal_unit_type" "Pointer to the return value of nal unit type."
 256     \return "AVCENC_SUCCESS if success, AVCENC_FAIL otherwise."
 257     */
 258     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncGetNALType(uint8 *bitstream, int size, int *nal_type, int *nal_ref_idc);
 259
 260     /**
 261     This function returns the pointer to internal overrun buffer. Users can call this to query
 262     whether the overrun buffer has been used to encode the current NAL.
 263     \param "avcHandle"  "Pointer to the handle."
 264     \return "Pointer to overrun buffer if it is used, otherwise, NULL."
 265     */
 266     OSCL_IMPORT_REF uint8* PVAVCEncGetOverrunBuffer(AVCHandle* avcHandle);
 267
 268     /**
 269     This function returns the reconstructed frame of the most recently encoded frame.
 270     Note that this frame is not returned to the users yet. Users should only read the
 271     content of this frame.
 272     \param "avcHandle"  "Handle to the AVC encoder library object."
 273     \param "output"     "Pointer to the input structure."
 274     \return "AVCENC_SUCCESS for success, AVCENC_NO_PICTURE if no picture to be outputted."
 275     */
 276     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncGetRecon(AVCHandle *avcHandle, AVCFrameIO *recon);
 277
 278     /**
 279     This function is used to return the recontructed frame back to the AVC encoder library
 280     in order to be re-used for encoding operation. If users want the content of it to remain
 281     unchanged for a long time, they should make a copy of it and release the memory back to
 282     the encoder. The encoder relies on the id element in the AVCFrameIO structure,
 283     thus users should not change the id value.
 284     \param "avcHandle"  "Handle to the AVC decoder library object."
 285     \param "output"      "Pointer to the AVCFrameIO structure."
 286     \return "AVCENC_SUCCESS for success, AVCENC_FAIL for fail for id not found."
 287     */
 288     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncReleaseRecon(AVCHandle *avcHandle, AVCFrameIO *recon);
 289
 290     /**
 291     This function performs clean up operation including memory deallocation.
 292     The encoder will also clear the list of input structures it has not released.
 293     This implies that users must keep track of the number of input structure they have allocated
 294     and free them accordingly.
 295     \param "avcHandle"  "Handle to the AVC encoder library object."
 296     */
 297     OSCL_IMPORT_REF void    PVAVCCleanUpEncoder(AVCHandle *avcHandle);
 298
 299     /**
 300     This function extracts statistics of the current frame. If the encoder has not finished
 301     with the current frame, the result is not accurate.
 302     \param "avcHandle"  "Handle to the AVC encoder library object."
 303     \param "avcStats"   "Pointer to AVCEncFrameStats structure."
 304     \return "void."
 305     */
 306     void PVAVCEncGetFrameStats(AVCHandle *avcHandle, AVCEncFrameStats *avcStats);
 307
 308     /**
 309     These functions are used for the modification of encoding parameters.
 310     To be polished.
 311     */
 312     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncUpdateBitRate(AVCHandle *avcHandle, uint32 bitrate);
 313     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncUpdateFrameRate(AVCHandle *avcHandle, uint32 num, uint32 denom);
 314     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncUpdateIDRInterval(AVCHandle *avcHandle, int IDRInterval);
 315     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncIDRRequest(AVCHandle *avcHandle);
 316     OSCL_IMPORT_REF AVCEnc_Status PVAVCEncUpdateIMBRefresh(AVCHandle *avcHandle, int numMB);
 317
 318
 319 #ifdef __cplusplus
 320 }
 321 #endif
 322 #endif  /* _AVCENC_API_H_ */
 323