1 /*
2 * Copyright (c) 2013, 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 * ======== viddec1.h ========
35 */
36 /**
37 * @file ti/sdo/ce/video1/viddec1.h
38 *
39 * @brief The VIDDEC1 video decoder interface. Provides the user an
40 * interface to create and interact with XDAIS algorithms that are
41 * compliant with the XDM-defined IVIDDEC1 video decoder
42 * interface.
43 */
44 /**
45 * @defgroup ti_sdo_ce_video1_VIDDEC1 VIDDEC1 - Video Decoder Interface
46 *
47 * This is the VIDDEC1 video decoder interface. Several of the data
48 * types in this API are specified by the XDM interface; please see
49 * the XDM documentation for those details.
50 */
52 #ifndef ti_sdo_ce_video1_VIDDEC1_
53 #define ti_sdo_ce_video1_VIDDEC1_
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
59 #include <ti/xdais/dm/xdm.h>
60 #include <ti/xdais/dm/ividdec1.h>
62 #include <ti/sdo/ce/Engine.h>
63 #include <ti/sdo/ce/visa.h>
64 #include <ti/sdo/ce/skel.h>
66 /** @ingroup ti_sdo_ce_video1_VIDDEC1 */
67 /*@{*/
69 typedef IVIDDEC1_Status VIDDEC1_Status; /**< @copydoc IVIDDEC1_Status */
71 #define VIDDEC1_EOK IVIDDEC1_EOK /**< @copydoc IVIDDEC1_EOK */
72 #define VIDDEC1_EFAIL IVIDDEC1_EFAIL /**< @copydoc IVIDDEC1_EFAIL */
74 /**< @copydoc IVIDDEC1_EUNSUPPORTED */
75 #define VIDDEC1_EUNSUPPORTED IVIDDEC1_EUNSUPPORTED
77 #define VIDDEC1_ETIMEOUT VISA_ETIMEOUT /**< @copydoc VISA_ETIMEOUT */
78 #define VIDDEC1_FOREVER VISA_FOREVER /**< @copydoc VISA_FOREVER */
80 /**
81 * @brief The VISA type
82 */
83 #define VIDDEC1_VISATYPE "ti.sdo.ce.video1.IVIDDEC1"
85 /**
86 * @brief Name of stub functions. Use this name when registering the
87 * VIDDEC1_STUBS functions with Engine_addStubFxns.
88 *
89 * @sa Engine_addStubFxns
90 */
91 #define VIDDEC1_STUBSNAME "VIDDEC1_STUBS"
94 /**
95 * @brief Opaque handle to a VIDDEC1 codec.
96 */
97 typedef VISA_Handle VIDDEC1_Handle;
99 /**
100 * @brief This structure defines the parameters necessary to create an
101 * instance of a Video Decoder object.
102 */
103 typedef struct IVIDDEC1_Params VIDDEC1_Params;
105 /**
106 * @copydoc IVIDDEC1_InArgs
107 */
108 typedef IVIDDEC1_InArgs VIDDEC1_InArgs;
110 /**
111 * @copydoc IVIDDEC1_OutArgs
112 */
113 typedef IVIDDEC1_OutArgs VIDDEC1_OutArgs;
115 /**
116 * @copydoc IVIDDEC1_Cmd
117 */
118 typedef IVIDDEC1_Cmd VIDDEC1_Cmd;
120 /**
121 * @copydoc IVIDDEC1_DynamicParams
122 */
123 typedef IVIDDEC1_DynamicParams VIDDEC1_DynamicParams;
125 /** @cond INTERNAL */
127 /**
128 * @brief An implementation of the skel interface; the skeleton side
129 * of the stubs.
130 */
131 extern SKEL_Fxns VIDDEC1_SKEL;
133 /**
134 * @brief Implementation of the IVIDDEC1 interface that is run remotely.
135 */
136 extern IVIDDEC1_Fxns VIDDEC1_STUBS;
138 /** @endcond */
140 /**
141 * @brief Definition of IVIDDEC1 codec class configurable parameters
142 *
143 * @sa VISA_getCodecClassConfig()
144 */
145 typedef struct IVIDDEC1_CodecClassConfig {
146 Bool manageInBufsCache [ XDM_MAX_IO_BUFFERS ];
147 Bool manageOutBufsCache [ XDM_MAX_IO_BUFFERS ];
148 } IVIDDEC1_CodecClassConfig;
150 /*
151 * ======== VIDDEC1_create ========
152 */
153 /**
154 * @brief Create an instance of a video decoder algorithm.
155 *
156 * Instance handles must not be concurrently accessed by multiple threads;
157 * each thread must either obtain its own handle (via VIDDEC1_create) or
158 * explicitly serialize access to a shared handle.
159 *
160 * @param[in] e Handle to an opened engine.
161 * @param[in] name String identifier of the type of video decoder
162 * to create.
163 * @param[in] params Creation parameters.
164 *
165 * @retval NULL An error has occurred.
166 * @retval non-NULL The handle to the newly created video decoder
167 * instance.
168 *
169 * @remarks @c params is optional. If it's not supplied, codec-specific
170 * default params will be used.
171 *
172 * @remark Depending on the configuration of the engine opened, this
173 * call may create a local or remote instance of the video
174 * decoder.
175 *
176 * @codecNameRemark
177 *
178 * @sa Engine_open()
179 * @sa VIDDEC1_delete()
180 */
181 extern VIDDEC1_Handle VIDDEC1_create(Engine_Handle e, String name,
182 VIDDEC1_Params *params);
185 /*
186 * ======== VIDDEC1_process ========
187 */
188 /**
189 * @brief Execute the process() method in this instance of a video
190 * decoder algorithm.
191 *
192 * @param[in] handle Handle to a created video decoder instance.
193 * @param[in] inBufs A buffer descriptor containing input buffers.
194 * @param[out] outBufs A buffer descriptor containing output buffers.
195 * @param[in] inArgs Input Arguments.
196 * @param[out] outArgs Output Arguments.
197 *
198 * @pre @c handle is a valid (non-NULL) video decoder handle
199 * and the video decoder is in the created state.
200 *
201 * @retval #VIDDEC1_EOK Success.
202 * @retval #VIDDEC1_EFAIL Failure.
203 * @retval #VIDDEC1_EUNSUPPORTED Unsupported request.
204 *
205 * @remark Since the VIDDEC1 decoder contains support for asynchronous
206 * buffer submission and retrieval, this API becomes known as
207 * synchronous in nature.
208 *
209 * @remark This is a blocking call, and will return after the data
210 * has been decoded.
211 *
212 * @remark The buffers supplied to VIDDEC1_process() may have constraints
213 * put on them. For example, in dual-processor, shared memory
214 * architectures, where the codec is running on a remote
215 * processor, the buffers may need to be physically contiguous.
216 * Additionally, the remote processor may place restrictions on
217 * buffer alignment.
218 *
219 * @sa VIDDEC1_create()
220 * @sa VIDDEC1_delete()
221 * @sa VIDDEC1_control()
222 * @sa VIDDEC1_processAsync()
223 * @sa VIDDEC1_processWait()
224 * @sa IVIDDEC1_Fxns::process() - the reflected algorithm interface,
225 * which may contain further usage
226 * details.
227 */
228 extern Int32 VIDDEC1_process(VIDDEC1_Handle handle, XDM1_BufDesc *inBufs,
229 XDM_BufDesc *outBufs, VIDDEC1_InArgs *inArgs, VIDDEC1_OutArgs *outArgs);
232 /*
233 * ======== VIDDEC1_control ========
234 */
235 /**
236 * @brief Execute the control() method in this instance of a video
237 * decoder algorithm.
238 *
239 * @param[in] handle Handle to a created video decoder instance.
240 * @param[in] id Command id for XDM control operation.
241 * @param[in] params Runtime control parameters used for decoding.
242 * @param[out] status Status info upon completion of decode operation.
243 *
244 * @pre @c handle is a valid (non-NULL) video decoder handle
245 * and the video decoder is in the created state.
246 *
247 * @retval #VIDDEC1_EOK Success.
248 * @retval #VIDDEC1_EFAIL Failure.
249 * @retval #VIDDEC1_EUNSUPPORTED Unsupported request.
250 *
251 * @remark This is a blocking call, and will return after the control
252 * command has been executed.
253 *
254 * @remark If an error is returned, @c status->extendedError may
255 * indicate further details about the error. See
256 * #VIDDEC1_Status::extendedError for details.
257 *
258 * @sa VIDDEC1_create()
259 * @sa VIDDEC1_delete()
260 * @sa IVIDDEC1_Fxns::process()
261 */
262 extern Int32 VIDDEC1_control(VIDDEC1_Handle handle, VIDDEC1_Cmd id,
263 VIDDEC1_DynamicParams *params, VIDDEC1_Status *status);
266 /*
267 * ======== VIDDEC1_delete ========
268 */
269 /**
270 * @brief Delete the instance of a video decoder algorithm.
271 *
272 * @param[in] handle Handle to a created video decoder instance.
273 *
274 * @remark Depending on the configuration of the engine opened, this
275 * call may delete a local or remote instance of the video
276 * decoder.
277 *
278 * @pre @c handle is a valid (non-NULL) handle which is
279 * in the created state.
280 *
281 * @post All resources allocated as part of the VIDDEC1_create()
282 * operation (memory, DMA channels, etc.) are freed.
283 *
284 * @sa VIDDEC1_create()
285 */
286 extern Void VIDDEC1_delete(VIDDEC1_Handle handle);
289 /*
290 * ======== VIDDEC1_processAsync ========
291 */
292 /**
293 * @brief Perform asynchronous submission to this instance of a video
294 * decoder algorithm.
295 *
296 * @param[in] handle Handle to a created video decoder instance.
297 * @param[in] inBufs A buffer descriptor containing input buffers.
298 * @param[out] outBufs A buffer descriptor containing output buffers.
299 * @param[in] inArgs Input Arguments.
300 * @param[out] outArgs Output Arguments.
301 *
302 * @pre @c handle is a valid (non-NULL) video decoder handle
303 * and the video decoder is in the created state.
304 *
305 * @retval #VIDDEC1_EOK Success.
306 * @retval #VIDDEC1_EFAIL Failure.
307 * @retval #VIDDEC1_EUNSUPPORTED Unsupported request.
308 *
309 * @remark This API is the asynchronous counterpart to the process()
310 * method. It allows for buffer and argument submission without
311 * waiting for retrieval. A response is retrieved using the
312 * VIDDEC1_processWait() API.
313 *
314 * @remark The buffers supplied to VIDDEC1_processAsync() may have
315 * constraints put on them. For example, in dual-processor,
316 * shared memory architectures, where the codec is running on a
317 * remote processor, the buffers may need to be physically
318 * contiguous. Additionally, the remote processor may place
319 * restrictions on buffer alignment.
320 *
321 * @sa VIDDEC1_create()
322 * @sa VIDDEC1_delete()
323 * @sa VIDDEC1_control()
324 * @sa VIDDEC1_process()
325 * @sa VIDDEC1_processWait()
326 * @sa IVIDDEC1_Fxns::process()
327 */
328 extern XDAS_Int32 VIDDEC1_processAsync(VIDDEC1_Handle handle,
329 XDM1_BufDesc *inBufs, XDM_BufDesc *outBufs,
330 VIDDEC1_InArgs *inArgs, VIDDEC1_OutArgs *outArgs);
333 /*
334 * ======== VIDDEC1_processWait ========
335 */
336 /**
337 * @brief Wait for a return message from a previous invocation of
338 * VIDDEC1_processAsync() in this instance of an video decoder
339 * algorithm.
340 *
341 * @param[in] handle Handle to a created video decoder instance.
342 * @param[in] inBufs A buffer descriptor containing input buffers.
343 * @param[out] outBufs A buffer descriptor containing output buffers.
344 * @param[in] inArgs Input Arguments.
345 * @param[out] outArgs Output Arguments.
346 * @param[in] timeout Amount of "time" to wait (from 0 -> #VIDDEC1_FOREVER)
347 *
348 * @pre @c handle is a valid (non-NULL) video decoder handle
349 * and the video decoder is in the created state.
350 *
351 * @retval #VIDDEC1_EOK Success.
352 * @retval #VIDDEC1_EFAIL Failure.
353 * @retval #VIDDEC1_EUNSUPPORTED Unsupported request.
354 * @retval #VIDDEC1_ETIMEOUT Operation timed out.
355 *
356 * @remark This is a blocking call, and will return after the data
357 * has been decoded.
358 *
359 * @remark "Polling" is supported by using a timeout of 0. Waiting
360 * forever is supported by using a timeout of #VIDDEC1_FOREVER.
361 *
362 * @remark There must have previously been an invocation of the
363 * VIDDEC1_processAsync() API.
364 *
365 * @remark The buffers supplied to VIDDEC1_processAsync() may have
366 * constraints put on them. For example, in dual-processor,
367 * shared memory architectures, where the codec is running on a
368 * remote processor, the buffers may need to be physically
369 * contiguous. Additionally, the remote processor may place
370 * restrictions on buffer alignment.
371 *
372 * @sa VIDDEC1_create()
373 * @sa VIDDEC1_delete()
374 * @sa VIDDEC1_control()
375 * @sa VIDDEC1_process()
376 * @sa VIDDEC1_processAsync()
377 */
378 extern XDAS_Int32 VIDDEC1_processWait(VIDDEC1_Handle handle,
379 XDM1_BufDesc *inBufs, XDM_BufDesc *outBufs,
380 VIDDEC1_InArgs *inArgs, VIDDEC1_OutArgs *outArgs, UInt timeout);
383 /*@}*/
385 #ifdef __cplusplus
386 }
387 #endif
389 #endif