Video Analytics Algorithm Interface

Detailed Description

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

Defines

#define VIDANALYTICS_EOK   IVIDANALYTICS_EOK

#define VIDANALYTICS_EFAIL   IVIDANALYTICS_EFAIL

#define VIDANALYTICS_EUNSUPPORTED   IVIDANALYTICS_EUNSUPPORTED

#define VIDANALYTICS_ETIMEOUT   VISA_ETIMEOUT

#define VIDANALYTICS_FOREVER   VISA_FOREVER

Typedefs

typedef VISA_Handle VIDANALYTICS_Handle

Opaque handle to a VIDANALYTICS codec.

typedef IVIDANALYTICS_Params VIDANALYTICS_Params

This structure defines the parameters necessary to create an instance of a video analytics algorithm.

typedef IVIDANALYTICS_InArgs VIDANALYTICS_InArgs

typedef IVIDANALYTICS_OutArgs VIDANALYTICS_OutArgs

typedef IVIDANALYTICS_Cmd VIDANALYTICS_Cmd

typedef IVIDANALYTICS_Status VIDANALYTICS_Status

typedef IVIDANALYTICS_DynamicParams VIDANALYTICS_DynamicParams

Functions

Int32 VIDANALYTICS_control (VIDANALYTICS_Handle handle, VIDANALYTICS_Cmd id, VIDANALYTICS_DynamicParams *params, VIDANALYTICS_Status *status)

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

VIDANALYTICS_Handle VIDANALYTICS_create (Engine_Handle e, String name, VIDANALYTICS_Params *params)

Create an instance of a video analytics algorithm.

Void VIDANALYTICS_delete (VIDANALYTICS_Handle handle)

Delete the instance of a video analytics algorithm.

Int32 VIDANALYTICS_process (VIDANALYTICS_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, VIDANALYTICS_InArgs *inArgs, VIDANALYTICS_OutArgs *outArgs)

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

XDAS_Int32 VIDANALYTICS_processAsync (VIDANALYTICS_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, IVIDANALYTICS_InArgs *inArgs, IVIDANALYTICS_OutArgs *outArgs)

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

XDAS_Int32 VIDANALYTICS_processWait (VIDANALYTICS_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, IVIDANALYTICS_InArgs *inArgs, IVIDANALYTICS_OutArgs *outArgs, UInt timeout)

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

Define Documentation

#define VIDANALYTICS_EOK IVIDANALYTICS_EOK

Success.

#define VIDANALYTICS_EFAIL IVIDANALYTICS_EFAIL

General failure.

#define VIDANALYTICS_EUNSUPPORTED IVIDANALYTICS_EUNSUPPORTED

Request is unsupported. Timeout occurred.

#define VIDANALYTICS_ETIMEOUT VISA_ETIMEOUT

Special value for timeout parameter indicating never timeout.

#define VIDANALYTICS_FOREVER VISA_FOREVER

Typedef Documentation

typedef VISA_Handle VIDANALYTICS_Handle

Opaque handle to a VIDANALYTICS codec.

typedef struct IVIDANALYTICS_Params VIDANALYTICS_Params

This structure defines the parameters necessary to create an instance of a video analytics algorithm.

typedef IVIDANALYTICS_InArgs VIDANALYTICS_InArgs

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

typedef IVIDANALYTICS_OutArgs VIDANALYTICS_OutArgs

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

typedef IVIDANALYTICS_Cmd VIDANALYTICS_Cmd

Defines the control commands for the IVIDANALYTICS module.

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

See also:: XDM_CmdId
IVIDANALYTICS_Fxns::control()

typedef IVIDANALYTICS_Status VIDANALYTICS_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 http://tiexpressdsp.com/index.php?title=Extending_data_structures_in_xDM for more details.

See also:: IVIDANALYTICS_Fxns::control()

typedef IVIDANALYTICS_DynamicParams VIDANALYTICS_DynamicParams

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

Function Documentation

Int32 VIDANALYTICS_control	(	VIDANALYTICS_Handle	handle,
		VIDANALYTICS_Cmd	id,
		VIDANALYTICS_DynamicParams *	params,
		VIDANALYTICS_Status *	status
	)

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

Parameters:

`[in]`	handle	Handle to a created video analytics instance.
`[in]`	id	Command id for xDM control operation.
`[in]`	params	Runtime control parameters used for the video analytics instance.
`[out]`	status	Status info returned by the video analytics instance.

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

Return values:

	VIDANALYTICS_EOK	Success.
	VIDANALYTICS_EFAIL	Failure.
	VIDANALYTICS_EUNSUPPORTED	Unsupported request.

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

See also:

VIDANALYTICS_create()

VIDANALYTICS_delete()

IVIDANALYTICS_Fxns::control()

VIDANALYTICS_Handle VIDANALYTICS_create	(	Engine_Handle	e,
		String	name,
		VIDANALYTICS_Params *	params
	)

Create an instance of a video analytics algorithm.

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

Return values:

	NULL	An error has occurred.
	non-NULL	The handle to the newly created video analytics 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 analytics 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, 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()
VIDANALYTICS_delete()

Void VIDANALYTICS_delete ( VIDANALYTICS_Handle handle )

Delete the instance of a video analytics algorithm.

Parameters:

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

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

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

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

