User Facing Image API

The Public Image API. More...

Classes
struct	_vx_imagepatch_addressing_t
	The addressing image patch structure is used by the Host only to address pixels in an image patch. The fields of the structure are defined as: More...
union	_vx_pixel_value_t
	Union that describes the value of a pixel for any image format. Use the field corresponding to the image format. More...

Macros
#define	VX_IMAGEPATCH_ADDR_INIT   {0u, 0u, 0, 0, 0u, 0u, 0u, 0u, 0u}
	Use to initialize a vx_imagepatch_addressing_t structure on the stack.

Typedefs
typedef uintptr_t	vx_map_id
	Holds the address of a variable where the map/unmap functions return a map identifier.
typedef struct Image *	vx_image
	An opaque reference to an image.
typedef struct _vx_imagepatch_addressing_t	vx_imagepatch_addressing_t
	The addressing image patch structure is used by the Host only to address pixels in an image patch. The fields of the structure are defined as:
typedef union _vx_pixel_value_t	vx_pixel_value_t
	Union that describes the value of a pixel for any image format. Use the field corresponding to the image format.

Enumerations
enum	vx_image_attribute_e {   VX_IMAGE_WIDTH = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x0 ,   VX_IMAGE_HEIGHT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x1 ,   VX_IMAGE_FORMAT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x2 ,   VX_IMAGE_PLANES = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x3 ,   VX_IMAGE_SPACE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x4 ,   VX_IMAGE_RANGE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x5 ,   VX_IMAGE_MEMORY_TYPE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x7 ,   VX_IMAGE_IS_UNIFORM = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x8 ,   VX_IMAGE_UNIFORM_VALUE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_IMAGE) + 0x9 }
	The image attributes list. More...
enum	vx_color_space_e {   VX_COLOR_SPACE_NONE = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_SPACE) + 0x0 ,   VX_COLOR_SPACE_BT601_525 = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_SPACE) + 0x1 ,   VX_COLOR_SPACE_BT601_625 = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_SPACE) + 0x2 ,   VX_COLOR_SPACE_BT709 = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_SPACE) + 0x3 ,   VX_COLOR_SPACE_DEFAULT = VX_COLOR_SPACE_BT709 }
	The image color space list used by the VX_IMAGE_SPACE attribute of a vx_image. More...
enum	vx_channel_range_e {   VX_CHANNEL_RANGE_FULL = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_RANGE) + 0x0 ,   VX_CHANNEL_RANGE_RESTRICTED = VX_ENUM_BASE(VX_ID_KHRONOS, VX_ENUM_COLOR_RANGE) + 0x1 }
	The image channel range list used by the VX_IMAGE_RANGE attribute of a vx_image. More...
enum	vx_map_flag_e { VX_NOGAP_X = 1 }
	The Map/Unmap operation enumeration. More...

Functions
VX_API_ENTRY vx_image VX_API_CALL	vxCreateImage (vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image color)
	Creates an opaque reference to an image buffer.
VX_API_ENTRY vx_image VX_API_CALL	vxCreateImageFromROI (vx_image img, const vx_rectangle_t *rect)
	Creates an image from another image given a rectangle. This second reference refers to the data in the original image. Updates to this image updates the parent image. The rectangle must be defined within the pixel space of the parent image.
VX_API_ENTRY vx_image VX_API_CALL	vxCreateUniformImage (vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image color, const vx_pixel_value_t *value)
	Creates a reference to an image object that has a singular, uniform value in all pixels. The uniform image created is read-only.
VX_API_ENTRY vx_image VX_API_CALL	vxCreateVirtualImage (vx_graph graph, vx_uint32 width, vx_uint32 height, vx_df_image color)
	Creates an opaque reference to an image buffer with no direct user access. This function allows setting the image width, height, or format.
VX_API_ENTRY vx_image VX_API_CALL	vxCreateImageFromHandle (vx_context context, vx_df_image color, const vx_imagepatch_addressing_t addrs[], void *const ptrs[], vx_enum memory_type)
	Creates a reference to an image object that was externally allocated.
VX_API_ENTRY vx_status VX_API_CALL	vxSwapImageHandle (vx_image image, void *const new_ptrs[], void *prev_ptrs[], vx_size num_planes)
	Swaps the image handle of an image previously created from handle.
VX_API_ENTRY vx_status VX_API_CALL	vxQueryImage (vx_image image, vx_enum attribute, void *ptr, vx_size size)
	Retrieves various attributes of an image.
VX_API_ENTRY vx_status VX_API_CALL	vxSetImageAttribute (vx_image image, vx_enum attribute, const void *ptr, vx_size size)
	Allows setting attributes on the image.
VX_API_ENTRY vx_status VX_API_CALL	vxSetImagePixelValues (vx_image image, const vx_pixel_value_t *pixel_value)
	Initialize an image with the given pixel value.
VX_API_ENTRY vx_status VX_API_CALL	vxReleaseImage (vx_image *image)
	Releases a reference to an image object. The object may not be garbage collected until its total reference count is zero.
VX_API_ENTRY void *VX_API_CALL	vxFormatImagePatchAddress1d (void *ptr, vx_uint32 index, const vx_imagepatch_addressing_t *addr)
	Accesses a specific indexed pixel in an image patch.
VX_API_ENTRY void *VX_API_CALL	vxFormatImagePatchAddress2d (void *ptr, vx_uint32 x, vx_uint32 y, const vx_imagepatch_addressing_t *addr)
	Accesses a specific pixel at a 2d coordinate in an image patch.
VX_API_ENTRY vx_status VX_API_CALL	vxGetValidRegionImage (vx_image image, vx_rectangle_t *rect)
	Retrieves the valid region of the image as a rectangle.
VX_API_ENTRY vx_status VX_API_CALL	vxCopyImagePatch (vx_image image, const vx_rectangle_t *image_rect, vx_uint32 image_plane_index, const vx_imagepatch_addressing_t *user_addr, void *user_ptr, vx_enum usage, vx_enum user_mem_type)
	Allows the application to copy a rectangular patch from/into an image object plane.
VX_API_ENTRY vx_status VX_API_CALL	vxMapImagePatch (vx_image image, const vx_rectangle_t *rect, vx_uint32 plane_index, vx_map_id *map_id, vx_imagepatch_addressing_t *addr, void **ptr, vx_enum usage, vx_enum mem_type, vx_uint32 flags)
	Allows the application to get direct access to a rectangular patch of an image object plane.
VX_API_ENTRY vx_status VX_API_CALL	vxUnmapImagePatch (vx_image image, vx_map_id map_id)
	Unmap and commit potential changes to a image object patch that were previously mapped. Unmapping an image patch invalidates the memory location from which the patch could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.
VX_API_ENTRY vx_image VX_API_CALL	vxCreateImageFromChannel (vx_image img, vx_enum channel)
	Create a sub-image from a single plane channel of another image.
VX_API_ENTRY vx_status VX_API_CALL	vxSetImageValidRectangle (vx_image image, const vx_rectangle_t *rect)
	Sets the valid rectangle for an image according to a supplied rectangle.

Detailed Description

The Public Image API.

Macro Definition Documentation

VX_IMAGEPATCH_ADDR_INIT

#define VX_IMAGEPATCH_ADDR_INIT   {0u, 0u, 0, 0, 0u, 0u, 0u, 0u, 0u}

#include <vx_types.h>

Use to initialize a vx_imagepatch_addressing_t structure on the stack.

Typedef Documentation

vx_image

typedef struct Image* vx_image

#include <vx_types.h>

An opaque reference to an image.

See also

vxCreateImage

vx_imagepatch_addressing_t

typedef struct _vx_imagepatch_addressing_t vx_imagepatch_addressing_t

#include <vx_types.h>

The addressing image patch structure is used by the Host only to address pixels in an image patch. The fields of the structure are defined as:

