Image 1.00 decoder codec interface

Detailed Description

This is the 1.00 image decoder codec interface. Several of the data types in this API are specified by the xDM 1.00 interface; please see the xDM documentation for those details.

Data Structures

struct IIMGDEC1_CodecClassConfig

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

Defines

#define IMGDEC1_EOK   IIMGDEC1_EOK

#define IMGDEC1_EFAIL   IIMGDEC1_EFAIL

#define IMGDEC1_EUNSUPPORTED   IIMGDEC1_EUNSUPPORTED

#define IMGDEC1_ETIMEOUT   VISA_ETIMEOUT

#define IMGDEC1_FOREVER   VISA_FOREVER

Typedefs

typedef VISA_Handle IMGDEC1_Handle

Opaque handle to a IMGDEC1 codec.

typedef IIMGDEC1_Params IMGDEC1_Params

This structure defines the parameters necessary to create an instance of an image decoder object.

typedef IIMGDEC1_InArgs IMGDEC1_InArgs

typedef IIMGDEC1_OutArgs IMGDEC1_OutArgs

typedef IIMGDEC1_Cmd IMGDEC1_Cmd

typedef IIMGDEC1_Status IMGDEC1_Status

typedef IIMGDEC1_DynamicParams IMGDEC1_DynamicParams

Functions

Int32 IMGDEC1_control (IMGDEC1_Handle handle, IMGDEC1_Cmd id, IMGDEC1_DynamicParams *params, IMGDEC1_Status *status)

Execute the control() method in this instance of an image1 decoder algorithm.

IMGDEC1_Handle IMGDEC1_create (Engine_Handle e, String name, IMGDEC1_Params *params)

Create an instance of an image decoder algorithm.

Void IMGDEC1_delete (IMGDEC1_Handle handle)

Delete the instance of an image decoder algorithm.

Int32 IMGDEC1_process (IMGDEC1_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, IMGDEC1_InArgs *inArgs, IMGDEC1_OutArgs *outArgs)

Execute the process() method in this instance of an image decoder algorithm.

XDAS_Int32 IMGDEC1_processAsync (IMGDEC1_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, IMGDEC1_InArgs *inArgs, IMGDEC1_OutArgs *outArgs)

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

XDAS_Int32 IMGDEC1_processWait (IMGDEC1_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, IMGDEC1_InArgs *inArgs, IMGDEC1_OutArgs *outArgs, UInt timeout)

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

Define Documentation

#define IMGDEC1_EOK IIMGDEC1_EOK

Success.

#define IMGDEC1_EFAIL IIMGDEC1_EFAIL

General failure.

#define IMGDEC1_EUNSUPPORTED IIMGDEC1_EUNSUPPORTED

Request is unsupported.

#define IMGDEC1_ETIMEOUT VISA_ETIMEOUT

#define IMGDEC1_FOREVER VISA_FOREVER

Typedef Documentation

typedef VISA_Handle IMGDEC1_Handle

Opaque handle to a IMGDEC1 codec.

typedef struct IIMGDEC1_Params IMGDEC1_Params

This structure defines the parameters necessary to create an instance of an image decoder object.

typedef IIMGDEC1_InArgs IMGDEC1_InArgs

Defines the input arguments for all IIMGDEC1 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 also:: IIMGDEC1_Fxns::process()

typedef IIMGDEC1_OutArgs IMGDEC1_OutArgs

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

typedef IIMGDEC1_Cmd IMGDEC1_Cmd

Defines the control commands for the IIMGDEC1 module.

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

See also:: XDM_CmdId
IIMGDEC1_Fxns::control()

typedef IIMGDEC1_Status IMGDEC1_Status

Defines instance status parameters.

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 also:: IIMGDEC1_Fxns::control()

typedef IIMGDEC1_DynamicParams IMGDEC1_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 also:: IIMGDEC1_Fxns::control()

Function Documentation

Int32 IMGDEC1_control	(	IMGDEC1_Handle	handle,
		IMGDEC1_Cmd	id,
		IMGDEC1_DynamicParams *	params,
		IMGDEC1_Status *	status
	)

Execute the control() method in this instance of an image1 decoder algorithm.

Parameters:

`[in]`	handle	Handle to a created image 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) image decoder handle and the image decoder is in the created state.

Return values:

	IMGDEC1_EOK	Success.
	IMGDEC1_EFAIL	Failure.
	IMGDEC1_EUNSUPPORTED	Unsupported request.

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

See also:

IMGDEC1_create()

IMGDEC1_delete()

IIMGDEC1_Fxns()control()

IMGDEC1_Handle IMGDEC1_create	(	Engine_Handle	e,
		String	name,
		IMGDEC1_Params *	params
	)

Create an instance of an image decoder algorithm.

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

