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
|
typedef vx_status(* | vx_kernel_deinitialize_f )(vx_node node, 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, vx_reference *parameters, vx_uint32 num) |
| The pointer to the Host side kernel. More...
|
|
typedef vx_status(* | vx_kernel_initialize_f )(vx_node node, 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 structure is used to extract meta data from a validation function. If the data object between nodes is virtual, this allows the framework to automatically create the data object, if needed.
|
|
typedef vx_status(* | vx_publish_kernels_f )(vx_context context) |
| The entry point into modules loaded by vxLoadKernels . More...
|
|
|
vx_kernel | vxAddKernel (vx_context context, 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 | 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 | 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. More...
|
|
vx_status | vxLoadKernels (vx_context context, 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 | vxRemoveKernel (vx_kernel kernel) |
| Removes a non-finalized vx_kernel from the vx_context . Once a vx_kernel has been finalized it cannot be removed. More...
|
|
vx_status | vxSetKernelAttribute (vx_kernel kernel, vx_enum attribute, void *ptr, vx_size size) |
| Sets kernel attributes. More...
|
|
vx_status | vxSetMetaFormatAttribute (vx_meta_format meta, vx_enum attribute, void *ptr, vx_size size) |
| Allows a user to set the attributes of a vx_meta_format object in a kernel output validator. More...
|
|
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 1153 of file vx_types.h.
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 1162 of file vx_types.h.
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 1173 of file vx_types.h.
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 1184 of file vx_types.h.
The user-defined kernel node input parameter validation function.
- Note
- This function is called once for each VX_INPUT or VI_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 1200 of file vx_types.h.
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 1216 of file vx_types.h.
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 942 of file vx_types.h.
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
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. |
This API is called after all parameters have been added to the kernel and the kernel is ready to be used.
- 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
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 a value from vx_direction_e . |
[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
Removes a non-finalized vx_kernel
from the vx_context
. 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. |
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 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.
Allows a user to set the attributes of a vx_meta_format
object in a kernel output validator.
- Parameters
-
[in] | meta | The reference to the vx_meta_format object to set. |
[in] | attribute | Use attributes from other objects that match the parameter type or 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 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. |