Object: Image

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 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...
void *VX_API_CALL	vxFormatImagePatchAddress1d (void *ptr, vx_uint32 index, const vx_imagepatch_addressing_t *addr)
	Accesses a specific indexed pixel in an image patch. More...
void *VX_API_CALL	vxFormatImagePatchAddress2d (void *ptr, vx_uint32 x, vx_uint32 y, const vx_imagepatch_addressing_t *addr)
	Accesses a specific pixel at a 2d coordinate in an image patch. More...
vx_status VX_API_CALL	vxGetValidRegionImage (vx_image image, vx_rectangle_t *rect)
	Retrieves the valid region of the image as a rectangle. More...
vx_status VX_API_CALL	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

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

See also

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.

See also

vxAccessImagePatch to obtain direct memory access to the image data.

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

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

Parameters

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

Returns

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

vx_image VX_API_CALL vxCreateUniformImage	(	vx_context	context,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color,
		const 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.

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 VX_API_CALL vxCreateVirtualImage	(	vx_graph	graph,
		vx_uint32	width,
		vx_uint32	height,
		vx_df_image	color
	)

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

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

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

Parameters

[in]	graph	The reference to the parent graph.
[in]	width	The width of the image in pixels. A value of zero informs the interface that the value is unspecified.
[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)
{
    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 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)
{
    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* VX_API_CALL vxFormatImagePatchAddress1d	(	void *	ptr,
		vx_uint32	index,
		const vx_imagepatch_addressing_t *	addr
	)

Accesses a specific indexed pixel in an image patch.

Parameters

[in]	ptr	The base pointer of the patch as returned from 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* VX_API_CALL vxFormatImagePatchAddress2d	(	void *	ptr,
		vx_uint32	x,
		vx_uint32	y,
		const vx_imagepatch_addressing_t *	addr
	)

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

Parameters

[in]	ptr	The base pointer of the patch as returned from 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 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.