The OpenVX Specification  r31169
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...

## 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 VX_API_CALL vxAccessImagePatch (vx_image image, const 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 VX_API_CALL vxCommitImagePatch (vx_image image, vx_rectangle_t *rect, vx_uint32 plane_index, vx_imagepatch_addressing_t *addr, const void *ptr)
This allows the User to commit a rectangular patch (subset) of an image from a single plane. More...

vx_size VX_API_CALL vxComputeImagePatchSize (vx_image image, const vx_rectangle_t *rect, vx_uint32 plane_index)
This computes the size needed to retrieve an image patch from an image. 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 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 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 void *value)
Creates a reference to an image object that has a singular, uniform value in all pixels. 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 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...

## 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.
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)
{
void *base_ptr = NULL;
vx_uint32 width = 640, height = 480, plane = 0;
vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
rect.start_x = rect.start_y = 0;
rect.end_x = rect.end_y = PATCH_DIM;
status = vxAccessImagePatch(image, &rect, plane,
if (status == VX_SUCCESS)
{
vx_uint32 x,y,i,j;
vx_uint8 pixel = 0;
/* a couple addressing options */
/* use linear addressing function/macro */
*ptr2 = pixel;
}
*ptr2 = pixel;
}
}
* for subsampled planes, scale will change
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
tmp[i] = pixel;
}
}
/* more efficient direct addressing by client.
* for subsampled planes, scale will change.
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
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 1309 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.

vxCreateImage

Definition at line 166 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 800 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 1063 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 1080 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. [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 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 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 vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.
 vxAccessImagePatch to obtain direct memory access to the image data.
Note
vxAccessImagePatch and vxCommitImagePatch 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_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 vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.
Note
Passing this reference to vxAccessImagePatch will return an error.
 vx_image VX_API_CALL 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
An image reference vx_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.
Note
The user must call vxAccessImagePatch 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 vxAccessImagePatch will result in undefined behavior.
 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. 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 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. 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 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.

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 image is not a vx_image.
 vx_size VX_API_CALL vxComputeImagePatchSize ( vx_image image, const 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 VX_API_CALL vxAccessImagePatch ( vx_image image, const 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. [in,out] addr A pointer to a structure describing the addressing information of the image patch to accessed. Input case: ptr is a pointer to a non-NULL pointer. The addr parameter must be the address of an addressing structure that describes how the user will access the requested image data at address (*ptr). Output case: ptr is a pointer to a NULL pointer. The function fills the structure pointed by addr with the addressing information that the user must consult to access the pixel data at address (*ptr). If the image being accessed was created via vxCreateImageFromHandle, then the returned addressing information will be the identical to that of the addressing structure provided when vxCreateImageFromHandle was called. [in,out] ptr A pointer to a pointer to a location to store the requested data. Input case: ptr is a pointer to a non-NULL pointer to a valid pixel buffer. This buffer will be used in one of two ways, depending on the value of the usage parameter. If usage is VX_WRITE_ONLY, then the buffer must contain pixel data that the user wants to replace the image's pixel data with. Otherwise (i.e., usage is not VX_WRITE_ONLY), the image's current pixel data will be written to the memory starting at address (*ptr) as storage memory for the access request. The caller must ensure enough memory has been allocated for the requested patch with the requested addressing. If image was created via vxCreateImageFromHandle, and the pixel buffer pointed to by (*ptr) overlaps the original pixel buffer provided when image was created, then the results of such a call to vxAccessImagePatch are undefined. Output case: ptr is a pointer to a NULL pointer. This NULL pointer will be overwritten with a pointer to the address where the requested data can be accessed. If image was created via vxCreateImageFromHandle then the overwriting pointer must be within the original pixel buffer provided when image was created. (*ptr) must eventually be provided as the ptr parameter of a call to vxCommitImagePatch. [in] usage This declares the intended usage of the pointer using the vx_accessor_e enumeration. For uniform images Only VX_READ_ONLY is supported.
Note
The addr and ptr parameters must both be input, or both be output, otherwise the behavior is undefined.
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)
{
void *base_ptr = NULL;
vx_uint32 width = 640, height = 480, plane = 0;
vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
rect.start_x = rect.start_y = 0;
rect.end_x = rect.end_y = PATCH_DIM;
status = vxAccessImagePatch(image, &rect, plane,
if (status == VX_SUCCESS)
{
vx_uint32 x,y,i,j;
vx_uint8 pixel = 0;
/* a couple addressing options */
/* use linear addressing function/macro */
*ptr2 = pixel;
}
*ptr2 = pixel;
}
}
* for subsampled planes, scale will change
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
tmp[i] = pixel;
}
}
/* more efficient direct addressing by client.
* for subsampled planes, scale will change.
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
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 VX_API_CALL vxCommitImagePatch ( vx_image image, vx_rectangle_t * rect, vx_uint32 plane_index, vx_imagepatch_addressing_t * addr, const 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 A pointer to a pixel buffer to be committed. If the user previously provided a pointer to this buffer to vxAccessImagePatch, the buffer can be freed or re-used after vxCommitImagePatch completes. If the pointer was returned by vxAccessImagePatch, reads or writes to the location pointed by ptr after vxCommitImagePatch completes will result in undefined behavior.
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)
{
void *base_ptr = NULL;
vx_uint32 width = 640, height = 480, plane = 0;
vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
rect.start_x = rect.start_y = 0;
rect.end_x = rect.end_y = PATCH_DIM;
status = vxAccessImagePatch(image, &rect, plane,
if (status == VX_SUCCESS)
{
vx_uint32 x,y,i,j;
vx_uint8 pixel = 0;
/* a couple addressing options */
/* use linear addressing function/macro */
*ptr2 = pixel;
}
*ptr2 = pixel;
}
}
* for subsampled planes, scale will change
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
tmp[i] = pixel;
}
}
/* more efficient direct addressing by client.
* for subsampled planes, scale will change.
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
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.

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)
{
void *base_ptr = NULL;
vx_uint32 width = 640, height = 480, plane = 0;
vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
rect.start_x = rect.start_y = 0;
rect.end_x = rect.end_y = PATCH_DIM;
status = vxAccessImagePatch(image, &rect, plane,
if (status == VX_SUCCESS)
{
vx_uint32 x,y,i,j;
vx_uint8 pixel = 0;
/* a couple addressing options */
/* use linear addressing function/macro */
*ptr2 = pixel;
}
*ptr2 = pixel;
}
}
* for subsampled planes, scale will change
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
tmp[i] = pixel;
}
}
/* more efficient direct addressing by client.
* for subsampled planes, scale will change.
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
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;
}

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)
{
void *base_ptr = NULL;
vx_uint32 width = 640, height = 480, plane = 0;
vx_image image = vxCreateImage(context, width, height, VX_DF_IMAGE_U8);
rect.start_x = rect.start_y = 0;
rect.end_x = rect.end_y = PATCH_DIM;
status = vxAccessImagePatch(image, &rect, plane,
if (status == VX_SUCCESS)
{
vx_uint32 x,y,i,j;
vx_uint8 pixel = 0;
/* a couple addressing options */
/* use linear addressing function/macro */
*ptr2 = pixel;
}
*ptr2 = pixel;
}
}
* for subsampled planes, scale will change
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
tmp[i] = pixel;
}
}
/* more efficient direct addressing by client.
* for subsampled planes, scale will change.
*/
vx_uint8 *tmp = (vx_uint8 *)base_ptr;
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 VX_API_CALL 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_SUCCESS 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.