Detailed Description

Defines the Image Object interface.

Data Structures
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}
	Use to initialize a `vx_imagepatch_addressing_t` structure on the stack.

Typedefs
typedef struct _vx_image *	vx_image
	An opaque reference to an image. More...

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

Enumerations
enum	vx_channel_range_e { VX_CHANNEL_RANGE_FULL = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_RANGE << 12)) + 0x0, VX_CHANNEL_RANGE_RESTRICTED = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_RANGE << 12)) + 0x1 }
	The image channel range list used by the `VX_IMAGE_RANGE` attribute of a `vx_image`. More...

enum	vx_color_space_e { VX_COLOR_SPACE_NONE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_SPACE << 12)) + 0x0, VX_COLOR_SPACE_BT601_525 = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_SPACE << 12)) + 0x1, VX_COLOR_SPACE_BT601_625 = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_SPACE << 12)) + 0x2, VX_COLOR_SPACE_BT709 = ((( VX_ID_KHRONOS ) << 20) \| ( VX_ENUM_COLOR_SPACE << 12)) + 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_image_attribute_e { VX_IMAGE_WIDTH = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x0, VX_IMAGE_HEIGHT = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x1, VX_IMAGE_FORMAT = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x2, VX_IMAGE_PLANES = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x3, VX_IMAGE_SPACE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x4, VX_IMAGE_RANGE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x5, VX_IMAGE_MEMORY_TYPE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x7, VX_IMAGE_IS_UNIFORM = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x8, VX_IMAGE_UNIFORM_VALUE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x9 }
	The image attributes list. More...

enum	vx_map_flag_e { VX_NOGAP_X = 1 }
	The Map/Unmap operation enumeration. More...

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

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

vx_image VX_API_CALL	vxCreateImageFromChannel (vx_image img, vx_enum channel)
	Create a sub-image from a single plane channel of another image. More...

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

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

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

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

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

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

vx_status VX_API_CALL	vxGetValidRegionImage (vx_image image, vx_rectangle_t *rect)
	Retrieves the valid region of the image as a rectangle. More...

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

vx_status VX_API_CALL	vxQueryImage (vx_image image, vx_enum attribute, void *ptr, vx_size size)
	Retrieves various attributes of an image. More...

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

vx_status VX_API_CALL	vxSetImageAttribute (vx_image image, vx_enum attribute, const void *ptr, vx_size size)
	Allows setting attributes on the image. More...

vx_status VX_API_CALL	vxSetImagePixelValues (vx_image image, const vx_pixel_value_t *pixel_value)
	Initialize an image with the given pixel value. More...

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

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

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

Data Structure Documentation

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:

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

Definition at line 1519 of file vx_types.h.

Data Fields
vx_uint32	dim_x	Width of patch in X dimension in pixels.
vx_uint32	dim_y	Height of patch in Y dimension in pixels.
vx_int32	stride_x	Stride in X dimension in bytes.
vx_int32	stride_y	Stride in Y dimension in bytes.
vx_uint32	scale_x	Scale of X dimension. For sub-sampled planes this is the scaling factor of the dimension of the plane in relation to the zero plane. Use `VX_SCALE_UNITY` in the numerator.
vx_uint32	scale_y	Scale of Y dimension. For sub-sampled planes this is the scaling factor of the dimension of the plane in relation to the zero plane. Use `VX_SCALE_UNITY` in the numerator.
vx_uint32	step_x	Step of X dimension in pixels.
vx_uint32	step_y	Step of Y dimension in pixels.

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.

Definition at line 1684 of file vx_types.h.

Data Fields
vx_uint8	RGB[3]	`VX_DF_IMAGE_RGB` format in the R,G,B order
vx_uint8	RGBX[4]	`VX_DF_IMAGE_RGBX` format in the R,G,B,X order
vx_uint8	YUV[3]	All YUV formats in the Y,U,V order.
vx_uint8	U8	`VX_DF_IMAGE_U8`
vx_uint16	U16	`VX_DF_IMAGE_U16`
vx_int16	S16	`VX_DF_IMAGE_S16`
vx_uint32	U32	`VX_DF_IMAGE_U32`
vx_int32	S32	`VX_DF_IMAGE_S32`
vx_uint8	reserved[16]

Typedef Documentation

typedef struct _vx_image* vx_image

An opaque reference to an image.

See also: vxCreateImage

Definition at line 179 of file vx_types.h.

Enumeration Type Documentation

enum vx_image_attribute_e

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.

Definition at line 946 of file vx_types.h.

enum vx_color_space_e

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.

Definition at line 1295 of file vx_types.h.

enum vx_channel_range_e

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.

Definition at line 1312 of file vx_types.h.

enum vx_map_flag_e

The Map/Unmap operation enumeration.

Enumerator
VX_NOGAP_X	No Gap.

Definition at line 1845 of file vx_types.h.

Function Documentation

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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.

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

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.

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.

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.

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.

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

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.

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

vx_status VX_API_CALL vxGetValidRegionImage	(	vx_image	image,
		vx_rectangle_t *	rect
	)

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.

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.

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.

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.

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

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.

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

vx_image VX_API_CALL vxCreateImageFromChannel	(	vx_image	img,
		vx_enum	channel
	)

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.

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.

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.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation