Detailed Description

Defines the User Kernels, which are a method to extend OpenVX with new vision functions.

User Kernels can be loaded by OpenVX and included as nodes in the graph or as immediate functions (if the Client supplies the interface). User Kernels will typically be loaded and executed on HLOS/CPU compatible targets, not on remote processors or other accelerators. This specification does not mandate what constitutes compatible platforms.

Call sequence of User Kernels Installation

Call sequence of a Graph Verify and Release with User Kernels.

Call sequence of a Graph Execution with User Kernels

Typedefs
typedef vx_status(*	vx_kernel_deinitialize_f )(vx_node node, const vx_reference *parameters, vx_uint32 num)
	The pointer to the kernel deinitializer. If the host code requires a call to deinitialize data during a node garbage collection, this function is called if not NULL. More...

typedef vx_status(*	vx_kernel_f )(vx_node node, const vx_reference *parameters, vx_uint32 num)
	The pointer to the Host side kernel. More...

typedef vx_status(*	vx_kernel_initialize_f )(vx_node node, const vx_reference *parameters, vx_uint32 num)
	The pointer to the kernel initializer. If the host code requires a call to initialize data once all the parameters have been validated, this function is called if not NULL. More...

typedef vx_status(*	vx_kernel_input_validate_f )(vx_node node, vx_uint32 index)
	The user-defined kernel node input parameter validation function. More...

typedef vx_status(*	vx_kernel_output_validate_f )(vx_node node, vx_uint32 index, vx_meta_format meta)
	The user-defined kernel node output parameter validation function. The function only needs to fill in the meta data structure. More...

typedef struct _vx_meta_format *	vx_meta_format
	This object is used by output validation functions to specify the meta data of the expected output data object. If the output object is an image, the vx_meta_format object can additionally store the valid region delta rectangle. More...

typedef vx_status(*	vx_publish_kernels_f )(vx_context context)
	The entry point into modules loaded by `vxLoadKernels`. More...

Enumerations
enum	vx_meta_format_attribute_e { VX_META_FORMAT_ATTRIBUTE_DELTA_RECTANGLE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_META_FORMAT << 8)) + 0x0 }
	The meta format object attributes. More...

Functions
vx_kernel VX_API_CALL	vxAddKernel (vx_context context, const vx_char name[VX_MAX_KERNEL_NAME], vx_enum enumeration, vx_kernel_f func_ptr, vx_uint32 numParams, vx_kernel_input_validate_f input, vx_kernel_output_validate_f output, vx_kernel_initialize_f init, vx_kernel_deinitialize_f deinit)
	Allows users to add custom kernels to the known kernel database in OpenVX at run-time. This would primarily be used by the module function `vxPublishKernels`. More...

vx_status VX_API_CALL	vxAddParameterToKernel (vx_kernel kernel, vx_uint32 index, vx_enum dir, vx_enum data_type, vx_enum state)
	Allows users to set the signatures of the custom kernel. More...

vx_status VX_API_CALL	vxFinalizeKernel (vx_kernel kernel)
	This API is called after all parameters have been added to the kernel and the kernel is ready to be used. Notice that the reference to the kernel created by vxAddKernel is still valid after the call to vxFinalizeKernel. More...

vx_status VX_API_CALL	vxLoadKernels (vx_context context, const vx_char *module)
	Loads one or more kernels into the OpenVX context. This is the interface by which OpenVX is extensible. Once the set of kernels is loaded new kernels and their parameters can be queried. More...

vx_status VX_API_CALL	vxRemoveKernel (vx_kernel kernel)
	Removes a non-finalized `vx_kernel` from the `vx_context` and releases it. Once a `vx_kernel` has been finalized it cannot be removed. More...

vx_status VX_API_CALL	vxSetKernelAttribute (vx_kernel kernel, vx_enum attribute, const void *ptr, vx_size size)
	Sets kernel attributes. More...

