Detailed Description

Defines the Distribution Object Interface.

Typedefs
typedef struct _vx_distribution *	vx_distribution
	The Distribution object. This has a user-defined number of bins over a user-defined range (within a uint32_t range).

Enumerations
enum	vx_distribution_attribute_e { VX_DISTRIBUTION_DIMENSIONS = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x0, VX_DISTRIBUTION_OFFSET = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x1, VX_DISTRIBUTION_RANGE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x2, VX_DISTRIBUTION_BINS = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x3, VX_DISTRIBUTION_WINDOW = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x4, VX_DISTRIBUTION_SIZE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_DISTRIBUTION << 8)) + 0x5 }
	The distribution attribute list. More...

Functions
vx_status VX_API_CALL	vxCopyDistribution (vx_distribution distribution, void *user_ptr, vx_enum usage, vx_enum user_mem_type)
	Allows the application to copy from/into a distribution object. More...

vx_distribution VX_API_CALL	vxCreateDistribution (vx_context context, vx_size numBins, vx_int32 offset, vx_uint32 range)
	Creates a reference to a 1D Distribution of a consecutive interval [offset, offset + range - 1] defined by a start offset and valid range, divided equally into numBins parts. More...

vx_distribution VX_API_CALL	vxCreateVirtualDistribution (vx_graph graph, vx_size numBins, vx_int32 offset, vx_uint32 range)
	Creates an opaque reference to a 1D Distribution object without direct user access. More...

vx_status VX_API_CALL	vxMapDistribution (vx_distribution distribution, vx_map_id map_id, void *ptr, vx_enum usage, vx_enum mem_type, vx_bitfield flags)
	Allows the application to get direct access to distribution object. More...

vx_status VX_API_CALL	vxQueryDistribution (vx_distribution distribution, vx_enum attribute, void *ptr, vx_size size)
	Queries a Distribution object. More...

vx_status VX_API_CALL	vxReleaseDistribution (vx_distribution *distribution)
	Releases a reference to a distribution object. The object may not be garbage collected until its total reference count is zero. More...

vx_status VX_API_CALL	vxUnmapDistribution (vx_distribution distribution, vx_map_id map_id)
	Unmap and commit potential changes to distribution object that was previously mapped. Unmapping a distribution invalidates the memory location from which the distribution data could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior. More...

Enumeration Type Documentation

enum vx_distribution_attribute_e

The distribution attribute list.

Enumerator
VX_DISTRIBUTION_DIMENSIONS	Indicates the number of dimensions in the distribution. Read-only. Use a `vx_size` parameter.
VX_DISTRIBUTION_OFFSET	Indicates the start of the values to use (inclusive). Read-only. Use a `vx_int32` parameter.
VX_DISTRIBUTION_RANGE	Indicates the total number of the consecutive values of the distribution interval.
VX_DISTRIBUTION_BINS	Indicates the number of bins. Read-only. Use a `vx_size` parameter.
VX_DISTRIBUTION_WINDOW	Indicates the width of a bin. Equal to the range divided by the number of bins. If the range is not a multiple of the number of bins, it is not valid. Read-only. Use a `vx_uint32` parameter.
VX_DISTRIBUTION_SIZE	Indicates the total size of the distribution in bytes. Read-only. Use a `vx_size` parameter.

Definition at line 1034 of file vx_types.h.

Function Documentation

vx_distribution VX_API_CALL vxCreateDistribution	(	vx_context	context,
		vx_size	numBins,
		vx_int32	offset,
		vx_uint32	range
	)

Creates a reference to a 1D Distribution of a consecutive interval [offset, offset + range - 1] defined by a start offset and valid range, divided equally into numBins parts.

Parameters

[in]	context	The reference to the overall context.
[in]	numBins	The number of bins in the distribution.
[in]	offset	The start offset into the range value that marks the begining of the 1D Distribution.
[in]	range	The total number of the consecutive values of the distribution interval.

Returns: A distribution reference vx_distribution. Any possible errors preventing a successful creation should be checked using vxGetStatus.

vx_distribution VX_API_CALL vxCreateVirtualDistribution	(	vx_graph	graph,
		vx_size	numBins,
		vx_int32	offset,
		vx_uint32	range
	)

Creates an opaque reference to a 1D Distribution object without direct user access.

Parameters

