add videnc2 header for encoders
[gstreamer-omap:ndecs-libdce.git] / packages / xdais / ti / xdais / dm / ividenc2.h
1 /* 
2  * Copyright (c) 2010, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * *  Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  *
12  * *  Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * *  Neither the name of Texas Instruments Incorporated nor the names of
17  *    its contributors may be used to endorse or promote products derived
18  *    from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  * 
32  */
33
34 /**
35  *  @file       ti/xdais/dm/ividenc2.h
36  *
37  *  @brief      This header defines all types, constants, and functions
38  *              shared by all implementations of the video encoder
39  *              algorithms.
40  */
41 /**
42  *  @defgroup   ti_xdais_dm_IVIDENC2   IVIDENC2 - XDM Video Encoder Interface
43  *
44  *  This is the XDM IVIDENC2 Video Encoder Interface.
45  */
46
47 #ifndef ti_xdais_dm_IVIDENC2_
48 #define ti_xdais_dm_IVIDENC2_
49
50 #include <ti/xdais/ialg.h>
51 #include <ti/xdais/xdas.h>
52 #include "xdm.h"
53 #include "ivideo.h"
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59
60 /** @ingroup    ti_xdais_dm_IVIDENC2 */
61 /*@{*/
62
63 #define IVIDENC2_EOK       XDM_EOK             /**< @copydoc XDM_EOK */
64 #define IVIDENC2_EFAIL     XDM_EFAIL           /**< @copydoc XDM_EFAIL */
65 #define IVIDENC2_EUNSUPPORTED XDM_EUNSUPPORTED /**< @copydoc XDM_EUNSUPPORTED */
66
67
68 /**
69  *  @brief  Enumeration of possible motion vector (MV) accuracy
70  *
71  *  @enumWarning
72  */
73 typedef enum {
74     IVIDENC2_MOTIONVECTOR_PIXEL = 0,     /**< Motion vectors accuracy is only integer pel. */
75     IVIDENC2_MOTIONVECTOR_HALFPEL = 1,   /**< Motion vectors accuracy is half pel. */
76     IVIDENC2_MOTIONVECTOR_QUARTERPEL = 2,/**< Motion vectors accuracy is quarter pel. */
77     IVIDENC2_MOTIONVECTOR_EIGHTHPEL = 3, /**< Motion vectors accuracy is one-eighth pel. */
78     IVIDENC2_MOTIONVECTOR_MAX = 4        /**< Motion vectors accuracy is not defined */
79 } IVIDENC2_MotionVectorAccuracy;
80
81 /**
82  *  @brief      Video frame control
83  *
84  *  @enumWarning
85  *
86  *  @extendedEnum
87  *
88  *  @remarks    This enumeration provides the application with some frame
89  *              level control of the video encoder.
90  *
91  *  @sa IVIDENC2_InArgs.control
92  */
93 typedef enum {
94     IVIDENC2_CTRL_NONE = 0,        /**< No control operations. */
95     IVIDENC2_CTRL_FORCESKIP = 1,   /**< Skip frame if it is not IDR/I frame. */
96     /** Default settings. */
97     IVIDENC2_CTRL_DEFAULT = IVIDENC2_CTRL_NONE
98 } IVIDENC2_Control;
99
100
101 /**
102  *  @brief      This must be the first field of all IVIDENC2
103  *              instance objects
104  */
105 typedef struct IVIDENC2_Obj {
106     struct IVIDENC2_Fxns *fxns;
107 } IVIDENC2_Obj;
108
109
110 /**
111  *  @brief      Opaque handle to an IVIDENC2 objects.
112  */
113 typedef struct IVIDENC2_Obj  *IVIDENC2_Handle;
114
115 /**
116  *  @brief      Default codec profile
117  *
118  *  @remarks    This definition is often used when the a particular codec
119  *              doesn't have a profile, or the application doesn't
120  *              know which profile the codec should use.
121  *
122  *  @sa IVIDENC2_Params.profile
123  */
124 #define IVIDENC2_DEFAULTPROFILE (-1)
125
126 /**
127  *  @brief      Default codec level
128  *
129  *  @remarks    This definition is often used when the a particular codec
130  *              doesn't have a level, or the application doesn't
131  *              know which profile the codec should use.
132  *
133  *  @sa IVIDENC2_Params.level
134  */
135 #define IVIDENC2_DEFAULTLEVEL (-1)
136
137 /**
138  *  @brief      Defines the creation time parameters for
139  *              all IVIDENC2 instance objects
140  *
141  *  @extensibleStruct
142  */
143 typedef struct IVIDENC2_Params {
144     XDAS_Int32 size;            /**< @sizeField */
145     XDAS_Int32 encodingPreset;  /**< Encoding preset. */
146     XDAS_Int32 rateControlPreset;/**< @copydoc IVIDEO_RateControlPreset
147                                  *
148                                  *   @sa IVIDEO_RateControlPreset
149                                  */
150     XDAS_Int32 maxHeight;       /**< Maximum video height in pixels. */
151     XDAS_Int32 maxWidth;        /**< Maximum video width in pixels. */
152     XDAS_Int32 dataEndianness;  /**< Endianness of output data.
153                                  *
154                                  *   @sa    XDM_DataFormat
155                                  */
156     XDAS_Int32 maxInterFrameInterval;/**< I to P frame distance. e.g. = 1 if
157                                  *   no B frames, 2 to insert one B frame.
158                                  *
159                                  *   @remarks   This is used for setting the
160                                  *              maximum number of B frames
161                                  *              between two refererence frames.
162                                  */
163     XDAS_Int32 maxBitRate;      /**< Maximum Bit-rate for encoding in bits
164                                  *   per second
165                                  */
166     XDAS_Int32 minBitRate;      /**< Minumum Bit-rate for encoding in bits
167                                  *   per second
168                                  */
169     XDAS_Int32 inputChromaFormat;/**< Chroma format for the input buffer.
170                                  *
171                                  *   @sa XDM_ChromaFormat
172                                  */
173     XDAS_Int32 inputContentType;/**< Video content type of the buffer being
174                                  *   encoded.
175                                  *
176                                  *   @sa IVIDEO_ContentType
177                                  */
178     XDAS_Int32 operatingMode;   /**< Video coding mode of operation.
179                                  *
180                                  *   @sa IVIDEO_OperatingMode
181                                  */
182     XDAS_Int32 profile;         /**< Profile indicator of video codec
183                                  *
184                                  *   @remarks   Only one default value
185                                  *              (#IVIDENC2_DEFAULTPROFILE) is
186                                  *              defined by XDM for this field.
187                                  *              The reason for not
188                                  *              defining further values
189                                  *              is to keep profile values as
190                                  *              defined by video codec
191                                  *              standards.
192                                  *
193                                  *   @sa IVIDENC2_Status.profile
194                                  */
195     XDAS_Int32 level;           /**< Level indicator of video codec
196                                  *
197                                  *   @remarks   Only one default value
198                                  *              (#IVIDENC2_DEFAULTLEVEL) is
199                                  *              defined by XDM for this field.
200                                  *              The reason for not
201                                  *              defining further values
202                                  *              is to keep profile values as
203                                  *              defined by video codec
204                                  *              standards.
205                                  *
206                                  *   @sa IVIDENC2_Status.level
207                                  */
208     XDAS_Int32 inputDataMode;   /**< Input data mode.
209                                  *
210                                  *   @remarks   If a subframe mode is provided,
211                                  *              the application must call
212                                  *              IVIDENC2_Fxns::control() with
213                                  *              #XDM_SETPARAMS id prior to
214                                  *              #IVIDENC2_Fxns::process() to
215                                  *              set the
216                                  *              IVIDENC2_DynamicParams::getDataFxn
217                                  *              and
218                                  *              IVIDENC2_DynamicParams::getDataHandle.
219                                  *              Else, the alg can return
220                                  *              error.
221                                  *
222                                  *   @sa IVIDEO_DataMode
223                                  */
224     XDAS_Int32 outputDataMode;  /**< Output data mode.
225                                  *
226                                  *   @remarks   If a subframe mode is provided,
227                                  *              the application must call
228                                  *              IVIDENC2_Fxns::control() with
229                                  *              #XDM_SETPARAMS id prior to
230                                  *              #IVIDENC2_Fxns::process() to
231                                  *              set the
232                                  *              IVIDENC2_DynamicParams::putDataFxn,
233                                  *              IVIDENC2_DynamicParams::putDataHandle
234                                  *              (and optionally
235                                  *              IVIDENC2_DynamicParams::getBufferFxn,
236                                  *              and
237                                  *              IVIDENC2_DynamicParams::getBufferHandle).
238                                  *              Else, the alg can return
239                                  *              error.
240                                  *
241                                  *   @sa IVIDEO_DataMode
242                                  */
243     XDAS_Int32 numInputDataUnits; /**< Number of input slices/rows.
244                                  *
245                                  *   @remarks  Units depend on the
246                                  *             @c inputDataMode, like number of
247                                  *             slices/rows/blocks etc.
248                                  *
249                                  *   @remarks  Ignored if @c inputDataMode
250                                  *             is set to full frame mode.
251                                  */
252     XDAS_Int32 numOutputDataUnits;/**< Number of output slices/rows.
253                                  *
254                                  *   @remarks  Units depend on the
255                                  *             @c outputDataMode, like number of
256                                  *             slices/rows/blocks etc.
257                                  *
258                                  *   @remarks  Ignored if @c outputDataMode
259                                  *             is set to full frame mode.
260                                  */
261     XDAS_Int32 metadataType[IVIDEO_MAX_NUM_METADATA_PLANES];/**< Type of
262                                  *   each metadata plane.
263                                  *
264                                  *   @sa IVIDEO_MetadataType
265                                  */
266 } IVIDENC2_Params;
267
268
269 /**
270  *  @brief      This structure defines the algorithm parameters that can be
271  *              modified after creation via control() calls
272  *
273  *  @remarks    It is not necessary that a given implementation support all
274  *              dynamic parameters to be configurable at run time.  If a
275  *              particular algorithm does not support run-time updates to
276  *              a parameter that the application is attempting to change
277  *              at runtime, it may indicate this as an error.
278  *
279  *  @extensibleStruct
280  *
281  *  @sa         IVIDENC2_Fxns::control()
282  */
283 typedef struct IVIDENC2_DynamicParams {
284     XDAS_Int32 size;            /**< @sizeField */
285     XDAS_Int32 inputHeight;     /**< Input frame height. */
286     XDAS_Int32 inputWidth;      /**< Input frame width. */
287     XDAS_Int32 refFrameRate;    /**< Reference, or input, frame rate in
288                                  *   fps * 1000.
289                                  *
290                                  *   @remarks   For example, if ref frame
291                                  *              rate is 30 frames per second,
292                                  *              this field will be 30000.
293                                  */
294     XDAS_Int32 targetFrameRate; /**< Target frame rate in
295                                  *   fps * 1000.
296                                  *
297                                  *   @remarks   For example, if target frame
298                                  *              rate is 30 frames per second,
299                                  *              this field will be 30000.
300                                  */
301     XDAS_Int32 targetBitRate;   /**< Target bit rate in bits per second. */
302     XDAS_Int32 intraFrameInterval;/**< The number of frames between two I
303                                  *    frames.  For example, 30.
304                                  *
305                                  *    @remarks  For example, this field will be:
306                                  *      - 0 - Only first frame to be intra
307                                  *        coded.  e.g. IPPPPPP...
308                                  *      - 1 - No inter frames (all intra
309                                  *        frames).
310                                  *      - 2 - Consecutive IPIPIP... sequence (if
311                                  *        no B frames).
312                                  *      - 3 - IPPIPP... or IPBIPBI... and so on.
313                                  */
314     XDAS_Int32 generateHeader;  /**< @copydoc XDM_EncMode
315                                  *
316                                  *   @sa XDM_EncMode
317                                  */
318     XDAS_Int32 captureWidth;    /**< DEFAULT(0): use imagewidth as
319                                  *   pitch else use given capture
320                                  *   width for pitch provided it
321                                  *   is greater than image width.
322                                  */
323     XDAS_Int32 forceFrame;      /**< Force the current (immediate) frame to be
324                                  *   encoded as a specific frame type.
325                                  *
326                                  *   @remarks   For example, this field will be:
327                                  *     - IVIDEO_NA_FRAME - No forcing of any
328                                  *       specific frame type for the frame.
329                                  *     - IVIDEO_I_FRAME - Force the frame to be
330                                  *       encoded as I frame.
331                                  *     - IVIDEO_IDR_FRAME - Force the frame to
332                                  *       be encoded as an IDR frame (specific
333                                  *       to H.264 codecs).
334                                  *     - IVIDEO_P_FRAME - Force the frame to be
335                                  *       encoded as a P frame.
336                                  *     - IVIDEO_B_FRAME - Force the frame to be
337                                  *       encoded as a B frame.
338                                  *
339                                  *   @sa IVIDEO_FrameType.
340                                  */
341     XDAS_Int32 interFrameInterval;/**< Number of B frames between two reference
342                                  *   frames; that is, the number of B frames
343                                  *   between two P frames or I/P frames.
344                                  *   DEFAULT(0).
345                                  *
346                                  *   @remarks   For example, this field will be:
347                                  *     - 0 - to use maxInterFrameInterval.
348                                  *     - 1 - 0 B frames between two reference
349                                  *       frames.
350                                  *     - 2 - 1 B frame between two reference
351                                  *       frames.
352                                  *     - 3 - 2 B frames between two reference
353                                  *       frames.
354                                  *     - and so on...
355                                  *
356                                  *   @sa IVIDENC2_Params.maxInterFrameInterval.
357                                  */
358     XDAS_Int32 mvAccuracy;      /**< Pixel Accuracy of the motion vector
359                                  *
360                                  *   @remarks   This parameter allows the user
361                                  *              to tune performance by
362                                  *              controlling the complexity of
363                                  *              motion estimation and
364                                  *              compensation within the video
365                                  *              encoder.
366                                  *
367                                  *    @sa IVIDENC2_MotionVectorAccuracy
368                                  */
369     XDAS_Int32 sampleAspectRatioHeight; /**< Sample aspect ratio: Height
370                                  *
371                                  *   @remarks   This parameter is used to
372                                  *              describe the desired aspect
373                                  *              ratio in the bitstream.
374                                  */
375     XDAS_Int32 sampleAspectRatioWidth; /**< Sample aspect ratio: Width
376                                  *
377                                  *   @remarks   This parameter is used to
378                                  *              describe the desired aspect
379                                  *              ratio in the bitstream.
380                                  */
381     XDAS_Int32 ignoreOutbufSizeFlag; /**< Flag to indicate that the application
382                                  *   has ignored the output buffer size
383                                  *   requirement.
384                                  *
385                                  *   @remarks   Typically video encoders
386                                  *              ask for large output buffers
387                                  *              (compressed bit-streams)
388                                  *              assuming theoretical worst
389                                  *              case.  But on memory
390                                  *              constrained systems, the
391                                  *              application may want to
392                                  *              allocate less than this
393                                  *              worst-case size, depending
394                                  *              upon the use case.
395                                  *              If the application provides a
396                                  *              buffer that is smaller than
397                                  *              the worst-case size, the
398                                  *              encoder will return an error.
399                                  *              To prevent the encoder from
400                                  *              returning an error, the
401                                  *              application can set this
402                                  *              @c ignoreOutbufSizeFlag field to
403                                  *              #XDAS_TRUE.  When this flag
404                                  *              is set to #XDAS_TRUE, the
405                                  *              encoder shouldn't return an
406                                  *              error even if the output
407                                  *              buffer size is less than
408                                  *              requested by the codec.
409                                  *
410                                  *    @remarks  Valid values are #XDAS_TRUE
411                                  *              and #XDAS_FALSE.
412                                  */
413     XDM_DataSyncPutFxn putDataFxn; /**< Optional datasync "put data" function.
414                                  *
415                                  *   @remarks   Apps/frameworks that don't
416                                  *              support datasync should set
417                                  *              this to NULL.
418                                  *
419                                  *   @remarks   This function is provided
420                                  *              by the app/framework to the
421                                  *              video encoder.  The encoder
422                                  *              calls this function when data
423                                  *              has been put into an output
424                                  *              buffer.
425                                  */
426     XDM_DataSyncHandle putDataHandle;/**< Datasync "put data" handle
427                                  *
428                                  *   @remarks   This is a handle which the
429                                  *              codec must provide when
430                                  *              calling the app-registered
431                                  *              IVIDENC2_DynamicParams.putDataFxn().
432                                  *
433                                  *   @remarks   Apps/frameworks that don't
434                                  *              support datasync should set
435                                  *              this to NULL.
436                                  *
437                                  *   @remarks   For an algorithm, this handle
438                                  *              is read-only; it must not be
439                                  *              modified when calling
440                                  *              the app-registered
441                                  *              IVIDENC2_DynamicParams.putDataFxn().
442                                  *
443                                  *   @remarks   The app/framework can use
444                                  *              this handle to differentiate
445                                  *              callbacks from different
446                                  *              algorithms.
447                                  */
448     XDM_DataSyncGetFxn getDataFxn;/**< Datasync "get data" function.
449                                  *
450                                  *   @remarks   This function is provided
451                                  *              by the app/framework to the
452                                  *              video encoder.  The encoder
453                                  *              calls this function to get
454                                  *              partial video buffer(s)
455                                  *              from the app/framework.
456                                  *
457                                  *   @remarks   Apps/frameworks that don't
458                                  *              support datasync should set
459                                  *              this to NULL.
460                                  */
461     XDM_DataSyncHandle getDataHandle;/**< Datasync "get data" handle
462                                  *
463                                  *   @remarks   This is a handle which the
464                                  *              codec must provide when
465                                  *              calling @c getDataFxn.
466                                  *
467                                  *   @remarks   Apps/frameworks that don't
468                                  *              support datasync should set
469                                  *              this to NULL.
470                                  *
471                                  *   @remarks   For an algorithm, this handle
472                                  *              is read-only; it must not be
473                                  *              modified when calling
474                                  *              the app-registered
475                                  *              IVIDENC2_DynamicParams.getDataFxn().
476                                  *
477                                  *   @remarks   The app/framework can use
478                                  *              this handle to differentiate
479                                  *              callbacks from different
480                                  *              algorithms.
481                                  */
482     XDM_DataSyncGetBufferFxn getBufferFxn;/**< Datasync "get buffer" function.
483                                  *
484                                  *   @remarks   This function is provided
485                                  *              by the app/framework to the
486                                  *              video encoder.  The encoder
487                                  *              calls this function to obtain
488                                  *              partial compressed bit-stream
489                                  *              data buffers from the
490                                  *              app/framework.
491                                  *
492                                  *   @remarks   Apps/frameworks that don't
493                                  *              support datasync should set
494                                  *              this to NULL.
495                                  */
496     XDM_DataSyncHandle getBufferHandle;/**< Datasync "get buffer" handle
497                                  *
498                                  *   @remarks   This is a handle which the
499                                  *              codec must provide when
500                                  *              calling the app-registered
501                                  *              IVIDENC2_DynamicParam.getBufferFxn().
502                                  *
503                                  *   @remarks   Apps/frameworks that don't
504                                  *              support datasync should set
505                                  *              this to NULL.
506                                  *
507                                  *   @remarks   For an algorithm, this handle
508                                  *              is read-only; it must not be
509                                  *              modified when calling
510                                  *              the app-registered
511                                  *              IVIDENC2_DynamicParams.getBufferFxn().
512                                  *
513                                  *   @remarks   The app/framework can use
514                                  *              this handle to differentiate
515                                  *              callbacks from different
516                                  *              algorithms.
517                                  */
518     XDAS_Int32 lateAcquireArg;  /**< Argument used during late acquire.
519                                  *
520                                  *   @remarks   For all control() commands
521                                  *              other than
522                                  *              #XDM_SETLATEACQUIREARG, this
523                                  *              field is ignored and can
524                                  *              therefore be set by the
525                                  *              caller to any value.
526                                  *
527                                  *   @remarks   This field is used to
528                                  *              provide the
529                                  *              'late acquire' arg required by
530                                  *              #XDM_SETLATEACQUIREARG.
531                                  *
532                                  *   @remarks   Late acquire support is
533                                  *              an optional feature for
534                                  *              video encoders.  If the
535                                  *              codec supports late
536                                  *              acquisition of resources,
537                                  *              and the application has supplied
538                                  *              a lateAcquireArg value (via
539                                  *              #XDM_SETLATEACQUIREARG), then the
540                                  *              codec must also provide this
541                                  *              @c lateAcquireArg value when
542                                  *              requesting resources (i.e.
543                                  *              during their call to
544                                  *              acquire() when requesting
545                                  *              the resource).
546                                  */
547 } IVIDENC2_DynamicParams;
548
549
550 /**
551  *  @brief      Defines the input arguments for all IVIDENC2 instance
552  *              process function
553  *
554  *  @extensibleStruct
555  *
556  *  @sa         IVIDENC2_Fxns::process()
557  */
558 typedef struct IVIDENC2_InArgs {
559     XDAS_Int32 size;            /**< @sizeField */
560     XDAS_Int32 inputID;         /**< Identifier to attach with the corresponding
561                                  *   input frames to be encoded.
562                                  *
563                                  *   @remarks   This is useful when frames
564                                  *              require buffering (e.g.
565                                  *              B frames), and to support
566                                  *              buffer management.
567                                  *
568                                  *   @remarks   When there is no re-ordering,
569                                  *              IVIDENC2_OutArgs::outputID will
570                                  *              be the same as this inputID
571                                  *              field.
572                                  *
573                                  *   @remarks   Zero (0) is <b>not</b> a
574                                  *              supported inputID.  This value
575                                  *              is reserved for cases when
576                                  *              there is no input buffer is
577                                  *              provided.
578                                  *
579                                  *   @sa IVIDENC2_OutArgs::outputID.
580                                  */
581    XDAS_Int32 control;          /**< Encoder control operations
582                                  *
583                                  *   @sa IVIDENC2_Control
584                                  */
585 } IVIDENC2_InArgs;
586
587
588 /**
589  *  @brief      Defines instance status parameters
590  *
591  *  @extensibleStruct
592  *
593  *  @sa         IVIDENC2_Fxns::control()
594  */
595 typedef struct IVIDENC2_Status {
596     XDAS_Int32 size;            /**< @sizeField */
597     XDAS_Int32 extendedError;   /**< @extendedErrorField */
598     XDM1_SingleBufDesc data;    /**< Buffer descriptor for data passing.
599                                  *
600                                  *   @remarks   If this field is not used,
601                                  *              the application <b>must</b>
602                                  *              set @c data.buf to NULL.
603                                  *
604                                  *   @remarks   This buffer can be used as
605                                  *              either input or output,
606                                  *              depending on the command.
607                                  *
608                                  *   @remarks   The buffer will be provided
609                                  *              by the application, and
610                                  *              returned to the application
611                                  *              upon return of the
612                                  *              IVIDENC2_Fxns.control()
613                                  *              call.  The algorithm must
614                                  *              not retain a pointer to this
615                                  *              data.
616                                  *
617                                  *   @sa #XDM_GETVERSION
618                                  */
619
620     XDAS_Int32  encodingPreset; /**< Encoding preset. */
621     XDAS_Int32  rateControlPreset;/**< @copydoc IVIDEO_RateControlPreset
622                                  *
623                                  *   @sa IVIDEO_RateControlPreset
624                                  */
625     XDAS_Int32  maxInterFrameInterval; /**< I to P frame distance. e.g. = 1 if
626                                  *   no B frames, 2 to insert one B frame.
627                                  *
628                                  *   @remarks   This is used for setting the
629                                  *              maximum number of B frames
630                                  *              between two refererence frames.
631                                  */
632     XDAS_Int32 inputChromaFormat;/**< Chroma format for the input buffer.
633                                  *
634                                  *   @sa XDM_ChromaFormat
635                                  */
636     XDAS_Int32 inputContentType; /**< Video content type of the buffer being
637                                  *   encoded.
638                                  *
639                                  *   @sa IVIDEO_ContentType
640                                  */
641     XDAS_Int32 operatingMode;   /**< Video encoding mode of operation.
642                                  *
643                                  *   @sa IVIDEO_OperatingMode
644                                  */
645     XDAS_Int32 profile;         /**< Profile indicator of video codec.
646                                  *
647                                  *   @sa IVIDENC2_DEFAULTPROFILE
648                                  *   @sa IVIDENC2_Params.profile
649                                  */
650     XDAS_Int32 level;           /**< Level indicator of video codec.
651                                  *
652                                  *   @sa IVIDENC2_DEFAULTLEVEL
653                                  *   @sa IVIDENC2_Params.level
654                                  */
655     XDAS_Int32 inputDataMode;   /**< Input data mode.
656                                  *
657                                  *   @sa IVIDENC2_Params.inputDataMode
658                                  *   @sa IVIDEO_DataMode
659                                  */
660     XDAS_Int32 outputDataMode;  /**< Output data mode.
661                                  *
662                                  *   @sa IVIDENC2_Params.outputDataMode
663                                  *   @sa IVIDEO_DataMode
664                                  */
665     XDAS_Int32 numInputDataUnits; /**< Number of input slices/rows.
666                                  *
667                                  *   @remarks   Units depend on the
668                                  *              IVIDENC2_Params.inputDataMode,
669                                  *              like number of
670                                  *              slices/rows/blocks etc.
671                                  *
672                                  *   @remarks   Ignored if
673                                  *              IVIDENC2_Params.inputDataMode
674                                  *              is set to full frame mode.
675                                  *
676                                  *   @sa IVIDENC2_Params.inputDataMode
677                                  */
678     XDAS_Int32 numOutputDataUnits;/**< Number of output slices/rows.
679                                  *
680                                  *   @remarks  Units depend on the
681                                  *             @c outputDataMode, like number of
682                                  *             slices/rows/blocks etc.
683                                  *
684                                  *   @remarks   Ignored if
685                                  *              IVIDENC2_Params.outputDataMode
686                                  *              is set to full frame mode.
687                                  *
688                                  *   @sa IVIDENC2_Params.outputDataMode
689                                  */
690    XDAS_Int32 configurationID;  /**< Configuration ID of given codec.
691                                  *
692                                  *   @remarks   This is used to differentiate
693                                  *              multiple images of a vendor.
694                                  *              It can be used by the
695                                  *              framework to optimize the
696                                  *              save/restore overhead of any
697                                  *              resources used.
698                                  *
699                                  *   @remarks   This can be useful in
700                                  *              multichannel use case
701                                  *              scenarios.
702                                  *
703                                  */
704     XDM1_AlgBufInfo bufInfo;    /**< Input and output buffer information.
705                                  *
706                                  *   @remarks   This field provides the
707                                  *              application with the algorithm's
708                                  *              buffer requirements.  The
709                                  *              requirements may vary depending
710                                  *              on the current configuration
711                                  *              of the algorithm instance.
712                                  *
713                                  *   @sa IVIDENC2_Params
714                                  *   @sa XDM1_AlgBufInfo
715                                  *   @sa IVIDENC2_Fxns.process()
716                                  */
717     XDAS_Int32 metadataType[IVIDEO_MAX_NUM_METADATA_PLANES];/**< Type of
718                                  *   each metadata plane.
719                                  *
720                                  *   @sa IVIDEO_MetadataType
721                                  */
722     IVIDENC2_DynamicParams encDynamicParams;  /**< Video encoder dynamic
723                                  *   parameters.
724                                  *
725                                  *   @todo      Need to better wordsmith this
726                                  *              section.
727                                  *
728                                  *   @remarks   In case of extened dynamic
729                                  *              Params, alg can check the
730                                  *              size of status or
731                                  *              DynamicParams and return
732                                  *              the parameters accordingly.
733                                  */
734 } IVIDENC2_Status;
735
736
737 /**
738  *  @brief      Defines the run time output arguments for all IVIDENC2
739  *              instance objects
740  *
741  *  @extensibleStruct
742  *
743  *  @sa         IVIDENC2_Fxns::process()
744  */
745 typedef struct IVIDENC2_OutArgs {
746     XDAS_Int32 size;            /**< @sizeField */
747     XDAS_Int32 extendedError;   /**< @extendedErrorField */
748     XDAS_Int32 bytesGenerated;  /**< Number of bytes generated during the
749                                  *   IVIDENC2_Fxns::process() call.
750                                  */
751     XDAS_Int32 encodedFrameType;/**< @copydoc IVIDEO_FrameType
752                                  *
753                                  *   @sa IVIDEO_FrameType
754                                  */
755     XDAS_Int32 inputFrameSkip;  /**< @copydoc IVIDEO_SkipMode
756                                  *
757                                  *   @sa IVIDEO_SkipMode
758                                  */
759    XDAS_Int32 freeBufID[IVIDEO2_MAX_IO_BUFFERS]; /**< This is an
760                                  *   array of inputID's corresponding to the
761                                  *   buffers that have been unlocked in the
762                                  *   current process call.
763                                  *
764                                  *   @remarks   The buffers released by the
765                                  *              algorithm are indicated by
766                                  *              their non-zero ID (previously
767                                  *              provided via
768                                  *              IVIDENC2_InArgs#inputID).
769                                  *
770                                  *   @remarks   A value of zero (0) indicates
771                                  *              an invalid ID.  The first zero
772                                  *              entry in array will indicate
773                                  *              end of valid freeBufIDs within
774                                  *              the array.  Hence the
775                                  *              application can stop searching
776                                  *              the array when it encounters the
777                                  *              first zero entry.
778                                  *
779                                  *   @remarks   If no buffer was unlocked in
780                                  *              the process call,
781                                  *              @c freeBufID[0] will
782                                  *              have a value of zero.
783                                  *
784                                  *   @sa IVIDENC2_InArgs#inputID
785                                  */
786
787     IVIDEO2_BufDesc reconBufs;  /**< Reconstruction frames. */
788 } IVIDENC2_OutArgs;
789
790
791 /**
792  *  @brief      Defines the control commands for the IVIDENC2 module
793  *
794  *  @remarks    This ID can be extended in IMOD interface for
795  *              additional controls.
796  *
797  *  @sa         XDM_CmdId
798  *
799  *  @sa         IVIDENC2_Fxns::control()
800  */
801 typedef  IALG_Cmd IVIDENC2_Cmd;
802
803
804 /**
805  *  @brief      Defines all of the operations on IVIDENC2 objects
806  */
807 typedef struct IVIDENC2_Fxns {
808     IALG_Fxns   ialg;             /**< XDAIS algorithm interface.
809                                    *
810                                    *   @sa      IALG_Fxns
811                                    */
812
813 /**
814  *  @brief      Basic video encoding call
815  *
816  *  @param[in]  handle          Handle to an algorithm instance.
817  *  @param[in,out] inBufs       Input video buffer descriptors.
818  *  @param[in,out] outBufs      Output buffer descriptors.  The algorithm
819  *                              may modify the output buffer pointers.
820  *  @param[in]  inArgs          Input arguments.  This is a required
821  *                              parameter.
822  *  @param[out] outArgs         Ouput results.  This is a required parameter.
823  *
824  *  @remarks    process() is a blocking call.  When process() returns, the
825  *              algorithm's processing is complete.
826  *
827  *  @pre        @c inBufs must not be NULL, and must point to a valid
828  *              IVIDEO2_BufDesc structure.
829  *
830  *  @pre        @c inBufs->numPlanes will indicate the total number of input
831  *              buffers supplied for input frame in the @c inBufs->planeDesc[]
832  *              array.
833  *
834  *  @pre        @c inBufs->numMetaPlanes will indicate the total number of input
835  *              buffers supplied for meta data planes in the
836  *              @c inBufs->metadataPlaneDesc[] array.
837  *
838  *  @pre        @c outBufs must not be NULL, and must point to a valid
839  *              XDM2_BufDesc structure.
840  *
841  *  @pre        @c outBufs->buf[0] must not be NULL, and must point to
842  *              a valid buffer of data that is at least
843  *              @c outBufs->bufSizes[0] bytes in length.
844  *
845  *  @pre        @c inArgs must not be NULL, and must point to a valid
846  *              IVIDENC2_InArgs structure.
847  *
848  *  @pre        @c outArgs must not be NULL, and must point to a valid
849  *              IVIDENC2_OutArgs structure.
850  *
851  *  @pre        The buffers in @c inBuf and @c outBuf are physically
852  *              contiguous and owned by the calling application.
853  *
854  *  @post       The algorithm <b>must not</b> modify the contents of @c inArgs.
855  *
856  *  @post       The algorithm <b>must not</b> modify the contents of
857  *              @c inBufs, with the exception of @c inBufs.bufDesc[].accessMask.
858  *              That is, the data and buffers pointed to by these parameters
859  *              must be treated as read-only.
860  *
861  *  @post       The algorithm <b>must</b> appropriately set/clear the
862  *              IVIDEO2_BufDesc.planeDesc[].accessMask and
863  *              IVIDEO2_BufDesc.metadataPlaneDesc[].accessMask fields in
864  *              @c inBufs to indicate the mode in which each of the respective
865  *              buffers were read.
866  *              For example, if the algorithm only read from
867  *              @c inBufs.planeDesc[0].buf using the algorithm processor, it
868  *              could utilize #XDM_SETACCESSMODE_READ to update the appropriate
869  *              @c accessMask fields.
870  *              The application <i>may</i> utilize these
871  *              returned values to appropriately manage cache.
872  *
873  *  @post       The buffers in @c inBufs are
874  *              owned by the calling application.
875  *
876  *  @retval     #IVIDENC2_EOK           @copydoc IVIDENC2_EOK
877  *  @retval     #IVIDENC2_EFAIL         @copydoc IVIDENC2_EFAIL
878  *                                      See IVIDENC2_Status.extendedError
879  *                                      for more detailed further error
880  *                                      conditions.
881  *  @retval     #IVIDENC2_EUNSUPPORTED  @copydoc IVIDENC2_EUNSUPPORTED
882  *
883  *  @todo       Need to review these comments.  Not sure @c inBufs and
884  *              @c outBufs are correctly described.
885  */
886     XDAS_Int32 (*process)(IVIDENC2_Handle handle, IVIDEO2_BufDesc *inBufs,
887             XDM2_BufDesc *outBufs, IVIDENC2_InArgs *inArgs,
888             IVIDENC2_OutArgs *outArgs);
889
890
891 /**
892  *  @brief      Control behavior of an algorithm
893  *
894  *  @param[in]  handle          Handle to an algorithm instance.
895  *  @param[in]  id              Command id.  See #XDM_CmdId.
896  *  @param[in]  params          Dynamic parameters.  This is a required
897  *                              parameter.
898  *  @param[out] status          Output results.  This is a required parameter.
899  *
900  *  @pre        @c handle must be a valid algorithm instance handle.
901  *
902  *  @pre        @c params must not be NULL, and must point to a valid
903  *              IVIDENC2_DynamicParams structure.
904  *
905  *  @pre        @c status must not be NULL, and must point to a valid
906  *              IVIDENC2_Status structure.
907  *
908  *  @pre        If a buffer is provided in the @c status->data field,
909  *              it must be physically contiguous and owned by the calling
910  *              application.
911  *
912  *  @post       The algorithm <b>must not</b> modify the contents of @c params.
913  *              That is, the data pointed to by this parameter must be
914  *              treated as read-only.
915  *
916  *  @post       If a buffer was provided in the @c status->data field,
917  *              it is owned by the calling application.
918  *
919  *  @retval     #IVIDENC2_EOK           @copydoc IVIDENC2_EOK
920  *  @retval     #IVIDENC2_EFAIL         @copydoc IVIDENC2_EFAIL
921  *                                      See IVIDENC2_Status.extendedError
922  *                                      for more detailed further error
923  *                                      conditions.
924  *  @retval     #IVIDENC2_EUNSUPPORTED  @copydoc IVIDENC2_EUNSUPPORTED
925  */
926     XDAS_Int32 (*control)(IVIDENC2_Handle handle, IVIDENC2_Cmd id,
927             IVIDENC2_DynamicParams *params, IVIDENC2_Status *status);
928
929 } IVIDENC2_Fxns;
930
931
932 /*@}*/
933
934 #ifdef __cplusplus
935 }
936 #endif
937
938 #endif
939 /*
940  *  @(#) ti.xdais.dm; 1, 0, 7,23; 10-21-2010 16:35:44; /db/wtree/library/trees/dais/dais.git/src/ dais-s07
941  */
942