Add VIDENC2 headers
[gstreamer-omap:libdce.git] / packages / codec_engine / ti / sdo / ce / video2 / videnc2.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  *  ======== videnc2.h ========
35  */
36 /**
37  *  @file       ti/sdo/ce/video2/videnc2.h
38  *
39  *  @brief      The VIDENC2 video encoder interface.  Provides the user an
40  *              interface to create and interact with XDAIS algorithms that are
41  *              compliant with the XDM-defined IVIDENC2 video encoder
42  *              interface.
43  */
44 /**
45  *  @defgroup   ti_sdo_ce_video2_VIDENC2    VIDENC2 - Video Encoder Interface
46  *
47  *  This is the VIDENC2 video encoder interface.  Several of the data
48  *  types in this API are specified by the XDM IVIDENC2 interface; please see
49  *  the XDM documentation for those details.
50  */
51
52 #ifndef ti_sdo_ce_video2_VIDENC2_
53 #define ti_sdo_ce_video2_VIDENC2_
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 #include <ti/xdais/dm/xdm.h>
60 #include <ti/xdais/dm/ividenc2.h>
61
62 #include <ti/sdo/ce/Engine.h>
63 #include <ti/sdo/ce/visa.h>
64 #include <ti/sdo/ce/skel.h>
65
66 /** @ingroup    ti_sdo_ce_video2_VIDENC2 */
67 /*@{*/
68
69 #define VIDENC2_EOK      IVIDENC2_EOK         /**< @copydoc IVIDENC2_EOK */
70 #define VIDENC2_EFAIL    IVIDENC2_EFAIL       /**< @copydoc IVIDENC2_EFAIL */
71
72 /** @copydoc IVIDENC2_EUNSUPPORTED */
73 #define VIDENC2_EUNSUPPORTED IVIDENC2_EUNSUPPORTED
74
75 #define VIDENC2_ETIMEOUT VISA_ETIMEOUT       /**< @copydoc VISA_ETIMEOUT */
76 #define VIDENC2_FOREVER  VISA_FOREVER        /**< @copydoc VISA_FOREVER */
77
78
79 /**
80  *  @brief      Opaque handle to a VIDENC2 codec.
81  */
82 typedef VISA_Handle VIDENC2_Handle;
83
84 /* The following are just wrapper typedefs */
85
86 /** @copydoc IVIDENC2_Params */
87 typedef struct IVIDENC2_Params VIDENC2_Params;
88
89 /** @copydoc IVIDENC2_InArgs */
90 typedef IVIDENC2_InArgs VIDENC2_InArgs;
91
92 /** @copydoc IVIDENC2_OutArgs */
93 typedef IVIDENC2_OutArgs VIDENC2_OutArgs;
94
95 /** @copydoc IVIDENC2_Cmd */
96 typedef IVIDENC2_Cmd VIDENC2_Cmd;
97
98 /** @copydoc IVIDENC2_DynamicParams */
99 typedef IVIDENC2_DynamicParams VIDENC2_DynamicParams;
100
101 /** @copydoc IVIDENC2_Status */
102 typedef IVIDENC2_Status VIDENC2_Status;
103
104 /** @cond INTERNAL */
105
106 /**
107  *  @brief      An implementation of the skel interface; the skeleton side
108  *              of the stubs.
109  */
110 extern SKEL_Fxns VIDENC2_SKEL;
111
112 /**
113  *  @brief      Implementation of the IVIDENC interface that is run remotely.
114  */
115 extern IVIDENC2_Fxns VIDENC2_STUBS;
116
117 /** @endcond */
118
119 /**
120  *  @brief      Definition of IVIDENC2 codec class configurable parameters
121  *
122  *  @sa         VISA_getCodecClassConfig()
123  */
124 typedef struct IVIDENC2_CodecClassConfig {
125     Bool manageInBufsPlaneDescCache[IVIDEO_MAX_NUM_PLANES];
126     Bool manageInBufsMetaPlaneDescCache[IVIDEO_MAX_NUM_METADATA_PLANES];
127     Bool manageOutBufsCache[XDM_MAX_IO_BUFFERS];
128 } IVIDENC2_CodecClassConfig;
129
130
131 /*
132  *  ======== VIDENC2_control ========
133  */
134 /**
135  *  @brief      Execute the control() method in this instance of a video
136  *              encoder algorithm.
137  *
138  *  @param[in]  handle  Handle to a created video encoder instance.
139  *  @param[in]  id      Command id for XDM control operation.
140  *  @param[in]  params  Runtime control parameters used for encoding.
141  *  @param[out] status  Status info upon completion of encode operation.
142  *
143  *  @pre        @c handle is a valid (non-NULL) video encoder handle
144  *              and the video encoder is in the created state.
145  *
146  *  @retval     #VIDENC2_EOK         Success.
147  *  @retval     #VIDENC2_EFAIL       Failure.
148  *  @retval     #VIDENC2_EUNSUPPORTED    The requested operation
149  *                                       is not supported.
150  *
151  *  @remark     This is a blocking call, and will return after the control
152  *              command has been executed.
153  *
154  *  @remark     If an error is returned, @c status->extendedError may
155  *              indicate further details about the error.  See
156  *              #VIDENC2_Status::extendedError for details.
157  *
158  *  @sa         VIDENC2_create()
159  *  @sa         VIDENC2_delete()
160  *  @sa         IVIDENC2_Fxns::process()
161  */
162 extern Int32 VIDENC2_control(VIDENC2_Handle handle, VIDENC2_Cmd id,
163         VIDENC2_DynamicParams *params, VIDENC2_Status *status);
164
165
166 /*
167  *  ======== VIDENC2_create ========
168  */
169 /**
170  *  @brief      Create an instance of a video encoder algorithm.
171  *
172  *  Instance handles must not be concurrently accessed by multiple threads;
173  *  each thread must either obtain its own handle (via VIDENC2_create()) or
174  *  explicitly serialize access to a shared handle.
175  *
176  *  @param[in]  e       Handle to an opened engine.
177  *  @param[in]  name    String identifier of the type of video encoder
178  *                      to create.
179  *  @param[in]  params  Creation parameters.
180  *
181  *  @retval     NULL            An error has occurred.
182  *  @retval     non-NULL        The handle to the newly created video encoder
183  *                              instance.
184  *
185  *  @remarks    @c params is optional.  If it's not supplied, codec-specific
186  *              default params will be used.
187  *
188  *  @remark     Depending on the configuration of the engine opened, this
189  *              call may create a local or remote instance of the video
190  *              encoder.
191  *
192  *  @codecNameRemark
193  *
194  *  @sa         Engine_open()
195  *  @sa         VIDENC2_delete()
196  */
197 extern VIDENC2_Handle VIDENC2_create(Engine_Handle e, String name,
198     VIDENC2_Params *params);
199
200
201 /*
202  *  ======== VIDENC2_delete ========
203  */
204 /**
205  *  @brief      Delete the instance of a video encoder algorithm.
206  *
207  *  @param[in]  handle  Handle to a created video encoder instance.
208  *
209  *  @remark     Depending on the configuration of the engine opened, this
210  *              call may delete a local or remote instance of the video
211  *              encoder.
212  *
213  *  @pre        @c handle is a valid (non-NULL) handle which is
214  *              in the created state.
215  *
216  *  @post       All resources allocated as part of the VIDENC2_create()
217  *              operation (memory, DMA channels, etc.) are freed.
218  *
219  *  @sa         VIDENC2_create()
220  */
221 extern Void VIDENC2_delete(VIDENC2_Handle handle);
222
223
224 /*
225  *  ======== VIDENC2_process ========
226  */
227 /**
228  *  @brief      Execute the process() method in this instance of a video
229  *              encoder algorithm.
230  *
231  *  @param[in]  handle  Handle to a created video encoder instance.
232  *  @param[in]  inBufs  A buffer descriptor containing input buffers.
233  *  @param[out] outBufs A buffer descriptor containing output buffers.
234  *  @param[in]  inArgs  Input Arguments.
235  *  @param[out] outArgs Output Arguments.
236  *
237  *  @pre        @c handle is a valid (non-NULL) video encoder handle
238  *              and the video encoder is in the created state.
239  *
240  *  @retval     #VIDENC2_EOK         Success.
241  *  @retval     #VIDENC2_EFAIL       Failure.
242  *  @retval     #VIDENC2_EUNSUPPORTED    The requested operation
243  *                                       is not supported.
244  *
245  *  @remark     Since the VIDENC2 decoder contains support for asynchronous
246  *              buffer submission and retrieval, this API becomes known as
247  *              synchronous in nature.
248  *
249  *  @remark     This is a blocking call, and will return after the data
250  *              has been encoded.
251  *
252  *  @remark     The buffers supplied to VIDENC2_process() may have constraints
253  *              put on them.  For example, in dual-processor, shared memory
254  *              architectures, where the codec is running on a remote
255  *              processor, the buffers may need to be physically contiguous.
256  *              Additionally, the remote processor may place restrictions on
257  *              buffer alignment.
258  *
259  *  @remark     If an error is returned, @c outArgs->extendedError may
260  *              indicate further details about the error.  See
261  *              #VIDENC2_OutArgs::extendedError for details.
262  *
263  *  @sa         VIDENC2_create()
264  *  @sa         VIDENC2_delete()
265  *  @sa         VIDENC2_control()
266  *  @sa         VIDENC2_processAsync()
267  *  @sa         VIDENC2_processWait()
268  *  @sa         IVIDENC2_Fxns::process() - the reflected algorithm interface,
269  *                                         which may contain further usage
270  *                                         details.
271  */
272 extern Int32 VIDENC2_process(VIDENC2_Handle handle, IVIDEO2_BufDesc *inBufs,
273         XDM2_BufDesc *outBufs, VIDENC2_InArgs *inArgs,
274         VIDENC2_OutArgs *outArgs);
275
276
277 /*
278  *  ======== VIDENC2_processAsync ========
279  */
280 /**
281  *  @brief      Perform asynchronous submission to this instance of a video
282  *              decoder algorithm.
283  *
284  *  @param[in]  handle  Handle to a created video decoder instance.
285  *  @param[in]  inBufs  A buffer descriptor containing input buffers.
286  *  @param[out] outBufs A buffer descriptor containing output buffers.
287  *  @param[in]  inArgs  Input Arguments.
288  *  @param[out] outArgs Output Arguments.
289  *
290  *  @pre        @c handle is a valid (non-NULL) video decoder handle
291  *              and the video decoder is in the created state.
292  *
293  *  @retval     #VIDENC2_EOK         Success.
294  *  @retval     #VIDENC2_EFAIL       Failure.
295  *  @retval     #VIDENC2_EUNSUPPORTED Unsupported request.
296  *
297  *  @remark     This API is the asynchronous counterpart to the process()
298  *              method.  It allows for buffer and argument submission without
299  *              waiting for retrieval.  A response is retrieved using the
300  *              VIDENC2_processWait() API.
301  *
302  *  @remark     The buffers supplied to VIDENC2_processAsync() may have
303  *              constraints put on them.  For example, in dual-processor,
304  *              shared memory architectures, where the codec is running on a
305  *              remote processor, the buffers may need to be physically
306  *              contiguous.  Additionally, the remote processor may place
307  *              restrictions on buffer alignment.
308  *
309  *  @sa         VIDENC2_create()
310  *  @sa         VIDENC2_delete()
311  *  @sa         VIDENC2_control()
312  *  @sa         VIDENC2_process()
313  *  @sa         VIDENC2_processWait()
314  *  @sa         IVIDENC2_Fxns::process()
315  */
316 extern XDAS_Int32 VIDENC2_processAsync(VIDENC2_Handle handle,
317         IVIDEO2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
318         IVIDENC2_InArgs *inArgs, IVIDENC2_OutArgs *outArgs);
319
320
321 /*
322  *  ======== VIDENC2_processWait ========
323  */
324 /**
325  *  @brief      Wait for a return message from a previous invocation of
326  *              VIDENC2_processAsync() in this instance of an video decoder
327  *              algorithm.
328  *
329  *  @param[in]  handle  Handle to a created video decoder instance.
330  *  @param[in]  inBufs  A buffer descriptor containing input buffers.
331  *  @param[out] outBufs A buffer descriptor containing output buffers.
332  *  @param[in]  inArgs  Input Arguments.
333  *  @param[out] outArgs Output Arguments.
334  *  @param[in]  timeout Amount of "time" to wait (from 0 -> #VIDENC2_FOREVER)
335  *
336  *  @pre        @c handle is a valid (non-NULL) video decoder handle
337  *              and the video decoder is in the created state.
338  *
339  *  @retval     #VIDENC2_EOK         Success.
340  *  @retval     #VIDENC2_EFAIL       Failure.
341  *  @retval     #VIDENC2_EUNSUPPORTED Unsupported request.
342  *  @retval     #VIDENC2_ETIMEOUT    Operation timed out.
343  *
344  *  @remark     This is a blocking call, and will return after the data
345  *              has been decoded.
346  *
347  *  @remark     "Polling" is supported by using a timeout of 0.  Waiting
348  *              forever is supported by using a timeout of #VIDENC2_FOREVER.
349  *
350  *  @remark     There must have previously been an invocation of the
351  *              VIDENC2_processAsync() API.
352  *
353  *  @remark     The buffers supplied to VIDENC2_processAsync() may have
354  *              constraints put on them.  For example, in dual-processor,
355  *              shared memory architectures, where the codec is running on a
356  *              remote processor, the buffers may need to be physically
357  *              contiguous.  Additionally, the remote processor may place
358  *              restrictions on buffer alignment.
359  *
360  *  @sa         VIDENC2_create()
361  *  @sa         VIDENC2_delete()
362  *  @sa         VIDENC2_control()
363  *  @sa         VIDENC2_process()
364  *  @sa         VIDENC2_processAsync()
365  */
366 extern XDAS_Int32 VIDENC2_processWait(VIDENC2_Handle handle,
367         IVIDEO2_BufDesc *inBufs, XDM2_BufDesc *outBufs, IVIDENC2_InArgs *inArgs,
368         IVIDENC2_OutArgs *outArgs, UInt timeout);
369
370
371 /*@}*/
372
373 #ifdef __cplusplus
374 }
375 #endif
376
377 #endif
378 /*
379  *  @(#) ti.sdo.ce.video2; 1, 0, 2,146; 7-27-2010 22:26:14; /db/atree/library/trees/ce/ce-q08x/src/
380  */
381