[in]	graph	The reference to the parent graph.
[in]	numBins	The number of bins in the distribution.
[in]	offset	The start offset into the range value that marks the begining of the 1D Distribution.
[in]	range	The total number of the consecutive values of the distribution interval.

See also: vxCreateDistribution

Returns: A distribution reference vx_distribution. Any possible errors preventing a successful creation should be checked using vxGetStatus.

vx_status VX_API_CALL vxReleaseDistribution ( vx_distribution * distribution )

Releases a reference to a distribution object. The object may not be garbage collected until its total reference count is zero.

Parameters

[in] distribution The reference to the distribution to release.

Postcondition: After returning from this function the reference is zeroed.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	distribution is not a valid `vx_distribution` reference.

vx_status VX_API_CALL vxQueryDistribution	(	vx_distribution	distribution,
		vx_enum	attribute,
		void *	ptr,
		vx_size	size
	)

Queries a Distribution object.

Parameters

[in]	distribution	The reference to the distribution to query.
[in]	attribute	The attribute to query. Use a `vx_distribution_attribute_e` enumeration.
[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; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	distribution is not a valid `vx_distribution` reference.

vx_status VX_API_CALL vxCopyDistribution	(	vx_distribution	distribution,
		void *	user_ptr,
		vx_enum	usage,
		vx_enum	user_mem_type
	)

Allows the application to copy from/into a distribution object.

Parameters

[in]	distribution	The reference to the distribution object that is the source or the destination of the copy.
[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 distribution object if the copy was requested in write mode. In the user memory, the distribution is represented as a `vx_uint32` array with a number of elements equal to the value returned via `VX_DISTRIBUTION_BINS`. The accessible memory must be large enough to contain this vx_uint32 array: accessible memory in bytes >= sizeof(vx_uint32) * num_bins.
[in]	usage	This declares the effect of the copy with regard to the distribution 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 distribution object into the user memory. `VX_WRITE_ONLY` means that data are copied into the distribution 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_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	distribution is not a valid `vx_distribution` reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

vx_status VX_API_CALL vxMapDistribution	(	vx_distribution	distribution,
		vx_map_id *	map_id,
		void **	ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_bitfield	flags
	)

Allows the application to get direct access to distribution object.

Parameters

[in]	distribution	The reference to the distribution object to map.
[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 `vxUnmapDistribution`.
[out]	ptr	The address of a pointer that the function sets to the address where the requested data can be accessed. In the mapped memory area, data are structured as a vx_uint32 array with a number of elements equal to the value returned via `VX_DISTRIBUTION_BINS`. Each element of this array corresponds to a bin of the distribution, with a range-major ordering. Accessing the memory out of the bound of this array is forbidden and has an undefined behavior. The returned (*ptr) address is only valid between the call to the function and the corresponding call to `vxUnmapDistribution`.
[in]	usage	This declares the access mode for the distribution, using the `vx_accessor_e` enumeration. `VX_READ_ONLY`: after the function call, the content of the memory location pointed by (ptr) contains the distribution data. Writing into this memory location is forbidden and its behavior is undefined. `VX_READ_AND_WRITE`: after the function call, the content of the memory location pointed by (ptr) contains the distribution data; writing into this memory is allowed only for the location of bins and will result in a modification of the affected bins in the distribution object once the distribution is unmapped. `VX_WRITE_ONLY`: after the function call, the memory location pointed by (*ptr) contains undefined data; writing each bin of distribution is required prior to unmapping. Bins not written by the application before unmap will become undefined 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 distribution is requested to be mapped.
[in]	flags	An integer that allows passing options to the map operation. Use 0 for this option.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	distribution is not a valid `vx_distribution` reference. reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Postcondition: vxUnmapDistribution with same (*map_id) value.

vx_status VX_API_CALL vxUnmapDistribution	(	vx_distribution	distribution,
		vx_map_id	map_id
	)

Unmap and commit potential changes to distribution object that was previously mapped. Unmapping a distribution invalidates the memory location from which the distribution data could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.

Parameters

[in]	distribution	The reference to the distribution object to unmap.
[out]	map_id	The unique map identifier that was returned when calling `vxMapDistribution` .

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	distribution is not a valid `vx_distribution` reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Precondition: vxMapDistribution returning the same map_id value

Detailed Description

Typedefs

Enumerations

Functions

Enumeration Type Documentation

Function Documentation