vx_status VX_API_CALL	vxSetMetaFormatAttribute (vx_meta_format meta, vx_enum attribute, const void *ptr, vx_size size)
	This function allows a user to set the attributes of a `vx_meta_format` object in a kernel output validator. More...

Typedef Documentation

typedef struct _vx_meta_format* vx_meta_format

This object is used by output validation functions to specify the meta data of the expected output data object. If the output object is an image, the vx_meta_format object can additionally store the valid region delta rectangle.

Note: when the actual output object of the user node is virtual, the information given through the vx_meta_format object allows the OpenVX framework to automatically create the data object when meta data were not specified by the application at object creation time.

Definition at line 289 of file vx_types.h.

typedef vx_status( * vx_publish_kernels_f)(vx_context context)

The entry point into modules loaded by vxLoadKernels.

Parameters

[in] context The handle to the implementation context.

Note: The symbol exported from the user module must be vxPublishKernels in extern C format.

Definition at line 1189 of file vx_types.h.

typedef vx_status( * vx_kernel_f)(vx_node node, const vx_reference *parameters, vx_uint32 num)

The pointer to the Host side kernel.

Parameters

[in]	node	The handle to the node that contains this kernel.
[in]	parameters	The array of parameter references.
[in]	num	The number of parameters.

Definition at line 1198 of file vx_types.h.

typedef vx_status( * vx_kernel_initialize_f)(vx_node node, const vx_reference *parameters, vx_uint32 num)

The pointer to the kernel initializer. If the host code requires a call to initialize data once all the parameters have been validated, this function is called if not NULL.

Parameters

[in]	node	The handle to the node that contains this kernel.
[in]	parameters	The array of parameter references.
[in]	num	The number of parameters.

Definition at line 1209 of file vx_types.h.

typedef vx_status( * vx_kernel_deinitialize_f)(vx_node node, const vx_reference *parameters, vx_uint32 num)

The pointer to the kernel deinitializer. If the host code requires a call to deinitialize data during a node garbage collection, this function is called if not NULL.

Parameters

[in]	node	The handle to the node that contains this kernel.
[in]	parameters	The array of parameter references.
[in]	num	The number of parameters.

Definition at line 1220 of file vx_types.h.

typedef vx_status( * vx_kernel_input_validate_f)(vx_node node, vx_uint32 index)

The user-defined kernel node input parameter validation function.

Note: This function is called once for each VX_INPUT or VX_BIDIRECTIONAL parameter index.

Parameters

[in]	node	The handle to the node that is being validated.
[in]	index	The index of the parameter being validated.

Returns: An error code describing the validation status on this parameter.

Return values

VX_ERROR_INVALID_FORMAT	The parameter format was incorrect.
VX_ERROR_INVALID_VALUE	The value of the parameter was incorrect.
VX_ERROR_INVALID_DIMENSION	The dimensionality of the parameter was incorrect.
VX_ERROR_INVALID_PARAMETERS	The index was out of bounds.

Definition at line 1236 of file vx_types.h.

typedef vx_status( * vx_kernel_output_validate_f)(vx_node node, vx_uint32 index, vx_meta_format meta)

The user-defined kernel node output parameter validation function. The function only needs to fill in the meta data structure.

Note: This function is called once for each VX_OUTPUT parameter index.

Parameters

[in]	node	The handle to the node that is being validated.
[in]	index	The index of the parameter being validated.
[in]	ptr	A pointer to a pre-allocated structure that the system holds. The validation function fills in the correct type, format, and dimensionality for the system to use either to create memory or to check against existing memory.

Returns: An error code describing the validation status on this parameter.

Return values

VX_ERROR_INVALID_PARAMETERS The index is out of bounds.

Definition at line 1252 of file vx_types.h.

Enumeration Type Documentation

enum vx_meta_format_attribute_e

The meta format object attributes.

Enumerator
VX_META_FORMAT_ATTRIBUTE_DELTA_RECTANGLE	Configures a delta rectangle during kernel output parameter validation. Use a `vx_delta_rectangle_t`.

