|
CoreFlow 1.0.0
A modern orchestration and execution runtime
|
The Public Tensor API. More...
Typedefs | |
| typedef struct Tensor * | vx_tensor |
| The multidimensional data object (Tensor). | |
Enumerations | |
| enum | vx_tensor_attribute_e { VX_TENSOR_NUMBER_OF_DIMS = VX_ATTRIBUTE_BASE( VX_ID_KHRONOS, VX_TYPE_TENSOR ) + 0x0 , VX_TENSOR_DIMS = VX_ATTRIBUTE_BASE( VX_ID_KHRONOS, VX_TYPE_TENSOR ) + 0x1 , VX_TENSOR_DATA_TYPE = VX_ATTRIBUTE_BASE( VX_ID_KHRONOS, VX_TYPE_TENSOR ) + 0x2 , VX_TENSOR_FIXED_POINT_POSITION = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_TENSOR) + 0x3 } |
| tensor Data attributes. More... | |
Functions | |
| VX_API_ENTRY vx_tensor VX_API_CALL | vxCreateTensor (vx_context context, vx_size number_of_dims, const vx_size *dims, vx_enum data_type, vx_int8 fixed_point_position) |
| Creates an opaque reference to a tensor data buffer. | |
| VX_API_ENTRY vx_object_array VX_API_CALL | vxCreateImageObjectArrayFromTensor (vx_tensor tensor, const vx_rectangle_t *rect, vx_size array_size, vx_size jump, vx_df_image image_format) |
| Creates an array of images into the multi-dimension data, this can be adjacent 2D images or not depending on the stride value. The stride value is representing bytes in the third dimension. The OpenVX image object that points to a three dimension data and access it as an array of images. This has to be portion of the third lowest dimension, and the stride correspond to that third dimension. The returned Object array is an array of images. Where the image data is pointing to a specific memory in the input tensor. | |
| VX_API_ENTRY vx_tensor VX_API_CALL | vxCreateTensorFromView (vx_tensor tensor, vx_size number_of_dims, const vx_size *view_start, const vx_size *view_end) |
| Creates a tensor data from another tensor data given a view. This second reference refers to the data in the original tensor data. Updates to this tensor data updates the parent tensor data. The view must be defined within the dimensions of the parent tensor data. | |
| VX_API_ENTRY vx_tensor VX_API_CALL | vxCreateVirtualTensor (vx_graph graph, vx_size number_of_dims, const vx_size *dims, vx_enum data_type, vx_int8 fixed_point_position) |
| Creates an opaque reference to a tensor data buffer with no direct user access. This function allows setting the tensor data dimensions or data format. | |
| VX_API_ENTRY vx_tensor VX_API_CALL | vxCreateTensorFromHandle (vx_context context, vx_size number_of_dims, const vx_size *dims, vx_enum data_type, vx_int8 fixed_point_position, const vx_size *stride, void *ptr, vx_enum memory_type) |
| Creates a reference to an tensor object that was externally allocated. | |
| VX_API_ENTRY vx_status VX_API_CALL | vxSwapTensorHandle (vx_tensor tensor, void *new_ptr, void **prev_ptr) |
| Swaps the tensor handle of an tensor previously created from handle. | |
| VX_API_ENTRY vx_status VX_API_CALL | vxCopyTensorPatch (vx_tensor tensor, vx_size number_of_dims, const vx_size *view_start, const vx_size *view_end, const vx_size *user_stride, void *user_ptr, vx_enum usage, vx_enum user_memory_type) |
| Allows the application to copy a view patch from/into an tensor object . | |
| VX_API_ENTRY vx_status VX_API_CALL | vxMapTensorPatch (vx_tensor tensor, vx_size number_of_dims, const vx_size *view_start, const vx_size *view_end, vx_map_id *map_id, vx_size *stride, void **ptr, vx_enum usage, vx_enum mem_type) |
| Allows the application to get direct access to a patch of tensor object. | |
| VX_API_ENTRY vx_status VX_API_CALL | vxUnmapTensorPatch (vx_tensor tensor, const vx_map_id map_id) |
| Unmap and commit potential changes to a tensor object patch that was previously mapped. Unmapping a tensor patch invalidates the memory location from which the patch could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior. | |
| VX_API_ENTRY vx_status VX_API_CALL | vxQueryTensor (vx_tensor tensor, vx_enum attribute, void *ptr, vx_size size) |
| Retrieves various attributes of a tensor data. | |
| VX_API_ENTRY vx_status VX_API_CALL | vxReleaseTensor (vx_tensor *tensor) |
| Releases a reference to a tensor data object. The object may not be garbage collected until its total reference count is zero. | |
The Public Tensor API.
| typedef struct Tensor* vx_tensor |
#include <vx_types.h>
tensor Data attributes.
| Enumerator | |
|---|---|
| VX_TENSOR_NUMBER_OF_DIMS | Number of dimensions. |
| VX_TENSOR_DIMS | Dimension sizes. |
| VX_TENSOR_DATA_TYPE | tensor Data element data type. |
| VX_TENSOR_FIXED_POINT_POSITION | fixed point position when the input element type is integer. |
| VX_API_ENTRY vx_status VX_API_CALL vxCopyTensorPatch | ( | vx_tensor | tensor, |
| vx_size | number_of_dims, | ||
| const vx_size * | view_start, | ||
| const vx_size * | view_end, | ||
| const vx_size * | user_stride, | ||
| void * | user_ptr, | ||
| vx_enum | usage, | ||
| vx_enum | user_memory_type ) |
#include <vx_api.h>
Allows the application to copy a view patch from/into an tensor object .
| [in] | tensor | The reference to the tensor object that is the source or the destination of the copy. |
| [in] | number_of_dims | Number of patch dimension. Error return if 0 or greater than number of tensor dimensions. If smaller than number of tensor dimensions, the lower dimensions are assumed. |
| [in] | view_start | Array of patch start points in each dimension |
| [in] | view_end | Array of patch end points in each dimension |
| [in] | user_stride | Array of user memory strides in each dimension |
| [in] | user_ptr | The address of the memory location where to store the requested data if the copy was requested in read mode, or from where to get the data to store into the tensor object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified patch with the specified layout: accessible memory in bytes >= (end[last_dimension] - start[last_dimension]) * stride[last_dimension]. The layout of the user memory must follow a row major order. |
| [in] | usage | This declares the effect of the copy with regard to the tensor object using the vx_accessor_e enumeration. Only VX_READ_ONLY and VX_WRITE_ONLY are supported:
|
| [in] | user_memory_type | A vx_memory_type_e enumeration that specifies the memory type of the memory referenced by the user_addr. |
vx_status_e enumeration. | VX_ERROR_OPTIMIZED_AWAY | This is a reference to a virtual tensor that cannot be accessed by the application. |
| VX_ERROR_INVALID_REFERENCE | The tensor reference is not actually an tensor reference. |
| VX_ERROR_INVALID_PARAMETERS | An other parameter is incorrect. |
| VX_API_ENTRY vx_object_array VX_API_CALL vxCreateImageObjectArrayFromTensor | ( | vx_tensor | tensor, |
| const vx_rectangle_t * | rect, | ||
| vx_size | array_size, | ||
| vx_size | jump, | ||
| vx_df_image | image_format ) |
#include <vx_api.h>
Creates an array of images into the multi-dimension data, this can be adjacent 2D images or not depending on the stride value. The stride value is representing bytes in the third dimension. The OpenVX image object that points to a three dimension data and access it as an array of images. This has to be portion of the third lowest dimension, and the stride correspond to that third dimension. The returned Object array is an array of images. Where the image data is pointing to a specific memory in the input tensor.
| [in] | tensor | The tensor data from which to extract the images. Has to be a 3d tensor. |
| [in] | rect | Image coordinates within tensor data. |
| [in] | array_size | Number of images to extract. |
| [in] | jump | Delta between two images in the array. |
| [in] | image_format | The requested image format. Should match the tensor data's data type. |
| VX_API_ENTRY vx_tensor VX_API_CALL vxCreateTensor | ( | vx_context | context, |
| vx_size | number_of_dims, | ||
| const vx_size * | dims, | ||
| vx_enum | data_type, | ||
| vx_int8 | fixed_point_position ) |
#include <vx_api.h>
Creates an opaque reference to a tensor data buffer.
Not guaranteed to exist until the vx_graph containing it has been verified. Since functions using tensors, need to understand the context of each dimension. We describe a layout of the dimensions in each function using tensors. That layout is not mandatory. It is done specifically to explain the functions and not to mandate layout. Different implementation may have different layout. Therefore the layout description is logical and not physical. It refers to the order of dimensions given in this function.
| [in] | context | The reference to the implementation context. |
| [in] | number_of_dims | The number of dimensions. |
| [in] | dims | Dimensions sizes in elements. |
| [in] | data_type | The vx_type_e that represents the data type of the tensor data elements. |
| [in] | fixed_point_position | Specifies the fixed point position when the input element type is integer. if 0, calculations are performed in integer math. |
vxGetStatus. | VX_API_ENTRY vx_tensor VX_API_CALL vxCreateTensorFromHandle | ( | vx_context | context, |
| vx_size | number_of_dims, | ||
| const vx_size * | dims, | ||
| vx_enum | data_type, | ||
| vx_int8 | fixed_point_position, | ||
| const vx_size * | stride, | ||
| void * | ptr, | ||
| vx_enum | memory_type ) |
#include <vx_api.h>
Creates a reference to an tensor object that was externally allocated.
| [in] | context | The reference to the implementation context. |
| [in] | number_of_dims | The number of dimensions. |
| [in] | dims | Dimensions sizes in elements. |
| [in] | data_type | The vx_type_e that represents the data type of the tensor data elements. |
| [in] | fixed_point_position | Specifies the fixed point position when the input element type is integer. if 0, calculations are performed in integer math. |
| [in] | stride | An array of stride in all dimensions in bytes. The stride value at index 0 must be size of the tensor data element type. |
| [in] | ptr | The platform-defined reference to tensor. See note below. |
| [in] | memory_type | vx_memory_type_e. When giving VX_MEMORY_TYPE_HOST the ptr is assumed to be HOST accessible pointer to memory. |
vxGetStatus. vxCreateTensorFromHandle. Reads or writes to memory referenced by ptr after calling vxCreateTensorFromHandle without first calling vxMapTensorPatch will result in undefined behavior. The property of stride[] and ptr is kept by the caller (It means that the implementation will make an internal copy of the provided information. stride and ptr can then simply be application's local variables).In order to release the tensor back to the application we should use vxSwapTensorHandle.
| VX_API_ENTRY vx_tensor VX_API_CALL vxCreateTensorFromView | ( | vx_tensor | tensor, |
| vx_size | number_of_dims, | ||
| const vx_size * | view_start, | ||
| const vx_size * | view_end ) |
#include <vx_api.h>
Creates a tensor data from another tensor data given a view. This second reference refers to the data in the original tensor data. Updates to this tensor data updates the parent tensor data. The view must be defined within the dimensions of the parent tensor data.
| [in] | tensor | The reference to the parent tensor data. |
| [in] | number_of_dims | Number of dimensions in the view. Error return if 0 or greater than number of tensor dimensions. If smaller than number of tensor dimensions, the lower dimensions are assumed. |
| [in] | view_start | View start coordinates |
| [in] | view_end | View end coordinates |
vxGetStatus. | VX_API_ENTRY vx_tensor VX_API_CALL vxCreateVirtualTensor | ( | vx_graph | graph, |
| vx_size | number_of_dims, | ||
| const vx_size * | dims, | ||
| vx_enum | data_type, | ||
| vx_int8 | fixed_point_position ) |
#include <vx_api.h>
Creates an opaque reference to a tensor data buffer with no direct user access. This function allows setting the tensor data dimensions or data format.
Virtual data objects allow users to connect various nodes within a graph via data references without access to that data, but they also permit the implementation to take maximum advantage of possible optimizations. Use this API to create a data reference to link two or more nodes together when the intermediate data are not required to be accessed by outside entities. This API in particular allows the user to define the tensor data format of the data without requiring the exact dimensions. Virtual objects are scoped within the graph they are declared a part of, and can't be shared outside of this scope. Since functions using tensors, need to understand the context of each dimension. We describe a layout of the dimensions in each function. That layout is not mandated. It is done specifically to explain the functions and not to mandate layout. Different implementation may have different layout. Therfore the layout description is logical and not physical. It refers to the order of dimensions given in vxCreateTensor and vxCreateVirtualTensor.
| [in] | graph | The reference to the parent graph. |
| [in] | number_of_dims | The number of dimensions. |
| [in] | dims | Dimensions sizes in elements. |
| [in] | data_type | The vx_type_e that represents the data type of the tensor data elements. |
| [in] | fixed_point_position | Specifies the fixed point position when the input element type is integer. If 0, calculations are performed in integer math. |
vxGetStatus. vxCopyTensorPatch will return an error. | VX_API_ENTRY vx_status VX_API_CALL vxMapTensorPatch | ( | vx_tensor | tensor, |
| vx_size | number_of_dims, | ||
| const vx_size * | view_start, | ||
| const vx_size * | view_end, | ||
| vx_map_id * | map_id, | ||
| vx_size * | stride, | ||
| void ** | ptr, | ||
| vx_enum | usage, | ||
| vx_enum | mem_type ) |
#include <vx_api.h>
Allows the application to get direct access to a patch of tensor object.
| [in] | tensor | The reference to the tensor object that is the source or the destination for direct access. |
| [in] | number_of_dims | The number of dimensions. Must be same as tensor number_of_dims. |
| [in] | view_start | Array of patch start points in each dimension. This is optional parameter and will be zero when NULL. |
| [in] | view_end | Array of patch end points in each dimension. This is optional parameter and will be dims[] of tensor when NULL. |
| [out] | map_id | The address of a vx_map_id variable where the function returns a map identifier.
|
| [out] | stride | An array of stride in all dimensions in bytes. The stride value at index 0 must be size of the tensor data element type. |
| [out] | ptr | The address of a pointer that the function sets to the address where the requested data can be accessed. The returned (*ptr) address is only valid between the call to the function and the corresponding call to vxUnmapTensorPatch. |
| [in] | usage | This declares the access mode for the tensor patch, using the vx_accessor_e enumeration.
|
| [in] | mem_type | A vx_memory_type_e enumeration that specifies the type of the memory where the tensor patch is requested to be mapped. |
vx_status_e enumeration. | VX_ERROR_OPTIMIZED_AWAY | This is a reference to a virtual tensor that cannot be accessed by the application. |
| VX_ERROR_INVALID_REFERENCE | The tensor reference is not actually an tensor reference. |
| VX_ERROR_INVALID_PARAMETERS | An other parameter is incorrect. |
| VX_ERROR_NO_MEMORY | Internal memory allocation failed. |
vxUnmapTensorPatch with same (*map_id) value. | VX_API_ENTRY vx_status VX_API_CALL vxQueryTensor | ( | vx_tensor | tensor, |
| vx_enum | attribute, | ||
| void * | ptr, | ||
| vx_size | size ) |
#include <vx_api.h>
Retrieves various attributes of a tensor data.
| [in] | tensor | The reference to the tensor data to query. |
| [in] | attribute | The attribute to query. Use a vx_tensor_attribute_e. |
| [out] | ptr | The location at which to store the resulting value. |
| [in] | size | The size of the container to which ptr points. |
vx_status_e enumeration. | VX_SUCCESS | No errors. |
| VX_ERROR_INVALID_REFERENCE | If data is not a vx_tensor. |
| VX_ERROR_INVALID_PARAMETERS | If any of the other parameters are incorrect. |
| VX_API_ENTRY vx_status VX_API_CALL vxReleaseTensor | ( | vx_tensor * | tensor | ) |
#include <vx_api.h>
Releases a reference to a tensor data object. The object may not be garbage collected until its total reference count is zero.
| [in] | tensor | The pointer to the tensor data to release. |
vx_status_e enumeration. | VX_SUCCESS | No errors; all other values indicate failure |
| * | An error occurred. See vx_status_e. |
| VX_API_ENTRY vx_status VX_API_CALL vxSwapTensorHandle | ( | vx_tensor | tensor, |
| void * | new_ptr, | ||
| void ** | prev_ptr ) |
#include <vx_api.h>
Swaps the tensor handle of an tensor previously created from handle.
This function sets the new tensor handle and returns the previous one.
Once this function call has completed, the application gets back the ownership of the memory referenced by the previous handle. This memory contains up-to-date tensor data, and the application can safely reuse or release it.
The memory referenced by the new handle must have been allocated consistently with the tensor properties since the import type, memory layout and dimensions are unchanged (see stride and memory_type in vxCreateTensorFromHandle).
All tensors created from view with this tensor as parent or ancestor will automatically use the memory referenced by the new handle.
The behavior of vxSwapTensorHandle when called from a user node is undefined.
| [in] | tensor | The reference to an tensor created from handle. |
| [in] | new_ptr | new tensor handle If new_ptr is NULL, If the new_ptr is NULL, the previous tensor storage memory is reclaimed by the caller, while no new handle is provided. |
| [out] | prev_ptr | pointer to return the previous tensor handle. If prev_ptr is NULL, the previous handle is not returned. |
vx_status_e enumeration. | VX_SUCCESS | No errors. |
| VX_ERROR_INVALID_REFERENCE | tensor is not a valid vx_tensor reference. reference. |
| VX_ERROR_INVALID_PARAMETERS | The tensor was not created from handle or the content of new_ptr is not valid. |
| VX_FAILURE | The tensor was already being accessed. |
| VX_API_ENTRY vx_status VX_API_CALL vxUnmapTensorPatch | ( | vx_tensor | tensor, |
| const vx_map_id | map_id ) |
#include <vx_api.h>
Unmap and commit potential changes to a tensor object patch that was previously mapped. Unmapping a tensor patch invalidates the memory location from which the patch could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.
| [in] | tensor | The reference to the tensor object to unmap. |
| [in] | map_id | The unique map identifier that was returned when calling vxMapTensorPatch . |
vx_status_e enumeration. | VX_ERROR_INVALID_REFERENCE | The tensor reference is not actually an tensor reference. |
| VX_ERROR_INVALID_PARAMETERS | An other parameter is incorrect. |
vxMapTensorPatch returning the same map_id value