VIDENC - Video Encoder Interface

Data Structures
struct	IVIDENC_CodecClassConfig
	Definition of IVIDENC codec class configurable parameters. More...
Defines
#define	VIDENC_EOK   IVIDENC_EOK
#define	VIDENC_EFAIL   IVIDENC_EFAIL
#define	VIDENC_ERUNTIME   IVIDENC_ERUNTIME
#define	VIDENC_ETIMEOUT   VISA_ETIMEOUT
#define	VIDENC_FOREVER   VISA_FOREVER
#define	VIDENC_VISATYPE   "ti.sdo.ce.video.IVIDENC"
	The VISA type.
Typedefs
typedef IVIDENC_Status	VIDENC_Status
typedef VISA_Handle	VIDENC_Handle
	Opaque handle to a VIDENC codec.
typedef struct IVIDENC_Params	VIDENC_Params
	This structure defines the parameters necessary to create an instance of a video encoder object.
typedef IVIDENC_InArgs	VIDENC_InArgs
typedef IVIDENC_OutArgs	VIDENC_OutArgs
typedef IVIDENC_Cmd	VIDENC_Cmd
typedef IVIDENC_DynamicParams	VIDENC_DynamicParams
typedef struct IVIDENC_CodecClassConfig	IVIDENC_CodecClassConfig
	Definition of IVIDENC codec class configurable parameters.
Functions
VIDENC_Handle	VIDENC_create (Engine_Handle e, String name, VIDENC_Params *params)
	Create an instance of a video encoder algorithm.
Int32	VIDENC_process (VIDENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, VIDENC_InArgs *inArgs, VIDENC_OutArgs *outArgs)
	Execute the process() method in this instance of a video encoder algorithm.
Int32	VIDENC_control (VIDENC_Handle handle, VIDENC_Cmd id, VIDENC_DynamicParams *params, VIDENC_Status *status)
	Execute the control() method in this instance of a video encoder algorithm.
Void	VIDENC_delete (VIDENC_Handle handle)
	Delete the instance of a video encoder algorithm.
XDAS_Int32	VIDENC_processAsync (VIDENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, IVIDENC_InArgs *inArgs, IVIDENC_OutArgs *outArgs)
	Perform asynchronous submission to this instance of a video decoder algorithm.
XDAS_Int32	VIDENC_processWait (VIDENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, IVIDENC_InArgs *inArgs, IVIDENC_OutArgs *outArgs, UInt timeout)
	Wait for a return message from a previous invocation of VIDENC_processAsync() in this instance of an video decoder algorithm.

---

Detailed Description

This is the VIDENC video encoder codec interface. Several of the data types in this API are specified by the XDM interface; please see the XDM documentation for those details.

---

Define Documentation

#define VIDENC_EOK   IVIDENC_EOK

Success.

#define VIDENC_EFAIL   IVIDENC_EFAIL

General failure.

#define VIDENC_ERUNTIME   IVIDENC_ERUNTIME

General runtime failure.

#define VIDENC_ETIMEOUT   VISA_ETIMEOUT

Timeout occurred.

#define VIDENC_FOREVER   VISA_FOREVER

Special value for timeout parameter indicating never timeout.

#define VIDENC_VISATYPE   "ti.sdo.ce.video.IVIDENC"

The VISA type.

---

Typedef Documentation

typedef IVIDENC_Status VIDENC_Status

Defines instance status parameters (read-only).

Remarks:

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

IVIDENC_Fxns::control()

typedef VISA_Handle VIDENC_Handle

Opaque handle to a VIDENC codec.

typedef struct IVIDENC_Params VIDENC_Params

This structure defines the parameters necessary to create an instance of a video encoder object.

typedef IVIDENC_InArgs VIDENC_InArgs

Defines the input arguments for all IVIDENC instance process function.

Remarks:

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

IVIDENC_Fxns::process()

typedef IVIDENC_OutArgs VIDENC_OutArgs

Defines the run time output arguments for all IVIDENC instance objects.

Remarks:

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

IVIDENC_Fxns::process()

typedef IVIDENC_Cmd VIDENC_Cmd

Defines the control commands for the IVIDENC module.

Remarks:

This ID can be extended in IMOD interface for additional controls.

See also:

XDM_CmdId

IVIDENC_Fxns::control()

typedef IVIDENC_DynamicParams VIDENC_DynamicParams

This structure defines the codec parameters that can be modified after creation via control() calls.

Remarks:

It is not necessary that given implementation support all dynamic parameters to be configurable at run time. If a particular algorithm does not support run-time updates to a parameter that the application is attempting to change at runtime, it may indicate this as an error.

This structure may be extended by individual codec implementations allowing customization with vendor specific parameters. The presence of vendor specific extensions will be detected by the value of the size parameter.

The size field must be correctly set by the caller. See http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:

IVIDENC_Fxns::control()

typedef struct IVIDENC_CodecClassConfig IVIDENC_CodecClassConfig

Definition of IVIDENC codec class configurable parameters.

See also:

VISA_getCodecClassConfig()

---

Function Documentation

VIDENC_Handle VIDENC_create	(	Engine_Handle	e,
		String	name,
		VIDENC_Params *	params
	)

Create an instance of a video encoder algorithm.

Instance handles must not be concurrently accessed by multiple threads; each thread must either obtain its own handle (via VIDENC_create()) or explicitly serialize access to a shared handle.

Parameters:

[in]	e	Handle to an opened engine.
[in]	name	String identifier of the type of video encoder to create.
[in]	params	Creation parameters.

Return values:

NULL	An error has occurred.
non-NULL	The handle to the newly created video encoder instance.

Remarks:

params is optional. If it's not supplied, codec-specific default params will be used.

Depending on the configuration of the engine opened, this call may create a local or remote instance of the video encoder.

In general, name is the name of the codec configured by the system integrator. However, an optional "argument string" may be appended to the codec name, to allow the codec's configured priority and/or the heaps where its memory will be allocated, to be overridden. This optional argument string is of the form ":priority", ":priority:flag", or "::flag".

priority is the new priority to create the codec with.

The flag must be either 0 or 1, and if 1, all memory allocated for the codec will be in the heap that corresponds to IALG_EXTERNAL. If flag is 0, the memory for the codec will be allocated from the heaps it has requested. For example, if a codec named "mp3" has been configured into the system, setting name to "mp3:4" would cause the codec to be created at priority 4, instead of whatever priority was configured. This feature is useful if more than one instance of the codec are to be created at different priorities.

The flag can be used to prevent the codec from using any internal memory, for example, if it is to be run at the same time as another codec that must use internal memory, and there is insufficient internal memory for both.

See also:

Engine_open()

VIDENC_delete()

Int32 VIDENC_process	(	VIDENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		VIDENC_InArgs *	inArgs,
		VIDENC_OutArgs *	outArgs
	)

Execute the process() method in this instance of a video encoder algorithm.

Parameters:

[in]	handle	Handle to a created video encoder instance.
[in]	inBufs	A buffer descriptor containing input buffers.
[out]	outBufs	A buffer descriptor containing output buffers.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) video encoder handle and the video encoder is in the created state.

Return values:

VIDENC_EOK	Success.
VIDENC_EFAIL	Failure.
VIDENC_ERUNTIME	Internal Runtime Error.

Remarks:

Since the VIDENC decoder contains support for asynchronous buffer submission and retrieval, this API becomes known as synchronous in nature.

This is a blocking call, and will return after the data has been encoded.

The buffers supplied to VIDENC_process() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

If an error is returned, outArgs->extendedError may indicate further details about the error. See VIDENC_OutArgs::extendedError for details.

See also:

VIDENC_create()

VIDENC_delete()

VIDENC_control()

VIDENC_processAsync()

VIDENC_processWait()

IVIDENC_Fxns::process() - the reflected algorithm interface, which may contain further usage details.

Int32 VIDENC_control	(	VIDENC_Handle	handle,
		VIDENC_Cmd	id,
		VIDENC_DynamicParams *	params,
		VIDENC_Status *	status
	)

Execute the control() method in this instance of a video encoder algorithm.

Parameters:

[in]	handle	Handle to a created video encoder instance.
[in]	id	Command id for XDM control operation.
[in]	params	Runtime control parameters used for encoding.
[out]	status	Status info upon completion of encode operation.

Precondition:

handle is a valid (non-NULL) video encoder handle and the video encoder is in the created state.

Return values:

VIDENC_EOK	Success.
VIDENC_EFAIL	Failure.
VIDENC_ERUNTIME	Internal Runtime Error.

Remarks:

This is a blocking call, and will return after the control command has been executed.

If an error is returned, status->extendedError may indicate further details about the error. See VIDENC_Status::extendedError for details.

See also:

VIDENC_create()

VIDENC_delete()

IVIDENC_Fxns::control() - the reflected algorithm interface, which may contain further usage details.

Void VIDENC_delete

(

VIDENC_Handle

handle )

Delete the instance of a video encoder algorithm.

Parameters:

[in]

handle

Handle to a created video encoder instance.

Remarks:

Depending on the configuration of the engine opened, this call may delete a local or remote instance of the video encoder.

Precondition:

handle is a valid (non-NULL) handle which is in the created state.

Postcondition:

All resources allocated as part of the VIDENC_create() operation (memory, DMA channels, etc.) are freed.

See also:

VIDENC_create()

XDAS_Int32 VIDENC_processAsync	(	VIDENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		IVIDENC_InArgs *	inArgs,
		IVIDENC_OutArgs *	outArgs
	)

Perform asynchronous submission to this instance of a video decoder algorithm.

Parameters:

[in]	handle	Handle to a created video decoder instance.
[in]	inBufs	A buffer descriptor containing input buffers.
[out]	outBufs	A buffer descriptor containing output buffers.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) video decoder handle and the video decoder is in the created state.

Return values:

VIDENC_EOK	Success.
VIDENC_EFAIL	Failure.
VIDENC_ERUNTIME	Internal Runtime Error.

Remarks:

This API is the asynchronous counterpart to the process() method. It allows for buffer and argument submission without waiting for retrieval. A response is retrieved using the VIDENC_processWait() API.

The buffers supplied to VIDENC_processAsync() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

See also:

VIDENC_create()

VIDENC_delete()

VIDENC_control()

VIDENC_process()

VIDENC_processWait()

IVIDENC_Fxns::process() - the reflected algorithm interface, which may contain further usage details.

XDAS_Int32 VIDENC_processWait	(	VIDENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		IVIDENC_InArgs *	inArgs,
		IVIDENC_OutArgs *	outArgs,
		UInt	timeout
	)

Wait for a return message from a previous invocation of VIDENC_processAsync() in this instance of an video decoder algorithm.

Parameters:

[in]	handle	Handle to a created video decoder instance.
[in]	inBufs	A buffer descriptor containing input buffers.
[out]	outBufs	A buffer descriptor containing output buffers.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.
[in]	timeout	Amount of "time" to wait (from 0 -> VIDENC_FOREVER)

Precondition:

handle is a valid (non-NULL) video decoder handle and the video decoder is in the created state.

Return values:

VIDENC_EOK	Success.
VIDENC_EFAIL	Failure.
VIDENC_ERUNTIME	Internal Runtime Error.
VIDENC_ETIMEOUT	Operation timed out.

Remarks:

This is a blocking call, and will return after the data has been decoded.

"Polling" is supported by using a timeout of 0. Waiting forever is supported by using a timeout of VIDENC_EFOREVER.

There must have previously been an invocation of the VIDENC_processAsync() API.

The buffers supplied to VIDENC_processAsync() may have constraints put on them. For example, in dual-processor, shared memory architectures, where the codec is running on a remote processor, the buffers may need to be physically contiguous. Additionally, the remote processor may place restrictions on buffer alignment.

See also:

VIDENC_create()

VIDENC_delete()

VIDENC_control()

VIDENC_process()

VIDENC_processAsync()