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

enum vx_tensor_attribute_e

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

Detailed Description

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation