The OpenVX Specification  dba1aa3
Object: Tensor

## Detailed Description

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 non-zero radix point. As an example: VX_TYPE_INT16 element with radix point of 8, corresponds to Q7.8 signed fixed-point 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 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. 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 Documentation

 typedef struct _vx_tensor_t* vx_tensor

The multidimensional data object (Tensor).

See also
vxCreateTensor

Definition at line 284 of file vx_types.h.

## Enumeration Type Documentation

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_type_e

VX_TENSOR_FIXED_POINT_POSITION

fixed point position when the input element type is integer.

Definition at line 1168 of file vx_types.h.

## Function Documentation

 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.

Parameters
 [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.
Returns
A tensor data reference. Any possible errors preventing a successful creation should be checked using 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 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.

Parameters
 [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.
Returns
An array of images pointing to the tensor data's data.
 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.

Parameters
 [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
Returns
The reference to the sub-tensor. Any possible errors preventing a successful creation should be checked using 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.

Parameters
 [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.
Returns
A tensor data reference.Any possible errors preventing a successful creation should be checked using vxGetStatus.
Note
Passing this reference to 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 .

Parameters
 [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: VX_READ_ONLY means that data is copied from the tensor object into the application memory VX_WRITE_ONLY means that data is copied into the tensor object from the application memory [in] user_memory_type A vx_memory_type_e enumeration that specifies the memory type of the memory referenced by the user_addr.
Returns
A vx_status_e enumeration.
Return values
 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.

Parameters
 [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.
Returns
A vx_status_e enumeration.
Return values
 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.

Parameters
 [in] tensor The pointer to the tensor data to release.
Postcondition
After returning from this function the reference is zeroed.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors; all other values indicate failure * An error occurred. See vx_status_e.