The OpenVX Specification
dba1aa3

Defines The Tensor Object Interface.
The vx_tensor
object represents an opaque multidimensional array. The object is said to be opaque because the programmer has no visibility into the internal implementation of the object, and can only manipulate them via the defined API. Implementations can apply many optimizations that are transparent to the user. OpenVX implementations must support vx_tensor
objects of at least 4 dimensions, although a vendor can choose to support more dimensions in his implementation. The maximum number of dimensions supported by a given implementation can be queried via the context attribute VX_CONTEXT_MAX_TENSOR_DIMS
. Implementations must support tensors from one dimension (i.e., vectors) through VX_CONTEXT_MAX_TENSOR_DIMS
, inclusive. The individual elements of the tensor object may be any numerical data type. For each kernel in the specification, it is specified which data types a compliant implementations must support. Integer elements can represent fractional values by assigning a nonzero radix point. As an example: VX_TYPE_INT16
element with radix point of 8, corresponds to Q7.8 signed fixedpoint in “Q” notation. A vendor may choose to support whatever values for the radix point in his implementation. 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. Therefore the layout description is logical and not physical. It refers to the order of dimensions given in vxCreateTensor
and vxCreateVirtualTensor
.
Typedefs  
typedef struct _vx_tensor_t *  vx_tensor 
The multidimensional data object (Tensor). More...  
Enumerations  
enum  vx_tensor_attribute_e { VX_TENSOR_NUMBER_OF_DIMS = ((( VX_ID_KHRONOS ) << 20)  ( VX_TYPE_TENSOR << 8)) + 0x0, VX_TENSOR_DIMS = ((( VX_ID_KHRONOS ) << 20)  ( VX_TYPE_TENSOR << 8)) + 0x1, VX_TENSOR_DATA_TYPE = ((( VX_ID_KHRONOS ) << 20)  ( VX_TYPE_TENSOR << 8)) + 0x2, VX_TENSOR_FIXED_POINT_POSITION = ((( VX_ID_KHRONOS ) << 20)  ( VX_TYPE_TENSOR << 8)) + 0x3 } 
tensor Data attributes. More...  
Functions  
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 . More...  
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 multidimension 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. More...  
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. More...  
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. More...  
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. More...  
vx_status VX_API_CALL  vxQueryTensor (vx_tensor tensor, vx_enum attribute, void *ptr, vx_size size) 
Retrieves various attributes of a tensor data. More...  
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. More...  
typedef struct _vx_tensor_t* vx_tensor 
The multidimensional data object (Tensor).
Definition at line 284 of file vx_types.h.
tensor Data attributes.
Definition at line 1168 of file vx_types.h.
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.
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_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 multidimension 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_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.
[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_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.
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_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 .
[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_status VX_API_CALL vxQueryTensor  (  vx_tensor  tensor, 
vx_enum  attribute,  
void *  ptr,  
vx_size  size  
) 
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_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.
[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 . 