Return values:

	NULL	An error has occurred.
	non-NULL	The handle to the newly created image 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 image 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()
IMGDEC1_delete()

Void IMGDEC1_delete ( IMGDEC1_Handle handle )

Delete the instance of an image decoder algorithm.

Parameters:

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

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

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

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

See also:: IMGDEC1_create()

Int32 IMGDEC1_process	(	IMGDEC1_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		IMGDEC1_InArgs *	inArgs,
		IMGDEC1_OutArgs *	outArgs
	)

Execute the process() method in this instance of an image decoder algorithm.

Parameters:

`[in]`	handle	Handle to a created image 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) image decoder handle and the image decoder is in the created state.

Return values:

	IMGDEC1_EOK	Success.
	IMGDEC1_EFAIL	Failure.
	IMGDEC1_EUNSUPPORTED	Unsupported request.

Remarks:

Since the IMGDEC1 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 IMGDEC1_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:

IMGDEC1_create()

IMGDEC1_delete()

IMGDEC1_control()

IMGDEC1_processAsync()

IMGDEC1_processWait()

IIMGDEC1_Fxns()process()

XDAS_Int32 IMGDEC1_processAsync	(	IMGDEC1_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		IMGDEC1_InArgs *	inArgs,
		IMGDEC1_OutArgs *	outArgs
	)

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

Parameters:

`[in]`	handle	Handle to a created image 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) image decoder handle and the image decoder is in the created state.

Return values:

	IMGDEC1_EOK	Success.
	IMGDEC1_EFAIL	Failure.
	IMGDEC1_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 IMGDEC1_processWait() API.
The buffers supplied to IMGDEC1_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:

IMGDEC1_processWait()

IIMGDEC1_Fxns::process()

XDAS_Int32 IMGDEC1_processWait	(	IMGDEC1_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		IMGDEC1_InArgs *	inArgs,
		IMGDEC1_OutArgs *	outArgs,
		UInt	timeout
	)

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

Parameters:

`[in]`	handle	Handle to a created image 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 -> IMGDEC1_FOREVER)

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

Return values:

	IMGDEC1_EOK	Success.
	IMGDEC1_EFAIL	Failure.
	IMGDEC1_EUNSUPPORTED	Unsupported request.
	IMGDEC1_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 IMGDEC1_EFOREVER.

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

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

IMGDEC1_processAsync()


Data Structures
struct	IIMGDEC1_CodecClassConfig
	Definition of IIMGDEC1 codec class configurable parameters. More...
Defines
#define	IMGDEC1_EOK IIMGDEC1_EOK
#define	IMGDEC1_EFAIL IIMGDEC1_EFAIL
#define	IMGDEC1_EUNSUPPORTED IIMGDEC1_EUNSUPPORTED
#define	IMGDEC1_ETIMEOUT VISA_ETIMEOUT
#define	IMGDEC1_FOREVER VISA_FOREVER
Typedefs
typedef VISA_Handle	IMGDEC1_Handle
	Opaque handle to a IMGDEC1 codec.
typedef IIMGDEC1_Params	IMGDEC1_Params
	This structure defines the parameters necessary to create an instance of an image decoder object.
typedef IIMGDEC1_InArgs	IMGDEC1_InArgs
typedef IIMGDEC1_OutArgs	IMGDEC1_OutArgs
typedef IIMGDEC1_Cmd	IMGDEC1_Cmd
typedef IIMGDEC1_Status	IMGDEC1_Status
typedef IIMGDEC1_DynamicParams	IMGDEC1_DynamicParams
Functions
Int32	IMGDEC1_control (IMGDEC1_Handle handle, IMGDEC1_Cmd id, IMGDEC1_DynamicParams params, IMGDEC1_Status status)
	Execute the control() method in this instance of an image1 decoder algorithm.
IMGDEC1_Handle	IMGDEC1_create (Engine_Handle e, String name, IMGDEC1_Params *params)
	Create an instance of an image decoder algorithm.
Void	IMGDEC1_delete (IMGDEC1_Handle handle)
	Delete the instance of an image decoder algorithm.
Int32	IMGDEC1_process (IMGDEC1_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, IMGDEC1_InArgs inArgs, IMGDEC1_OutArgs outArgs)
	Execute the process() method in this instance of an image decoder algorithm.
XDAS_Int32	IMGDEC1_processAsync (IMGDEC1_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, IMGDEC1_InArgs inArgs, IMGDEC1_OutArgs outArgs)
	Perform asynchronous submission to this instance of a image decoder algorithm.
XDAS_Int32	IMGDEC1_processWait (IMGDEC1_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, IMGDEC1_InArgs inArgs, IMGDEC1_OutArgs outArgs, UInt timeout)
	Wait for a return message from a previous invocation of IMGDEC1_processAsync() in this instance of an image decoder algorithm.