See also:: VIDANALYTICS_create()

Int32 VIDANALYTICS_process	(	VIDANALYTICS_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		VIDANALYTICS_InArgs *	inArgs,
		VIDANALYTICS_OutArgs *	outArgs
	)

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

Parameters:

`[in]`	handle	Handle to a created video analytics 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 analytics handle and the video analytics algorithm instance is in the created state.

Return values:

	VIDANALYTICS_EOK	Success.
	VIDANALYTICS_EFAIL	Failure.
	VIDANALYTICS_EUNSUPPORTED	Unsupported request.

Remarks:

Since the VIDANALYTICS 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 VIDANALYTICS_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:

VIDANALYTICS_create()

VIDANALYTICS_delete()

VIDANALYTICS_control()

VIDANALYTICS_processAsync()

VIDANALYTICS_processWait()

IVIDANALYTICS_Fxns::process()

XDAS_Int32 VIDANALYTICS_processAsync	(	VIDANALYTICS_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		IVIDANALYTICS_InArgs *	inArgs,
		IVIDANALYTICS_OutArgs *	outArgs
	)

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

Parameters:

`[in]`	handle	Handle to a created video analytics 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 analytics handle and the video analytics algorithm instance is in the created state.

Return values:

	VIDANALYTICS_EOK	Success.
	VIDANALYTICS_EFAIL	Failure.
	VIDANALYTICS_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 VIDANALYTICS_processWait() API.
The buffers supplied to VIDANALYTICS_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:

VIDANALYTICS_create()

VIDANALYTICS_delete()

VIDANALYTICS_control()

VIDANALYTICS_process()

VIDANALYTICS_processWait()

IVIDANALYTICS_Fxns::process()

XDAS_Int32 VIDANALYTICS_processWait	(	VIDANALYTICS_Handle	handle,
		XDM1_BufDesc *	inBufs,
		XDM1_BufDesc *	outBufs,
		IVIDANALYTICS_InArgs *	inArgs,
		IVIDANALYTICS_OutArgs *	outArgs,
		UInt	timeout
	)

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

Parameters:

`[in]`	handle	Handle to a created video analytics 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 -> VIDANALYTICS_FOREVER)

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

Return values:

	VIDANALYTICS_EOK	Success.
	VIDANALYTICS_EFAIL	Failure.
	VIDANALYTICS_EUNSUPPORTED	Unsupported request.
	VIDANALYTICS_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 VIDANALYTICS_EFOREVER.

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

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

VIDANALYTICS_create()

VIDANALYTICS_delete()

VIDANALYTICS_control()

VIDANALYTICS_process()

VIDANALYTICS_processAsync()


Defines
#define	VIDANALYTICS_EOK IVIDANALYTICS_EOK
#define	VIDANALYTICS_EFAIL IVIDANALYTICS_EFAIL
#define	VIDANALYTICS_EUNSUPPORTED IVIDANALYTICS_EUNSUPPORTED
#define	VIDANALYTICS_ETIMEOUT VISA_ETIMEOUT
#define	VIDANALYTICS_FOREVER VISA_FOREVER
Typedefs
typedef VISA_Handle	VIDANALYTICS_Handle
	Opaque handle to a VIDANALYTICS codec.
typedef IVIDANALYTICS_Params	VIDANALYTICS_Params
	This structure defines the parameters necessary to create an instance of a video analytics algorithm.
typedef IVIDANALYTICS_InArgs	VIDANALYTICS_InArgs
typedef IVIDANALYTICS_OutArgs	VIDANALYTICS_OutArgs
typedef IVIDANALYTICS_Cmd	VIDANALYTICS_Cmd
typedef IVIDANALYTICS_Status	VIDANALYTICS_Status
typedef IVIDANALYTICS_DynamicParams	VIDANALYTICS_DynamicParams
Functions
Int32	VIDANALYTICS_control (VIDANALYTICS_Handle handle, VIDANALYTICS_Cmd id, VIDANALYTICS_DynamicParams params, VIDANALYTICS_Status status)
	Execute the control() method in this instance of a video analytics algorithm.
VIDANALYTICS_Handle	VIDANALYTICS_create (Engine_Handle e, String name, VIDANALYTICS_Params *params)
	Create an instance of a video analytics algorithm.
Void	VIDANALYTICS_delete (VIDANALYTICS_Handle handle)
	Delete the instance of a video analytics algorithm.
Int32	VIDANALYTICS_process (VIDANALYTICS_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, VIDANALYTICS_InArgs inArgs, VIDANALYTICS_OutArgs outArgs)
	Execute the process() method in this instance of a video analytics algorithm.
XDAS_Int32	VIDANALYTICS_processAsync (VIDANALYTICS_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, IVIDANALYTICS_InArgs inArgs, IVIDANALYTICS_OutArgs outArgs)
	Perform asynchronous submission to this instance of a video analytics algorithm.
XDAS_Int32	VIDANALYTICS_processWait (VIDANALYTICS_Handle handle, XDM1_BufDesc inBufs, XDM1_BufDesc outBufs, IVIDANALYTICS_InArgs inArgs, IVIDANALYTICS_OutArgs outArgs, UInt timeout)
	Wait for a return message from a previous invocation of VIDANALYTICS_processAsync() in this instance of an video analytics algorithm.