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 * ======== videnc1.h ========
35 */
36 /**
37 * @file ti/sdo/ce/video1/videnc1.h
38 *
39 * @brief The VIDENC1 video encoder interface. Provides the user an
40 * interface to create and interact with XDAIS algorithms that are
41 * compliant with the XDM-defined IVIDENC1 video encoder
42 * interface.
43 */
44 /**
45 * @defgroup ti_sdo_ce_video1_VIDENC1 VIDENC1 - Video Encoder Interface
46 *
47 * This is the VIDENC1 video encoder interface. Several of the data
48 * types in this API are specified by the XDM IVIDENC1 interface; please see
49 * the XDM documentation for those details.
50 */
52 #ifndef ti_sdo_ce_video1_VIDENC1_
53 #define ti_sdo_ce_video1_VIDENC1_
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
59 #include <ti/xdais/dm/xdm.h>
60 #include <ti/xdais/dm/ividenc1.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_VIDENC1 */
67 /*@{*/
69 #define VIDENC1_EOK IVIDENC1_EOK /**< @copydoc IVIDENC1_EOK */
70 #define VIDENC1_EFAIL IVIDENC1_EFAIL /**< @copydoc IVIDENC1_EFAIL */
72 /**< @copydoc IVIDENC1_EUNSUPPORTED */
73 #define VIDENC1_EUNSUPPORTED IVIDENC1_EUNSUPPORTED
75 #define VIDENC1_ETIMEOUT VISA_ETIMEOUT /**< @copydoc VISA_ETIMEOUT */
76 #define VIDENC1_FOREVER VISA_FOREVER /**< @copydoc VISA_FOREVER */
78 /**
79 * @brief The VISA type
80 */
81 #define VIDENC1_VISATYPE "ti.sdo.ce.video1.IVIDENC1"
83 /**
84 * @brief Name of stub functions. Use this name when registering the
85 * VIDENC1_STUBS functions with Engine_addStubFxns.
86 *
87 * @sa Engine_addStubFxns
88 */
89 #define VIDENC1_STUBSNAME "VIDENC1_STUBS"
92 /**
93 * @brief Opaque handle to a VIDENC1 codec.
94 */
95 typedef VISA_Handle VIDENC1_Handle;
97 /* The following are just wrapper typedefs */
99 /** @copydoc IVIDENC1_Params */
100 typedef struct IVIDENC1_Params VIDENC1_Params;
102 /** @copydoc IVIDENC1_InArgs */
103 typedef IVIDENC1_InArgs VIDENC1_InArgs;
105 /** @copydoc IVIDENC1_OutArgs */
106 typedef IVIDENC1_OutArgs VIDENC1_OutArgs;
108 /** @copydoc IVIDENC1_Cmd */
109 typedef IVIDENC1_Cmd VIDENC1_Cmd;
111 /** @copydoc IVIDENC1_DynamicParams */
112 typedef IVIDENC1_DynamicParams VIDENC1_DynamicParams;
114 /** @copydoc IVIDENC1_Status */
115 typedef IVIDENC1_Status VIDENC1_Status;
117 /** @cond INTERNAL */
119 /**
120 * @brief An implementation of the skel interface; the skeleton side
121 * of the stubs.
122 */
123 extern SKEL_Fxns VIDENC1_SKEL;
125 /**
126 * @brief Implementation of the IVIDENC1 interface that is run remotely.
127 */
128 extern IVIDENC1_Fxns VIDENC1_STUBS;
130 /** @endcond */
132 /**
133 * @brief Definition of IVIDENC1 codec class configurable parameters
134 *
135 * @sa VISA_getCodecClassConfig()
136 */
137 typedef struct IVIDENC1_CodecClassConfig {
138 Bool manageInBufsCache [ XDM_MAX_IO_BUFFERS ];
139 Bool manageOutBufsCache [ XDM_MAX_IO_BUFFERS ];
140 } IVIDENC1_CodecClassConfig;
142 /*
143 * ======== VIDENC1_control ========
144 */
145 /**
146 * @brief Execute the control() method in this instance of a video
147 * encoder algorithm.
148 *
149 * @param[in] handle Handle to a created video encoder instance.
150 * @param[in] id Command id for XDM control operation.
151 * @param[in] params Runtime control parameters used for encoding.
152 * @param[out] status Status info upon completion of encode operation.
153 *
154 * @pre @c handle is a valid (non-NULL) video encoder handle
155 * and the video encoder is in the created state.
156 *
157 * @retval #VIDENC1_EOK Success.
158 * @retval #VIDENC1_EFAIL Failure.
159 * @retval #VIDENC1_EUNSUPPORTED The requested operation
160 * is not supported.
161 *
162 * @remark This is a blocking call, and will return after the control
163 * command has been executed.
164 *
165 * @remark If an error is returned, @c status->extendedError may
166 * indicate further details about the error. See
167 * #VIDENC1_Status::extendedError for details.
168 *
169 * @sa VIDENC1_create()
170 * @sa VIDENC1_delete()
171 * @sa IVIDENC1_Fxns::control() - the reflected algorithm interface,
172 * which may contain further usage
173 * details.
174 */
175 extern Int32 VIDENC1_control(VIDENC1_Handle handle, VIDENC1_Cmd id,
176 VIDENC1_DynamicParams *params, VIDENC1_Status *status);
179 /*
180 * ======== VIDENC1_create ========
181 */
182 /**
183 * @brief Create an instance of a video encoder algorithm.
184 *
185 * Instance handles must not be concurrently accessed by multiple threads;
186 * each thread must either obtain its own handle (via VIDENC1_create()) or
187 * explicitly serialize access to a shared handle.
188 *
189 * @param[in] e Handle to an opened engine.
190 * @param[in] name String identifier of the type of video encoder
191 * to create.
192 * @param[in] params Creation parameters.
193 *
194 * @retval NULL An error has occurred.
195 * @retval non-NULL The handle to the newly created video encoder
196 * instance.
197 *
198 * @remarks @c params is optional. If it's not supplied, codec-specific
199 * default params will be used.
200 *
201 * @remark Depending on the configuration of the engine opened, this
202 * call may create a local or remote instance of the video
203 * encoder.
204 *
205 * @codecNameRemark
206 *
207 * @sa Engine_open()
208 * @sa VIDENC1_delete()
209 */
210 extern VIDENC1_Handle VIDENC1_create(Engine_Handle e, String name,
211 VIDENC1_Params *params);
214 /*
215 * ======== VIDENC1_delete ========
216 */
217 /**
218 * @brief Delete the instance of a video encoder algorithm.
219 *
220 * @param[in] handle Handle to a created video encoder instance.
221 *
222 * @remark Depending on the configuration of the engine opened, this
223 * call may delete a local or remote instance of the video
224 * encoder.
225 *
226 * @pre @c handle is a valid (non-NULL) handle which is
227 * in the created state.
228 *
229 * @post All resources allocated as part of the VIDENC1_create()
230 * operation (memory, DMA channels, etc.) are freed.
231 *
232 * @sa VIDENC1_create()
233 */
234 extern Void VIDENC1_delete(VIDENC1_Handle handle);
237 /*
238 * ======== VIDENC1_process ========
239 */
240 /**
241 * @brief Execute the process() method in this instance of a video
242 * encoder algorithm.
243 *
244 * @param[in] handle Handle to a created video encoder instance.
245 * @param[in] inBufs A buffer descriptor containing input buffers.
246 * @param[out] outBufs A buffer descriptor containing output buffers.
247 * @param[in] inArgs Input Arguments.
248 * @param[out] outArgs Output Arguments.
249 *
250 * @pre @c handle is a valid (non-NULL) video encoder handle
251 * and the video encoder is in the created state.
252 *
253 * @retval #VIDENC1_EOK Success.
254 * @retval #VIDENC1_EFAIL Failure.
255 * @retval #VIDENC1_EUNSUPPORTED The requested operation
256 * is not supported.
257 *
258 * @remark Since the VIDENC1 decoder contains support for asynchronous
259 * buffer submission and retrieval, this API becomes known as
260 * synchronous in nature.
261 *
262 * @remark This is a blocking call, and will return after the data
263 * has been encoded.
264 *
265 * @remark The buffers supplied to VIDENC1_process() may have constraints
266 * put on them. For example, in dual-processor, shared memory
267 * architectures, where the codec is running on a remote
268 * processor, the buffers may need to be physically contiguous.
269 * Additionally, the remote processor may place restrictions on
270 * buffer alignment.
271 *
272 * @remark If an error is returned, @c outArgs->extendedError may
273 * indicate further details about the error. See
274 * #VIDENC1_OutArgs::extendedError for details.
275 *
276 * @sa VIDENC1_create()
277 * @sa VIDENC1_delete()
278 * @sa VIDENC1_control()
279 * @sa VIDENC1_processAsync()
280 * @sa VIDENC1_processWait()
281 * @sa IVIDENC1_Fxns::process() - the reflected algorithm interface,
282 * which may contain further usage
283 * details.
284 */
285 extern Int32 VIDENC1_process(VIDENC1_Handle handle, IVIDEO1_BufDescIn *inBufs,
286 XDM_BufDesc *outBufs, VIDENC1_InArgs *inArgs, VIDENC1_OutArgs *outArgs);
289 /*
290 * ======== VIDENC1_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 #VIDENC1_EOK Success.
306 * @retval #VIDENC1_EFAIL Failure.
307 * @retval #VIDENC1_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 * VIDENC1_processWait() API.
313 *
314 * @remark The buffers supplied to VIDENC1_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 VIDENC1_create()
322 * @sa VIDENC1_delete()
323 * @sa VIDENC1_control()
324 * @sa VIDENC1_process()
325 * @sa VIDENC1_processWait()
326 * @sa IVIDENC1_Fxns::process() - the reflected algorithm interface,
327 * which may contain further usage
328 * details.
329 */
330 extern XDAS_Int32 VIDENC1_processAsync(VIDENC1_Handle handle,
331 IVIDEO1_BufDescIn *inBufs, XDM_BufDesc *outBufs,
332 IVIDENC1_InArgs *inArgs, IVIDENC1_OutArgs *outArgs);
335 /*
336 * ======== VIDENC1_processWait ========
337 */
338 /**
339 * @brief Wait for a return message from a previous invocation of
340 * VIDENC1_processAsync() in this instance of an video decoder
341 * algorithm.
342 *
343 * @param[in] handle Handle to a created video decoder instance.
344 * @param[in] inBufs A buffer descriptor containing input buffers.
345 * @param[out] outBufs A buffer descriptor containing output buffers.
346 * @param[in] inArgs Input Arguments.
347 * @param[out] outArgs Output Arguments.
348 * @param[in] timeout Amount of "time" to wait (from 0 -> #VIDENC1_FOREVER)
349 *
350 * @pre @c handle is a valid (non-NULL) video decoder handle
351 * and the video decoder is in the created state.
352 *
353 * @retval #VIDENC1_EOK Success.
354 * @retval #VIDENC1_EFAIL Failure.
355 * @retval #VIDENC1_EUNSUPPORTED Unsupported request.
356 * @retval #VIDENC1_ETIMEOUT Operation timed out.
357 *
358 * @remark This is a blocking call, and will return after the data
359 * has been decoded.
360 *
361 * @remark "Polling" is supported by using a timeout of 0. Waiting
362 * forever is supported by using a timeout of #VIDENC1_FOREVER.
363 *
364 * @remark There must have previously been an invocation of the
365 * VIDENC1_processAsync() API.
366 *
367 * @remark The buffers supplied to VIDENC1_processAsync() may have
368 * constraints put on them. For example, in dual-processor,
369 * shared memory architectures, where the codec is running on a
370 * remote processor, the buffers may need to be physically
371 * contiguous. Additionally, the remote processor may place
372 * restrictions on buffer alignment.
373 *
374 * @sa VIDENC1_create()
375 * @sa VIDENC1_delete()
376 * @sa VIDENC1_control()
377 * @sa VIDENC1_process()
378 * @sa VIDENC1_processAsync()
379 */
380 extern XDAS_Int32 VIDENC1_processWait(VIDENC1_Handle handle,
381 IVIDEO1_BufDescIn *inBufs, XDM_BufDesc *outBufs,
382 IVIDENC1_InArgs *inArgs, IVIDENC1_OutArgs *outArgs, UInt timeout);
385 /*@}*/
387 #ifdef __cplusplus
388 }
389 #endif
391 #endif