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