Definition at line 978 of file vx_types.h.

Function Documentation

vx_status VX_API_CALL vxLoadKernels	(	vx_context	context,
		const vx_char *	module
	)

Loads one or more kernels into the OpenVX context. This is the interface by which OpenVX is extensible. Once the set of kernels is loaded new kernels and their parameters can be queried.

Note: When all references to loaded kernels are released, the module may be automatically unloaded.

Parameters

[in]	context	The reference to the implementation context.
[in]	module	The short name of the module to load. On systems where there are specific naming conventions for modules, the name passed should ignore such conventions. For example: `libxyz.so` should be passed as just `xyz` and the implementation will do the right thing that the platform requires.

Note: This API uses the system pre-defined paths for modules.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the context is not a `vx_context`.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

See also: vxGetKernelByName

vx_kernel VX_API_CALL vxAddKernel	(	vx_context	context,
		const vx_char	name[VX_MAX_KERNEL_NAME],
		vx_enum	enumeration,
		vx_kernel_f	func_ptr,
		vx_uint32	numParams,
		vx_kernel_input_validate_f	input,
		vx_kernel_output_validate_f	output,
		vx_kernel_initialize_f	init,
		vx_kernel_deinitialize_f	deinit
	)

Allows users to add custom kernels to the known kernel database in OpenVX at run-time. This would primarily be used by the module function vxPublishKernels.

Parameters

[in]	context	The reference to the implementation context.
[in]	name	The string to use to match the kernel.
[in]	enumeration	The enumerated value of the kernel to be used by clients.
[in]	func_ptr	The process-local function pointer to be invoked.
[in]	numParams	The number of parameters for this kernel.
[in]	input	The pointer to `vx_kernel_input_validate_f`, which validates the input parameters to this kernel.
[in]	output	The pointer to `vx_kernel_output_validate_f` , which validates the output parameters to this kernel.
[in]	init	The kernel initialization function.
[in]	deinit	The kernel de-initialization function.

Returns: vx_kernel

Return values

0	Indicates that an error occurred when adding the kernel.
*	Kernel added to OpenVX.

vx_status VX_API_CALL vxFinalizeKernel ( vx_kernel kernel )

This API is called after all parameters have been added to the kernel and the kernel is ready to be used. Notice that the reference to the kernel created by vxAddKernel is still valid after the call to vxFinalizeKernel.

Parameters

[in] kernel The reference to the loaded kernel from vxAddKernel.

Returns: A vx_status_e enumeration. If an error occurs, the kernel is not available for usage by the clients of OpenVX. Typically this is due to a mismatch between the number of parameters requested and given.

Precondition: vxAddKernel and vxAddParameterToKernel

vx_status VX_API_CALL vxAddParameterToKernel	(	vx_kernel	kernel,
		vx_uint32	index,
		vx_enum	dir,
		vx_enum	data_type,
		vx_enum	state
	)

Allows users to set the signatures of the custom kernel.

Parameters

[in]	kernel	The reference to the kernel added with `vxAddKernel`.
[in]	index	The index of the parameter to add.
[in]	dir	The direction of the parameter. This must be either `VX_INPUT` or `VX_OUTPUT`. `VX_BIDIRECTIONAL` is not supported for this function.
[in]	data_type	The type of parameter. This must be a value from `vx_type_e`.
[in]	state	The state of the parameter (required or not). This must be a value from `vx_parameter_state_e`.

Returns: A vx_status_e enumerated value.

Return values

VX_SUCCESS	Parameter is successfully set on kernel.
VX_ERROR_INVALID_REFERENCE	The value passed as kernel was not a `vx_kernel`.

Precondition: vxAddKernel

vx_status VX_API_CALL vxRemoveKernel ( vx_kernel kernel )

Removes a non-finalized vx_kernel from the vx_context and releases it. Once a vx_kernel has been finalized it cannot be removed.

Parameters

[in] kernel The reference to the kernel to remove. Returned from vxAddKernel.

