CoreFlow 1.0.0
A modern orchestration and execution runtime
Loading...
Searching...
No Matches
User Facing User Kernels API

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_CALLvx_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_CALLvx_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_CALLBACKvx_kernel_f) (vx_node node, const vx_reference *parameters, vx_uint32 num)
 The pointer to the Host side kernel.
 
typedef vx_status(VX_CALLBACKvx_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_CALLBACKvx_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_CALLBACKvx_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_CALLBACKvx_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.
 

Detailed Description

The Public User Kernels API.

Typedef Documentation

◆ vx_kernel_deinitialize_f

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.

Parameters
[in]nodeThe handle to the node that contains this kernel.
[in]parametersThe array of parameter references.
[in]numThe number of parameters.

◆ vx_kernel_f

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.

Parameters
[in]nodeThe handle to the node that contains this kernel.
[in]parametersThe array of parameter references.
[in]numThe number of parameters.

◆ vx_kernel_image_valid_rectangle_f

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:

  • One of the input arguments of a user node is a pyramid or an array of images.
  • Either input or output argument of a user node is an array of pyramids.
Parameters
[in,out]nodeThe handle to the node that is being validated.
[in]indexThe index of the output parameter for which a valid region should be set.
[in]input_validA 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_validAn 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.
Returns
An error code describing the validation status on parameters.

◆ vx_kernel_initialize_f

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.

Parameters
[in]nodeThe handle to the node that contains this kernel.
[in]parametersThe array of parameter references.
[in]numThe number of parameters.

◆ vx_kernel_validate_f

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).

Note
This function is called once for whole set of parameters.
Parameters
[in]nodeThe handle to the node that is being validated.
[in]parametersThe array of parameters to be validated.
[in]numNumber of parameters to be validated.
[in]metasA 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.
Returns
An error code describing the validation status on parameters.

◆ vx_meta_format

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.

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.

◆ vx_publish_kernels_f

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.

Parameters
[in]contextThe reference to the context kernels must be added to.

◆ vx_unpublish_kernels_f

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.

Parameters
[in]contextThe reference to the context kernels have been added to.

Enumeration Type Documentation

◆ vx_meta_valid_rect_attribute_e

#include <vx_types.h>

The meta valid rectangle attributes.

Enumerator
VX_VALID_RECT_CALLBACK 

Valid rectangle callback during output parameter validation. Write-only.

Function Documentation

◆ vxAddParameterToKernel()

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.

Parameters
[in]kernelThe reference to the kernel added with vxAddUserKernel.
[in]indexThe index of the parameter to add.
[in]dirThe direction of the parameter. This must be either VX_INPUT or VX_OUTPUT.
[in]data_typeThe type of parameter. This must be a value from vx_type_e.
[in]stateThe 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_SUCCESSParameter is successfully set on kernel; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEkernel is not a valid vx_kernel reference.
VX_ERROR_INVALID_PARAMETERSIf the parameter is not valid for any reason.
Precondition
vxAddUserKernel

◆ 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.

Parameters
[in]contextThe reference to the context the kernel must be added to.
[in]nameThe string to use to match the kernel.
[in]enumerationThe enumerated value of the kernel to be used by clients.
[in]func_ptrThe process-local function pointer to be invoked.
[in]numParamsThe number of parameters for this kernel.
[in]validateThe pointer to vx_kernel_validate_f, which validates parameters to this kernel.
[in]initThe kernel initialization function.
[in]deinitThe kernel de-initialization function.
Returns
A vx_kernel reference. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ vxAllocateUserKernelId()

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).

Parameters
[in]contextThe reference to the implementation context.
[out]pKernelEnumIdpointer to return vx_enum for user-defined kernel.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEIf the context is not a valid vx_context reference.
VX_ERROR_NO_RESOURCESThe enumerations has been exhausted.

◆ vxAllocateUserKernelLibraryId()

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:

#define MY_KERNEL_ID1(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 0);
#define MY_KERNEL_ID2(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 1);
#define MY_KERNEL_ID3(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 2);
Parameters
[in]contextThe reference to the implementation context.
[out]pLibraryIdpointer to vx_enum for user-kernel libraryId.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_NO_RESOURCESThe enumerations has been exhausted.

◆ vxFinalizeKernel()

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.

Parameters
[in]kernelThe reference to the loaded kernel from vxAddUserKernel.
Returns
A vx_status_e enumeration.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEkernel is not a valid vx_kernel reference.
Precondition
vxAddUserKernel and vxAddParameterToKernel

◆ vxLoadKernels()

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.

Note
When all references to loaded kernels are released, the module may be automatically unloaded.
Parameters
[in]contextThe reference to the context the kernels must be added to.
[in]moduleThe 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_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEcontext is not a valid vx_context reference.
VX_ERROR_INVALID_PARAMETERSIf any of the other parameters are incorrect.
Precondition
vxRegisterKernelLibrary if the module is not a dynamic library
See also
vxGetKernelByName
Examples
bubble_pop.cpp, and orb.cpp.

◆ vxRegisterKernelLibrary()

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.

Parameters
[in]contextThe reference to the context the kernels must be added to.
[in]moduleThe short name of the module to load.
[in]publishmust add kernels to the context by calling vxAddUserKernel for each new kernel. It is called by vxLoadKernels.
[in]unpublishmust remove kernels from the context by calling vxRemoveKernel for each kernel the vxPublishKernels has added. It is called by vxUnloadKernels.
Returns
A vx_status_e enumeration.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEcontext is not a valid vx_context reference.
VX_ERROR_INVALID_PARAMETERSIf any of the other parameters are incorrect.
See also
vxLoadKernels

◆ vxRemoveKernel()

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.

Parameters
[in]kernelThe reference to the kernel to remove. Returned from vxAddUserKernel.
Note
Any kernel enumerated in the base standard cannot be removed; only kernels added through vxAddUserKernel can be removed.
Returns
A vx_status_e enumeration. The function returns to the application full control over the memory resources provided at the kernel creation time.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEkernel is not a valid vx_kernel reference.
VX_ERROR_INVALID_PARAMETERSIf a base kernel is passed in.
VX_FAILUREIf 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.

◆ vxSetKernelAttribute()

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.

Parameters
[in]kernelThe reference to the kernel.
[in]attributeThe enumeration of the attributes. See vx_kernel_attribute_e.
[in]ptrThe pointer to the location from which to read the attribute.
[in]sizeThe 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.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEkernel is not a valid vx_kernel reference.

◆ vxSetMetaFormatAttribute()

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:

◆ vxSetMetaFormatFromReference()

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

Parameters
[in]metaThe meta format object to set
[in]exemplarThe exemplar data object.
Returns
A vx_status_e enumeration.
Return values
VX_SUCCESSThe meta format was correctly set; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEmeta is not a valid vx_meta_format reference, or exemplar is not a valid vx_reference reference.

◆ vxUnloadKernels()

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.

Note
vxUnpublishKernels is defined in the description of vxLoadKernels.
Parameters
[in]contextThe reference to the context the kernels must be removed from.
[in]moduleThe 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.
Note
This API uses the system pre-defined paths for modules.
Returns
A vx_status_e enumeration.
Return values
VX_SUCCESSNo errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCEcontext is not a valid vx_context reference.
VX_ERROR_INVALID_PARAMETERSIf any of the other parameters are incorrect.
See also
vxLoadKernels