Defines the Distribution Object Interface.
|
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).
|
|
|
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 [R00998]. 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 [R00982]. 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 [R01006]. More...
|
|
vx_status VX_API_CALL | vxQueryDistribution (vx_distribution distribution, vx_enum attribute, void *ptr, vx_size size) |
| Queries a Distribution object [R00992]. More...
|
|
vx_status VX_API_CALL | vxReleaseDistribution (vx_distribution *distribution) |
| Releases a reference to a distribution object [R00988]. 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 [R01023]. 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 implementation dependant behavior [R01024]. More...
|
|
◆ vxCreateDistribution()
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 [R00982].
- Parameters
-
[in] | context | The reference to the overall context [R00983]. |
[in] | numBins | The number of bins in the distribution [R00984]. |
[in] | offset | The start offset into the range value that marks the begining of the 1D Distribution [R00985]. |
[in] | range | The total number of the consecutive values of the distribution interval [R00986]. |
- Returns
- A distribution reference
vx_distribution
[R00987]. Any possible errors preventing a successful creation should be checked using vxGetStatus
.
◆ vxReleaseDistribution()
Releases a reference to a distribution object [R00988]. The object may not be garbage collected until its total reference count is zero.
- Parameters
-
[in] | distribution | The reference to the distribution to release [R00989]. |
- Postcondition
- After returning from this function the reference is zeroed [R00990].
- Returns
- A
The vx_status Constants
value.
- Return values
-
VX_SUCCESS | No errors; any other value indicates failure [R00991]. |
VX_ERROR_INVALID_REFERENCE | distribution is not a valid vx_distribution reference. |
◆ vxQueryDistribution()
Queries a Distribution object [R00992].
- Parameters
-
[in] | distribution | The reference to the distribution to query [R00993]. |
[in] | attribute | The attribute to query. Use a The distribution attribute list. value [R00994]. |
[out] | ptr | The location at which to store the resulting value [R00995]. |
[in] | size | The size in bytes of the container to which ptr points [R00996]. |
- Returns
- A
The vx_status Constants
value.
- Return values
-
VX_SUCCESS | No errors; any other value indicates failure [R00997]. |
VX_ERROR_INVALID_REFERENCE | distribution is not a valid vx_distribution reference. |
◆ vxCopyDistribution()
Allows the application to copy from/into a distribution object [R00998].
- Parameters
-
[in] | distribution | The reference to the distribution object that is the source or the destination of the copy [R00999]. |
[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 [R01000]. 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 [R01001]. |
[in] | usage | This declares the effect of the copy with regard to the distribution object [R01002] Only VX_READ_ONLY and VX_WRITE_ONLY are supported [R01003]:
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 Memory import type constants. value that specifies the memory type of the memory referenced by the user_addr [R01004]. |
- Returns
- A
The vx_status Constants
value.
- Return values
-
VX_SUCCESS | No errors; any other value indicates failure [R01005]. |
VX_ERROR_INVALID_REFERENCE | distribution is not a valid vx_distribution reference. |
VX_ERROR_INVALID_PARAMETERS | An other parameter is incorrect. |
◆ vxMapDistribution()
Allows the application to get direct access to distribution object [R01006].
- Parameters
-
[in] | distribution | The reference to the distribution object to map [R01007]. |
[out] | map_id | The address of a vx_map_id variable where the function returns a map identifier [R01008].
- (*map_id) must eventually be provided as the map_id parameter of a call to
vxUnmapDistribution [R01009].
|
[out] | ptr | The address of a pointer that the function sets to the address where the requested data can be accessed [R01010]. 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 is implementation dependant [R01011]. The returned (*ptr) address is only valid between the call to the function and the corresponding call to vxUnmapDistribution [R01012] |
[in] | usage | This declares the access mode for the distribution [R01013]
VX_READ_ONLY : after the function call, the content of the memory location pointed by (*ptr) contains the distribution data [R01014]. Writing into this memory location is forbidden and its behavior is implementation dependant.
VX_READ_AND_WRITE : after the function call, the content of the memory location pointed by (*ptr) contains the distribution data [R01015]; 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 [R01016].
VX_WRITE_ONLY : after the function call, the data at memory location pointed by (*ptr) is implementation-dependent; writing each bin of distribution is required prior to unmapping [R01017]. Bins not written by the application before unmap will become implementation-dependent after unmap, even if they were well defined before map.
|
[in] | mem_type | A Memory import type constants. value that specifies the type of the memory where the distribution is requested to be mapped [R01018]. |
[in] | flags | An integer that allows passing options to the map operation [R01019]. Use 0 for this option [R01020]. |
- Returns
- A
The vx_status Constants
value.
- Return values
-
VX_SUCCESS | No errors; any other value indicates failure [R01021]. |
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 [R01022].
◆ vxUnmapDistribution()
Unmap and commit potential changes to distribution object that was previously mapped [R01023]. 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 implementation dependant behavior [R01024].
- Parameters
-
[in] | distribution | The reference to the distribution object to unmap [R01025]. |
[out] | map_id | The unique map identifier that was returned when calling vxMapDistribution [R01026]. |
- Returns
- A
The vx_status Constants
value.
- Return values
-
VX_SUCCESS | No errors; any other value indicates failure [R01027]. |
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 [R01028].