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 324