Updated Ducati header files (codecs and XDC tools)
[gstreamer-omap:libdce.git] / packages / ivahd_codecs / ti / sdo / codecs / mpeg4enc / impeg4enc.h
1 /* ======================================================================
2  *   Copyright (C) 2010 Texas Instruments Incorporated
3  *
4  *   All rights reserved. Property of Texas Instruments Incorporated.
5  *   Restricted rights to use, duplicate or disclose this code are
6  *   granted through contract.
7  *
8  *   The program may not be used without the written permission
9  *   of Texas Instruments Incorporated or against the terms and conditions
10  *   stipulated in the agreement under which this program has been
11  *   supplied.
12  * ====================================================================*/
13 /*
14 ********************************************************************************
15  * HDVICP2.0 Based MPEG4 SP Encoder
16  *
17  * "HDVICP2.0 Based MPEG4 SP Encoder" is software module developed on TI's
18  *  HDVICP2 based SOCs. This module is capable of compressing a 4:2:0 Raw
19  *  video into a simple profile bit-stream. Based on ISO/IEC 14496-2."
20  *
21  * Copyright (C) 2009 Texas Instruments Incorporated - http://www.ti.com/
22  * ALL RIGHTS RESERVED
23 ********************************************************************************
24 */
25 /**
26 ********************************************************************************
27  * @file <impeg4enc.h>
28  *
29  * @brief Interface header file for MPEG4 SP Encoder
30  *
31  * @author: Venugopala Krishna
32  *
33  * @version 0.0 (Feb 2009) : Initial version.
34  *                           [Venugopala Krishna]
35  * @version 0.1 (Apr 2009) : Updated version.
36  *                           [Radhesh Bhat]
37  *
38  *******************************************************************************
39 */
40
41 /* -------------------- compilation control switches -------------------------*/
42 #ifndef IMPEG4ENC_
43 #define IMPEG4ENC_
44
45 /**
46  *  @defgroup   HDVICP2MPEG4 IMPEG4ENC_TI (V7M)
47  *  @ingroup    m3
48  *
49  *              The IMPEG4ENC_TI interface enables encoding in MPEG-4 format
50  *
51  */
52
53 /** @ingroup    HDVICP2MPEG4 */
54 /*@{*/
55
56 /*-------------------------------------------*/
57 /* typecasting of control method commands    */
58 /*-------------------------------------------*/
59 #define IMPEG4ENC_GETSTATUS      XDM_GETSTATUS
60 #define IMPEG4ENC_SETPARAMS      XDM_SETPARAMS
61 #define IMPEG4ENC_RESET          XDM_RESET
62 #define IMPEG4ENC_FLUSH          XDM_FLUSH
63 #define IMPEG4ENC_SETDEFAULT     XDM_SETDEFAULT
64 #define IMPEG4ENC_GETBUFINFO     XDM_GETBUFINFO
65
66 /**
67 * MPEG4 Simple profile IDC
68 */
69 #define MPEG4_SIMPLE_PROFILE_IDC               3
70
71 /*******************************************************************************
72 *                             INCLUDE FILES
73 *******************************************************************************/
74 /* -------------------- system and platform files ----------------------------*/
75
76 /*--------------------- program files ----------------------------------------*/
77 #include <ti/xdais/ialg.h>
78 #include <ti/xdais/dm/ividenc2.h>
79
80 #ifdef __cplusplus
81 extern "C" {
82 #endif
83
84 /*******************************************************************************
85 *  PUBLIC DECLARATIONS Defined here, used elsewhere
86 *******************************************************************************/
87 /*---------------------- data declarations -----------------------------------*/
88
89 /*******************************************************************************
90 *  PRIVATE DECLARATIONS Defined here, used only here
91 *******************************************************************************/
92 /*---------------------- data declarations -----------------------------------*/
93 /*---------------------- function prototypes ---------------------------------*/
94
95
96 /**
97  *******************************************************************************
98  *  @enum       IMPEG4ENC_ErrorBit
99  *  @brief      error informations of IVAHD MPEG4 encoder implementation by TI.
100  *
101  *  @remarks    When an internal error occurs, the algorithm will return
102  *              an error return value (e.g. EFAIL, EUNSUPPORTED)
103  *
104  *  @remarks    The value of each enum is the bit which is set.
105  *
106  *  @remarks    Bits 8-15 are defined by XDM and hence not used by codec
107  *              implementation. rest all bits are used.
108  *              XDM defined error bits are also active.
109  *
110  *  @remarks    The algorithm can set multiple bits to 1 based on conditions.
111  *              e.g. it will set bits #XDM_FATALERROR (fatal) and
112  *              #XDM_UNSUPPORTEDPARAM (unsupported params) in case
113  *              of unsupported run time parameters.
114  *
115  *******************************************************************************
116 */
117 typedef enum {
118     IMPEG4ENC_LEVEL_INCOMPLAINT_PARAMETER = 0,
119     /**< Bit 0 - level incomplaint parameters.
120     *   @remarks  This error is applicable when some parameters are set
121     *             which are not meeting the limits set by MPEG4 standard
122     */
123
124     IMPEG4ENC_PROFILE_INCOMPLAINT_CONTENTTYPE = 1,
125     /**< Bit 1 - Profile incomplaint content type.
126     *   @remarks  This error is applicable when
127     *             IVIDENC2_Params::inputContentType is not set as
128     *             IVIDEO_PROGRESSIVE but IVIDENC2_Params::profile is set
129     *             as IMPEG4_SIPPLE_PROFILE
130     */
131
132     IMPEG4ENC_IMPROPER_HDVICP2_STATE = 16,
133     /**< Bit 16 - Device is not proper state to use.
134     */
135
136     IMPEG4ENC_WARNING_H263_PLUS_CUSTOM_SOURCE_FORMAT = 17,
137     /**< Bit 17 - Indication that the input resolution given to codec
138     *             is custom source format supported in H.263+ not the
139     *             standard resolutions supported with H263 baseline or
140     *             MPEG4 with short video header.
141     */
142
143     IMPEG4ENC_ERROR_BITSTREAM_MEMORY_INSUFFICIENT = 18,
144     /**< Bit 18 - Indication that the buffer given to codec from
145      *            getBuffer function is insufficient so that codec
146      *            cannot continue encoding. It means that if return value
147      *            from getBuffer function is -1, then this bit gets set
148      *            by the codec. This is the situation where application
149      *            might not be able to provide memory to codec.
150     */
151
152     IMPEG4ENC_IMPROPER_DATASYNC_SETTING = 19,
153     /**< Bit 19 - data synch settings are not proper
154     *   @remarks  This error is set when encoder is asked to operate
155     *             at sub frame level but the call back function pointer
156     *             is  NULL
157     */
158
159     IMPEG4ENC_UNSUPPORTED_VIDENC2PARAMS = 20,
160     /**< Bit 20 - Invalid videnc2 parameters
161     *   @remarks  This error is set when any parameter of struct
162     *             IVIDENC2_Params is not in allowed range
163     */
164
165     IMPEG4ENC_UNSUPPORTED_RATECONTROLPARAMS = 21,
166     /**< Bit 21 - Invalid rate control parameters
167     *   @remarks  This error is set when any parameter of struct
168     *             IMPEG4ENC_RateControlParams is not in allowed range
169     */
170
171     IMPEG4ENC_UNSUPPORTED_INTERCODINGPARAMS = 22,
172     /**< Bit 22 - Invalid inter coding parameters
173     *   @remarks  This error is set when any parameter of struct
174     *             IMPEG4ENC_InterCodingParams is not in allowed range
175     */
176
177     IMPEG4ENC_UNSUPPORTED_INTRACODINGPARAMS = 23,
178     /**< Bit 23 - Invalid Intra coding parameters
179     *   @remarks  This error is set when any parameter of struct
180     *             IMPEG4ENC_IntraCodingParams is not in allowed range
181     */
182
183     IMPEG4ENC_UNSUPPORTED_SLICECODINGPARAMS = 25,
184     /**< Bit 25 - Invalid slice coding parameters
185     *   @remarks  This error is set when any parameter of struct
186     *             IMPEG4ENC_SliceControlParams is not in allowed range
187     */
188
189     IMPEG4ENC_UNSUPPORTED_MPEG4ENCPARAMS = 29,
190     /**< Bit 29 - Invalid Create time extended parameters
191     *   @remarks  This error is set when any parameter of struct
192     *             IMPEG4ENC_CreateParams is not in allowed range
193     */
194
195     IMPEG4ENC_UNSUPPORTED_VIDENC2DYNAMICPARAMS = 30,
196     /**< Bit 30 - Invalid base class dyanmic parameters during control
197     *   @remarks  This error is set when any parameter of struct
198     *             IVIDENC2_DynamicParams is not in allowed range
199     */
200
201     IMPEG4ENC_UNSUPPORTED_MPEG4ENCDYNAMICPARAMS = 31
202                                                   /**< Bit 31 -Invalid extended class dyanmic parameters during control
203                                                   *   @remarks  This error is set when any parameter of struct
204                                                   *             IMPEG4ENC_DynamicParams (excluding embedded structures)
205                                                   *             is not in allowed range
206                                                   */
207
208 } IMPEG4ENC_ErrorBit;
209
210
211 /**
212  *******************************************************************************
213  *  @enum       IMPEG4ENC_Level
214  *  @brief      Enum for MPEG-4 Simple profile levels
215  *
216  *  @remarks    allowed levels are 0, 0b, 1, 2, 3, 4a & 5
217  *
218  *******************************************************************************
219 */
220 typedef enum {
221     IMPEG4ENC_SP_LEVEL_0   = 0,  /**< MPEG4 Simple Profile Level 0 */
222
223     IMPEG4ENC_SP_LEVEL_0B  = 9,  /**< MPEG4 Simple Profile Level 0b*/
224
225     IMPEG4ENC_SP_LEVEL_1   = 1,  /**< MPEG4 Simple Profile Level 1 */
226
227     IMPEG4ENC_SP_LEVEL_2   = 2,  /**< MPEG4 Simple Profile Level 2 */
228
229     IMPEG4ENC_SP_LEVEL_3   = 3,  /**< MPEG4 Simple Profile Level 3 */
230
231     IMPEG4ENC_SP_LEVEL_4A  = 4,  /**< MPEG4 Simple Profile Level 4a*/
232
233     IMPEG4ENC_SP_LEVEL_5   = 5,  /**< MPEG4 Simple Profile Level 5 */
234
235     IMPEG4ENC_SP_LEVEL_6   = 6   /**< MPEG4 Simple Profile Level 6 */
236
237 } IMPEG4ENC_Level;
238
239
240 /**
241  *******************************************************************************
242  *  @enum       IMPEG4ENC_H263Level
243  *  @brief      Enum for H.263 base profile levels
244  *
245  *  @remarks    allowed levels are 10,20,30,40, 45, 50, 60 and 70
246  *
247  *******************************************************************************
248 */
249 typedef enum {
250     IMPEG4ENC_H263_LEVEL_10 = 10,   /**< H263 Baseline Profile Level 10 */
251
252     IMPEG4ENC_H263_LEVEL_20 = 20,   /**< H263 Baseline Profile Level 20 */
253
254     IMPEG4ENC_H263_LEVEL_30 = 30,   /**< H263 Baseline Profile Level 30 */
255
256     IMPEG4ENC_H263_LEVEL_40 = 40,   /**< H263 Baseline Profile Level 40 */
257
258     IMPEG4ENC_H263_LEVEL_45 = 45,   /**< H263 Baseline Profile Level 45 */
259
260     IMPEG4ENC_H263_LEVEL_50 = 50,   /**< H263 Baseline Profile Level 50 */
261
262     IMPEG4ENC_H263_LEVEL_60 = 60,   /**< H263 Baseline Profile Level 60 */
263
264     IMPEG4ENC_H263_LEVEL_70 = 70    /**< H263 Baseline Profile Level 70 */
265 } IMPEG4ENC_H263Level;
266
267 /**
268  *******************************************************************************
269  *  @enum       IMPEG4ENC_PixelRange
270  *  @brief      pixel/video range enum
271  *
272  *  @remarks
273  *
274  *******************************************************************************
275 */
276
277 typedef enum {
278     /**
279      * Y varies from 16 to 235 and Cb/Cr varies from 16 to 240
280      */
281     IMPEG4ENC_PR_16_235  = 0,
282
283     /**
284      * Y/Cb/Cr varies from 0 to 255
285      */
286     IMPEG4ENC_PR_0_255   = 1,
287
288     IMPEG4ENC_PR_DEFAULT = IMPEG4ENC_PR_0_255
289
290 } IMPEG4ENC_PixelRange;
291
292
293 /**
294  *******************************************************************************
295  *  @enum       IMPEG4ENC_SceneChangeAlgo
296  *  @brief      Enum for enabling or disabling scene change detection algo
297  *
298  *  @remarks
299  *
300  *******************************************************************************
301 */
302
303 typedef enum {
304     /**
305      * Disables the scene change detection algorithm
306      */
307     IMPEG4ENC_SCDA_DISABLE  = 0,
308
309     /**
310      * Enables the scene change detection algorithm
311      */
312     IMPEG4ENC_SCDA_ENABLE   = 1,
313
314     IMPEG4ENC_SCDA_DEFAULT = IMPEG4ENC_SCDA_ENABLE
315
316 } IMPEG4ENC_SceneChangeAlgo;
317
318
319 /**
320  *******************************************************************************
321  *  @enum       IMPEG4ENC_RateControlParamsPreset
322  *  @brief      These enumerations control the RateControl Params
323  *
324  *  @remarks
325  *
326  *******************************************************************************
327 */
328 typedef enum {
329     IMPEG4_RATECONTROLPARAMS_DEFAULT     = 0, /**< Default RC params */
330
331     IMPEG4_RATECONTROLPARAMS_USERDEFINED = 1, /**< User defined RC params*/
332
333     /**
334      * Keep the Rate Control params as existing.
335      * This is useful because during control call if user don't want to chnage
336      * the Rate Control Params
337      */
338     IMPEG4_RATECONTROLPARAMS_EXISTING    = 2,
339
340
341     IMPEG4_RATECONTROLPARAMS_MAX
342
343 } IMPEG4ENC_RateControlParamsPreset;
344
345
346 /**
347  *******************************************************************************
348  *  @enum       IMPEG4ENC_RateControlAlgoPreset
349  *  @brief      These enumerations control the RateControl Algorithm
350  *
351  *  @remarks
352  *
353  *******************************************************************************
354 */
355 typedef enum {
356     /**
357      * Fixed QP
358      */
359     IMPEG4_RATECONTROLALGO_NONE        = 0,
360
361     /**
362      * VBR Rate Control Algorithm
363      */
364     IMPEG4_RATECONTROLALGO_VBR         = 1,
365
366     /**
367      * CBR Rate Control Algorithm -- Low Delay
368      */
369     IMPEG4_RATECONTROLALGO_CBR         = 2,
370
371     IMPEG4_RATECONTROLALGO_MAX
372
373 } IMPEG4ENC_RateControlAlgoPreset;
374
375
376 /**
377  *******************************************************************************
378  *  @enum   IMPEG4ENC_InterCodingPreset
379  *  @brief  These enumerations control the type of inter coding
380  *
381  *  @remarks
382  *
383  *******************************************************************************
384 */
385 typedef enum {
386
387     /**
388      * Default Inter coding params
389     */
390
391     IMPEG4_INTERCODING_DEFAULT     = 0,
392
393     /**
394      * User defined inter coding params
395     */
396     IMPEG4_INTERCODING_USERDEFINED = 1,
397
398
399     /**
400      * Keep the inter coding params as existing
401     */
402     IMPEG4_INTERCODING_EXISTING    = 2,
403
404     IMPEG4_INTERCODING_MAX
405
406 } IMPEG4ENC_InterCodingPreset;
407
408
409 /**
410  *******************************************************************************
411  *  @enum   IMPEG4ENC_InterBlockSize
412  *  @brief  These enumerations control the block size of each MB in encoding
413  *
414  *  @remarks
415  *
416  *******************************************************************************
417 */
418 typedef enum {
419     /**
420      * 16x16 Block size
421      */
422     IMPEG4_BLOCKSIZE_16x16     = 0,
423
424     /**
425      * 8x8 Block size
426      */
427     IMPEG4_BLOCKSIZE_8x8       = 1,
428
429     /**
430       * Default block size
431       */
432     IMPEG4_BLOCKSIZE_DEFAULT   = IMPEG4_BLOCKSIZE_8x8,
433
434     IMPEG4_BLOCKSIZE_MAX       = 2
435
436 } IMPEG4ENC_InterBlockSize;
437
438
439 /**
440  *******************************************************************************
441  *  @enum   IMPEG4ENC_IntraRefreshMethods
442  *  @brief  Refresh method Type Identifier for MPEG4 Encoder
443  *
444  *  @remarks
445  *
446  *******************************************************************************
447 */
448 typedef enum {
449
450     /**
451      * Doesn't insert forcefully any intra macro blocks
452     */
453     IMPEG4_INTRAREFRESH_NONE       = 0,
454     /**
455       * Inserts intra macro blocks in a cyclic fashion
456       * cyclic interval is equal to intraRefreshRate
457      */
458     IMPEG4_INTRAREFRESH_CYCLIC_MBS,
459
460     /**
461      * Inserts Intra Rows in a cyclic fashion
462      * Number of Rows equal to intraRefreshRate
463     */
464     IMPEG4_INTRAREFRESH_CYCLIC_ROWS,
465
466     /**
467      *  Mandatory Intra Refresh -- evenly distributes number of INTRA MBs over
468      *  frames.
469     */
470     IMPEG4_INTRAREFRESH_MANDATORY,
471
472     /**
473      * position of intra macro blocks is intelligently chosen by encoder, but the
474      * number of forcely coded intra macro blocks in a frame is gaurnteed to be
475      * equal to totalMbsInFrame/intraRefreshRate.
476      * This method is not implemented currently.
477      */
478     IMPEG4_INTRAREFRESH_RDOPT_MBS
479
480 } IMPEG4ENC_IntraRefreshMethods;
481
482
483 /**
484  *******************************************************************************
485  *  @enum   IMPEG4ENC_IntraCodingPreset
486  *  @brief  These enumerations control the type of intra coding
487  *
488  *  @remarks
489  *
490  *******************************************************************************
491 */
492 typedef enum {
493     /**
494      * Default intra coding params
495      */
496     IMPEG4_INTRACODING_DEFAULT     = 0,
497
498     /**
499      * User defined intra coding params
500      */
501     IMPEG4_INTRACODING_USERDEFINED = 1,
502     IMPEG4_INTRACODING_MAX
503
504 } IMPEG4ENC_IntraCodingPreset;
505
506
507 /**
508  *******************************************************************************
509  *  @enum   IMPEG4ENC_SliceCodingPreset
510  *  @brief  These enumerations control the type of slice coding
511  *
512  *  @remarks
513  *
514  *******************************************************************************
515 */
516 typedef enum {
517     /**
518      * Default slice coding params
519      */
520     IMPEG4_SLICECODING_DEFAULT     = 0,
521
522     /**
523      * User defined slicecoding params
524      */
525     IMPEG4_SLICECODING_USERDEFINED = 1,
526
527     /**
528      * Keep the slice coding params as existing
529      * This is useful because during control call if user don't want to chnage
530      * the sliceCodingParams
531      */
532     IMPEG4_SLICECODING_EXISTING    = 2,
533     IMPEG4_SLICECODING_MAX
534
535 } IMPEG4ENC_SliceCodingPreset;
536
537
538 /**
539  *******************************************************************************
540  *  @enum   IMPEG4ENC_SliceMode
541  *  @brief  These enumerations control the mode of slice coding
542  *
543  *  @remarks
544  *
545  *******************************************************************************
546 */
547 typedef enum {
548     IMPEG4_SLICEMODE_NONE    = 0,
549
550     /**
551      * Default slice coding mode is MB based
552      */
553     IMPEG4_SLICEMODE_DEFAULT = IMPEG4_SLICEMODE_NONE,
554
555     /**
556      * Slices are controlled based upon number of Macroblocks
557      */
558     IMPEG4_SLICEMODE_MBUNIT  = 1,
559
560     /**
561      * Slices are controlled based upon number of bits consumed
562      */
563     IMPEG4_SLICEMODE_BITS   = 2,
564     IMPEG4_SLICEMODE_MAX
565
566 } IMPEG4ENC_SliceMode;
567
568 /**
569  *******************************************************************************
570  *  @enum   IMPEG4ENC_nonMultiple16RefPadMethod
571  *  @brief  These enumerations captures different methods of padding the Ref
572  *          frame when dimension is non multiple of 16.
573  *
574  *  @remarks
575  *
576  *******************************************************************************
577 */
578 typedef enum {
579     /**
580      * Method as suggested by DivX spec.
581      */
582     IMPEG4_PAD_METHOD_DIVX     = 0,
583
584     /**
585      * Method as suggested by MPEG4 spec.
586      */
587     IMPEG4_PAD_METHOD_MPEG4    = 1,
588
589     /**
590      * Default mode is MPEG4 suggested way.
591     */
592     IMPEG4_PAD_METHOD_DEFAULT = IMPEG4_PAD_METHOD_MPEG4,
593     IMPEG4_PAD_METHOD_MAX
594
595 } IMPEG4ENC_nonMultiple16RefPadMethod;
596
597
598 /**
599
600   @enum   IMPEG4ENC_AspectRatioIdc
601   @brief  Defines aspect ratio IDs
602
603 */
604 typedef enum {
605     IMPEG4ENC_ASPECTRATIO_SQUARE = 1,   /**< 1:1 (square) aspect ratio */
606     IMPEG4ENC_ASPECTRATIO_12_11,        /**<  12:11  aspect ratio      */
607     IMPEG4ENC_ASPECTRATIO_10_11,        /**<  10:11  aspect ratio      */
608     IMPEG4ENC_ASPECTRATIO_16_11,        /**<  16:11  aspect ratio      */
609     IMPEG4ENC_ASPECTRATIO_40_33,        /**<  40:33  aspect ratio      */
610     IMPEG4ENC_ASPECTRATIO_EXTENDED = 15 /**<  Extended aspect ratio    */
611
612 } IMPEG4ENC_AspectRatioIdc;
613
614 /**
615  *******************************************************************************
616  *  @struct  IMPEG4ENC_Cmd
617  *  @brief   This structure defines the control commands for the IMP4VENC module
618  *
619  *******************************************************************************
620 */
621 typedef IVIDENC2_Cmd IMPEG4ENC_Cmd;
622
623
624 /**
625  *******************************************************************************
626  *  @struct  IMPEG4ENC_Obj
627  *  @brief   This structure must be the first field of all MPEG4ENC instance
628  *           objects
629  *
630  *  @param   fxns - is a pointer to IMPEG4ENC_Fxns structure which includes the
631  *           below function pointers
632  *           IALG_Fxns
633  *             Void algActivate(IALG_Handle handle)
634  *             Int  algAlloc(const IALG_Params *params,
635  *               struct IALG_Fxns **parentFxns, IALG_MemRec *memTab)
636  *             Void algControl(IALG_Handle handle, IALG_Cmd cmd,
637  *               IALG_Status *status)
638  *             Void algDeactivate(IALG_Handle handle)
639  *             Int algFree(IALG_Handle handle, IALG_MemRec *memTab)
640  *             Int algInit(IALG_Handle handle, const IALG_MemRec *memTab,
641  *               IALG_Handle parent, const IALG_Params *params)
642  *             Void algMoved(IALG_Handle handle, const IALG_MemRec *memTab,
643  *               IALG_Handle parent, const IALG_Params *params)
644  *             Int algNumAlloc(Void)
645  *
646  *           XDAS_Int32 process(IVIDENC2_Handle handle, IVIDEO2_BufDesc *inBufs,
647  *             XDM2_BufDesc *outBufs, IVIDENC2_InArgs *inArgs,
648  *             IVIDENC2_OutArgs *outArgs)
649  *
650  *           XDAS_Int32 control(IVIDENC2_Handle handle, IVIDENC2_Cmd id,
651  *             IVIDENC2_DynamicParams *params, IVIDENC2_Status *status)
652  *
653  *******************************************************************************
654 */
655 typedef struct IMPEG4ENC_Obj {
656     struct IMPEG4ENC_Fxns *fxns;
657 } IMPEG4ENC_Obj;
658
659
660 /**
661  *******************************************************************************
662  *  @struct  IMPEG4ENC_Handle
663  *  @brief   This handle is used to reference all MPEG4ENC instance objects
664  *
665  *******************************************************************************
666 */
667 typedef struct IMPEG4ENC_Obj *IMPEG4ENC_Handle;
668
669 /**
670  *******************************************************************************
671  *  @struct IMPEG4ENC_RateControlParams
672  *  @brief  This structure contains all the parameters which controls Rate
673  *          Control behavior
674  *
675  *  @param  rateControlParamsPreset  :
676  *          if this is IMPEG4_RATECONTROLPARAMS_DEFAULT the algorithm loads the
677  *          default rate control parameters.
678  *          if this is IMPEG4_RATECONTROLPARAMS_USERDEFINED the algorithm loads
679  *          the user defined rate control parameters. if user is not aware of
680  *          the floowing parameters it should be set to this enumeration.
681  *          if this is IMPEG4_RATECONTROLPARAMS_EXISTING the algorithm loads
682  *          the default rate control parameters.
683  *
684  *  @param  rcAlgo  :
685  *          if this is IMPEG4_RATECONTROLALGO_NONE the algorithm uses the fixed
686  *          qpI/qpP depending on the Frame
687  *          if this is IMPEG4_RATECONTROLALGO_PLR the algorithm uses the
688  *          PLR algorithm for QP Selection and bitrate achievement
689  *
690  *  @param  qpI  :
691  *          Initial Quantization Parameter for I frames. Valid Range is [1, 31].
692  *          when rateControlPreset = IVIDEO_NONE, this quantization parameter is
693  *          used by the I frame encoding
694  *
695  *  @param  qpP  :
696  *          Initial Quantization Parameter for P frames. Valid Range is [1, 31]
697  *          when rateControlPreset = IVIDEO_NONE, this quantization parameter is
698  *          used by the P frame encoding
699  *
700  *  @param  seIntialQP  :
701  *          when rcAlgo is anything other than IMPEG4_RATECONTROLALGO_NONE,
702  *          frame encoding start with seIntialQP value.
703  *          When the user does not have understanding of what to set, set to 0,
704  *          so the Codec internally decides intelligently the initial QP to be
705  *          used.
706  *
707  *  @param  qpMax  :
708  *          Maximum Quantization Parameter. Range [1, 31]. Useful to control
709  *          a minimum quality level
710  *
711  *  @param  qpMin  :
712  *          Minimum Quantization Parameter. Range [1, 31]. Useful to control
713  *          a maximum bit-rate level
714  *
715  *  @param  enablePerceptualQuantMode  :
716  *          perceptual quantization is enabled or diasabled. It varies the Qp at
717  *          MB level instead of row level to improve the perceptual quality of
718  *          video.
719  *          1 for enable
720  *          0 for disable
721  *
722  *  @param  allowFrameSkip  :
723  *          This enables the Frame Skip Feature looking at the VBV Fullness.
724  *          This should be enabled when Low Delay Mode is enabled.
725  *          2 for enabling early frame skip
726  *          1 for enabling late frame skip
727  *          0 for disabling frame skip
728  *  @param  initialBufferLevel :
729  *          Initial buffer level for VBV compliance. It informs that
730  *          hypothetical decoder can start depending on the fullness of the
731  *          VBV buffer. Default value is 0, where codec will internally
732  *          calculate the value based on the RC algo type
733  *  @param  vbvBufferSize :
734  *          Virtual Buffer Verifier buffer size. This size controls the frame
735  *          skip logic of the encoder. For low delay applications this size
736  *          should be small. This size is in bits.
737  *          Default value is 0, where codec will internally calculate the
738  *          value based on the RC algo type.
739  *
740  *******************************************************************************
741 */
742 typedef struct IMPEG4ENC_RateControlParams {
743     XDAS_Int32 rateControlParamsPreset;
744     XDAS_Int32 rcAlgo;
745     XDAS_Int32 qpI;
746     XDAS_Int32 qpP;
747     XDAS_Int32 seIntialQP;
748     XDAS_Int32 qpMax;
749     XDAS_Int32 qpMin;
750     XDAS_Int32 enablePerceptualQuantMode;
751     XDAS_Int32 allowFrameSkip;
752     XDAS_Int32 initialBufferLevel;
753     XDAS_Int32 vbvBufferSize;
754     XDAS_Int32 qpMinIntra;
755 } IMPEG4ENC_RateControlParams;
756
757
758 /**
759  *******************************************************************************
760  *  @struct IMPEG4ENC_InterCodingParams
761  *  @brief  This structure contains all the parameters which controls Inter MBs
762  *          coding behavior
763  *
764  *  @param  interCodingPreset  :
765  *          This Preset controls the USER_DEFINED vs DEFAULT mode. if User is
766  *          not aware about following fields, it should be set as
767  *          IMPEG4_INTERCODING_DEFAULT
768  *
769  *  @param  searchRangeHorP  :
770  *          Horizontal Search Range for ME algo, range is [16, 144]
771  *
772  *  @param  searchRangeVerP  :
773  *          Vertical Search Range for ME algo, range is [16, 32]
774  *
775  *  @param  globalOffsetME  :
776  *          This variable is used to control ME search algorithm to improve
777  *          video quality by doing ME around Temporal average MV.
778  *          1 for Enable
779  *          0 for Disable
780  *
781  *  @param  earlySkipThreshold  :
782  *          Threshold to use for early skip determination
783  *          The Inter SAD is compared against this Threshold for early skip
784  *          selection
785  *
786  *  @param  enableThresholdingMethod  :
787  *          Thresholding cost Method is used by CALC3 suppress expensive
788  *          coefficients.Thresholding cost Method is used to set a block to be
789  *          not_coded if the block has very few small amplitude coeffs.
790  *
791  *  @param  minBlockSizeP  : minimum block size for P frames.
792  *          Refer IMPEG4ENC_InterBlockSize enumeration to see the valid values
793  *          if this variable takes value of IMPEG4_BLOCKSIZE_8x8 a MB in P Frame
794  *          can have 4 Motion Vectors one for each 8x8 MB to
795  *          improve video quality (not necessarily). This mode is used only for
796  *          MPEG-4. This Field is neglected or read as Disable for H263 encoding.
797  *          Set
798  *          IMPEG4_BLOCKSIZE_8x8 for 4MV
799  *          else only 1MV
800  *
801  *  @param  enableRoundingControl  :
802  *          When enabled reduces the IDCT drift
803  *          1 for Enable
804  *          0 for Disable
805  *******************************************************************************
806 */
807 typedef struct IMPEG4ENC_InterCodingParams {
808     XDAS_Int32  interCodingPreset;
809     XDAS_Int32  searchRangeHorP;
810     XDAS_Int32  searchRangeVerP;
811     XDAS_UInt32 globalOffsetME;
812     XDAS_Int32  earlySkipThreshold;
813     XDAS_Int32  enableThresholdingMethod;
814     XDAS_UInt32 minBlockSizeP;
815     XDAS_UInt32 enableRoundingControl;
816
817 } IMPEG4ENC_InterCodingParams;
818
819
820 /**
821  *******************************************************************************
822  *  @struct IMPEG4ENC_IntraCodingParams
823  *  @brief  This structure contains all the parameters which controls Intra
824  *          encoding
825  *
826  *  @param  intraCodingPreset  :
827  *          This Preset controls the USER_DEFINED vs DEFAULT mode. if User is
828  *          not aware about following fields, it should be set as
829  *          IMPEG4_INTERCODING_DEFAULT
830  *
831  *  @param  intraRefreshMethod  :
832  *          Intra Refresh methods, this can be any one of the
833  *          IMPEG4ENC_IntraRefreshMethods enumeration.
834  *          refer IMPEG4ENC_IntraRefreshMethods enumeration above.
835  *
836  *  @param  intraRefreshRate  :
837  *          if intraRefreshMethod is IMPEG4_INTRAREFRESH_CYCLIC_MBS, this value
838  *          represents madulo cyclic MBs value. MPEG4 Encoder encodes a
839  *          macro block as Intra after every intraRefreshRate number of macro
840  *          blocks.if intraRefreshMethod is IMPEG4_INTRAREFRESH_CYCLIC_ROWS,
841  *          this value represents number if rows which are intra. MPEG4 Encoder
842  *          encodes those many rows as intra every frame and the location of
843  *          intra rows moves in cyclic fashion.
844  *          This variable is ignored if intraRefreshMethod is
845  *          IMPEG4_INTRAREFRESH_NONE.
846  *
847  *  @param  acpredEnable  :
848  *          AC prediction
849  *          0 for Disable
850  *          1 for Enable
851  *
852  *  @param  insertGOVHdrBeforeIframe  :
853  *          inserts GOV Header before I Frame if enabled
854  *          0 for Disable
855  *          1 for Enable
856  *
857  *******************************************************************************
858 */
859 typedef struct IMPEG4ENC_IntraCodingParams {
860     XDAS_Int32  intraCodingPreset;
861     XDAS_UInt32 intraRefreshMethod;
862     XDAS_UInt32 intraRefreshRate;
863     XDAS_UInt32 acpredEnable;
864     XDAS_UInt32 insertGOVHdrBeforeIframe;
865     XDAS_UInt32 enableDriftControl;
866
867 } IMPEG4ENC_IntraCodingParams;
868
869
870 /**
871  *******************************************************************************
872  *  @struct IMPEG4ENC_sliceCodingParams
873  *  @brief  This structure contains all the parameters which controls Intra
874  *          encoding
875  *
876  *  @param  sliceCodingPreset  :
877  *          This Preset controls the USER_DEFINED vs DEFAULT mode. if User is
878  *          not aware about following fields, it should be set as
879  *          IMPEG4_INTERCODING_DEFAULT
880  *
881  *  @param  sliceMode  :
882  *         This defines the control mechanism to split a picture in slices.
883  *         It can be either MB based or bits based and takes the enum
884  *         IMPEG4ENC_SliceMode
885  *
886  *  @param  sliceUnitSize  :
887  *         The meaning of this parameter depends upon sliceMode.
888  *         sliceMode == IMPEG4_SLICEMODE_MBUNIT then this
889  *         parameter informs the number of Macroblocks in one slice
890  *         sliceMode == IMPEG4_SLICEMODE_BITS then this
891  *         parameter informs the number of bits in one slice in MPEG4
892  *         jargon resyncIntervalInBits
893  *         sliceMode == IMPEG4_SLICEMODE_NONE then this
894  *         parameter is not respected
895  *
896  *  @param  gobInterval  :
897  *          insert GOB header after every n GOBs
898  *          This field is only used for H263
899  *          gobInterval range is [0, Max GOB Number-1]
900  *
901  *  @param  useHec  :
902  *          Use Header extension code [0-2]
903  *          0 for Disable
904  *          1 Include HEC for only First GobHeader
905  *          2 Include HEC for for all GobHeader
906  *
907  *
908  *******************************************************************************
909 */
910 typedef struct IMPEG4ENC_sliceCodingParams {
911     XDAS_Int32  sliceCodingPreset;
912     XDAS_Int32  sliceMode;
913     XDAS_Int32  sliceUnitSize;
914     XDAS_UInt32 gobInterval;
915     XDAS_UInt32 useHec;
916
917 } IMPEG4ENC_sliceCodingParams;
918
919
920 /**
921  *******************************************************************************
922  *  @struct IMPEG4ENC_DynamicParams
923  *  @brief  This structure defines the dynamic parameters for MPEG4ENC objects
924  *
925  *  @param  videnc2DynamicParams  :
926  *          refer IVIDENC2_DynamicParams in ividenc2.h file
927  *
928  *  @param  rateControlParams  :
929  *          refer IMPEG4ENC_RateControlParams structure above
930  *
931  *  @param  interCodingParams  :
932  *          refer IMPEG4ENC_InterCodingParams structure above
933  *
934  *  @param  sliceCodingParams  :
935  *          refer IMPEG4ENC_sliceCodingParams structure above
936  *
937  *  @param  aspectRatioIdc  :
938  *          defines the value of pixel aspect ratio
939  *          See Table 6-12 of standard spec for aspect ratio details
940  *
941  *******************************************************************************
942 */
943 typedef struct IMPEG4ENC_DynamicParams {
944     IVIDENC2_DynamicParams      videnc2DynamicParams;
945     IMPEG4ENC_RateControlParams rateControlParams;
946     IMPEG4ENC_InterCodingParams interCodingParams;
947     IMPEG4ENC_sliceCodingParams sliceCodingParams;
948     XDAS_UInt32                 aspectRatioIdc;
949 }IMPEG4ENC_DynamicParams;
950
951
952 /**
953  *******************************************************************************
954  *  @struct IMPEG4ENC_DynamicParams
955  *  @brief  Default dynamic parameter values for MPEG4ENC instance objects
956  *          if user defined dynamic parameters are not given to the encoder then
957  *          encoder uses this default dynamic parameters (which can be found in
958  *          impeg4enc.c file) for encoding.
959  *
960  *******************************************************************************
961 */
962 extern IMPEG4ENC_DynamicParams    MPEG4ENC_TI_DYNAMICPARAMS;
963
964
965 /**
966  *******************************************************************************
967  *  @struct IMPEG4ENC_Params
968  *  @brief  This structure defines the creation parameters for MPEG4ENC objects
969  *
970  *  @param  videnc2Params  :
971  *          Defines creation time parameters for all IVIDENC2 instance objects.
972  *          refer IVIDENC2_Params structure in ividenc2.h file
973  *
974  *  @param  rateControlParams  :
975  *          refer IMPEG4ENC_RateControlParams structure above
976  *
977  *  @param  interCodingParams  :
978  *          refer IMPEG4ENC_InterCodingParams structure above
979  *
980  *  @param  intraCodingParams  :
981  *          refer IMPEG4ENC_IntraCodingParams structure above
982  *
983  *  @param  sliceCodingParams  :
984  *          refer IMPEG4ENC_sliceCodingParams structure above
985  *
986  *  @param  useDataPartitioning  :
987  *          Controls data partitioning for MPEG4 Encoder.
988  *          This mode is automatically disabled when short video header is
989  *          enabled
990  *          0 for Disable
991  *          1 for Enable
992  *
993  *  @param  useRvlc  :
994  *          Use Reversible Variable Length Coding.
995  *          MPEG4 Encoder expects Data Partitioning to be enabled when RVLC is
996  *          enabled or else it returns error.
997  *          This mode is automatically disabled when short video header is
998  *          enabled
999  *          0 for Disable
1000  *          1 for Enable
1001  *
1002  *  @param  useShortVideoHeader  :
1003  *          short video header / h263 base line profile
1004  *          MPEG4 Encoder automatically disable the 4 MV, Data Partitioning,
1005  *          RVLC modes and reset resync interval in bits (disable H.241 flow)
1006  *          0 for Disable
1007  *          1 for Enable
1008  *
1009  *  @param  vopTimeIncrementResolution  :
1010  *          resolution of vop_time_increment bit-stream syntax element,
1011  *          number of ticks/sec
1012  *
1013  *  @param  nonMultiple16RefPadMethod  :
1014  *          Controls the way the padding is done for Ref Frame when Height is
1015  *          non-multiple of  16.
1016  *          Follows the enum IMPEG4ENC_nonMultiple16RefPadMethod
1017  *          IMPEG4_PAD_METHOD_DIVX  - VLC, DIVx way of padding
1018  *          IMPEG4_PAD_METHOD_MPEG4 - MPEG4 Standard specific way of padding
1019  *          default value is IMPEG4_PAD_METHOD_MPEG4.
1020  *
1021  * @param pixelRange :video_range=0 :Y from 16 to 235, Cb and Cr from 16 to 240;
1022  *                    video_range=1 : Y from 0 to 255,Cb and Cr from 0 to 255.
1023  *
1024  * @param enableSceneChangeAlgo : Parameter to enable or disable scene change
1025  *                                algorithm.
1026  * @param useVOS                : VOS header insertion, 0 = off, 1 = on
1027  * @param enableMONA            : enable MONA settings  0 = off, 1 = on
1028  * @param enableAnalyticinfo    : enable MV and SAD access to user
1029  *                                0 = off, 1 = on
1030  *
1031  * @param debugTraceLevel       : Indicates level of debug trace info to be
1032  *                                dumped.
1033  *                                Disabled if this value is zero.
1034  *
1035  * @param lastNFramesToLog      : Indicates no. of frames for which debug trace
1036  *                              info to be dumped. Valid only if debugTraceLevel
1037  *                   is non zero.
1038  *******************************************************************************
1039 */
1040 typedef struct IMPEG4ENC_Params {
1041     IVIDENC2_Params             videnc2Params;
1042     IMPEG4ENC_RateControlParams rateControlParams;
1043     IMPEG4ENC_InterCodingParams interCodingParams;
1044     IMPEG4ENC_IntraCodingParams intraCodingParams;
1045     IMPEG4ENC_sliceCodingParams sliceCodingParams;
1046
1047     XDAS_UInt32 useDataPartitioning;
1048     XDAS_UInt32 useRvlc;
1049     XDAS_UInt32 useShortVideoHeader;
1050     XDAS_UInt32 vopTimeIncrementResolution;
1051     XDAS_UInt32 nonMultiple16RefPadMethod;
1052     XDAS_UInt32 pixelRange;
1053     XDAS_UInt32 enableSceneChangeAlgo;
1054     XDAS_UInt32 useVOS;
1055     XDAS_UInt32 enableMONA;
1056     XDAS_Int32  enableAnalyticinfo;
1057
1058     XDAS_UInt32 debugTraceLevel;
1059     XDAS_UInt32 lastNFramesToLog;
1060
1061 } IMPEG4ENC_Params;
1062
1063
1064 /**
1065  *******************************************************************************
1066  *  @struct IMPEG4ENC_Params
1067  *  @brief  Default parameter values for MPEG4ENC instance objects
1068  *          if user defined parameters are not given to the encoder then
1069  *          encoder uses this default parameters (which can be found in
1070  *          impeg4enc.c file) for encoding.
1071  *
1072  *******************************************************************************
1073 */
1074 extern IMPEG4ENC_Params    MPEG4ENC_TI_PARAMS;
1075
1076
1077 /**
1078  *******************************************************************************
1079  *  @struct IMPEG4ENC_Status
1080  *  @brief  Status structure defines the parameters that can be changed or read
1081  *          during real-time operation of the alogrithm.
1082  *
1083  *  @param  videnc2Status  :
1084  *          Status of the MPEG4 encoder along with error information, if any.
1085  *          refer IVIDENC2_Status structure in ividenc2.h file
1086  *
1087  *  @param  rateControlParams  :
1088  *          refer IMPEG4ENC_RateControlParams structure above
1089  *
1090  *  @param  interCodingParams  :
1091  *          refer IMPEG4ENC_InterCodingParams structure above
1092  *
1093  *  @param  intraCodingParams  :
1094  *          refer IMPEG4ENC_IntraCodingParams structure above
1095  *
1096  *  @param  sliceCodingParams  :
1097  *          refer IMPEG4ENC_sliceCodingParams structure above
1098  *
1099  *  @param  useDataPartitioning  :
1100  *          Use data partitioning
1101  *          0 for Disable
1102  *          1 for Enable
1103  *
1104  *  @param  useRvlc  :
1105  *          Use Reversible Variable Length Coding
1106  *          0 for Disable
1107  *          1 for Enable
1108  *
1109  *  @param  useShortVideoHeader  :
1110  *          short video header / h263 base line profile
1111  *          0 for Disable
1112  *          1 for Enable
1113  *  @param  vopTimeIncrementResolution  :Resolution of vop_time_increment
1114  *                                       bit-stream syntax element,
1115  *                                       number of ticks/sec.
1116  *
1117  *  @param  nonMultiple16RefPadMethod  : Controls the way the padding is done
1118  *                                       for Ref Frame when Height is
1119  *                                       Non-multiple of 16.
1120  *  @param  pixelRange  : Pixel range to be put in header
1121  *                        See IMPEG4VENC_PixelRange enumeration for details.
1122  *
1123  *  @param  enableSceneChangeAlgo  :
1124  *          Scene change detection algorithm.
1125  *          0 for Disable
1126  *          1 for Enable
1127  * @param   useVOS                : VOS header insertion, 0 = off, 1 = on
1128  * @param   enableMONA            : enable MONA settings  0 = off, 1 = on
1129  * @param   enableAnalyticinfo    : enable MV and SAD access to user
1130  *                                  0 = off, 1 = on
1131  *
1132  * @param   debugTraceLevel        :
1133  *          0 Disable dumping debug data
1134  *           1-4 enable dumping debug data
1135  *
1136  * @param lastNFramesToLog : No. of frame for which debug trace info to be
1137  *                           dumped.
1138  *
1139  * @param   extMemoryDebugTraceAddr : External memory address where debug trace
1140  *                                    info is dunped
1141  *
1142  * @param   extMemoryDebugTraceSize : Size of the debug trace info in the
1143  *                                    external memory.
1144  *
1145  *******************************************************************************
1146 */
1147 typedef struct {
1148     IVIDENC2_Status             videnc2Status;
1149     IMPEG4ENC_RateControlParams rateControlParams;
1150     IMPEG4ENC_InterCodingParams interCodingParams;
1151     IMPEG4ENC_IntraCodingParams intraCodingParams;
1152     IMPEG4ENC_sliceCodingParams sliceCodingParams;
1153
1154     XDAS_UInt32 useDataPartitioning;
1155     XDAS_UInt32 useRvlc;
1156     XDAS_UInt32 useShortVideoHeader;
1157     XDAS_UInt32 vopTimeIncrementResolution;
1158     XDAS_UInt32 nonMultiple16RefPadMethod;
1159     XDAS_UInt32 pixelRange;
1160     XDAS_UInt32 enableSceneChangeAlgo;
1161     XDAS_UInt32 useVOS;
1162     XDAS_UInt32 enableMONA;
1163     XDAS_Int32  enableAnalyticinfo;
1164
1165     XDAS_UInt32  debugTraceLevel;
1166     XDAS_UInt32  lastNFramesToLog;
1167     XDAS_UInt32 *extMemoryDebugTraceAddr;
1168     XDAS_UInt32  extMemoryDebugTraceSize;
1169
1170 } IMPEG4ENC_Status;
1171
1172
1173 /**
1174  *******************************************************************************
1175  *  @struct IMPEG4ENC_InArgs
1176  *  @brief  This structure defines the runtime input arguments for
1177  *          IMPEG4ENC::process function
1178  *
1179  *  @param  videnc2InArgs  :
1180  *          Parameters common to video encoders
1181  *          refer IVIDENC2_InArgs structure in ividenc2.h file
1182  *
1183  *******************************************************************************
1184 */
1185 typedef struct IMPEG4ENC_InArgs {
1186     IVIDENC2_InArgs videnc2InArgs;
1187 } IMPEG4ENC_InArgs;
1188
1189
1190 /**
1191  *******************************************************************************
1192  *  @struct IMPEG4ENC_OutArgs
1193  *  @brief  This structure defines the run time output arguments for
1194  *          IMPEG4ENC::process function
1195  *
1196  *  @param  videnc2OutArgs  :
1197  *          output parameters from the IMPEG4ENC::process call
1198  *          refer IVIDENC2_OutArgs structure in ividenc2.h file
1199  *
1200  *******************************************************************************
1201 */
1202 typedef struct IMPEG4ENC_OutArgs {
1203     IVIDENC2_OutArgs videnc2OutArgs;
1204 } IMPEG4ENC_OutArgs;
1205
1206
1207 /**
1208  *******************************************************************************
1209  *  @struct IMPEG4ENC_Fxns
1210  *  @brief  This structure defines all of the operations on MPEG4ENC objects
1211  *
1212  *  @param  ividenc  :
1213  *          refer IVIDENC2_Fxns structure in ividenc2.h file
1214  *
1215  *******************************************************************************
1216 */
1217 typedef struct IMPEG4ENC_Fxns {
1218     IVIDENC2_Fxns ividenc; /* IMPEG4ENC extends IVIDENC */
1219 } IMPEG4ENC_Fxns;
1220
1221 /**
1222  ******************************************************************************
1223  *  @struct IMPEG4ENC_DataSyncDesc
1224  *  @brief  This structure is an extension of XDM_DataSyncDesc to provide add-
1225  *           itional information required for Mode B Packetization according to
1226  *           RFC2190.
1227  *
1228  *  @param mbAddr: this is a pointer to an array of FIrst MB Addresses in diff
1229  *                   packets.
1230  *  @param gobNumber: this is a pointer to an array of GOB Number of first Mb
1231  *                     in different packets
1232  *  @param quantScale: this is a pointer to an array of Quant values of first
1233  *                      Mb in different packets
1234  *  @param mv: this is a pointer to an array of MV of first MB in different
1235  *              packets. Note: the MV is in half-pel reolution as required in
1236  *              RFC2190.
1237  ******************************************************************************
1238 */
1239 typedef struct IMPEG4ENC_DataSyncDesc {
1240     XDM_DataSyncDesc dataSyncDesc;
1241     XDAS_UInt16     *mbAddr;
1242     XDAS_UInt16     *gobNumber;
1243     XDAS_UInt16     *quantScale;
1244     XDAS_UInt32     *mv;
1245 } IMPEG4ENC_DataSyncDesc;
1246
1247 #ifdef __cplusplus
1248 }
1249 #endif /* extern "C" */
1250
1251 /*@}*/ /* ingroup HDVICP2MPEG4 */
1252
1253 #endif /* IMPEG4ENC_ */
1254