The OpenVX User Data Object extension API. More...

#include <VX/vx.h>

Macros
#define	VX_TYPE_USER_DATA_OBJECT 0x816
	The object type enumeration for user data object. More...

Typedefs
typedef struct _vx_user_data_object *	vx_user_data_object
	The User Data Object. User Data Object is a strongly-typed container for other data structures.

Enumerations
enum	vx_user_data_object_attribute_e { VX_USER_DATA_OBJECT_NAME = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_USER_DATA_OBJECT) + 0x0, VX_USER_DATA_OBJECT_SIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_USER_DATA_OBJECT) + 0x1 }
	The user data object attributes. More...

Functions
VX_API_ENTRY vx_user_data_object VX_API_CALL	vxCreateUserDataObject (vx_context context, const vx_char type_name, vx_size size, const void ptr)
	Creates a reference to a User Data Object. More...

VX_API_ENTRY vx_user_data_object VX_API_CALL	vxCreateVirtualUserDataObject (vx_graph graph, const vx_char *type_name, vx_size size)
	Creates an opaque reference to a virtual User Data Object with no direct user access. More...

VX_API_ENTRY vx_status VX_API_CALL	vxReleaseUserDataObject (vx_user_data_object *user_data_object)
	Releases a reference of a User data object. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed. More...

VX_API_ENTRY vx_status VX_API_CALL	vxQueryUserDataObject (vx_user_data_object user_data_object, vx_enum attribute, void *ptr, vx_size size)
	Queries the User data object for some specific information. More...

VX_API_ENTRY vx_status VX_API_CALL	vxCopyUserDataObject (vx_user_data_object user_data_object, vx_size offset, vx_size size, void *user_ptr, vx_enum usage, vx_enum user_mem_type)
	Allows the application to copy a subset from/into a user data object. More...

VX_API_ENTRY vx_status VX_API_CALL	vxMapUserDataObject (vx_user_data_object user_data_object, vx_size offset, vx_size size, vx_map_id map_id, void *ptr, vx_enum usage, vx_enum mem_type, vx_uint32 flags)
	Allows the application to get direct access to a subset of the user data object. More...

VX_API_ENTRY vx_status VX_API_CALL	vxUnmapUserDataObject (vx_user_data_object user_data_object, vx_map_id map_id)
	Unmap and commit potential changes to a user data object subset that was previously mapped. Unmapping a user data object subset invalidates the memory location from which the subset could be accessed by the application. Accessing this memory location after the unmap function completes is implementation specific. More...

Detailed Description

The OpenVX User Data Object extension API.

Definition in file vx_khr_user_data_object.h.

Macro Definition Documentation

◆ VX_TYPE_USER_DATA_OBJECT

#define VX_TYPE_USER_DATA_OBJECT 0x816

The object type enumeration for user data object.

A vx_user_data_object.

Definition at line 42 of file vx_khr_user_data_object.h.

Enumeration Type Documentation

◆ vx_user_data_object_attribute_e

enum vx_user_data_object_attribute_e

The user data object attributes.

Enumerator
VX_USER_DATA_OBJECT_NAME	The type name of the user data object. Read-only. Use a `vx_char`[`VX_MAX_REFERENCE_NAME`] array.
VX_USER_DATA_OBJECT_SIZE	The number of bytes in the user data object. Read-only. Use a `vx_size` parameter.

Definition at line 47 of file vx_khr_user_data_object.h.

Function Documentation

◆ vxCreateUserDataObject()

VX_API_ENTRY vx_user_data_object VX_API_CALL vxCreateUserDataObject	(	vx_context	context,
		const vx_char *	type_name,
		vx_size	size,
		const void *	ptr
	)

Creates a reference to a User Data Object.

User data objects can be used to pass a user kernel defined data structure or blob of memory as a parameter to a user kernel.

Parameters

[in]	context	The reference to the overall Context.
[in]	type_name	Pointer to the '\0' terminated string that identifies the type of object. The string is copied by the function so that it stays the property of the caller. The length of the string shall be lower than VX_MAX_REFERENCE_NAME bytes. The string passed here is what shall be returned when passing the `VX_USER_DATA_OBJECT_NAME` attribute enum to the `vxQueryUserDataObject` function. In the case where NULL is passed to type_name, then the query of the `VX_USER_DATA_OBJECT_NAME` attribute enum will return a single character '\0' string.
[in]	size	The number of bytes required to store this instance of the user data object.
[in]	ptr	The pointer to the initial value of the user data object. If NULL, then entire size bytes of the user data object is initialized to all 0s, otherwise, `size` bytes is copied into the object from ptr to initialize the object

Returns: A user data object reference vx_user_data_object. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ vxCreateVirtualUserDataObject()

VX_API_ENTRY vx_user_data_object VX_API_CALL vxCreateVirtualUserDataObject	(	vx_graph	graph,
		const vx_char *	type_name,
		vx_size	size
	)

Creates an opaque reference to a virtual User Data Object with no direct user access.

Virtual User Data Objects are useful when the User Data Object is used as internal graph edge. Virtual User Data Objects are scoped within the parent graph only.

Parameters

[in]	graph	The reference to the parent graph.
[in]	type_name	Pointer to the '\0' terminated string that identifies the type of object. The string is copied by the function so that it stays the property of the caller. The length of the string shall be lower than VX_MAX_REFERENCE_NAME bytes. The string passed here is what shall be returned when passing the `VX_USER_DATA_OBJECT_NAME` attribute enum to the `vxQueryUserDataObject` function. In the case where NULL is passed to type_name, then the query of the `VX_USER_DATA_OBJECT_NAME` attribute enum will return a single character '\0' string.
[in]	size	The number of bytes required to store this instance of the user data object.

Returns: A user data object reference vx_user_data_object. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ vxReleaseUserDataObject()

VX_API_ENTRY vx_status VX_API_CALL vxReleaseUserDataObject ( vx_user_data_object * user_data_object )

Releases a reference of a User data object. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed.

Parameters

[in] user_data_object The pointer to the User Data Object to release.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If user_data_object is not a `vx_user_data_object`.

◆ vxQueryUserDataObject()

VX_API_ENTRY vx_status VX_API_CALL vxQueryUserDataObject	(	vx_user_data_object	user_data_object,
		vx_enum	attribute,
		void *	ptr,
		vx_size	size
	)

Queries the User data object for some specific information.

Parameters

[in]	user_data_object	The reference to the User data object.
[in]	attribute	The attribute to query. Use a `vx_user_data_object_attribute_e`.
[out]	ptr	The location at which to store the resulting value.
[in]	size	The size in bytes of the container to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the user_data_object is not a `vx_user_data_object`.
VX_ERROR_NOT_SUPPORTED	If the attribute is not a value supported on this implementation.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

◆ vxCopyUserDataObject()

VX_API_ENTRY vx_status VX_API_CALL vxCopyUserDataObject	(	vx_user_data_object	user_data_object,
		vx_size	offset,
		vx_size	size,
		void *	user_ptr,
		vx_enum	usage,
		vx_enum	user_mem_type
	)

Allows the application to copy a subset from/into a user data object.

Parameters

[in]	user_data_object	The reference to the user data object that is the source or the destination of the copy.
[in]	offset	The byte offset into the user data object to copy.
[in]	size	The number of bytes to copy. The size must be within the bounds of the user data object: 0 <= (offset + size) <= size of the user data object. If zero, then copy until the end of the object.
[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 user data object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified size.
[in]	usage	This declares the effect of the copy with regard to the user data object using the `vx_accessor_e` enumeration. Only VX_READ_ONLY and VX_WRITE_ONLY are supported: VX_READ_ONLY means that data are copied from the user data object into the user memory. VX_WRITE_ONLY means that data are copied into the user data object from the user memory.
[in]	user_mem_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 user data object that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	The user_data_object reference is not actually a user data object reference.
VX_ERROR_INVALID_PARAMETERS	Another parameter is incorrect.

◆ vxMapUserDataObject()

VX_API_ENTRY vx_status VX_API_CALL vxMapUserDataObject	(	vx_user_data_object	user_data_object,
		vx_size	offset,
		vx_size	size,
		vx_map_id *	map_id,
		void **	ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_uint32	flags
	)

Allows the application to get direct access to a subset of the user data object.

Parameters

[in]	user_data_object	The reference to the user data object that contains the subset to map.
[in]	offset	The byte offset into the user data object to map.
[in]	size	The number of bytes to map. The size must be within the bounds of the user data object: 0 <= (offset + size) <= size of the user data object. If zero, then map until the end of the object.
[out]	map_id	The address of a vx_map_id variable where the function returns a map identifier. (*map_id) must eventually be provided as the map_id parameter of a call to `vxUnmapUserDataObject`.
[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 `vxUnmapUserDataObject`.
[in]	usage	This declares the access mode for the user data object subset, using the `vx_accessor_e` enumeration. VX_READ_ONLY: after the function call, the content of the memory location pointed by (ptr) contains the user data object subset data. Writing into this memory location is forbidden and its behavior is implementation specific. VX_READ_AND_WRITE : after the function call, the content of the memory location pointed by (ptr) contains the user data object subset data; writing into this memory is allowed only for the location of data and will result in a modification of the affected data in the user data object once the subset is unmapped. VX_WRITE_ONLY: after the function call, the memory location pointed by (*ptr) contains undefined data; writing to all data in the subset is required prior to unmapping. Data values not written by the application before unmap may be defined differently in different implementations after unmap, even if they were well defined before map.
[in]	mem_type	A `vx_memory_type_e` enumeration that specifies the type of the memory where the user data object subset is requested to be mapped.
[in]	flags	An integer that allows passing options to the map operation. Use the `vx_map_flag_e` enumeration.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual user data object that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	The user_data_object reference is not actually a user data object reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Postcondition: vxUnmapUserDataObject with same (*map_id) value.

◆ vxUnmapUserDataObject()

VX_API_ENTRY vx_status VX_API_CALL vxUnmapUserDataObject	(	vx_user_data_object	user_data_object,
		vx_map_id	map_id
	)

Unmap and commit potential changes to a user data object subset that was previously mapped. Unmapping a user data object subset invalidates the memory location from which the subset could be accessed by the application. Accessing this memory location after the unmap function completes is implementation specific.

Parameters

[in]	user_data_object	The reference to the user data object to unmap.
[in]	map_id	The unique map identifier that was returned when calling `vxMapUserDataObject` .

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_INVALID_REFERENCE	The user_data_object reference is not actually a user data object reference.
VX_ERROR_INVALID_PARAMETERS	Another parameter is incorrect.

Precondition: vxMapUserDataObject returning the same map_id value

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ VX_TYPE_USER_DATA_OBJECT

Enumeration Type Documentation

◆ vx_user_data_object_attribute_e

Function Documentation

◆ vxCreateUserDataObject()

◆ vxCreateVirtualUserDataObject()

◆ vxReleaseUserDataObject()

◆ vxQueryUserDataObject()

◆ vxCopyUserDataObject()

◆ vxMapUserDataObject()

◆ vxUnmapUserDataObject()