• dim - The dimensions of the image in logical pixel units in the x & y direction.
• stride - The physical byte distance from a logical pixel to the next logically adjacent pixel in the positive x or y direction.
• scale - The relationship of scaling from the primary plane (typically the zero indexed plane) to this plane. An integer down-scaling factor of \( f \) shall be set to a value equal to \( scale = \frac{unity}{f} \) and an integer up-scaling factor of \( f \) shall be set to a value of \( scale = unity * f \). \( unity \) is defined as VX_SCALE_UNITY.
• step - The step is the number of logical pixel units to skip to arrive at the next physically unique pixel. For example, on a plane that is half-scaled in a dimension, the step in that dimension is 2 to indicate that every other pixel in that dimension is an alias. This is useful in situations where iteration over unique pixels is required, such as in serializing or de-serializing the image patch information.

  See also

  vxMapImagePatch

  Note

  For VX_DF_IMAGE_U1 images it is defined that stride_x == 0 since it is less than one byte. The least significant bit (bit number 0, value 1) in the first byte in the image, is the left-most pixel in the upper left corner, i.e. origo. A VX_DF_IMAGE_U1 image always start on a byte boundary and each row has a stride_y that is a multiple of whole bytes, which means padding bits of undefined value may be present at the end of each row. Imagepatches can only be accessed at a multiple of eight pixels: the x-coordinate must be a multiple of eight. Individual pixel access is also different: the byte at the imagepatch-calculated pointer value is a collection of eight pixels. Each byte can then be masked with the bit-mask 1 << (x % 8) to get individual pixel values (shifted x times). See ref sub_image_access for an example.

vx_map_id

typedef uintptr_t vx_map_id

#include <vx_types.h>

Holds the address of a variable where the map/unmap functions return a map identifier.

vx_pixel_value_t

typedef union _vx_pixel_value_t vx_pixel_value_t

#include <vx_types.h>

Union that describes the value of a pixel for any image format. Use the field corresponding to the image format.

Enumeration Type Documentation

vx_channel_range_e

enum vx_channel_range_e

#include <vx_types.h>

The image channel range list used by the VX_IMAGE_RANGE attribute of a vx_image.

Enumerator
VX_CHANNEL_RANGE_FULL	Full range of the unit of the channel.
VX_CHANNEL_RANGE_RESTRICTED	Restricted range of the unit of the channel based on the space given.

vx_color_space_e

enum vx_color_space_e

#include <vx_types.h>

The image color space list used by the VX_IMAGE_SPACE attribute of a vx_image.

Enumerator
VX_COLOR_SPACE_NONE	Use to indicate that no color space is used.
VX_COLOR_SPACE_BT601_525	Use to indicate that the BT.601 coefficients and SMPTE C primaries are used for conversions.
VX_COLOR_SPACE_BT601_625	Use to indicate that the BT.601 coefficients and BTU primaries are used for conversions.
VX_COLOR_SPACE_BT709	Use to indicate that the BT.709 coefficients are used for conversions.
VX_COLOR_SPACE_DEFAULT	All images in VX are by default BT.709.

vx_image_attribute_e

enum vx_image_attribute_e

#include <vx_types.h>

The image attributes list.

Enumerator
VX_IMAGE_WIDTH	Queries an image for its width. Read-only. Use a vx_uint32 parameter.
VX_IMAGE_HEIGHT	Queries an image for its height. Read-only. Use a vx_uint32 parameter.
VX_IMAGE_FORMAT	Queries an image for its format. Read-only. Use a vx_df_image parameter.
VX_IMAGE_PLANES	Queries an image for its number of planes. Read-only. Use a vx_size parameter.
VX_IMAGE_SPACE	Queries an image for its color space (see vx_color_space_e). Read-write. Use a vx_enum parameter.
VX_IMAGE_RANGE	Queries an image for its channel range (see vx_channel_range_e). Read-only. Use a vx_enum parameter.
VX_IMAGE_MEMORY_TYPE	Queries memory type if created using vxCreateImageFromHandle. If vx_image was not created using vxCreateImageFromHandle, VX_MEMORY_TYPE_NONE is returned. Use a vx_memory_type_e parameter.
VX_IMAGE_IS_UNIFORM	Queries if an image is uniform. Read-only. Use a vx_bool parameter.
VX_IMAGE_UNIFORM_VALUE	Queries the image uniform value if any. Read-only. Use a vx_pixel_value_t parameter.

vx_map_flag_e

enum vx_map_flag_e

#include <vx_types.h>

The Map/Unmap operation enumeration.

