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