0.9 Image Encoder Codec Interface

Detailed Description

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

Data Structures

struct IIMGENC_CodecClassConfig

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

Defines

#define IMGENC_EOK   IIMGENC_EOK

#define IMGENC_EFAIL   IIMGENC_EFAIL

#define IMGENC_ERUNTIME   IIMGENC_ERUNTIME

#define IMGENC_ETIMEOUT   VISA_ETIMEOUT

#define IMGENC_FOREVER   VISA_FOREVER

Typedefs

typedef IIMGENC_Status IMGENC_Status

typedef VISA_Handle IMGENC_Handle

Opaque handle to a IMGENC codec.

typedef IIMGENC_Params IMGENC_Params

This structure defines the parameters necessary to create an instance of a Image Encoder object.

typedef IIMGENC_InArgs IMGENC_InArgs

typedef IIMGENC_OutArgs IMGENC_OutArgs

typedef IIMGENC_Cmd IMGENC_Cmd

typedef IIMGENC_DynamicParams IMGENC_DynamicParams

Functions

IMGENC_Handle IMGENC_create (Engine_Handle e, String name, IMGENC_Params *params)

Create an instance of a image encoder algorithm.

Int32 IMGENC_process (IMGENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, IMGENC_InArgs *inArgs, IMGENC_OutArgs *outArgs)

Execute the "process" method in this instance of a image encoder algorithm.

Int32 IMGENC_control (IMGENC_Handle handle, IMGENC_Cmd id, IMGENC_DynamicParams *params, IMGENC_Status *status)

Execute the "control" method in this instance of a image encoder algorithm.

Void IMGENC_delete (IMGENC_Handle handle)

Delete the instance of a image encoder algorithm.

XDAS_Int32 IMGENC_processAsync (IMGENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, IIMGENC_InArgs *inArgs, IIMGENC_OutArgs *outArgs)

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

XDAS_Int32 IMGENC_processWait (IMGENC_Handle handle, XDM_BufDesc *inBufs, XDM_BufDesc *outBufs, IIMGENC_InArgs *inArgs, IIMGENC_OutArgs *outArgs, UInt timeout)

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

Define Documentation

#define IMGENC_EOK IIMGENC_EOK

Success.

#define IMGENC_EFAIL IIMGENC_EFAIL

General failure.

#define IMGENC_ERUNTIME IIMGENC_ERUNTIME

General runtime failure.

#define IMGENC_ETIMEOUT VISA_ETIMEOUT

#define IMGENC_FOREVER VISA_FOREVER

Typedef Documentation

typedef IIMGENC_Status IMGENC_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 also:: IIMGENC_Fxns::control()

typedef VISA_Handle IMGENC_Handle

Opaque handle to a IMGENC codec.

typedef struct IIMGENC_Params IMGENC_Params

This structure defines the parameters necessary to create an instance of a Image Encoder object.

typedef IIMGENC_InArgs IMGENC_InArgs

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

typedef IIMGENC_OutArgs IMGENC_OutArgs

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

typedef IIMGENC_Cmd IMGENC_Cmd

Defines the control commands for the IIMGENC module.

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

See also:: XDM_CmdId
IIMGENC_Fxns::control()

typedef IIMGENC_DynamicParams IMGENC_DynamicParams

This structure defines the algorithm 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:: IIMGENC_Fxns::control()

Function Documentation

IMGENC_Handle IMGENC_create	(	Engine_Handle	e,
		String	name,
		IMGENC_Params *	params
	)

Create an instance of a image encoder algorithm.

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

Return values:

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

Remarks:

Depending on the configuration of the engine opened, this call may create a local or remote instance of the image 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()

Int32 IMGENC_process	(	IMGENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		IMGENC_InArgs *	inArgs,
		IMGENC_OutArgs *	outArgs
	)

Execute the "process" method in this instance of a image encoder algorithm.

Parameters:

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

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

Return values:

	IMGENC_EOK	Success.
	IMGENC_EFAIL	Failure.
	IMGENC_ERUNTIME	Internal Runtime Error.

Remarks:

Since the IMGENC encoder 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 IMGENC_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.

IMGENC_processAsync()

IMGENC_processWait()

Int32 IMGENC_control	(	IMGENC_Handle	handle,
		IMGENC_Cmd	id,
		IMGENC_DynamicParams *	params,
		IMGENC_Status *	status
	)

Execute the "control" method in this instance of a image encoder algorithm.

Parameters:

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

Return values:

	IMGENC_EOK	Success.
	IMGENC_EFAIL	Failure.
	IMGENC_ERUNTIME	Internal Runtime Error.

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

See also:: IMGENC_create(), IMGENC_delete()

Void IMGENC_delete ( IMGENC_Handle handle )

Delete the instance of a image encoder algorithm.

Parameters:

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

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

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

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

See also:: IMGENC_create()

XDAS_Int32 IMGENC_processAsync	(	IMGENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		IIMGENC_InArgs *	inArgs,
		IIMGENC_OutArgs *	outArgs
	)

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

Parameters:

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

Return values:

	IMGENC_EOK	Success.
	IMGENC_EFAIL	Failure.
	IMGENC_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 IMGENC_processWait() API.
The buffers supplied to IMGENC_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:

IIMGENC_Fxns::process()

XDAS_Int32 IMGENC_processWait	(	IMGENC_Handle	handle,
		XDM_BufDesc *	inBufs,
		XDM_BufDesc *	outBufs,
		IIMGENC_InArgs *	inArgs,
		IIMGENC_OutArgs *	outArgs,
		UInt	timeout
	)

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

Parameters:

`[in]`	handle	Handle to a created image 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.
`[in]`	timeout	Amount of "time" to wait (from 0 -> IMGENC_FOREVER)

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

Return values:

	IMGENC_EOK	Success.
	IMGENC_EFAIL	Failure.
	IMGENC_EUNSUPPORTED	Unsupported request.
	IMGENC_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 IMGENC_EFOREVER.

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

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

IMGENC_processAsync()


Data Structures
struct	IIMGENC_CodecClassConfig
	Definition of IIMGDEC codec class configurable parameters. More...
Defines
#define	IMGENC_EOK IIMGENC_EOK
#define	IMGENC_EFAIL IIMGENC_EFAIL
#define	IMGENC_ERUNTIME IIMGENC_ERUNTIME
#define	IMGENC_ETIMEOUT VISA_ETIMEOUT
#define	IMGENC_FOREVER VISA_FOREVER
Typedefs
typedef IIMGENC_Status	IMGENC_Status
typedef VISA_Handle	IMGENC_Handle
	Opaque handle to a IMGENC codec.
typedef IIMGENC_Params	IMGENC_Params
	This structure defines the parameters necessary to create an instance of a Image Encoder object.
typedef IIMGENC_InArgs	IMGENC_InArgs
typedef IIMGENC_OutArgs	IMGENC_OutArgs
typedef IIMGENC_Cmd	IMGENC_Cmd
typedef IIMGENC_DynamicParams	IMGENC_DynamicParams
Functions
IMGENC_Handle	IMGENC_create (Engine_Handle e, String name, IMGENC_Params *params)
	Create an instance of a image encoder algorithm.
Int32	IMGENC_process (IMGENC_Handle handle, XDM_BufDesc inBufs, XDM_BufDesc outBufs, IMGENC_InArgs inArgs, IMGENC_OutArgs outArgs)
	Execute the "process" method in this instance of a image encoder algorithm.
Int32	IMGENC_control (IMGENC_Handle handle, IMGENC_Cmd id, IMGENC_DynamicParams params, IMGENC_Status status)
	Execute the "control" method in this instance of a image encoder algorithm.
Void	IMGENC_delete (IMGENC_Handle handle)
	Delete the instance of a image encoder algorithm.
XDAS_Int32	IMGENC_processAsync (IMGENC_Handle handle, XDM_BufDesc inBufs, XDM_BufDesc outBufs, IIMGENC_InArgs inArgs, IIMGENC_OutArgs outArgs)
	Perform asynchronous submission to this instance of a image encoder algorithm.
XDAS_Int32	IMGENC_processWait (IMGENC_Handle handle, XDM_BufDesc inBufs, XDM_BufDesc outBufs, IIMGENC_InArgs inArgs, IIMGENC_OutArgs outArgs, UInt timeout)
	Wait for a return message from a previous invocation of IMGENC_processAsync() in this instance of an image encoder algorithm.