Enumerator
VX_NOGAP_X	No Gap.

Function Documentation

vxCopyImagePatch()

VX_API_ENTRY vx_status VX_API_CALL vxCopyImagePatch	(	vx_image	image,
		const vx_rectangle_t *	image_rect,
		vx_uint32	image_plane_index,
		const vx_imagepatch_addressing_t *	user_addr,
		void *	user_ptr,
		vx_enum	usage,
		vx_enum	user_mem_type )

#include <vx_api.h>

Allows the application to copy a rectangular patch from/into an image object plane.

Parameters

[in]	image	The reference to the image object that is the source or the destination of the copy.
[in]	image_rect	The coordinates of the image patch. The patch must be within the bounds of the image. (start_x, start_y) gives the coordinates of the topleft pixel inside the patch, while (end_x, end_y) gives the coordinates of the bottomright element out of the patch. Must be 0 <= start < end <= number of pixels in the image dimension.
[in]	image_plane_index	The plane index of the image object that is the source or the destination of the patch copy.
[in]	user_addr	The address of a structure describing the layout of the user memory location pointed by user_ptr. In the structure, only dim_x, dim_y, stride_x and stride_y fields must be provided, other fields are ignored by the function. The layout of the user memory must follow a row major order: stride_x >= pixel size in bytes, and stride_y >= stride_x * dim_x.
[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 image object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified patch with the specified layout: accessible memory in bytes >= (end_y - start_y) * stride_y.
[in]	usage	This declares the effect of the copy with regard to the image object using the vx_accessor_e enumeration. For uniform images, only VX_READ_ONLY is supported. For other images, Only VX_READ_ONLY and VX_WRITE_ONLY are supported: VX_READ_ONLY means that data is copied from the image object into the application memory VX_WRITE_ONLY means that data is copied into the image object from the application 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_OPTIMIZED_AWAY	This is a reference to a virtual image that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Note

The application may ask for data outside the bounds of the valid region, but such data has an undefined value.

Some special restrictions apply to VX_DF_IMAGE_U1 images.

Examples

bubble_pop.cpp, canny.cpp, optical_flow.cpp, orb.cpp, and skinToneDetector.cpp.

vxCreateImage()

VX_API_ENTRY vx_image VX_API_CALL vxCreateImage	(	vx_context	context,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color )

#include <vx_api.h>

Creates an opaque reference to an image buffer.

Not guaranteed to exist until the vx_graph containing it has been verified.

Parameters

[in]	context	The reference to the implementation context.
[in]	width	The image width in pixels. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV, VX_DF_IMAGE_UYVY, VX_DF_IMAGE_YUYV must have even width.
[in]	height	The image height in pixels. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV must have even height.
[in]	color	The VX_DF_IMAGE (vx_df_image_e) code that represents the format of the image and the color space.

Returns

An image reference vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

See also

vxMapImagePatch to obtain direct memory access to the image data.

Examples

bubble_pop.cpp, canny.cpp, optical_flow.cpp, orb.cpp, and skinToneDetector.cpp.

vxCreateImageFromChannel()

VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromChannel	(	vx_image	img,
		vx_enum	channel )

#include <vx_api.h>

Create a sub-image from a single plane channel of another image.

The sub-image refers to the data in the original image. Updates to this image update the parent image and reversely.

The function supports only channels that occupy an entire plane of a multi-planar images, as listed below. Other cases are not supported. VX_CHANNEL_Y from YUV4, IYUV, NV12, NV21 VX_CHANNEL_U from YUV4, IYUV VX_CHANNEL_V from YUV4, IYUV

Parameters

[in]	img	The reference to the parent image.
[in]	channel	The vx_channel_e channel to use.

Returns

An image reference vx_image to the sub-image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

vxCreateImageFromHandle()

VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromHandle	(	vx_context	context,
		vx_df_image	color,
		const vx_imagepatch_addressing_t	addrs[],
		void *const	ptrs[],
		vx_enum	memory_type )

#include <vx_api.h>

Creates a reference to an image object that was externally allocated.

Parameters

[in]	context	The reference to the implementation context.
[in]	color	See the vx_df_image_e codes. This mandates the number of planes needed to be valid in the addrs and ptrs arrays based on the format given.
[in]	addrs[]	The array of image patch addressing structures that define the dimension and stride of the array of pointers. See note below.
[in]	ptrs[]	The array of platform-defined references to each plane. See note below.
[in]	memory_type	vx_memory_type_e. When giving VX_MEMORY_TYPE_HOST the ptrs array is assumed to be HOST accessible pointers to memory.

Returns

An image reference vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

Note

The user must call vxMapImagePatch prior to accessing the pixels of an image, even if the image was created via vxCreateImageFromHandle. Reads or writes to memory referenced by ptrs[ ] after calling vxCreateImageFromHandle without first calling vxMapImagePatch will result in undefined behavior. The property of addr[] and ptrs[] arrays is kept by the caller (It means that the implementation will make an internal copy of the provided information. addr and ptrs can then simply be application's local variables). Only dim_x, dim_y, stride_x and stride_y fields of the vx_imagepatch_addressing_t need to be provided by the application. Other fields (step_x, step_y, scale_x & scale_y) are ignored by this function. The layout of the imported memory must follow a row-major order. In other words, stride_x should be sufficiently large so that there is no overlap between data elements corresponding to different pixels, and stride_y >= stride_x * dim_x.

In order to release the image back to the application we should use vxSwapImageHandle. An exception is for VX_DF_IMAGE_U1 images where stride_x == 0 and instead stride_y >= ⌈dim_x / 8⌉.

Import type of the created image is available via the image attribute vx_image_attribute_e parameter.

vxCreateImageFromROI()

VX_API_ENTRY vx_image VX_API_CALL vxCreateImageFromROI	(	vx_image	img,
		const vx_rectangle_t *	rect )

#include <vx_api.h>

Creates an image from another image given a rectangle. This second reference refers to the data in the original image. Updates to this image updates the parent image. The rectangle must be defined within the pixel space of the parent image.

Parameters

[in]	img	The reference to the parent image.
[in]	rect	The region of interest rectangle. Must contain points within the parent image pixel space.

Returns

An image reference vx_image to the sub-image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

vxCreateUniformImage()

VX_API_ENTRY vx_image VX_API_CALL vxCreateUniformImage	(	vx_context	context,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color,
		const vx_pixel_value_t *	value )

#include <vx_api.h>

Creates a reference to an image object that has a singular, uniform value in all pixels. The uniform image created is read-only.

Parameters

[in]	context	The reference to the implementation context.
[in]	width	The image width in pixels. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV, VX_DF_IMAGE_UYVY, VX_DF_IMAGE_YUYV must have even width.
[in]	height	The image height in pixels. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV must have even height.
[in]	color	The VX_DF_IMAGE (vx_df_image_e) code that represents the format of the image and the color space.
[in]	value	The pointer to the pixel value to which to set all pixels. See vx_pixel_value_t.

Returns

An image reference vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

See also

vxMapImagePatch to obtain direct memory access to the image data.

Note

vxMapImagePatch and vxUnmapImagePatch may be called with a uniform image reference.

vxCreateVirtualImage()

VX_API_ENTRY vx_image VX_API_CALL vxCreateVirtualImage	(	vx_graph	graph,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color )

#include <vx_api.h>

Creates an opaque reference to an image buffer with no direct user access. This function allows setting the image width, height, or format.

Virtual data objects allow users to connect various nodes within a graph via data references without access to that data, but they also permit the implementation to take maximum advantage of possible optimizations. Use this API to create a data reference to link two or more nodes together when the intermediate data are not required to be accessed by outside entities. This API in particular allows the user to define the image format of the data without requiring the exact dimensions. Virtual objects are scoped within the graph they are declared a part of, and can't be shared outside of this scope. All of the following constructions of virtual images are valid.

vx_context context = vxCreateContext();
vx_graph graph = vxCreateGraph(context);
vx_image virt[] = {
    vxCreateVirtualImage(graph, 0, 0, VX_DF_IMAGE_U8), // no specified dimension
    vxCreateVirtualImage(graph, 320, 240, VX_DF_IMAGE_VIRT), // no specified format
    vxCreateVirtualImage(graph, 640, 480, VX_DF_IMAGE_U8), // no user access
};

Parameters

[in]	graph	The reference to the parent graph.
[in]	width	The width of the image in pixels. A value of zero informs the interface that the value is unspecified. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV, VX_DF_IMAGE_UYVY, VX_DF_IMAGE_YUYV must have even width.
[in]	height	The height of the image in pixels. A value of zero informs the interface that the value is unspecified. The image in the formats of VX_DF_IMAGE_NV12, VX_DF_IMAGE_NV21, VX_DF_IMAGE_IYUV must have even height.
[in]	color	The VX_DF_IMAGE (vx_df_image_e) code that represents the format of the image and the color space. A value of VX_DF_IMAGE_VIRT informs the interface that the format is unspecified.

Returns

An image reference vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

Note

Passing this reference to vxMapImagePatch will return an error.

Examples

bubble_pop.cpp, canny.cpp, optical_flow.cpp, and skinToneDetector.cpp.

vxFormatImagePatchAddress1d()

VX_API_ENTRY void *VX_API_CALL vxFormatImagePatchAddress1d	(	void *	ptr,
		vx_uint32	index,
		const vx_imagepatch_addressing_t *	addr )

#include <vx_api.h>

Accesses a specific indexed pixel in an image patch.

Parameters

[in]	ptr	The base pointer of the patch as returned from vxMapImagePatch.
[in]	index	The 0 based index of the pixel count in the patch. Indexes increase horizontally by 1 then wrap around to the next row.
[in]	addr	The pointer to the addressing mode information returned from vxMapImagePatch.

Returns

void * Returns the pointer to the specified pixel.

Precondition

vxMapImagePatch

Note

Some special restrictions apply to VX_DF_IMAGE_U1 images.

vxFormatImagePatchAddress2d()

VX_API_ENTRY void *VX_API_CALL vxFormatImagePatchAddress2d	(	void *	ptr,
		vx_uint32	x,
		vx_uint32	y,
		const vx_imagepatch_addressing_t *	addr )

#include <vx_api.h>

Accesses a specific pixel at a 2d coordinate in an image patch.

Parameters

[in]	ptr	The base pointer of the patch as returned from vxMapImagePatch.
[in]	x	The x dimension within the patch.
[in]	y	The y dimension within the patch.
[in]	addr	The pointer to the addressing mode information returned from vxMapImagePatch.

Returns

void * Returns the pointer to the specified pixel.

Precondition

vxMapImagePatch

Note

Some special restrictions apply to VX_DF_IMAGE_U1 images.

vxGetValidRegionImage()

VX_API_ENTRY vx_status VX_API_CALL vxGetValidRegionImage	(	vx_image	image,
		vx_rectangle_t *	rect )

#include <vx_api.h>

Retrieves the valid region of the image as a rectangle.

Parameters

[in]	image	The image from which to retrieve the valid region.
[out]	rect	The destination rectangle.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference.
VX_ERROR_INVALID_PARAMETERS	Invalid rect.

Note

This rectangle can be passed directly to vxMapImagePatch to get the full valid region of the image.

Some special restrictions apply to VX_DF_IMAGE_U1 images.

vxMapImagePatch()

VX_API_ENTRY vx_status VX_API_CALL vxMapImagePatch	(	vx_image	image,
		const vx_rectangle_t *	rect,
		vx_uint32	plane_index,
		vx_map_id *	map_id,
		vx_imagepatch_addressing_t *	addr,
		void **	ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_uint32	flags )

#include <vx_api.h>

Allows the application to get direct access to a rectangular patch of an image object plane.

Parameters

[in]	image	The reference to the image object that contains the patch to map.
[in]	rect	The coordinates of image patch. The patch must be within the bounds of the image. (start_x, start_y) gives the coordinate of the topleft element inside the patch, while (end_x, end_y) give the coordinate of the bottomright element out of the patch. Must be 0 <= start < end.
[in]	plane_index	The plane index of the image object to be accessed.
[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 vxUnmapImagePatch.
[out]	addr	The address of a vx_imagepatch_addressing_t structure describing the memory layout of the image patch to access. The function fills the structure pointed by addr with the layout information that the application must consult to access the pixel data at address (*ptr). The layout of the mapped memory follows a row-major order: stride_x>0, stride_y>0 and stride_y >= stride_x * dim_x. An exception is for VX_DF_IMAGE_U1 where stride_x == 0, stride_x_bits > 0 and stride_y {geq} (stride_x_bits * dim_x + 7) / 8 (i.e., at least the number of bytes needed to hold dim_x pixels). If the image object being accessed was created via vxCreateImageFromHandle, then the returned memory layout will be the identical to that of the addressing structure provided when vxCreateImageFromHandle was called.
[out]	ptr	The address of a pointer that the function sets to the address where the requested data can be accessed. This returned (*ptr) address is only valid between the call to this function and the corresponding call to vxUnmapImagePatch. If image was created via vxCreateImageFromHandle then the returned address (*ptr) will be the address of the patch in the original pixel buffer provided when image was created.
[in]	usage	This declares the access mode for the image patch, using the vx_accessor_e enumeration. For uniform images, only VX_READ_ONLY is supported. VX_READ_ONLY: after the function call, the content of the memory location pointed by (*ptr) contains the image patch 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 image patch data; writing into this memory is allowed only for the location of pixels only and will result in a modification of the written pixels in the image object once the patch is unmapped. Writing into a gap between pixels (when addr->stride_x > pixel size in bytes or addr->stride_y > addr->stride_x*addr->dim_x) is forbidden and its behavior is undefined. VX_WRITE_ONLY: after the function call, the memory location pointed by (*ptr) contains undefined data; writing each pixel of the patch is required prior to unmapping. Pixels not written by the application before unmap will become undefined after unmap, even if they were well defined before map. Like for VX_READ_AND_WRITE, writing into a gap between pixels is forbidden and its behavior is undefined.
[in]	mem_type	A vx_memory_type_e enumeration that specifies the type of the memory where the image patch is requested to be mapped.
[in]	flags	An integer that allows passing options to the map operation. Use the vx_map_flag_e enumeration.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual image that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference. reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Note

The user may ask for data outside the bounds of the valid region, but such data has an undefined value.

Postcondition

vxUnmapImagePatch with same (*map_id) value.

Examples

bubble_pop.cpp, canny.cpp, and skinToneDetector.cpp.

vxQueryImage()

VX_API_ENTRY vx_status VX_API_CALL vxQueryImage	(	vx_image	image,
		vx_enum	attribute,
		void *	ptr,
		vx_size	size )

#include <vx_api.h>

Retrieves various attributes of an image.

Parameters

[in]	image	The reference to the image to query.
[in]	attribute	The attribute to query. Use a vx_image_attribute_e.
[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	image is not a valid vx_image reference.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.
VX_ERROR_NOT_SUPPORTED	If the attribute is not supported on this implementation.

vxReleaseImage()

VX_API_ENTRY vx_status VX_API_CALL vxReleaseImage

(

vx_image *

image

)

#include <vx_api.h>

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

An implementation may defer the actual object destruction after its total reference count is zero (potentially until context destruction). Thus, releasing an image created from handle (see vxCreateImageFromHandle) and all others objects that may reference it (nodes, ROI, or channel for instance) are not sufficient to get back the ownership of the memory referenced by the current image handle. The only way for this is to call vxSwapImageHandle) before releasing the image.

Parameters

[in]

image

The pointer to the image 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	image is not a valid vx_image reference.

Examples

bubble_pop.cpp, canny.cpp, optical_flow.cpp, orb.cpp, and skinToneDetector.cpp.

vxSetImageAttribute()

VX_API_ENTRY vx_status VX_API_CALL vxSetImageAttribute	(	vx_image	image,
		vx_enum	attribute,
		const void *	ptr,
		vx_size	size )

#include <vx_api.h>

Allows setting attributes on the image.

Parameters

[in]	image	The reference to the image on which to set the attribute.
[in]	attribute	The attribute to set. Use a vx_image_attribute_e enumeration.
[in]	ptr	The pointer to the location from which to read the value.
[in]	size	The size in bytes of the object pointed to by ptr.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

vxSetImagePixelValues()

VX_API_ENTRY vx_status VX_API_CALL vxSetImagePixelValues	(	vx_image	image,
		const vx_pixel_value_t *	pixel_value )

#include <vx_api.h>

Initialize an image with the given pixel value.

Parameters

[in]	image	The reference to the image to initialize.
[in]	pixel_value	The pointer to the constant pixel value to initialize all image pixels. See vx_pixel_value_t.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the image is a uniform image, a virtual image, or not a vx_image.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

Note

All pixels of the entire image are initialized to the indicated pixel value, independently from the valid region. The valid region of the image is unaffected by this function. The image remains mutable after the call to this function, so its pixels and mutable attributes may be changed by subsequent functions.

vxSetImageValidRectangle()

VX_API_ENTRY vx_status VX_API_CALL vxSetImageValidRectangle	(	vx_image	image,
		const vx_rectangle_t *	rect )

#include <vx_api.h>

Sets the valid rectangle for an image according to a supplied rectangle.

Note

Setting or changing the valid region from within a user node by means other than the call-back, for example by calling vxSetImageValidRectangle, might result in an incorrect valid region calculation by the framework.

Parameters

[in]	image	The reference to the image.
[in]	rect	The value to be set to the image valid rectangle. A NULL indicates that the valid region is the entire image.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference.
VX_ERROR_INVALID_PARAMETERS	The rect does not define a proper valid rectangle.

vxSwapImageHandle()

VX_API_ENTRY vx_status VX_API_CALL vxSwapImageHandle	(	vx_image	image,
		void *const	new_ptrs[],
		void *	prev_ptrs[],
		vx_size	num_planes )

#include <vx_api.h>

Swaps the image handle of an image previously created from handle.

This function sets the new image handle (i.e. pointer to all image planes) and returns the previous one.

Once this function call has completed, the application gets back the ownership of the memory referenced by the previous handle. This memory contains up-to-date pixel data, and the application can safely reuse or release it.

The memory referenced by the new handle must have been allocated consistently with the image properties since the import type, memory layout and dimensions are unchanged (see addrs, color, and memory_type in vxCreateImageFromHandle).

All images created from ROI or channel with this image as parent or ancestor will automatically use the memory referenced by the new handle.

The behavior of vxSwapImageHandle when called from a user node is undefined.

Parameters

[in]	image	The reference to an image created from handle
[in]	new_ptrs[]	pointer to a caller owned array that contains the new image handle (image plane pointers) new_ptrs is non NULL. new_ptrs[i] must be non NULL for each i such as 0 < i < nbPlanes, otherwise, this is an error. The address of the storage memory for image plane i is set to new_ptrs[i] new_ptrs is NULL: the previous image storage memory is reclaimed by the caller, while no new handle is provided.
[out]	prev_ptrs[]	pointer to a caller owned array in which the application returns the previous image handle prev_ptrs is non NULL. prev_ptrs must have at least as many elements as the number of image planes. For each i such as 0 < i < nbPlanes , prev_ptrs[i] is set to the address of the previous storage memory for plane i. prev_ptrs NULL: the previous handle is not returned.
[in]	num_planes	Number of planes in the image. This must be set equal to the number of planes of the input image. The number of elements in new_ptrs and prev_ptrs arrays must be equal to or greater than num_planes. If either array has more than num_planes elements, the extra elements are ignored. If either array is smaller than num_planes, the results are undefined.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	image is not a valid vx_image reference. reference.
VX_ERROR_INVALID_PARAMETERS	The image was not created from handle or the content of new_ptrs is not valid.
VX_FAILURE	The image was already being accessed.

vxUnmapImagePatch()

VX_API_ENTRY vx_status VX_API_CALL vxUnmapImagePatch	(	vx_image	image,
		vx_map_id	map_id )

#include <vx_api.h>

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

Parameters

[in]	image	The reference to the image object to unmap.
[out]	map_id	The unique map identifier that was returned by vxMapImagePatch .

Returns

A vx_status_e enumeration.

Return values

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

Precondition

vxMapImagePatch with same map_id value

Examples

bubble_pop.cpp, canny.cpp, and skinToneDetector.cpp.