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 uint32_t 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