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 /* File: cvei.h */ 20 /* Purpose: */ 21 /* Date: */ 22 /* Revision History: */ 23 /** @introduction Common Video Encoder Interface (CVEI) is intended to be used by 24 application developers who want to create a multimedia application with video 25 encoding feature. CVEI is designed such that new video encoder algorithms or 26 modules can be plugged in seamlessly without user interaction. In other words, 27 any changes to the CVEI library are transparent to the users. Users can still 28 use the same set of APIs for new encoding tools. 29 30 @requirement CVEI will take an input frame in one of several format supported 31 by PV and encode it to an MPEG4 bitstream. It will also return a reconstructed 32 image in YUV 4:2:0 format. Currently the input format supported are YUV 4:2:0, 33 RGB24 and UYVY 4:2:2. 34 35 CVEI is designed such that it is simple to use. It should hides implementation 36 dependency from the users. In this version, we decided that the operation will 37 be synchronous, i.e., the encoding will be a blocked call. Asynchronous operation 38 will be in the level above CVEI, i.e., in Author Engine Video Module which will 39 take care of capturing device as well. 40 41 @brief The following classes are used to interface with codecs. Their names 42 are CPVxxxVideoEncoder where xxx is codec specific such as MPEG4, H263, H26L, 43 etc. All of them are subclasses of CPVCommonVideoEncoder. 44 */ 45 /*********************************************************************************/ 46 47 #ifndef __CVEI_H 48 #define __CVEI_H 49 50 #include "oscl_scheduler_ao.h" 51 #include "oscl_base.h" 52 #include "mp4enc_api.h" /* for MP4HintTrack */ 53 54 #define MAX_LAYER 2 55 56 /** General returned values. */ 57 enum TCVEI_RETVAL 58 { 59 ECVEI_SUCCESS, 60 ECVEI_FAIL, 61 ECVEI_FLUSH, 62 ECVEI_MORE_OUTPUT 63 } ; 64 65 /** Returned events with the callback function. */ 66 enum TCVEI_EVENT 67 { 68 /** Called when a packet or a frame of output bitstream is ready. */ 69 ECVEI_BUFFER_READY, 70 71 /** Called when the last packet of a frame of output bitstream is ready. */ 72 ECVEI_FRAME_DONE, 73 74 /** Called when no buffers is available for output bitstream. A buffer can be added thru AddBuffer API. */ 75 ECVEI_NO_BUFFERS, 76 77 /** Called when there is an error with the encoding operation. */ 78 ECVEI_ERROR 79 }; 80 81 /** Contains supported input format */ 82 enum TPVVideoFormat 83 { 84 ECVEI_RGB24, 85 ECVEI_RGB12, 86 ECVEI_YUV420, 87 ECVEI_UYVY, 88 ECVEI_YUV420SEMIPLANAR 89 }; 90 91 /** Type of contents for optimal encoding mode. */ 92 enum TPVContentType 93 { 94 /** Content is to be streamed in real-time. */ 95 ECVEI_STREAMING, 96 97 /** Content is to be downloaded and playbacked later.*/ 98 ECVEI_DOWNLOAD, 99 100 /** Content is to be 3gpp baseline compliant. */ 101 ECVEI_H263 102 }; 103 104 /** Rate control type. */ 105 enum TMP4RateControlType 106 { 107 /** Constant quality, variable bit rate, fixed quantization level. */ 108 ECONSTANT_Q, 109 110 /** Short-term constant bit rate control. */ 111 ECBR_1, 112 113 /** Long-term constant bit rate control. */ 114 EVBR_1 115 }; 116 117 /** Targeted profile and level to encode. */ 118 enum TPVM4VProfileLevel 119 { 120 /* Non-scalable profile */ 121 ECVEI_SIMPLE_LEVEL0 = 0, 122 ECVEI_SIMPLE_LEVEL1, 123 ECVEI_SIMPLE_LEVEL2, 124 ECVEI_SIMPLE_LEVEL3, 125 ECVEI_CORE_LEVEL1, 126 ECVEI_CORE_LEVEL2, 127 128 /* Scalable profile */ 129 ECVEI_SIMPLE_SCALABLE_LEVEL0 = 6, 130 ECVEI_SIMPLE_SCALABLE_LEVEL1, 131 ECVEI_SIMPLE_SCALABLE_LEVEL2, 132 133 ECVEI_CORE_SCALABLE_LEVEL1 = 10, 134 ECVEI_CORE_SCALABLE_LEVEL2, 135 ECVEI_CORE_SCALABLE_LEVEL3 136 }; 137 138 /** This structure contains encoder settings. */ 139 struct TPVVideoEncodeParam 140 { 141 /** Specifies an ID that will be used to specify this encoder while returning 142 the bitstream in asynchronous mode. */ 143 uint32 iEncodeID; 144 145 /** Specifies whether base only (iNumLayer = 1) or base + enhancement layer 146 (iNumLayer =2 ) is to be used. */ 147 int32 iNumLayer; 148 149 /** Specifies the width in pixels of the encoded frames. IFrameWidth[0] is for 150 base layer and iFrameWidth[1] is for enhanced layer. */ 151 int iFrameWidth[MAX_LAYER]; 152 153 /** Specifies the height in pixels of the encoded frames. IFrameHeight[0] is for 154 base layer and iFrameHeight[1] is for enhanced layer. */ 155 int iFrameHeight[MAX_LAYER]; 156 157 /** Specifies the cumulative bit rate in bit per second. IBitRate[0] is for base 158 layer and iBitRate[1] is for base+enhanced layer.*/ 159 int iBitRate[MAX_LAYER]; 160 161 /** Specifies the cumulative frame rate in frame per second. IFrameRate[0] is for 162 base layer and iFrameRate[1] is for base+enhanced layer. */ 163 float iFrameRate[MAX_LAYER]; 164 165 /** Specifies the picture quality factor on the scale of 1 to 10. It trades off 166 the picture quality with the frame rate. Higher frame quality means lower frame rate. 167 Lower frame quality for higher frame rate.*/ 168 int32 iFrameQuality; 169 170 /** Enable the use of iFrameQuality to determine the frame rate. If it is false, 171 the encoder will try to meet the specified frame rate regardless of the frame quality.*/ 172 bool iEnableFrameQuality; 173 174 /** Specifies the maximum number of P-frames between 2 INTRA frames. An INTRA mode is 175 forced to a frame once this interval is reached. When there is only one I-frame is present 176 at the beginning of the clip, iIFrameInterval should be set to -1. */ 177 int32 iIFrameInterval; 178 179 /** According to iIFrameInterval setting, the minimum number of intra MB per frame is 180 optimally calculated for error resiliency. However, when iIFrameInterval is set to -1, 181 iNumIntraMBRefresh must be specified to guarantee the minimum number of intra 182 macroblocks per frame.*/ 183 uint32 iNumIntraMBRefresh; 184 185 /** Specifies the VBV buffer size which determines the end-to-end delay between the 186 encoder and the decoder. The size is in unit of seconds. For download application, 187 the buffer size can be larger than the streaming application. For 2-way application, 188 this buffer shall be kept minimal. For a special case, in VBR mode, iBufferDelay will 189 be set to -1 to allow buffer underflow. */ 190 float iBufferDelay; 191 192 /** Specifies the type of the access whether it is streaming, CVEI_STREAMING 193 (data partitioning mode) or download, CVEI_DOWNLOAD (combined mode).*/ 194 TPVContentType iContentType; 195 196 /** Specifies the rate control algorithm among one of the following constant Q, 197 CBR and VBR. The structure TMP4RateControlType is defined below.*/ 198 TMP4RateControlType iRateControlType; 199 200 /** Specifies high quality but also high complexity mode for rate control. */ 201 bool iRDOptimal; 202 203 /** Specifies the initial quantization parameter for the first I-frame. If constant Q 204 rate control is used, this QP will be used for all the I-frames. This number must be 205 set between 1 and 31, otherwise, Initialize() will fail. */ 206 int iIquant[2]; 207 208 /** Specifies the initial quantization parameter for the first P-frame. If constant Q 209 rate control is used, this QP will be used for all the P-frames. This number must be 210 set between 1 and 31, otherwise, Initialize() will fail. */ 211 int iPquant[2]; 212 213 /** Specifies the initial quantization parameter for the first B-frame. If constant Q 214 rate control is used, this QP will be used for all the B-frames. This number must be 215 set between 1 and 31, otherwise, Initialize() will fail. */ 216 int iBquant[2]; 217 218 /** Specifies the search range in pixel unit for motion vector. The range of the 219 motion vector will be of dimension [-iSearchRange.5, +iSearchRange.0]. */ 220 int32 iSearchRange; 221 222 /** Specifies the use of 8x8 motion vectors. */ 223 bool iMV8x8; 224 225 /** Specifies the use of half-pel motion vectors. */ 226 bool iMVHalfPel; 227 228 /** Specifies automatic scene detection where I-frame will be used the the first frame 229 in a new scene. */ 230 bool iSceneDetection; 231 232 /** Specifies the packet size in bytes which represents the number of bytes between two resync markers. 233 For ECVEI_DOWNLOAD and ECVEI_H263, if iPacketSize is set to 0, there will be no resync markers in the bitstream. 234 For ECVEI_STREAMING is parameter must be set to a value greater than 0.*/ 235 uint32 iPacketSize; 236 237 /** Specifies whether the current frame skipping decision is allowed after encoding 238 the current frame. If there is no memory of what has been coded for the current frame, 239 iNoCurrentSkip has to be on. */ 240 bool iNoCurrentSkip; 241 242 /** Specifies that no frame skipping is allowed. Frame skipping is a tool used to 243 control the average number of bits spent to meet the target bit rate. */ 244 bool iNoFrameSkip; 245 246 /** Specifies the duration of the clip in millisecond.*/ 247 int32 iClipDuration; 248 249 /** Specifies the profile and level used to encode the bitstream. When present, 250 other settings will be checked against the range allowable by this target profile 251 and level. Fail may be returned from the Initialize call. */ 252 TPVM4VProfileLevel iProfileLevel; 253 254 /** Specifies FSI Buffer input */ 255 uint8* iFSIBuff; 256 257 /** Specifies FSI Buffer Length */ 258 int iFSIBuffLength; 259 260 261 }; 262 263 264 /** Structure for input format information */ 265 struct TPVVideoInputFormat 266 { 267 /** Contains the width in pixels of the input frame. */ 268 int32 iFrameWidth; 269 270 /** Contains the height in pixels of the input frame. */ 271 int32 iFrameHeight; 272 273 /** Contains the input frame rate in the unit of frame per second. */ 274 float iFrameRate; 275 276 /** Contains Frame Orientation. Used for RGB input. 1 means Bottom_UP RGB, 0 means Top_Down RGB, -1 for video formats other than RGB*/ 277 int iFrameOrientation; 278 279 /** Contains the format of the input video, e.g., YUV 4:2:0, UYVY, RGB24, etc. */ 280 TPVVideoFormat iVideoFormat; 281 }; 282 283 284 /** Contains the input data information */ 285 struct TPVVideoInputData 286 { 287 /** Pointer to an input frame buffer in input source format.*/ 288 uint8 *iSource; 289 290 /** The corresponding time stamp of the input frame. */ 291 uint32 iTimeStamp; 292 }; 293 294 /** Contains the output data information */ 295 struct TPVVideoOutputData 296 { 297 /** Pointer to the reconstructed frame buffer in YUV 4:2:0 domain. */ 298 uint8 *iFrame; 299 300 /** The number of layer encoded, 0 for base, 1 for enhanced. */ 301 int32 iLayerNumber; 302 303 /** Pointer to the encoded bitstream buffer. */ 304 uint8 *iBitStream; 305 306 /** The size in bytes of iBStream. */ 307 int32 iBitStreamSize; 308 309 /** The time stamp of the encoded frame according to the bitstream. */ 310 uint32 iVideoTimeStamp; 311 312 /** The time stamp of the encoded frame as given before the encoding. */ 313 uint32 iExternalTimeStamp; 314 315 /** The hint track information. */ 316 MP4HintTrack iHintTrack; 317 }; 318 319 /** An observer class for callbacks to report the status of the CVEI */ 320 class MPVCVEIObserver 321 { 322 public: 323 /** The callback funtion with aEvent being one of TCVEIEvent enumeration. */ 324 virtual void HandlePVCVEIEvent 325 (uint32 aId, uint32 aEvent, uint32 aParam1 = 0) = 0; ~MPVCVEIObserver()326 virtual ~MPVCVEIObserver() {} 327 }; 328 329 /** This class is the base class for codec specific interface class. 330 The users must maintain an instance of the codec specific class throughout 331 the encoding session. 332 */ 333 class CommonVideoEncoder : public OsclTimerObject 334 { 335 public: 336 /** Constructor for CVEI class. */ CommonVideoEncoder()337 CommonVideoEncoder() : OsclTimerObject(OsclActiveObject::EPriorityNominal, "PVEncoder") {}; 338 339 /** Initialization function to set the input video format and the 340 encoding parameters. This function returns CVEI_ERROR if there is 341 any errors. Otherwise, the function returns CVEI_SUCCESS.*/ 342 virtual TCVEI_RETVAL Initialize(TPVVideoInputFormat *aVidInFormat, TPVVideoEncodeParam *aEncParam) = 0; 343 344 /** Set the observer for asynchronous encoding mode. */ 345 virtual TCVEI_RETVAL SetObserver(MPVCVEIObserver *aObserver) = 0; 346 347 /** Add a buffer to the queue of output buffers for output bitstream in 348 asynchronous encoding mode. */ 349 virtual TCVEI_RETVAL AddBuffer(TPVVideoOutputData *aVidOut) = 0; 350 351 /** This function sends in an input video data structure containing a source 352 frame and the associated timestamp. The encoded bitstream will be returned by 353 observer callback. 354 The above 3 APIs only replace EncodeFrame() API. Other APIs such as initialization 355 and update parameters remain the same. */ 356 virtual TCVEI_RETVAL Encode(TPVVideoInputData *aVidIn) = 0; 357 358 /** This function returns the maximum VBV buffer size such that the 359 application can allocate a buffer that guarantees to fit one frame.*/ 360 virtual int32 GetBufferSize() = 0; 361 362 /** This function returns the VOL header part (starting from the VOS header) 363 of the encoded bitstream. This function must be called after Initialize. 364 The output is written to the memory (volHeader) allocated by the users.*/ 365 virtual TCVEI_RETVAL GetVolHeader(uint8 *volHeader, int32 *size, int32 layer) = 0; 366 367 /** This function sends in an input video data structure containing a source 368 frame and the associated timestamp. It returns an output video data structure 369 containing coded bit stream, reconstructed frame in YUV 4:2:0 (can be changed 370 to source format) and the timestamp associated with the coded frame. 371 The input timestamp may not correspond to the output timestamp. User can send 372 an input structure in without getting any encoded data back or getting an encoded 373 frame in the past. This function returns ECVEI_ERROR if there is any errors. 374 Otherwise, the function returns ECVEI_SUCCESS. 375 In case of Overrun Buffer usage, it is possible that return value is ECVEI_MORE_OUTPUT 376 which indicates that frame cannot fit in the current buffer*/ 377 virtual TCVEI_RETVAL EncodeFrame(TPVVideoInputData *aVidIn, TPVVideoOutputData *aVidOut, int *aRemainingBytes 378 #ifdef PVAUTHOR_PROFILING 379 , void *aParam1 = 0 380 #endif 381 ) = 0; 382 383 /** Before the termination of the encoding process, the users have to query 384 whether there are any encoded frame pending inside the CVEI. The returned value 385 will indicate whether there are more frames to be flushed (ECVEI_FLUSH). 386 FlushOutput has to be called until there are no more frames, i.e., it returns 387 ECVEI_SUCCESS. This function may be called during the encoding operation if 388 there is no input frame and the application does not want to waste the time 389 waiting for input frame. It can call this function to flush encoded frame 390 out of the memory. */ 391 virtual TCVEI_RETVAL FlushOutput(TPVVideoOutputData *aVidOut) = 0; 392 393 /** This function cleanup the CVEI allocated resources. */ 394 virtual TCVEI_RETVAL Terminate() = 0; 395 396 /**This function dynamically changes the target bit rate of the encoder 397 while encoding. aBitRate[n] is the new accumulate target bit rate of layer n. 398 Successful update is returned with ECVEI_SUCCESS.*/ 399 virtual TCVEI_RETVAL UpdateBitRate(int32 aNumLayer, int32 *aBitRate) = 0; 400 401 /** This function dynamically changes the target frame rate of the encoder 402 while encoding. aFrameRate[n] is the new accumulate target frame rate of 403 layer n. Successful update is returned with ECVEI_SUCCESS. */ 404 virtual TCVEI_RETVAL UpdateFrameRate(int32 aNumLayer, float *aFrameRate) = 0; 405 406 /** This function dynamically changes the I-Vop update interval while 407 encoding to a new value, aIFrameInterval. */ 408 virtual TCVEI_RETVAL UpdateIFrameInterval(int32 aIFrameInterval) = 0; 409 410 /** This function forces an I-Vop mode to the next frame to be encoded. */ 411 virtual TCVEI_RETVAL IFrameRequest() = 0; 412 413 /** This function returns the input width of a specific layer 414 (not necessarily multiple of 16). */ 415 virtual int32 GetEncodeWidth(int32 aLayer) = 0; 416 417 /** This function returns the input height of a specific layer 418 (not necessarily multiple of 16). */ 419 virtual int32 GetEncodeHeight(int32 aLayer) = 0; 420 421 /** This function returns the target encoded frame rate of a specific layer. */ 422 virtual float GetEncodeFrameRate(int32 aLayer) = 0; 423 protected: 424 virtual void Run(void) = 0; 425 virtual void DoCancel(void) = 0; 426 /* internal enum */ 427 enum TCVEIState 428 { 429 EIdle, 430 EEncode 431 }; 432 433 TCVEIState iState; 434 uint32 iId; 435 }; 436 437 #endif 438