CoreFlow 1.0.0
A modern orchestration and execution runtime
|
The Public User Kernels API. More...
Typedefs | |
typedef struct MetaFormat * | vx_meta_format |
This object is used by output validation functions to specify the meta data of the expected output data object. | |
typedef vx_status(VX_API_CALL * | vx_publish_kernels_f) (vx_context context) |
The type of the vxPublishKernels entry function of modules loaded by vxLoadKernels and unloaded by vxUnloadKernels . | |
typedef vx_status(VX_API_CALL * | vx_unpublish_kernels_f) (vx_context context) |
The type of the vxUnpublishKernels entry function of modules loaded by vxLoadKernels and unloaded by vxUnloadKernels . | |
typedef vx_status(VX_CALLBACK * | vx_kernel_f) (vx_node node, const vx_reference *parameters, vx_uint32 num) |
The pointer to the Host side kernel. | |
typedef vx_status(VX_CALLBACK * | 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. | |
typedef vx_status(VX_CALLBACK * | 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. | |
typedef vx_status(VX_CALLBACK * | vx_kernel_validate_f) (vx_node node, const vx_reference parameters[], vx_uint32 num, vx_meta_format metas[]) |
The user-defined kernel node parameters validation function. The function only needs to fill in the meta data structure(s). | |
typedef vx_status(VX_CALLBACK * | vx_kernel_image_valid_rectangle_f) (vx_node node, vx_uint32 index, const vx_rectangle_t *const input_valid[], vx_rectangle_t *const output_valid[]) |
A user-defined callback function to set the valid rectangle of an output image. | |
Enumerations | |
enum | vx_meta_valid_rect_attribute_e { VX_VALID_RECT_CALLBACK = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_META_FORMAT) + 0x1 } |
The meta valid rectangle attributes. More... | |
Functions | |
VX_API_ENTRY vx_status VX_API_CALL | vxAllocateUserKernelId (vx_context context, vx_enum *pKernelEnumId) |
Allocates and registers user-defined kernel enumeration to a context. The allocated enumeration is from available pool of 4096 enumerations reserved for dynamic allocation from VX_KERNEL_BASE(VX_ID_USER,0). | |
VX_API_ENTRY vx_status VX_API_CALL | vxAllocateUserKernelLibraryId (vx_context context, vx_enum *pLibraryId) |
Allocates and registers user-defined kernel library ID to a context. | |
VX_API_ENTRY vx_status VX_API_CALL | vxRegisterKernelLibrary (vx_context context, const vx_char *module, vx_publish_kernels_f publish, vx_unpublish_kernels_f unpublish) |
Registers a module with kernels in a context. | |
VX_API_ENTRY vx_status VX_API_CALL | vxLoadKernels (vx_context context, const vx_char *module) |
Loads a library of kernels, called module, into a context. | |
VX_API_ENTRY vx_status VX_API_CALL | vxUnloadKernels (vx_context context, const vx_char *module) |
Unloads all kernels from the OpenVX context that had been loaded from the module using the vxLoadKernels function. | |
VX_API_ENTRY vx_kernel VX_API_CALL | vxAddUserKernel (vx_context context, const vx_char name[VX_MAX_KERNEL_NAME], vx_enum enumeration, vx_kernel_f func_ptr, vx_uint32 numParams, vx_kernel_validate_f validate, vx_kernel_initialize_f init, vx_kernel_deinitialize_f deinit) |
Allows users to add custom kernels to a context at run-time. | |
VX_API_ENTRY 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 vxAddUserKernel is still valid after the call to vxFinalizeKernel. 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. | |
VX_API_ENTRY 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. | |
VX_API_ENTRY vx_status VX_API_CALL | vxRemoveKernel (vx_kernel kernel) |
Removes a custom kernel from its context and releases it. | |
VX_API_ENTRY vx_status VX_API_CALL | vxSetKernelAttribute (vx_kernel kernel, vx_enum attribute, const void *ptr, vx_size size) |
Sets kernel attributes. | |
VX_API_ENTRY 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. | |
VX_API_ENTRY vx_status VX_API_CALL | vxSetMetaFormatFromReference (vx_meta_format meta, vx_reference exemplar) |
Set a meta format object from an exemplar data object reference. | |
The Public User Kernels API.
typedef vx_status(VX_CALLBACK * vx_kernel_deinitialize_f) (vx_node node, const vx_reference *parameters, vx_uint32 num) |
#include <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.
[in] | node | The handle to the node that contains this kernel. |
[in] | parameters | The array of parameter references. |
[in] | num | The number of parameters. |
typedef vx_status(VX_CALLBACK * vx_kernel_f) (vx_node node, const vx_reference *parameters, vx_uint32 num) |
#include <vx_types.h>
The pointer to the Host side kernel.
[in] | node | The handle to the node that contains this kernel. |
[in] | parameters | The array of parameter references. |
[in] | num | The number of parameters. |
typedef vx_status(VX_CALLBACK * vx_kernel_image_valid_rectangle_f) (vx_node node, vx_uint32 index, const vx_rectangle_t *const input_valid[], vx_rectangle_t *const output_valid[]) |
#include <vx_types.h>
A user-defined callback function to set the valid rectangle of an output image.
The VX_VALID_RECT_CALLBACK
attribute in the vx_meta_format
object should be set to the desired callback during user node's output validator. The callback must not call vxGetValidRegionImage
or vxSetImageValidRectangle
. Instead, an array of the valid rectangles of all the input images is supplied to the callback to calculate the output valid rectangle. The output of the user node may be a pyramid, or just an image. If it is just an image, the 'Out' array associated with that output only has one element. If the output is a pyramid, the array size is equal to the number of pyramid levels. Notice that the array memory allocation passed to the callback is managed by the framework, the application must not allocate or deallocate those pointers.
The behavior of the callback function vx_kernel_image_valid_rectangle_f is undefined if one of the following is true:
[in,out] | node | The handle to the node that is being validated. |
[in] | index | The index of the output parameter for which a valid region should be set. |
[in] | input_valid | A pointer to an array of valid regions of input images or images contained in image container (e.g. pyramids). They are provided in same order as the parameter list of the kernel's declaration. |
[out] | output_valid | An array of valid regions that should be set for the output images or image containers (e.g. pyramid) after graph processing. The length of the array should be equal to the size of the image container (e.g. number of levels in the pyramid). For a simple output image the array size is always one. Each rectangle supplies the valid region for one image. The array memory allocation is managed by the framework. |
typedef vx_status(VX_CALLBACK * vx_kernel_initialize_f) (vx_node node, const vx_reference *parameters, vx_uint32 num) |
#include <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.
[in] | node | The handle to the node that contains this kernel. |
[in] | parameters | The array of parameter references. |
[in] | num | The number of parameters. |
typedef vx_status(VX_CALLBACK * vx_kernel_validate_f) (vx_node node, const vx_reference parameters[], vx_uint32 num, vx_meta_format metas[]) |
#include <vx_types.h>
The user-defined kernel node parameters validation function. The function only needs to fill in the meta data structure(s).
[in] | node | The handle to the node that is being validated. |
[in] | parameters | The array of parameters to be validated. |
[in] | num | Number of parameters to be validated. |
[in] | metas | A pointer to a pre-allocated array of structure references that the system holds. The system pre-allocates a number of vx_meta_format structures for the output parameters only, indexed by the same indices as parameters[]. 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. |
typedef struct MetaFormat* vx_meta_format |
#include <vx_types.h>
This object is used by output validation functions to specify the meta data of the expected output data object.
typedef vx_status(VX_API_CALL * vx_publish_kernels_f) (vx_context context) |
#include <vx_types.h>
The type of the vxPublishKernels
entry function of modules loaded by vxLoadKernels
and unloaded by vxUnloadKernels
.
[in] | context | The reference to the context kernels must be added to. |
typedef vx_status(VX_API_CALL * vx_unpublish_kernels_f) (vx_context context) |
#include <vx_types.h>
The type of the vxUnpublishKernels
entry function of modules loaded by vxLoadKernels
and unloaded by vxUnloadKernels
.
[in] | context | The reference to the context kernels have been added to. |
#include <vx_types.h>
The meta valid rectangle attributes.
Enumerator | |
---|---|
VX_VALID_RECT_CALLBACK | Valid rectangle callback during output parameter validation. Write-only. |
VX_API_ENTRY vx_status VX_API_CALL vxAddParameterToKernel | ( | vx_kernel | kernel, |
vx_uint32 | index, | ||
vx_enum | dir, | ||
vx_enum | data_type, | ||
vx_enum | state ) |
#include <vx_api.h>
Allows users to set the signatures of the custom kernel.
[in] | kernel | The reference to the kernel added with vxAddUserKernel . |
[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 . |
[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 . |
vx_status_e
enumerated value. VX_SUCCESS | Parameter is successfully set on kernel; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | kernel is not a valid vx_kernel reference. |
VX_ERROR_INVALID_PARAMETERS | If the parameter is not valid for any reason. |
vxAddUserKernel
VX_API_ENTRY vx_kernel VX_API_CALL vxAddUserKernel | ( | vx_context | context, |
const vx_char | name[VX_MAX_KERNEL_NAME], | ||
vx_enum | enumeration, | ||
vx_kernel_f | func_ptr, | ||
vx_uint32 | numParams, | ||
vx_kernel_validate_f | validate, | ||
vx_kernel_initialize_f | init, | ||
vx_kernel_deinitialize_f | deinit ) |
#include <vx_api.h>
Allows users to add custom kernels to a context at run-time.
[in] | context | The reference to the context the kernel must be added to. |
[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] | validate | The pointer to vx_kernel_validate_f , which validates parameters to this kernel. |
[in] | init | The kernel initialization function. |
[in] | deinit | The kernel de-initialization function. |
vx_kernel
reference. Any possible errors preventing a successful creation should be checked using vxGetStatus
. VX_API_ENTRY vx_status VX_API_CALL vxAllocateUserKernelId | ( | vx_context | context, |
vx_enum * | pKernelEnumId ) |
#include <vx_api.h>
Allocates and registers user-defined kernel enumeration to a context. The allocated enumeration is from available pool of 4096 enumerations reserved for dynamic allocation from VX_KERNEL_BASE(VX_ID_USER,0).
[in] | context | The reference to the implementation context. |
[out] | pKernelEnumId | pointer to return vx_enum for user-defined kernel. |
VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | If the context is not a valid vx_context reference. |
VX_ERROR_NO_RESOURCES | The enumerations has been exhausted. |
VX_API_ENTRY vx_status VX_API_CALL vxAllocateUserKernelLibraryId | ( | vx_context | context, |
vx_enum * | pLibraryId ) |
#include <vx_api.h>
Allocates and registers user-defined kernel library ID to a context.
The allocated library ID is from available pool of library IDs (1..255) reserved for dynamic allocation. The returned libraryId can be used by user-kernel library developer to specify individual kernel enum IDs in a header file, shown below:
[in] | context | The reference to the implementation context. |
[out] | pLibraryId | pointer to vx_enum for user-kernel libraryId. |
VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_NO_RESOURCES | The enumerations has been exhausted. |
VX_API_ENTRY vx_status VX_API_CALL vxFinalizeKernel | ( | vx_kernel | kernel | ) |
#include <vx_api.h>
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 vxAddUserKernel is still valid after the call to vxFinalizeKernel. 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.
[in] | kernel | The reference to the loaded kernel from vxAddUserKernel . |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | kernel is not a valid vx_kernel reference. |
vxAddUserKernel
and vxAddParameterToKernel
VX_API_ENTRY vx_status VX_API_CALL vxLoadKernels | ( | vx_context | context, |
const vx_char * | module ) |
#include <vx_api.h>
Loads a library of kernels, called module, into a context.
The module must be registered by vxRegisterKernelLibrary
if it is not a dynamic library or the module must be a dynamic library with by convention, two exported functions named vxPublishKernels
and vxUnpublishKernels
.
vxPublishKernels
must have type vx_publish_kernels_f
, and must add kernels to the context by calling vxAddUserKernel
for each new kernel. vxPublishKernels
is called by vxLoadKernels
.
vxUnpublishKernels
must have type vx_unpublish_kernels_f
, and must remove kernels from the context by calling vxRemoveKernel
for each kernel the vxPublishKernels
has added. vxUnpublishKernels
is called by vxUnloadKernels
.
[in] | context | The reference to the context the kernels must be added to. |
[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. |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | context is not a valid vx_context reference. |
VX_ERROR_INVALID_PARAMETERS | If any of the other parameters are incorrect. |
vxRegisterKernelLibrary
if the module is not a dynamic library VX_API_ENTRY vx_status VX_API_CALL vxRegisterKernelLibrary | ( | vx_context | context, |
const vx_char * | module, | ||
vx_publish_kernels_f | publish, | ||
vx_unpublish_kernels_f | unpublish ) |
#include <vx_api.h>
Registers a module with kernels in a context.
This function registers the appropriate publish and unpublish functions with the module name if the module is not a dynamic library, so vxLoadKernels
and vxUnloadKernels
can be called.
[in] | context | The reference to the context the kernels must be added to. |
[in] | module | The short name of the module to load. |
[in] | publish | must add kernels to the context by calling vxAddUserKernel for each new kernel. It is called by vxLoadKernels . |
[in] | unpublish | must remove kernels from the context by calling vxRemoveKernel for each kernel the vxPublishKernels has added. It is called by vxUnloadKernels . |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | context is not a valid vx_context reference. |
VX_ERROR_INVALID_PARAMETERS | If any of the other parameters are incorrect. |
VX_API_ENTRY vx_status VX_API_CALL vxRemoveKernel | ( | vx_kernel | kernel | ) |
#include <vx_api.h>
Removes a custom kernel from its context and releases it.
[in] | kernel | The reference to the kernel to remove. Returned from vxAddUserKernel . |
vxAddUserKernel
can be removed. vx_status_e
enumeration. The function returns to the application full control over the memory resources provided at the kernel creation time. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | kernel is not a valid vx_kernel reference. |
VX_ERROR_INVALID_PARAMETERS | If a base kernel is passed in. |
VX_FAILURE | If the application has not released all references to the kernel object OR if the application has not released all references to a node that is using this kernel OR if the application has not released all references to a graph which has nodes that is using this kernel. |
VX_API_ENTRY vx_status VX_API_CALL vxSetKernelAttribute | ( | vx_kernel | kernel, |
vx_enum | attribute, | ||
const void * | ptr, | ||
vx_size | size ) |
#include <vx_api.h>
Sets kernel attributes.
[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. |
vxFinalizeKernel
, no attributes can be altered. vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | kernel is not a valid vx_kernel reference. |
VX_API_ENTRY vx_status VX_API_CALL vxSetMetaFormatAttribute | ( | vx_meta_format | meta, |
vx_enum | attribute, | ||
const void * | ptr, | ||
vx_size | size ) |
#include <vx_api.h>
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:
[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 . |
[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. |
vx_status_e
enumeration. VX_SUCCESS | The attribute was set; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | meta is not a valid vx_meta_format reference. |
VX_ERROR_INVALID_PARAMETERS | 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. |
VX_API_ENTRY vx_status VX_API_CALL vxSetMetaFormatFromReference | ( | vx_meta_format | meta, |
vx_reference | exemplar ) |
#include <vx_api.h>
Set a meta format object from an exemplar data object reference.
This function sets a vx_meta_format object from the meta data of the exemplar
[in] | meta | The meta format object to set |
[in] | exemplar | The exemplar data object. |
vx_status_e
enumeration. VX_SUCCESS | The meta format was correctly set; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | meta is not a valid vx_meta_format reference, or exemplar is not a valid vx_reference reference. |
VX_API_ENTRY vx_status VX_API_CALL vxUnloadKernels | ( | vx_context | context, |
const vx_char * | module ) |
#include <vx_api.h>
Unloads all kernels from the OpenVX context that had been loaded from the module using the vxLoadKernels function.
The kernel unloading is performed by calling the vxUnpublishKernels
exported function of the module.
vxUnpublishKernels
is defined in the description of vxLoadKernels
.[in] | context | The reference to the context the kernels must be removed from. |
[in] | module | The short name of the module to unload. 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. |
vx_status_e
enumeration. VX_SUCCESS | No errors; any other value indicates failure. |
VX_ERROR_INVALID_REFERENCE | context is not a valid vx_context reference. |
VX_ERROR_INVALID_PARAMETERS | If any of the other parameters are incorrect. |