VisionWorks Toolkit Reference

December 18, 2015 | 1.2 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Image Data Object Extensions

Detailed Description

Adds various extensions to the vx_image object.

This section describes different extensions and features to the standard Object: Image.

Image Size Limitation

Image dimensions in VisionWorks implementations must not exceed INT32_MAX.

Image Access

In VisionWorks, images can be accessed from the CUDA device memory in addition to the host CPU memory defined in the OpenVX specification. For this, the application must use CUDA-specific accessors nvx_accessor_e for the usage parameter of function vxAccessImagePatch .

Example Code

vx_uint8 *cudaInputPtr = NULL;
vx_uint8 *cudaOutputPtr = NULL;
vx_rectangle_t rect = { 0, 0, 640, 400 };
vxAccessImagePatch(input_image, &rect, 0, &addrInput, (void **)&cudaInputPtr, NVX_READ_ONLY_CUDA);
vxAccessImagePatch(output_image, &rect, 0, &addrOutput, (void **)&cudaOutputPtr, NVX_WRITE_ONLY_CUDA);
dim3 block(1, 1);
dim3 grid(640, 400);
myKernel<<<grid, block, 0, stream>>>(cudaInputPtr, addrInput.stride_x, addrInput.stride_y,
cudaOutputPtr, addrOutput.stride_x, addrOutput.stride_y);
vxCommitImagePatch(input_image, &rect, 0, &addrInput, cudaInputPtr);
vxCommitImagePatch(output_image, &rect, 0, &addrOutput, cudaOutputPtr);
See also
CUDA Interoperability

Images Import

In VisionWorks, the vxCreateImageFromHandle function can import images from:

In both cases, the imported memory must satisfy the following memory layout condition:

By creating an image from handle, the application temporarily transfers the property of the memory referenced by the handle to VisionWorks. VisionWorks uses it as pixel storage memory for the newly created vx_image object. The application gets back possession of the memory when the vx_image object is destroyed (when its total reference count is zero).

Since the property of the memory is transferred to VisionWorks, the application is not allowed to directly access image pixels through the memory handle it passed to the vxCreateImageFromHandle function. The application must use vxAccessImagePatch/vxCommitImagePatch functions to access pixels similar to standard images. vxAccessImagePatch/vxCommitImagePatch methods notify the framework about image access so that the framework can perform appropriate synchronization internally between CPU and GPU memory.

Warning
If the application accesses the imported memory directly without access/commit functions, it results in an undefined behavior.

When the application requests access to an image created from handle in 'map' mode (when *ptr is null, ptr being a parameter of the vxAccessImagePatch function) and for the same memory type as the handle given at image creation time, then the requested patch is mapped at its original address and with the original layout.

After the destruction of a vx_image object created from handle that occurs when its total reference count reaches zero, the memory referenced by the handle contains up-to-date pixel data. The property of the memory is also transferred back to the application that can reuse or deallocate it freely.

See also
CUDA Interoperability
Import NV12 Image from CUDA Address Space

Modules

 Extra Map Flags
 Extra flags for map operation.
 

Enumerations

enum  nvx_df_image_e {
  NVX_DF_IMAGE_F32 = VX_DF_IMAGE('F','0','3','2'),
  NVX_DF_IMAGE_2F32 = VX_DF_IMAGE('2','F','3','2'),
  NVX_DF_IMAGE_2S16 = VX_DF_IMAGE('2','S','1','6'),
  NVX_DF_IMAGE_RGB16 = VX_DF_IMAGE('S','3','1','6')
}
 Defines additional image formats. More...
 

Functions

vx_image nvxCreateImageFromChannel (vx_image imgref, vx_enum channel)
 Creates an image from a single channel of another image. More...
 
vx_status nvxMapImagePatch (vx_image image, const vx_rectangle_t *rect, vx_uint32 plane_index, vx_imagepatch_addressing_t *addr, void **ptr, vx_enum usage, vx_enum memory_type, vx_uint32 flags)
 Maps a rectangular patch (subset) of an image from a single plane. More...
 
vx_status nvxUnmapImagePatch (vx_image image, const vx_rectangle_t *rect, vx_uint32 plane_index, void *ptr, vx_enum memory_type)
 Unmaps a mapped patch (subset) of an image. More...
 

Enumeration Type Documentation

Defines additional image formats.

Enumerator
NVX_DF_IMAGE_F32 

A single plane of vx_float32 data.

NVX_DF_IMAGE_2F32 

A single plane of vx_float32[2] data (eg.

motion fields).

NVX_DF_IMAGE_2S16 

A single plane of vx_int16[2] data (eg.

motion fields).

NVX_DF_IMAGE_RGB16 

A single plane of 48 bit pixels as 3 interleaved 16 bit signed integers of R then G then B data.

Definition at line 264 of file nvx.h.

Function Documentation

vx_image nvxCreateImageFromChannel ( vx_image  imgref,
vx_enum  channel 
)

Creates an image from a single channel of another image.

This second image refers to the data in the original image. Updates to this image updates the parent image.

The method supports only multi-planar images (YUV4, IYUV, NV12, NV21) and only channels that occupy an entire plane.

Parameters
[in]imgrefSpecifies the parent image.
[in]channelSpecifies the channel to use.
Returns
vx_image object.
vx_status nvxMapImagePatch ( vx_image  image,
const vx_rectangle_t rect,
vx_uint32  plane_index,
vx_imagepatch_addressing_t addr,
void **  ptr,
vx_enum  usage,
vx_enum  memory_type,
vx_uint32  flags 
)

Maps a rectangular patch (subset) of an image from a single plane.

Parameters
[in]imageThe reference to the image from which to map the patch.
[in]rectThe coordinates from which to get the patch. Must be 0 <= start < end.
[in]plane_indexThe plane index from which to get the data.
[out]addrA pointer to a structure describing the addressing information of the image patch to be accessed.
[out]ptrA pointer to a pointer to a location to access the requested data.
[in]usageThis declares the intended usage of the pointer using the vx_accessor_e enumeration.
[in]memory_typeThis declares the intended memory type of the mapped memory. Supported values : VX_IMPORT_TYPE_HOST and NVX_IMPORT_TYPE_CUDA.
[in]flagsExtra flags for map operation. It must be a bitwise combination of values from Extra Map Flags or 0 for default behavior.

If an image is imported from user memory and memory_type corresponds to its import type and flags is equal to 0, then the original imported pointer and memory layout is returned.

Returns
A vx_status_e enumeration.
vx_status nvxUnmapImagePatch ( vx_image  image,
const vx_rectangle_t rect,
vx_uint32  plane_index,
void *  ptr,
vx_enum  memory_type 
)

Unmaps a mapped patch (subset) of an image.

Parameters
[in]imageThe reference to the image.
[in]rectThe coordinates of the patch.
[in]plane_indexThe plane index.
[in]ptrThe mapped pointer returned by nvxMapImagePatch.
[in]memory_typeThe memory type of the mapped pointer.
Returns
A vx_status_e enumeration.