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 #ifndef _MP4ENC_API_H_ 19 #define _MP4ENC_API_H_ 20 21 #ifndef OSCL_BASE_H_INCLUDED 22 #include "oscl_base.h" 23 #endif 24 25 #ifndef _PV_TYPES_ 26 #define _PV_TYPES_ 27 typedef unsigned char UChar; 28 typedef char Char; 29 typedef unsigned int UInt; 30 typedef int Int; 31 typedef unsigned short UShort; 32 typedef short Short; 33 typedef unsigned int Bool; 34 typedef unsigned long ULong; 35 36 #define PV_CODEC_INIT 0 37 #define PV_CODEC_STOP 1 38 #endif 39 40 #define PV_TRUE 1 41 #define PV_FALSE 0 42 43 typedef enum 44 { 45 SHORT_HEADER, 46 SHORT_HEADER_WITH_ERR_RES, 47 H263_MODE, 48 H263_MODE_WITH_ERR_RES, 49 DATA_PARTITIONING_MODE, 50 COMBINE_MODE_NO_ERR_RES, 51 COMBINE_MODE_WITH_ERR_RES 52 53 } MP4EncodingMode; 54 55 typedef enum 56 { 57 CONSTANT_Q, 58 CBR_1, 59 VBR_1, 60 CBR_2, 61 VBR_2, 62 CBR_LOWDELAY 63 } MP4RateControlType; 64 65 typedef enum 66 { 67 PASS1, 68 PASS2 69 } PassNum; 70 71 typedef enum 72 { 73 PV_OFF, 74 PV_ON 75 } ParamEncMode; 76 77 78 /* {SPL0, SPL1, SPL2, SPL3, CPL1, CPL2, CPL2, CPL2} , SPL0: Simple Profile@Level0 , CPL1: Core Profile@Level1 */ 79 /* {SSPL0, SSPL1, SSPL2, SSPL2, CSPL1, CSPL2, CSPL3, CSPL3} , SSPL0: Simple Scalable Profile@Level0, CPL1: Core Scalable Profile@Level1 */ 80 81 typedef enum 82 { 83 /* Non-scalable profile */ 84 SIMPLE_PROFILE_LEVEL0 = 0, 85 SIMPLE_PROFILE_LEVEL1, 86 SIMPLE_PROFILE_LEVEL2, 87 SIMPLE_PROFILE_LEVEL3, 88 CORE_PROFILE_LEVEL1, 89 CORE_PROFILE_LEVEL2, 90 91 /* Scalable profile */ 92 SIMPLE_SCALABLE_PROFILE_LEVEL0 = 6, 93 SIMPLE_SCALABLE_PROFILE_LEVEL1, 94 SIMPLE_SCALABLE_PROFILE_LEVEL2, 95 96 CORE_SCALABLE_PROFILE_LEVEL1 = 10, 97 CORE_SCALABLE_PROFILE_LEVEL2, 98 CORE_SCALABLE_PROFILE_LEVEL3 99 100 } ProfileLevelType; 101 102 103 typedef struct tagMP4HintTrack 104 { 105 UChar MTB; 106 UChar LayerID; 107 UChar CodeType; 108 UChar RefSelCode; 109 } MP4HintTrack; 110 111 typedef struct tagvideoEncControls 112 { 113 void *videoEncoderData; 114 Int videoEncoderInit; 115 } VideoEncControls; 116 117 118 typedef struct tagvideoEncFrameIO 119 { 120 UChar *yChan; /* pointer to Y */ 121 UChar *uChan; /* pointer to U */ 122 UChar *vChan; /* pointer to V */ 123 Int height; /* height for Y */ 124 Int pitch; /* stride for Y */ 125 ULong timestamp; /* modulo timestamp in millisecond*/ 126 127 } VideoEncFrameIO ; 128 129 /** 130 @brief Encoding options structure */ 131 typedef struct tagvideoEncOptions 132 { 133 /** @brief Sets the encoding mode, defined by the above enumaration. If there are conflicts between the encoding mode 134 * and subsequent encoding options, encoding mode take precedent over encoding options. */ 135 MP4EncodingMode encMode; 136 137 /** @brief Sets the number of bytes per packet, only used in DATA_PARTITIONING_MODE or COMBINE_MODE_WITH_ERR_RES mode. 138 * The resync marker will be inserted as often as the size of the packet.*/ 139 Int packetSize; 140 141 /** @brief Selects MPEG-4/H.263 profile and level, if specified other encoding options must conform with it. */ 142 ProfileLevelType profile_level; 143 144 /** @brief Enables reversible variable length code (RVLC) mode. Normally it is set to PV_OFF.*/ 145 ParamEncMode rvlcEnable; 146 147 /** @brief Set the frequency of GOB header interval */ 148 Int gobHeaderInterval; 149 150 /** @brief Sets the number of bitstream layers: 1 is base only: 2 is base + enhancement */ 151 Int numLayers; 152 153 /** @brief Sets the number of ticks per second used for timing information encoded in MPEG4 bitstream.*/ 154 Int timeIncRes; 155 156 /** @brief Sets the number of ticks in time increment resolution between 2 source frames (equivalent to source frame rate). */ 157 Int tickPerSrc; 158 159 /** @brief Specifies encoded heights in pixels, height[n] represents the n-th layer's height. */ 160 Int encHeight[2]; 161 162 /** @brief Specifies encoded widths in pixels, width[n] represents the n-th layer's width.*/ 163 Int encWidth[2]; 164 165 /** @brief Specifies target frame rates in frames per second, frameRate[n] represents the n-th layer's target frame rate.*/ 166 float encFrameRate[2]; 167 168 /** @brief Specifies target bit rates in bits per second unit, bitRate[n] represents the n-th layer's target bit rate. */ 169 Int bitRate[2]; 170 171 /** @brief Specifies default quantization parameters for I-Vop. Iquant[n] represents the n-th layer default quantization parameter. The default is Iquant[0]=12.*/ 172 Int iQuant[2]; 173 174 /** @brief Specifies default quantization parameters for P-Vop. Pquant[n] represents the n-th layer default quantization parameter. The default is Pquant[0]=10.*/ 175 Int pQuant[2]; 176 177 /** @brief specifies quantization mode (H263 mode or MPEG mode) of the encoded base and enhance layer (if any). 178 * In Simple and Simple Scalable profile, we use only H263 mode.*/ 179 Int quantType[2]; 180 181 /** @brief Sets rate control algorithm, one of (CONSTANT_Q, CBR_1, or VBR_1). 182 * CONSTANT_Q uses the default quantization values to encode the sequence. 183 * CBR_1 (constant bit rate) controls the output at a desired bit rate 184 * VBR_1 (variable bit rate) gives better picture quality at the expense of bit rate fluctuation 185 * Note: type=CONSTANT_Q produces sequences with arbitrary bit rate. 186 * type=CBR_1 produces sequences suitable for streaming. 187 * type=VBR_1 produces sequences suitable for download. */ 188 MP4RateControlType rcType; 189 190 /** @brief Sets the VBV buffer size (in the unit of second delay) used to prevent buffer overflow and underflow 191 * on the decoder side. This function is redundant to PVSetVBVSize. Either one of them is used at a time. */ 192 float vbvDelay; 193 194 /** @brief Specifies whether frame skipping is permitted or not. When rate control type is set to CONSTANT_Q 195 * frame skipping is automatically banned. In CBR_1 and VBR_1 rate control, frame skipping is allowed by default. 196 * However, users can force no frame skipping with this flag, but buffer constraint may be violated.*/ 197 ParamEncMode noFrameSkipped; 198 199 /** @brief Sets the maximum number of P-frames between two I-frames. I-frame mode is periodically forced 200 * if no I-frame is encoded after the specified period to add error resiliency and help resynchronize in case of errors. 201 * If scene change detection can add additional I-frame if new scenes are detected. 202 * intraPeriod is the I frame interval in terms of second. 203 * intraPeriod =0 indicates I-frame encoding only; 204 * intraPeriod = -1 indicates I-frame followed by all P-frames; (default) 205 * intraPeriod = N, indicates the number of P-frames between 2 I-frames.*/ 206 Int intraPeriod; 207 208 209 /** @brief Specifies the number Intra MBs to be refreshed in a P-frame. */ 210 Int numIntraMB; 211 212 /** 213 * @brief Specifies whether the scene change detection (SCD) is enabled or disabled. 214 * With SCD enable, when a new scene is detected, I-Vop mode will be used for the first frame of 215 * the new scene resulting in better picture quality. An insertion of an I-VOP resets the intraPeriod 216 * specified by the IntraPeriodAPI().*/ 217 ParamEncMode sceneDetect; 218 219 /** @brief Specifies the search range of motion estimation search. Larger value implies 220 * larger search range, better motion vector match, but more complexity. 221 * If searchRange=n, the motion vector search is in the range of [-n,n-1] pixels. 222 * If half-pel mode is on, the range is [-n, (n-1)+1/2] pixels. The default value is 16.*/ 223 Int searchRange; 224 225 /** @brief Turns on/off 8x8 block motion estimation and compensation. 226 * If on, four motion vectors may be used for motion estimation and compensation of a macroblock, 227 * otherwise one motion vector per macroblock is used. When the 8x8 MV is off, the total encoding complexity 228 * is less but the image quality is also worse. Therefore, it can be used in complexity limited environment.*/ 229 ParamEncMode mv8x8Enable; 230 231 232 /** @brief Set the threshold for using intra DC VLC. 233 * Value must range from 0-7.*/ 234 Int intraDCVlcTh; 235 236 /** @brief This flag turns on the use of AC prediction */ 237 Bool useACPred; 238 239 } VideoEncOptions; 240 241 #ifdef __cplusplus 242 extern "C" 243 { 244 #endif 245 246 247 /* API's */ 248 /* Always start with this one !!*/ 249 /** 250 * @brief Gets default encoding options. This way users only have to set relevant encoding options and leave the one 251 * they are unsure of. 252 * @encOption Pointer to VideoEncOption structure. 253 * @encUseCase This value determines the set of default encoding options, for example, different encoding options 254 * are assigned to streaming use-case as compared to download use-case. It can be project dependent too. 255 * @return true for correct operation; false if error happens 256 */ 257 OSCL_IMPORT_REF Bool PVGetDefaultEncOption(VideoEncOptions *encOption, Int encUseCase); 258 259 /** 260 * @brief Verifies the consistency of encoding parameters, allocates memory needed and set necessary internal variables. 261 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 262 * @return true for correct operation; false if error happens 263 */ 264 OSCL_IMPORT_REF Bool PVInitVideoEncoder(VideoEncControls *encCtrl, VideoEncOptions *encOption); 265 266 /* acquiring encoder info APIs */ 267 /** 268 * @brief This function returns VOL header. It has to be called before the frame is encoded. If so, 269 * then the VOL Header is passed back to the application. Then all frames that are encoded do not contain the VOL Header. 270 * If you do not call the API then the VOL Header is passed within the first frame that is encoded. 271 * The behavior is unknown if it is called after the first frame is encoded. It is mainly used for MP4 file format authoring. 272 * @param encCtrl is video encoder control structure that is always passed as input in all APIs. 273 * @param volHeader is the Buffer for VOL header. 274 * @param size is the size of VOL header in bytes. 275 * @param layer is the layer of the requested VOL header. 276 * @return true for correct operation; false if error happens. 277 */ 278 OSCL_IMPORT_REF Bool PVGetVolHeader(VideoEncControls *encCtrl, UChar *volHeader, Int *size, Int layer); 279 280 /** 281 * @brief This function returns the profile and level in H.263 coding when the encoding parameters are set 282 * @param encCtrl is video encoder control structure that is always passed as input in all APIs. 283 * @param profileID is the pointer of the profile ID. Right now we only support profile 0 284 * @param levelID is the pointer of the level ID that could be 10-70. 285 * @return true for correct operation; false if error happens. 286 */ 287 OSCL_IMPORT_REF Bool PVGetH263ProfileLevelID(VideoEncControls *encCtrl, Int *profileID, Int *levelID); 288 289 /** 290 * @brief This function returns the profile and level of MPEG4 when the encoding parameters are set 291 * @param encCtrl is video encoder control structure that is always passed as input in all APIs. 292 * @param profile_level is the pointer of the profile enumeration 293 * @param nLayer is the index of the layer of interest 294 * @return true for correct operation; false if error happens. 295 */ 296 OSCL_IMPORT_REF Bool PVGetMPEG4ProfileLevelID(VideoEncControls *encCtrl, Int *profile_level, Int nLayer); 297 298 /** 299 * @brief This function returns maximum frame size in bytes 300 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 301 * @param maxVideoFrameSize is the pointer of the maximum frame size 302 * @return true for correct operation; false if error happens 303 */ 304 OSCL_IMPORT_REF Bool PVGetMaxVideoFrameSize(VideoEncControls *encCtrl, Int *maxVideoFrameSize); 305 306 #ifndef LIMITED_API 307 /** 308 * @brief This function returns the total amount of memory (in bytes) allocated by the encoder library. 309 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 310 * @return true for correct operation; false if error happens 311 */ 312 OSCL_IMPORT_REF Int PVGetEncMemoryUsage(VideoEncControls *encCtrl); 313 314 /** 315 * @brief This function is used by PVAuthor to get the size of the VBV buffer. 316 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 317 * @param VBVSize is the pointer of The size of the VBV buffer in bytes. 318 * @return true for correct operation; false if error happens 319 */ 320 OSCL_IMPORT_REF Bool PVGetVBVSize(VideoEncControls *encCtrl, Int *VBVSize); 321 #endif 322 323 /** 324 * @brief This function encodes a frame in YUV 4:2:0 format from the *video_in input frame and put the result in YUV 325 * for reconstructed frame and bstream for MPEG4 bitstream. The application is required to allocate memory for 326 * bitstream buffer.The size of the input bitstream memory and the returned output buffer are specified in the 327 * size field. The encoded layer is specified by the nLayer field. If the current frame is not encoded, size=0 and nLayer=-1. 328 * Note: If the allocated buffer size is too small to fit a bitstream of a frame, then those extra bits will be left out 329 * which can cause syntactic error at the decoder side. 330 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 331 * @param vid_in is the pointer to VideoEncFrameIO structure containing the YUV input data 332 * @param vid_out is the pointer to VideoEncFrameIO structure containing the reconstructed YUV output data after encoding 333 * @param nextModTime is the timestamp encoder expects from the next input 334 * @param bstream is the pointer to MPEG4 bitstream buffer 335 * @param size is the size of bitstream buffer allocated (input) and size of the encoded bitstream (output). 336 * @param nLayer is the layer of the encoded frame either 0 for base or 1 for enhancement layer. The value -1 indicates skipped frame due to buffer overflow. 337 * @return true newfor correct operation; false if error happens 338 */ 339 OSCL_IMPORT_REF Bool PVEncodeVideoFrame(VideoEncControls *encCtrl, VideoEncFrameIO *vid_in, VideoEncFrameIO *vid_out, 340 ULong *nextModTime, UChar *bstream, Int *size, Int *nLayer); 341 342 343 /** 344 * @brief This function is used to query overrun buffer. It is used when PVEncodeVideoFrame.returns size that is 345 * larger than the input size. 346 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 347 * @return Pointer to the overrun buffer. NULL if overrun buffer is not used. 348 */ 349 OSCL_IMPORT_REF UChar* PVGetOverrunBuffer(VideoEncControls *encCtrl); 350 351 #ifndef NO_SLICE_ENCODE /* This set of APIs are not working. This functionality has been partially 352 replaced by the introduction of overrun buffer. */ 353 354 /* slice-based coding */ 355 /** 356 * @brief This function sets the input YUV frame and timestamp to be encoded by the slice-based encoding function PVEncodeSlice(). 357 * It also return the memory address the reconstructed frame will be copied to (in advance) and the coded layer number. 358 * The encoder library processes the timestamp and determine if this frame is to be encoded or not. If the current frame 359 * is not encoded, nLayer=-1. For frame-based motion estimation, the motion estimation of the entire frame is also performed 360 * in this function. For MB-based motion estimation, the motion vector is searched while coding each MB in PVEncodeSlice(). 361 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 362 * @param vid_in is the pointer to VideoEncFrameIO structure containing the YUV input data 363 * @param nextModTime is the timestamp encoder expects from the next input if this input is rejected and nLayer is set to -1. 364 * @param nLayer is the layer of the encoded frame either 0 for base or 1 for enhancement layer. The value -1 indicates skipped frame due to buffer overflow. 365 * @return true newfor correct operation; false if error happens 366 */ 367 OSCL_IMPORT_REF Bool PVEncodeFrameSet(VideoEncControls *encCtrl, VideoEncFrameIO *vid_in, ULong *nextModTime, Int *nLayer); 368 /** 369 * @brief This function encodes a GOB (short header mode) or a packet (data partitioning mode or combined mode with resync marker) 370 * and output the reconstructed frame and MPEG4 bitstream. The application is required to allocate memory for the bitstream buffer. 371 * The size of the input bitstream memory and the returned output buffer are specified in the size field. If the buffer size is 372 * smaller than the requested packet size, user has to call PVEncodeSlice again to get the rest of that pending packet before moving 373 * on to the next packet. For the combined mode without resync marker, the function returns when the buffer is full. 374 * The end-of-frame flag indicates the completion of the frame encoding. Next frame must be sent in with PVEncodeFrameSet(). 375 * At the end-of-frame, the next video input address and the next video modulo timestamp will be set. 376 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 377 * @param bstream is the pointer to MPEG4 bitstream buffer. 378 * @param size is the size of bitstream buffer allocated (input) and size of the encoded bitstream (output). 379 * @param endofFrame is a flag indicating the end-of-frame, '1'. Otherwise, '0'. When PVSetNoCurrentFrameSkip is OFF, 380 * end-of-frame '-1' indicates current frame bitstream must be disregarded. 381 * @param vid_out is the pointer to VideoEncFrameIO structure containing the reconstructed YUV output data after encoding 382 * @param nextModTime is the timestamp encoder expects from the next input 383 * @return true newfor correct operation; false if error happens 384 */ 385 OSCL_IMPORT_REF Bool PVEncodeSlice(VideoEncControls *encCtrl, UChar *bstream, Int *size, 386 Int *endofFrame, VideoEncFrameIO *vid_out, ULong *nextModTime); 387 #endif 388 389 /** 390 * @brief This function returns MP4 file format hint track information. 391 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 392 * @param info is the structure for MP4 hint track information 393 * @return true for correct operation; false if error happens 394 */ 395 OSCL_IMPORT_REF Bool PVGetHintTrack(VideoEncControls *encCtrl, MP4HintTrack *info); 396 397 #ifndef LIMITED_API 398 /** 399 * @brief updates target frame rates of the encoded base and enhance layer (if any) while encoding operation is ongoing. 400 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 401 * @param frameRate is the pointers to array of target frame rates in frames per second, 402 * frameRate[n] represents the n-th layer's target frame rate. 403 * @return true for correct operation; false if error happens 404 */ 405 OSCL_IMPORT_REF Bool PVUpdateEncFrameRate(VideoEncControls *encCtrl, float *frameRate); /* for 2-way */ 406 407 408 /** 409 * @brief updates target bit rates of the encoded base and enhance layer (if any) while encoding operation is ongoing. 410 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 411 * @param bitRate is the pointers to array of target bit rates in bits per second unit, 412 * bitRate[n] represents the n-th layer's target bit rate. 413 * @return true for correct operation; false if error happens 414 */ 415 OSCL_IMPORT_REF Bool PVUpdateBitRate(VideoEncControls *encCtrl, Int *bitRate); /* for 2-way */ 416 417 418 /** 419 * @brief updates the INTRA frame refresh interval while encoding operation is ongoing. 420 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 421 * @param aIFramePeriod is a new value of INTRA frame interval in the unit of number of coded frames. 422 * @return true for correct operation; false if error happens 423 */ 424 425 OSCL_IMPORT_REF Bool PVUpdateIFrameInterval(VideoEncControls *encCtrl, Int aIFramePeriod);/* for 2-way */ 426 427 /** 428 * @brief specifies the number Intra MBs to be refreshed 429 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 430 * @param numMB is the number of Intra MBs to be refreshed 431 * @return true for correct operation; false if error happens 432 */ 433 OSCL_IMPORT_REF Bool PVUpdateNumIntraMBRefresh(VideoEncControls *encCtrl, Int numMB); /* for 2-way */ 434 435 /** 436 * @brief This function is called whenever users want the next base frame to be encoded as an I-Vop. 437 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 438 * @return true for correct operation; false if error happens 439 */ 440 OSCL_IMPORT_REF Bool PVIFrameRequest(VideoEncControls *encCtrl); /* for 2-way */ 441 442 #endif // LIMITED_API 443 444 /* finishing encoder */ 445 /** 446 * @brief This function frees up all the memory allocated by the encoder library. 447 * @param encCtrl is video encoder control structure that is always passed as input in all APIs 448 * @return true for correct operation; false if error happens 449 */ 450 OSCL_IMPORT_REF Bool PVCleanUpVideoEncoder(VideoEncControls *encCtrl); 451 452 #ifdef __cplusplus 453 } 454 #endif 455 #endif /* _MP4ENC_API_H_ */ 456 457