The OpenVX Specification  dba1aa3
Object: Distribution

## 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

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