Note: Any kernel enumerated in the base standard cannot be removed; only kernels added through vxAddKernel can be removed.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_INVALID_REFERENCE	If an invalid kernel is passed in.
VX_ERROR_INVALID_PARAMETER	If a base kernel is passed in.

vx_status VX_API_CALL vxSetKernelAttribute	(	vx_kernel	kernel,
		vx_enum	attribute,
		const void *	ptr,
		vx_size	size
	)

Sets kernel attributes.

Parameters

[in]	kernel	The reference to the kernel.
[in]	attribute	The enumeration of the attributes. See `vx_kernel_attribute_e`.
[in]	ptr	The pointer to the location from which to read the attribute.
[in]	size	The size in bytes of the data area indicated by ptr in bytes.

Note: After a kernel has been passed to vxFinalizeKernel, no attributes can be altered.

Returns: A vx_status_e enumeration.

vx_status VX_API_CALL vxSetMetaFormatAttribute	(	vx_meta_format	meta,
		vx_enum	attribute,
		const void *	ptr,
		vx_size	size
	)

This function allows a user to set the attributes of a vx_meta_format object in a kernel output validator.

The vx_meta_format object contains two types of information : data object meta data and some specific information that defines how the valid region of an image changes

The meta data attributes that can be set are identified by this list:

vx_image : VX_IMAGE_ATTRIBUTE_FORMAT, VX_IMAGE_ATTRIBUTE_HEIGHT, VX_IMAGE_ATTRIBUTE_WIDTH
vx_array : VX_ARRAY_ATTRIBUTE_CAPACITY, VX_ARRAY_ATTRIBUTE_ITEMTYPE
vx_pyramid : VX_PYRAMID_ATTRIBUTE_FORMAT, VX_PYRAMID_ATTRIBUTE_HEIGHT, VX_PYRAMID_ATTRIBUTE_WIDTH, VX_PYRAMID_ATTRIBUTE_LEVELS, VX_PYRAMID_ATTRIBUTE_SCALE
vx_scalar : VX_SCALAR_ATTRIBUTE_TYPE
vx_matrix : VX_MATRIX_ATTRIBUTE_TYPE, VX_MATRIX_ATTRIBUTE_ROWS, VX_MATRIX_ATTRIBUTE_COLUMNS
vx_distribution : VX_DISTRIBUTION_ATTRIBUTE_BINS, VX_DISTRIBUTION_ATTRIBUTE_OFFSET, VX_DISTRIBUTION_ATTRIBUTE_RANGE
vx_remap : VX_REMAP_ATTRIBUTE_SOURCE_WIDTH, VX_REMAP_ATTRIBUTE_SOURCE_HEIGHT, VX_REMAP_ATTRIBUTE_DESTINATION_WIDTH, VX_REMAP_ATTRIBUTE_DESTINATION_HEIGHT
vx_lut : VX_LUT_ATTRIBUTE_TYPE, VX_LUT_ATTRIBUTE_COUNT
vx_threshold : VX_THRESHOLD_ATTRIBUTE_TYPE

VX_META_FORMAT_ATTRIBUTE_DELTA_RECTANGLE

Note: For vx_image, a specific attribute can be used to specify the valid region evolution. This information is not a meta data.

Parameters

[in]	meta	The reference to the vx_meta_format struct to set
[in]	attribute	Use the subset of data object attributes that define the meta data of this object or attributes from `vx_meta_format_attribute_e`.
[in]	ptr	The input pointer of the value to set on the meta format object.
[in]	size	The size in bytes of the object to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	The attribute was set.
VX_ERROR_INVALID_REFERENCE	meta was not a `vx_meta_format`.
VX_ERROR_INVALID_PARAMETER	size was not correct for the type needed.
VX_ERROR_NOT_SUPPORTED	the object attribute was not supported on the meta format object.
VX_ERROR_INVALID_TYPE	attribute type did not match known meta format type.

Detailed Description

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation