Universal Algorithm Interface

Defines
#define	UNIVERSAL_EOK   IUNIVERSAL_EOK
#define	UNIVERSAL_EFAIL   IUNIVERSAL_EFAIL
#define	UNIVERSAL_EUNSUPPORTED   IUNIVERSAL_EUNSUPPORTED
#define	UNIVERSAL_ETIMEOUT   VISA_ETIMEOUT
#define	UNIVERSAL_FOREVER   VISA_FOREVER
Typedefs
typedef VISA_Handle	UNIVERSAL_Handle
	Opaque handle to a UNIVERSAL codec.
typedef struct IUNIVERSAL_Params	UNIVERSAL_Params
	This structure defines the parameters necessary to create an instance of a "universal" algorithm.
typedef IUNIVERSAL_InArgs	UNIVERSAL_InArgs
typedef IUNIVERSAL_OutArgs	UNIVERSAL_OutArgs
typedef IUNIVERSAL_Cmd	UNIVERSAL_Cmd
typedef IUNIVERSAL_Status	UNIVERSAL_Status
typedef IUNIVERSAL_DynamicParams	UNIVERSAL_DynamicParams
Functions
Int32	UNIVERSAL_control (UNIVERSAL_Handle handle, UNIVERSAL_Cmd id, UNIVERSAL_DynamicParams *params, UNIVERSAL_Status *status)
	Execute the control() method in this instance of a "universal" algorithm.
UNIVERSAL_Handle	UNIVERSAL_create (Engine_Handle e, String name, UNIVERSAL_Params *params)
	Create an instance of a universal algorithm.
Void	UNIVERSAL_delete (UNIVERSAL_Handle handle)
	Delete the instance of a universal algorithm.
Int32	UNIVERSAL_process (UNIVERSAL_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs, UNIVERSAL_InArgs *inArgs, UNIVERSAL_OutArgs *outArgs)
	Execute the process() method in this instance of a universal algorithm.
XDAS_Int32	UNIVERSAL_processAsync (UNIVERSAL_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs, IUNIVERSAL_InArgs *inArgs, IUNIVERSAL_OutArgs *outArgs)
	Perform asynchronous submission to this instance of a universal algorithm.
XDAS_Int32	UNIVERSAL_processWait (UNIVERSAL_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs, IUNIVERSAL_InArgs *inArgs, IUNIVERSAL_OutArgs *outArgs, UInt timeout)
	Wait for a return message from a previous invocation of UNIVERSAL_processAsync() in this instance of a universal algorithm.

---

Detailed Description

This is the "universal" algorithm 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 UNIVERSAL_EOK   IUNIVERSAL_EOK

Success.

#define UNIVERSAL_EFAIL   IUNIVERSAL_EFAIL

General failure.

#define UNIVERSAL_EUNSUPPORTED   IUNIVERSAL_EUNSUPPORTED

Request is unsupported. Timeout occurred.

#define UNIVERSAL_ETIMEOUT   VISA_ETIMEOUT

Special value for timeout parameter indicating never timeout.

#define UNIVERSAL_FOREVER   VISA_FOREVER

---

Typedef Documentation

typedef VISA_Handle UNIVERSAL_Handle

Opaque handle to a UNIVERSAL codec.

typedef struct IUNIVERSAL_Params UNIVERSAL_Params

This structure defines the parameters necessary to create an instance of a "universal" algorithm.

typedef IUNIVERSAL_InArgs UNIVERSAL_InArgs

Defines the input arguments for all IUNIVERSAL 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:

IUNIVERSAL_Fxns::process()

typedef IUNIVERSAL_OutArgs UNIVERSAL_OutArgs

Defines the run time output arguments for all IUNIVERSAL 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:

IUNIVERSAL_Fxns::process()

typedef IUNIVERSAL_Cmd UNIVERSAL_Cmd

Defines the control commands for the IUNIVERSAL module.

Remarks:

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

See also:

XDM_CmdId

IUNIVERSAL_Fxns::control()

typedef IUNIVERSAL_Status UNIVERSAL_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:

IUNIVERSAL_Fxns::control()

typedef IUNIVERSAL_DynamicParams UNIVERSAL_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:

IUNIVERSAL_Fxns::control()

---

Function Documentation

Int32 UNIVERSAL_control	(	UNIVERSAL_Handle	handle,
		UNIVERSAL_Cmd	id,
		UNIVERSAL_DynamicParams *	params,
		UNIVERSAL_Status *	status
	)

Execute the control() method in this instance of a "universal" algorithm.

Parameters:

[in]	handle	Handle to a created universal algorithm instance.
[in]	id	Command id for XDM control operation.
[in]	params	Runtime control parameters used for the universal algorithm instance.
[out]	status	Status info returned by the algorithm instance.

Precondition:

handle is a valid (non-NULL) universal algorithm handle and the universal algorithm instance is in the created state.

Return values:

	UNIVERSAL_EOK	Success.
	UNIVERSAL_EFAIL	Failure.
	UNIVERSAL_EUNSUPPORTED	Unsupported request.

Remarks:

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

See also:

UNIVERSAL_create()

UNIVERSAL_delete()

IUNIVERSAL_Fxns::control()

UNIVERSAL_Handle UNIVERSAL_create	(	Engine_Handle	e,
		String	name,
		UNIVERSAL_Params *	params
	)

Create an instance of a universal algorithm.

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

Return values:

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

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 and/or the number of VISA messages to allocate, to be overridden. This optional argument string is of the form ":priority:flag:number-of-messages", and can be specified with an empty field for any element that you don't want to be overridden, e.g. "mp3:::3" to cause 3 messages to be allocated while using the default values for priority and the heap 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.

The number-of-messages overrides the default of 1 message, and is useful (or required, practically speaking) for when the "asynchronous" process method is used, i.e. "AUDENC1_processAsync()"

See also:

Engine_open()

UNIVERSAL_delete()

Void UNIVERSAL_delete

(

UNIVERSAL_Handle

handle

)

Delete the instance of a universal algorithm.

Parameters:

[in]

handle

Handle to a created universal algorithm instance.

Remarks:

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

Precondition:

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

Postcondition:

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

See also:

UNIVERSAL_create()

Int32 UNIVERSAL_process	(	UNIVERSAL_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		XDM1_BufDesc *	inOutBufs,
		UNIVERSAL_InArgs *	inArgs,
		UNIVERSAL_OutArgs *	outArgs
	)

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

Parameters:

[in]	handle	Handle to a created universal algorithm instance.
[in]	inBufs	A buffer descriptor containing input buffers.
[out]	outBufs	A buffer descriptor containing output buffers.
[in,out]	inOutBufs	A buffer descriptor containing in/out buffers.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) universal algorithm handle and the universal algorithm instance is in the created state.

Return values:

	UNIVERSAL_EOK	Success.
	UNIVERSAL_EFAIL	Failure.
	UNIVERSAL_EUNSUPPORTED	Unsupported request.

Remarks:

Since the UNIVERSAL algorithm 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 UNIVERSAL_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:

UNIVERSAL_create()

UNIVERSAL_delete()

UNIVERSAL_control()

UNIVERSAL_processAsync()

UNIVERSAL_processWait()

IUNIVERSAL_Fxns::process()

XDAS_Int32 UNIVERSAL_processAsync	(	UNIVERSAL_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		XDM1_BufDesc *	inOutBufs,
		IUNIVERSAL_InArgs *	inArgs,
		IUNIVERSAL_OutArgs *	outArgs
	)

Perform asynchronous submission to this instance of a universal algorithm.

Parameters:

[in]	handle	Handle to a created universal algorithm instance.
[in]	inBufs	A buffer descriptor containing input buffers.
[out]	outBufs	A buffer descriptor containing output buffers.
[in,out]	inOutBufs	A buffer descriptor containing in/out buffers.
[in]	inArgs	Input Arguments.
[out]	outArgs	Output Arguments.

Precondition:

handle is a valid (non-NULL) universal algorithm handle and the universal algorithm instance is in the created state.

Return values:

	UNIVERSAL_EOK	Success.
	UNIVERSAL_EFAIL	Failure.
	UNIVERSAL_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 UNIVERSAL_processWait() API.

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

UNIVERSAL_create()

UNIVERSAL_delete()

UNIVERSAL_control()

UNIVERSAL_process()

UNIVERSAL_processWait()

IUNIVERSAL_Fxns::process()

XDAS_Int32 UNIVERSAL_processWait	(	UNIVERSAL_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		XDM1_BufDesc *	inOutBufs,
		IUNIVERSAL_InArgs *	inArgs,
		IUNIVERSAL_OutArgs *	outArgs,
		UInt	timeout
	)

Wait for a return message from a previous invocation of UNIVERSAL_processAsync() in this instance of a universal algorithm.

Parameters:

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

Precondition:

handle is a valid (non-NULL) universal algorithm handle and the universal algorithm instance is in the created state.

Return values:

	UNIVERSAL_EOK	Success.
	UNIVERSAL_EFAIL	Failure.
	UNIVERSAL_EUNSUPPORTED	Unsupported request.
	UNIVERSAL_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 UNIVERSAL_EFOREVER.

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

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

UNIVERSAL_create()

UNIVERSAL_delete()

UNIVERSAL_control()

UNIVERSAL_process()

UNIVERSAL_processAsync()