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

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

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_ATTRIBUTE_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_ATTRIBUTE_SPACE` attribute of a `vx_image`. More...

enum	vx_image_attribute_e { VX_IMAGE_ATTRIBUTE_WIDTH = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x0, VX_IMAGE_ATTRIBUTE_HEIGHT = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x1, VX_IMAGE_ATTRIBUTE_FORMAT = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x2, VX_IMAGE_ATTRIBUTE_PLANES = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x3, VX_IMAGE_ATTRIBUTE_SPACE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x4, VX_IMAGE_ATTRIBUTE_RANGE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x5, VX_IMAGE_ATTRIBUTE_SIZE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_IMAGE << 8)) + 0x6 }
	The image attributes list. More...

Functions
vx_status	vxAccessImagePatch (vx_image image, vx_rectangle_t rect, vx_uint32 plane_index, vx_imagepatch_addressing_t addr, void **ptr, vx_enum usage)
	Allows the User to extract a rectangular patch (subset) of an image from a single plane. More...

vx_status	vxCommitImagePatch (vx_image image, vx_rectangle_t rect, vx_uint32 plane_index, vx_imagepatch_addressing_t addr, void *ptr)
	This allows the User to commit a rectangular patch (subset) of an image from a single plane. More...

vx_size	vxComputeImagePatchSize (vx_image image, vx_rectangle_t *rect, vx_uint32 plane_index)
	This computes the size needed to retrieve an image patch from an image. More...

vx_image	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	vxCreateImageFromHandle (vx_context context, vx_df_image color, vx_imagepatch_addressing_t addrs[], void *ptrs[], vx_enum import_type)
	Creates a reference to an image object that was externally allocated. More...

vx_image	vxCreateImageFromROI (vx_image img, 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	vxCreateUniformImage (vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image color, void *value)
	Creates a reference to an image object that has a singular, uniform value in all pixels. More...

vx_image	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 *	vxFormatImagePatchAddress1d (void ptr, vx_uint32 index, vx_imagepatch_addressing_t addr)
	Accesses a specific indexed pixel in an image patch. More...

void *	vxFormatImagePatchAddress2d (void ptr, vx_uint32 x, vx_uint32 y, vx_imagepatch_addressing_t addr)
	Accesses a specific pixel at a 2d coordinate in an image patch. More...

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

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

vx_status	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	vxSetImageAttribute (vx_image image, vx_enum attribute, void *out, vx_size size)
	Allows setting attributes on the image. 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
vxAccessImagePatch

/*

* Copyright (c) 2013-2014 The Khronos Group Inc.

*

* Permission is hereby granted, free of charge, to any person obtaining a

* copy of this software and/or associated documentation files (the

* "Materials"), to deal in the Materials without restriction, including

* without limitation the rights to use, copy, modify, merge, publish,

* distribute, sublicense, and/or sell copies of the Materials, and to

* permit persons to whom the Materials are furnished to do so, subject to

* the following conditions:

*

* The above copyright notice and this permission notice shall be included

* in all copies or substantial portions of the Materials.

*

* THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

* MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

*/

#include <VX/vx.h>

#define PATCH_DIM 16

vx_status example_imagepatch(vx_context context)

{

vx_status status = VX_SUCCESS;

void *base_ptr = NULL;

vx_uint32 width = 640, height = 480, plane = 0;

vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);

vx_rectangle_t rect;

vx_imagepatch_addressing_t addr;

rect.start_x = rect.start_y = 0;

rect.end_x = rect.end_y = PATCH_DIM;

status = vxAccessImagePatch(image, &rect, plane,

&addr, &base_ptr,

VX_READ_AND_WRITE);

if (status == VX_SUCCESS)

{

vx_uint32 x,y,i,j;

vx_uint8 pixel = 0;

/* a couple addressing options */

/* use linear addressing function/macro */

for (i = 0; i < addr.dim_x*addr.dim_y; i++) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress1d(base_ptr,

i, &addr);

*ptr2 = pixel;

}

/* 2d addressing option */

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress2d(base_ptr,

x, y, &addr);

*ptr2 = pixel;

}

}

/* direct addressing by client

* for subsampled planes, scale will change

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = ((addr.stride_y*y*addr.scale_y) /

VX_SCALE_UNITY) +

((addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY);

tmp[i] = pixel;

}

}

/* more efficient direct addressing by client.

* for subsampled planes, scale will change.

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

j = (addr.stride_y*y*addr.scale_y)/VX_SCALE_UNITY;

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = j + (addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY;

tmp[i] = pixel;

}

}

/* this commits the data back to the image. If rect were 0 or empty, it

* would just decrement the reference (used when reading an image only)

*/

status = vxCommitImagePatch(image, &rect, plane, &addr, base_ptr);

}

vxReleaseImage(&image);

return status;

}

Definition at line 1273 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.

Typedef Documentation

typedef struct _vx_image* vx_image

An opaque reference to an image.

See also: vxCreateImage

Definition at line 144 of file vx_types.h.

Enumeration Type Documentation

enum vx_image_attribute_e

The image attributes list.

Enumerator
VX_IMAGE_ATTRIBUTE_WIDTH	Queries an image for its height. Use a `vx_uint32` parameter.
VX_IMAGE_ATTRIBUTE_HEIGHT	Queries an image for its width. Use a `vx_uint32` parameter.
VX_IMAGE_ATTRIBUTE_FORMAT	Queries an image for its format. Use a `vx_df_image` parameter.
VX_IMAGE_ATTRIBUTE_PLANES	Queries an image for its number of planes. Use a `vx_size` parameter.
VX_IMAGE_ATTRIBUTE_SPACE	Queries an image for its color space (see `vx_color_space_e`). Use a `vx_enum` parameter.
VX_IMAGE_ATTRIBUTE_RANGE	Queries an image for its channel range (see `vx_channel_range_e`). Use a `vx_enum` parameter.
VX_IMAGE_ATTRIBUTE_SIZE	Queries an image for its total number of bytes. Use a `vx_size` parameter.

Definition at line 766 of file vx_types.h.

enum vx_color_space_e

The image color space list used by the VX_IMAGE_ATTRIBUTE_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 1027 of file vx_types.h.

enum vx_channel_range_e

The image channel range list used by the VX_IMAGE_ATTRIBUTE_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 1044 of file vx_types.h.

Function Documentation

vx_image 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.
[in]	height	The image height in pixels.
[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 or zero when an error is encountered.

See also: vxAccessImagePatch to obtain direct memory access to the image data.

vx_image vxCreateImageFromROI	(	vx_image	img,
		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: The reference to the sub-image or zero if the rectangle is invalid.

vx_image vxCreateUniformImage	(	vx_context	context,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color,
		void *	value
	)

Creates a reference to an image object that has a singular, uniform value in all pixels.

The value pointer must reflect the specific format of the desired image. For example:

Color	Value Ptr
`VX_DF_IMAGE_U8`	vx_uint8 *
`VX_DF_IMAGE_S16`	vx_int16 *
`VX_DF_IMAGE_U16`	vx_uint16 *
`VX_DF_IMAGE_S32`	vx_int32 *
`VX_DF_IMAGE_U32`	vx_uint32 *
`VX_DF_IMAGE_RGB`	vx_uint8 pixel[3] in R, G, B order
`VX_DF_IMAGE_RGBX`	vx_uint8 pixels[4]
Any YUV	vx_uint8 pixel[3] in Y, U, V order

Parameters

[in]	context	The reference to the implementation context.
[in]	width	The image width in pixels.
[in]	height	The image height in pixels.
[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.

Returns: An image reference or zero when an error is encountered.

See also: vxAccessImagePatch to obtain direct memory access to the image data.

Note: vxAccessImagePatch and vxCommitImagePatch may be called with a uniform image reference.

vx_image 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.
[in]	height	The height of the image in pixels. A value of zero informs the interface that the value is unspecified.
[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 or zero when an error is encountered.

Note: Passing this reference to vxAccessImagePatch will return an error.

vx_image vxCreateImageFromHandle	(	vx_context	context,
		vx_df_image	color,
		vx_imagepatch_addressing_t	addrs[],
		void *	ptrs[],
		vx_enum	import_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.
[in]	ptrs[]	The array of platform-defined references to each plane.
[in]	import_type	`vx_import_type_e`. When giving `VX_IMPORT_TYPE_HOST` the ptrs array is assumed to be HOST accessible pointers to memory.

Returns: vx_image.

Return values

0	Image could not be created.
*	Valid Image reference.

vx_status 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 of the container to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the image is not a `vx_image`.
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 vxSetImageAttribute	(	vx_image	image,
		vx_enum	attribute,
		void *	out,
		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]	out	The pointer to the location from which to read the value.
[in]	size	The size of the object pointed to by out.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the image is not a `vx_image`.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

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

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.
VX_ERROR_INVALID_REFERENCE	If graph is not a `vx_graph`.

vx_size vxComputeImagePatchSize	(	vx_image	image,
		vx_rectangle_t *	rect,
		vx_uint32	plane_index
	)

This computes the size needed to retrieve an image patch from an image.

Parameters

[in]	image	The reference to the image from which to extract the patch.
[in]	rect	The coordinates. Must be 0 <= start < end <= dimension where dimension is width for x and height for y.
[in]	plane_index	The plane index from which to get the data.

Returns: vx_size

vx_status vxAccessImagePatch	(	vx_image	image,
		vx_rectangle_t *	rect,
		vx_uint32	plane_index,
		vx_imagepatch_addressing_t *	addr,
		void **	ptr,
		vx_enum	usage
	)

Allows the User to extract a rectangular patch (subset) of an image from a single plane.

Parameters

[in]	image	The reference to the image from which to extract the patch.
[in]	rect	The coordinates from which to get the patch. Must be 0 <= start < end.
[in]	plane_index	The plane index from which to get the data.
[out]	addr	The addressing information for the image patch to be written into the data structure.
[out]	ptr	The pointer to a pointer of a location to store the data. If the user passes in a NULL, an error occurs. If the user passes in a pointer to a NULL, the function returns internal memory, map, or allocates a buffer and returns it. If the user passes in a pointer to a non-NULL pointer, the function attempts to copy to the location provided by the user. (*ptr) must be given to `vxCommitImagePatch`.
[in]	usage	This declares the intended usage of the pointer using the `vx_accessor_e` enumeration.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_OPTIMIZED_AWAY	The reference is a virtual image and cannot be accessed or committed.
VX_ERROR_INVALID_PARAMETERS	The start, end, plane_index, stride_x, or stride_y pointer is incorrect.
VX_ERROR_INVALID_REFERENCE	The image reference is not actually an image reference.

Note: The user may ask for data outside the bounds of the valid region, but such data has an undefined value.; Users must be cautious to prevent passing in uninitialized pointers or addresses of uninitialized pointers to this function.

Precondition: vxComputeImagePatchSize if users wish to allocate their own memory.

Postcondition: vxCommitImagePatch with same (*ptr) value.

/*
 * Copyright (c) 2013-2014 The Khronos Group Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and/or associated documentation files (the
 * "Materials"), to deal in the Materials without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Materials, and to
 * permit persons to whom the Materials are furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Materials.
 *
 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
 */
#include <VX/vx.h>
#define PATCH_DIM 16
vx_status example_imagepatch(vx_context context)
{
    vx_status status = VX_SUCCESS;
    void *base_ptr = NULL;
    vx_uint32 width = 640, height = 480, plane = 0;
    vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
    vx_rectangle_t rect;
    vx_imagepatch_addressing_t addr;
    rect.start_x = rect.start_y = 0;
    rect.end_x = rect.end_y = PATCH_DIM;
    status = vxAccessImagePatch(image, &rect, plane,
                                &addr, &base_ptr,
                                VX_READ_AND_WRITE);
    if (status == VX_SUCCESS)
    {
        vx_uint32 x,y,i,j;
        vx_uint8 pixel = 0;
        /* a couple addressing options */
        /* use linear addressing function/macro */
        for (i = 0; i < addr.dim_x*addr.dim_y; i++) {
            vx_uint8 *ptr2 = vxFormatImagePatchAddress1d(base_ptr,
                                                         i, &addr);
            *ptr2 = pixel;
        }
        /* 2d addressing option */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *ptr2 = vxFormatImagePatchAddress2d(base_ptr,
                                                             x, y, &addr);
                *ptr2 = pixel;
            }
        }
        /* direct addressing by client
         * for subsampled planes, scale will change
         */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *tmp = (vx_uint8 *)base_ptr;
                i = ((addr.stride_y*y*addr.scale_y) /
                      VX_SCALE_UNITY) +
                    ((addr.stride_x*x*addr.scale_x) /
                      VX_SCALE_UNITY);
                tmp[i] = pixel;
            }
        }
        /* more efficient direct addressing by client.
         * for subsampled planes, scale will change.
         */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            j = (addr.stride_y*y*addr.scale_y)/VX_SCALE_UNITY;
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *tmp = (vx_uint8 *)base_ptr;
                i = j + (addr.stride_x*x*addr.scale_x) /
                    VX_SCALE_UNITY;
                tmp[i] = pixel;
            }
        }
        /* this commits the data back to the image. If rect were 0 or empty, it
         * would just decrement the reference (used when reading an image only)
         */
        status = vxCommitImagePatch(image, &rect, plane, &addr, base_ptr);
    }
    vxReleaseImage(&image);
    return status;
}

vx_status vxCommitImagePatch	(	vx_image	image,
		vx_rectangle_t *	rect,
		vx_uint32	plane_index,
		vx_imagepatch_addressing_t *	addr,
		void *	ptr
	)

This allows the User to commit a rectangular patch (subset) of an image from a single plane.

Parameters

[in]	image	The reference to the image from which to extract the patch.
[in]	rect	The coordinates to which to set the patch. Must be 0 <= start <= end. This may be 0 or a rectangle of zero area in order to indicate that the commit must only decrement the reference count.
[in]	plane_index	The plane index to which to set the data.
[in]	addr	The addressing information for the image patch.
[in]	ptr	The pointer of a location from which to read the data. If the user allocated the pointer they must free it. If the pointer was set by `vxAccessImagePatch`, the user may not access the pointer after this call completes.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_OPTIMIZED_AWAY	The reference is a virtual image and cannot be accessed or committed.
VX_ERROR_INVALID_PARAMETERS	The start, end, plane_index, stride_x, or stride_y pointer is incorrect.
VX_ERROR_INVALID_REFERENCE	The image reference is not actually an image reference.

/*
 * Copyright (c) 2013-2014 The Khronos Group Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and/or associated documentation files (the
 * "Materials"), to deal in the Materials without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Materials, and to
 * permit persons to whom the Materials are furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Materials.
 *
 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
 */
#include <VX/vx.h>
#define PATCH_DIM 16
vx_status example_imagepatch(vx_context context)
{
    vx_status status = VX_SUCCESS;
    void *base_ptr = NULL;
    vx_uint32 width = 640, height = 480, plane = 0;
    vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
    vx_rectangle_t rect;
    vx_imagepatch_addressing_t addr;
    rect.start_x = rect.start_y = 0;
    rect.end_x = rect.end_y = PATCH_DIM;
    status = vxAccessImagePatch(image, &rect, plane,
                                &addr, &base_ptr,
                                VX_READ_AND_WRITE);
    if (status == VX_SUCCESS)
    {
        vx_uint32 x,y,i,j;
        vx_uint8 pixel = 0;
        /* a couple addressing options */
        /* use linear addressing function/macro */
        for (i = 0; i < addr.dim_x*addr.dim_y; i++) {
            vx_uint8 *ptr2 = vxFormatImagePatchAddress1d(base_ptr,
                                                         i, &addr);
            *ptr2 = pixel;
        }
        /* 2d addressing option */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *ptr2 = vxFormatImagePatchAddress2d(base_ptr,
                                                             x, y, &addr);
                *ptr2 = pixel;
            }
        }
        /* direct addressing by client
         * for subsampled planes, scale will change
         */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *tmp = (vx_uint8 *)base_ptr;
                i = ((addr.stride_y*y*addr.scale_y) /
                      VX_SCALE_UNITY) +
                    ((addr.stride_x*x*addr.scale_x) /
                      VX_SCALE_UNITY);
                tmp[i] = pixel;
            }
        }
        /* more efficient direct addressing by client.
         * for subsampled planes, scale will change.
         */
        for (y = 0; y < addr.dim_y; y+=addr.step_y) {
            j = (addr.stride_y*y*addr.scale_y)/VX_SCALE_UNITY;
            for (x = 0; x < addr.dim_x; x+=addr.step_x) {
                vx_uint8 *tmp = (vx_uint8 *)base_ptr;
                i = j + (addr.stride_x*x*addr.scale_x) /
                    VX_SCALE_UNITY;
                tmp[i] = pixel;
            }
        }
        /* this commits the data back to the image. If rect were 0 or empty, it
         * would just decrement the reference (used when reading an image only)
         */
        status = vxCommitImagePatch(image, &rect, plane, &addr, base_ptr);
    }
    vxReleaseImage(&image);
    return status;
}

Note: If the implementation gives the client a pointer from vxAccessImagePatch then implementation-specific behavior may occur. If not, then a copy occurs from the users pointer to the internal data of the object.; If the rectangle intersects bounds of the current valid region, the valid region grows to the union of the two rectangles as long as they occur within the bounds of the original image dimensions.

void* vxFormatImagePatchAddress1d	(	void *	ptr,
		vx_uint32	index,
		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 `vxAccessImagePatch`.
[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 `vxAccessImagePatch`.

Returns: void * Returns the pointer to the specified pixel.

Precondition: vxAccessImagePatch
/*

* Copyright (c) 2013-2014 The Khronos Group Inc.

*

* Permission is hereby granted, free of charge, to any person obtaining a

* copy of this software and/or associated documentation files (the

* "Materials"), to deal in the Materials without restriction, including

* without limitation the rights to use, copy, modify, merge, publish,

* distribute, sublicense, and/or sell copies of the Materials, and to

* permit persons to whom the Materials are furnished to do so, subject to

* the following conditions:

*

* The above copyright notice and this permission notice shall be included

* in all copies or substantial portions of the Materials.

*

* THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

* MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

*/

#include <VX/vx.h>

#define PATCH_DIM 16

vx_status example_imagepatch(vx_context context)

{

vx_status status = VX_SUCCESS;

void *base_ptr = NULL;

vx_uint32 width = 640, height = 480, plane = 0;

vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);

vx_rectangle_t rect;

vx_imagepatch_addressing_t addr;

rect.start_x = rect.start_y = 0;

rect.end_x = rect.end_y = PATCH_DIM;

status = vxAccessImagePatch(image, &rect, plane,

&addr, &base_ptr,

VX_READ_AND_WRITE);

if (status == VX_SUCCESS)

{

vx_uint32 x,y,i,j;

vx_uint8 pixel = 0;

/* a couple addressing options */

/* use linear addressing function/macro */

for (i = 0; i < addr.dim_x*addr.dim_y; i++) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress1d(base_ptr,

i, &addr);

*ptr2 = pixel;

}

/* 2d addressing option */

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress2d(base_ptr,

x, y, &addr);

*ptr2 = pixel;

}

}

/* direct addressing by client

* for subsampled planes, scale will change

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = ((addr.stride_y*y*addr.scale_y) /

VX_SCALE_UNITY) +

((addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY);

tmp[i] = pixel;

}

}

/* more efficient direct addressing by client.

* for subsampled planes, scale will change.

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

j = (addr.stride_y*y*addr.scale_y)/VX_SCALE_UNITY;

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = j + (addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY;

tmp[i] = pixel;

}

}

/* this commits the data back to the image. If rect were 0 or empty, it

* would just decrement the reference (used when reading an image only)

*/

status = vxCommitImagePatch(image, &rect, plane, &addr, base_ptr);

}

vxReleaseImage(&image);

return status;

}

void* vxFormatImagePatchAddress2d	(	void *	ptr,
		vx_uint32	x,
		vx_uint32	y,
		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 `vxAccessImagePatch`.
[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 `vxAccessImagePatch`.

Returns: void * Returns the pointer to the specified pixel.

Precondition: vxAccessImagePatch
/*

* Copyright (c) 2013-2014 The Khronos Group Inc.

*

* Permission is hereby granted, free of charge, to any person obtaining a

* copy of this software and/or associated documentation files (the

* "Materials"), to deal in the Materials without restriction, including

* without limitation the rights to use, copy, modify, merge, publish,

* distribute, sublicense, and/or sell copies of the Materials, and to

* permit persons to whom the Materials are furnished to do so, subject to

* the following conditions:

*

* The above copyright notice and this permission notice shall be included

* in all copies or substantial portions of the Materials.

*

* THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

* MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

*/

#include <VX/vx.h>

#define PATCH_DIM 16

vx_status example_imagepatch(vx_context context)

{

vx_status status = VX_SUCCESS;

void *base_ptr = NULL;

vx_uint32 width = 640, height = 480, plane = 0;

vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);

vx_rectangle_t rect;

vx_imagepatch_addressing_t addr;

rect.start_x = rect.start_y = 0;

rect.end_x = rect.end_y = PATCH_DIM;

status = vxAccessImagePatch(image, &rect, plane,

&addr, &base_ptr,

VX_READ_AND_WRITE);

if (status == VX_SUCCESS)

{

vx_uint32 x,y,i,j;

vx_uint8 pixel = 0;

/* a couple addressing options */

/* use linear addressing function/macro */

for (i = 0; i < addr.dim_x*addr.dim_y; i++) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress1d(base_ptr,

i, &addr);

*ptr2 = pixel;

}

/* 2d addressing option */

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *ptr2 = vxFormatImagePatchAddress2d(base_ptr,

x, y, &addr);

*ptr2 = pixel;

}

}

/* direct addressing by client

* for subsampled planes, scale will change

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = ((addr.stride_y*y*addr.scale_y) /

VX_SCALE_UNITY) +

((addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY);

tmp[i] = pixel;

}

}

/* more efficient direct addressing by client.

* for subsampled planes, scale will change.

*/

for (y = 0; y < addr.dim_y; y+=addr.step_y) {

j = (addr.stride_y*y*addr.scale_y)/VX_SCALE_UNITY;

for (x = 0; x < addr.dim_x; x+=addr.step_x) {

vx_uint8 *tmp = (vx_uint8 *)base_ptr;

i = j + (addr.stride_x*x*addr.scale_x) /

VX_SCALE_UNITY;

tmp[i] = pixel;

}

}

/* this commits the data back to the image. If rect were 0 or empty, it

* would just decrement the reference (used when reading an image only)

*/

status = vxCommitImagePatch(image, &rect, plane, &addr, base_ptr);

}

vxReleaseImage(&image);

return status;

}

vx_status vxGetValidRegionImage	(	vx_image	image,
		vx_rectangle_t *	rect
	)

Retrieves the valid region of the image as a rectangle.

After the image is allocated but has not been written to this returns the full rectangle of the image so that functions do not have to manage a case for uninitialized data. The image still retains an uninitialized value, but once the image is written to via any means such as vxCommitImagePatch, the valid region is altered to contain the maximum bounds of the written area.

Parameters

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

Returns: vx_status

Return values

VX_ERROR_INVALID_REFERENCE	Invalid image.
VX_ERROR_INVALID_PARAMETERS	Invalid rect.
VX_STATUS	Valid image.

Note: This rectangle can be passed directly to vxAccessImagePatch to get the full valid region of the image. Modifications from vxCommitImagePatch grows the valid region.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation