Video decoder codec interface

Detailed Description

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

Data Structures

struct IVIDDEC2_CodecClassConfig

Definition of IVIDDEC2 codec class configurable parameters. More...

Defines

#define VIDDEC2_EOK   IVIDDEC2_EOK

#define VIDDEC2_EFAIL   IVIDDEC2_EFAIL

#define VIDDEC2_EUNSUPPORTED   IVIDDEC2_EUNSUPPORTED

#define VIDDEC2_ETIMEOUT   VISA_ETIMEOUT

#define VIDDEC2_FOREVER   VISA_FOREVER

Typedefs

typedef VISA_Handle VIDDEC2_Handle

Opaque handle to a VIDDEC2 codec.

typedef IVIDDEC2_Params VIDDEC2_Params

typedef IVIDDEC2_InArgs VIDDEC2_InArgs

typedef IVIDDEC2_OutArgs VIDDEC2_OutArgs

typedef IVIDDEC2_Cmd VIDDEC2_Cmd

typedef IVIDDEC2_DynamicParams VIDDEC2_DynamicParams

typedef IVIDDEC2_Status VIDDEC2_Status

Functions

Int32 VIDDEC2_control (VIDDEC2_Handle handle, VIDDEC2_Cmd id, VIDDEC2_DynamicParams *params, VIDDEC2_Status *status)

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

VIDDEC2_Handle VIDDEC2_create (Engine_Handle e, String name, VIDDEC2_Params *params)

Create an instance of a video decoder algorithm.

Void VIDDEC2_delete (VIDDEC2_Handle handle)

Delete the instance of a video decoder algorithm.

Int32 VIDDEC2_process (VIDDEC2_Handle handle, XDM1_BufDesc *inBufs, XDM_BufDesc *outBufs, VIDDEC2_InArgs *inArgs, VIDDEC2_OutArgs *outArgs)

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

XDAS_Int32 VIDDEC2_processAsync (VIDDEC2_Handle handle, XDM1_BufDesc *inBufs, XDM_BufDesc *outBufs, VIDDEC2_InArgs *inArgs, VIDDEC2_OutArgs *outArgs)

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

XDAS_Int32 VIDDEC2_processWait (VIDDEC2_Handle handle, XDM1_BufDesc *inBufs, XDM_BufDesc *outBufs, VIDDEC2_InArgs *inArgs, VIDDEC2_OutArgs *outArgs, UInt timeout)

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

Define Documentation

#define VIDDEC2_EOK IVIDDEC2_EOK

Success.

#define VIDDEC2_EFAIL IVIDDEC2_EFAIL

General failure.

#define VIDDEC2_EUNSUPPORTED IVIDDEC2_EUNSUPPORTED

Request is unsupported.

#define VIDDEC2_ETIMEOUT VISA_ETIMEOUT

Timeout occurred.

#define VIDDEC2_FOREVER VISA_FOREVER

Special value for timeout parameter indicating never timeout.

Typedef Documentation

typedef VISA_Handle VIDDEC2_Handle

Opaque handle to a VIDDEC2 codec.

typedef IVIDDEC2_Params VIDDEC2_Params

Defines the creation time parameters for all IVIDDEC2 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.

typedef IVIDDEC2_InArgs VIDDEC2_InArgs

Defines the input arguments for all IVIDDEC2 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:: IVIDDEC2_Fxns::process()

typedef IVIDDEC2_OutArgs VIDDEC2_OutArgs

Defines the run time output arguments for all IVIDDEC2 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:: IVIDDEC2_Fxns::process()

typedef IVIDDEC2_Cmd VIDDEC2_Cmd

Defines the control commands for the IVIDDEC2 module.

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

See also:: XDM_CmdId
IVIDDEC2_Fxns::control()

typedef IVIDDEC2_DynamicParams VIDDEC2_DynamicParams

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

Remarks:

It is not necessary that a 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:: IVIDDEC2_Fxns::control()

typedef IVIDDEC2_Status VIDDEC2_Status

Defines instance status parameters.

Remarks:

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.

All fields correspond to latest IVIDDEC2_Fxns::process() call on the particular instance of the decoder.

See also:: IVIDDEC2_Fxns::control()

Function Documentation

Int32 VIDDEC2_control	(	VIDDEC2_Handle	handle,
		VIDDEC2_Cmd	id,
		VIDDEC2_DynamicParams *	params,
		VIDDEC2_Status *	status
	)

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

Parameters:

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

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

Return values:

	VIDDEC2_EOK	Success.
	VIDDEC2_EFAIL	Failure.
	VIDDEC2_EUNSUPPORTED	Unsupported request.

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

See also:

VIDDEC2_create()

VIDDEC2_delete()

IVIDDEC2_Fxns::process()

VIDDEC2_Handle VIDDEC2_create	(	Engine_Handle	e,
		String	name,
		VIDDEC2_Params *	params
	)

Create an instance of a video decoder algorithm.

