The OpenVX Specification  dba1aa3
Object: Image

Detailed Description

Defines the Image Object interface.

Data Structures

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

Accesses a specific indexed pixel in an image patch. More...

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

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

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

1 vx_context context = vxCreateContext();
2 vx_graph graph = vxCreateGraph(context);
3 vx_image virt[] = {
4  vxCreateVirtualImage(graph, 0, 0, VX_DF_IMAGE_U8), // no specified dimension
5  vxCreateVirtualImage(graph, 320, 240, VX_DF_IMAGE_VIRT), // no specified format
6  vxCreateVirtualImage(graph, 640, 480, VX_DF_IMAGE_U8), // no user access
7 };
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.

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

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