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_imagepatch_addressing_t addrInput;
vx_uint8 *cudaOutputPtr = NULL;
vx_imagepatch_addressing_t addrOutput;
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:

• HOST pointers in the ptrs parameter : the import_type parameter must be set to VX_IMPORT_TYPE_HOST
• CUDA DEVICE pointers in the ptrs parameter : the import_type parameter must be set to NVX_IMPORT_TYPE_CUDA
• CUDA ARRAY pointers in the ptrs parameter : the import_type parameter must be set to NVX_IMPORT_TYPE_CUDA_ARRAY and addrs parameter must be set to NULL

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

• It must follow a row-major order. In other words, the stride_y field must be strictly greater than the stride_x field.

By creating an image from handle, the application temporarily transfers the ownership 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 ownership 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 ownership 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

Data Structures
struct	nvx_cuarray_handle_2d_t
	Defines a CUDA array handle to use with image map/unmap operations. More...

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

---

Data Structure Documentation

struct nvx_cuarray_handle_2d_t

Data Fields
cudaArray_t	array	Holds the mapped CUDA Array object.
vx_size	offset_x	Holds the x offset in array buffer.
vx_size	offset_y	Holds the y offset in array buffer.

Enumeration Type Documentation

enum nvx_df_image_e

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 243 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]	imgref	Specifies the parent image.
[in]	channel	Specifies 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]	image	The reference to the image from which to map the patch.
[in]	rect	The coordinates from which to get the patch. Must be 0 <= start < end. It must be NULL if memory_type is NVX_IMPORT_TYPE_CUDA_ARRAY.
[in]	plane_index	The plane index from which to get the data.
[out]	addr	A pointer to a structure describing the addressing information of the image patch to be accessed. It must be NULL if memory_type is NVX_IMPORT_TYPE_CUDA_ARRAY.
[out]	ptr	A pointer to a pointer to a location to access the requested data. A pointer to nvx_cuarray_handle_2d_t struct if memory_type is NVX_IMPORT_TYPE_CUDA_ARRAY.
[in]	usage	This declares the intended usage of the pointer using the vx_accessor_e enumeration.
[in]	memory_type	This declares the intended memory type of the mapped memory. Supported values : VX_IMPORT_TYPE_HOST, NVX_IMPORT_TYPE_CUDA and NVX_IMPORT_TYPE_CUDA_ARRAY.
[in]	flags	Extra 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.

Referenced by nvx_cv::VXImageToCVMatMapper::VXImageToCVMatMapper().

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]	image	The reference to the image.
[in]	rect	The coordinates of the patch. It must be NULL if the memory_type is NVX_IMPORT_TYPE_CUDA_ARRAY.
[in]	plane_index	The plane index.
[in]	ptr	The mapped pointer returned by nvxMapImagePatch. A pointer to nvx_cuarray_handle_2d_t struct if the memory_type is NVX_IMPORT_TYPE_CUDA_ARRAY.
[in]	memory_type	The memory type of the mapped pointer.

Returns

A vx_status_e enumeration.

Referenced by nvx_cv::VXImageToCVMatMapper::~VXImageToCVMatMapper().