Instance handles must not be concurrently accessed by multiple threads; each thread must either obtain its own handle (via VIDDEC2_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 decoder to create.
`[in]`	params	Creation parameters.

Return values:

	NULL	An error has occurred.
	non-NULL	The handle to the newly created video decoder 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 decoder.

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()
VIDDEC2_delete()

Void VIDDEC2_delete ( VIDDEC2_Handle handle )

Delete the instance of a video decoder algorithm.

Parameters:

[in] handle Handle to a created video decoder instance.

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

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

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

See also:: VIDDEC2_create()

Int32 VIDDEC2_process	(	VIDDEC2_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		VIDDEC2_InArgs *	inArgs,
		VIDDEC2_OutArgs *	outArgs
	)

Execute the process() method in 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:

	VIDDEC2_EOK	Success.
	VIDDEC2_EFAIL	Failure.
	VIDDEC2_EUNSUPPORTED	Unsupported request.

Remarks:

Since the VIDDEC2 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 decoded.

The buffers supplied to VIDDEC2_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.

See also:

VIDDEC2_create()

VIDDEC2_delete()

VIDDEC2_control()

VIDDEC2_processAsync()

VIDDEC2_processWait()

IVIDDEC2_Fxns::process()

XDAS_Int32 VIDDEC2_processAsync	(	VIDDEC2_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		VIDDEC2_InArgs *	inArgs,
		VIDDEC2_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:

	VIDDEC2_EOK	Success.
	VIDDEC2_EFAIL	Failure.
	VIDDEC2_EUNSUPPORTED	Unsupported request.

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 VIDDEC2_processWait() API.
The buffers supplied to VIDDEC2_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:

VIDDEC2_processWait()

IVIDDEC2_Fxns::process()

XDAS_Int32 VIDDEC2_processWait	(	VIDDEC2_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		VIDDEC2_InArgs *	inArgs,
		VIDDEC2_OutArgs *	outArgs,
		UInt	timeout
	)

Wait for a return message from a previous invocation of VIDDEC2_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 -> VIDDEC2_FOREVER)

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

Return values:

	VIDDEC2_EOK	Success.
	VIDDEC2_EFAIL	Failure.
	VIDDEC2_EUNSUPPORTED	Unsupported request.
	VIDDEC2_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 VIDDEC2_EFOREVER.

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

The buffers supplied to VIDDEC2_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:

VIDDEC2_processAsync()


Data Structures
struct	IVIDDEC2_CodecClassConfig
	Definition of IVIDDEC2 codec class configurable parameters. More...
Defines
#define	VIDDEC2_EOK IVIDDEC2_EOK
#define	VIDDEC2_EFAIL IVIDDEC2_EFAIL
#define	VIDDEC2_EUNSUPPORTED IVIDDEC2_EUNSUPPORTED
#define	VIDDEC2_ETIMEOUT VISA_ETIMEOUT
#define	VIDDEC2_FOREVER VISA_FOREVER
Typedefs
typedef VISA_Handle	VIDDEC2_Handle
	Opaque handle to a VIDDEC2 codec.
typedef IVIDDEC2_Params	VIDDEC2_Params
typedef IVIDDEC2_InArgs	VIDDEC2_InArgs
typedef IVIDDEC2_OutArgs	VIDDEC2_OutArgs
typedef IVIDDEC2_Cmd	VIDDEC2_Cmd
typedef IVIDDEC2_DynamicParams	VIDDEC2_DynamicParams
typedef IVIDDEC2_Status	VIDDEC2_Status
Functions
Int32	VIDDEC2_control (VIDDEC2_Handle handle, VIDDEC2_Cmd id, VIDDEC2_DynamicParams params, VIDDEC2_Status status)
	Execute the control() method in this instance of a video decoder algorithm.
VIDDEC2_Handle	VIDDEC2_create (Engine_Handle e, String name, VIDDEC2_Params *params)
	Create an instance of a video decoder algorithm.
Void	VIDDEC2_delete (VIDDEC2_Handle handle)
	Delete the instance of a video decoder algorithm.
Int32	VIDDEC2_process (VIDDEC2_Handle handle, XDM1_BufDesc inBufs, XDM_BufDesc outBufs, VIDDEC2_InArgs inArgs, VIDDEC2_OutArgs outArgs)
	Execute the process() method in this instance of a video decoder algorithm.
XDAS_Int32	VIDDEC2_processAsync (VIDDEC2_Handle handle, XDM1_BufDesc inBufs, XDM_BufDesc outBufs, VIDDEC2_InArgs inArgs, VIDDEC2_OutArgs outArgs)
	Perform asynchronous submission to this instance of a video decoder algorithm.
XDAS_Int32	VIDDEC2_processWait (VIDDEC2_Handle handle, XDM1_BufDesc inBufs, XDM_BufDesc outBufs, VIDDEC2_InArgs inArgs, VIDDEC2_OutArgs outArgs, UInt timeout)
	Wait for a return message from a previous invocation of VIDDEC2_processAsync() in this instance of an video decoder algorithm.