Copyright 2013-2025 The Khronos Group Inc.
This specification is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.
This specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at www.khronos.org/files/member_agreement.pdf. Khronos Group grants a conditional copyright license to use and reproduce the unmodified specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms. Parties desiring to implement the specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos IP Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this specification; see https://www.khronos.org/adopters.
Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.
Khronos is a registered trademark, and OpenVX is a trademark of The Khronos Group Inc. OpenCL is a trademark of Apple Inc., used under license by Khronos. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.
1. Extension to support object arrays of sub-images
1.1. Purpose
Node replication is a useful mechanism whereby several images may be processed the same way, in parallel. To accomplish this, nodes are connected with data objects that are the first elements in object arrays, and the nodes then replicated. Often it is convenient to perform some graph operations on sub-images, such as regions of interest or single channels from a multi-channel image, and this is accomplished by creating the necessary sub-image and connecting this to one or more nodes. However, since it is not possible currently to create object arrays that are sub-images, it is not possible to replicate these nodes.
The other method of replication uses image pyramids, but at present we cannot see a use case where a pyramid of sub-images of another pyramid is required.
1.2. Example Use Case
-
Replication of nodes in graphs where sub-images are involved
1.3. Acknowledgements
This specification would not be possible without the contributions from this partial list of the following individuals from the Khronos Working Group and the companies that they represented at the time:
-
Simon Barfield - ETAS (Robert Bosch GmbH)
-
Raphael Cano - Robert Bosch GmbH
-
Radhakrishna Giduthuri - Intel
-
Andrew Graves - ETAS (Robert Bosch GmbH)
-
Viktor Gyenes - AI Motive
-
Kiriti Nagesh Gowda - AMD
-
Stephen Ramm - ETAS (Robert Bosch GmbH)
-
Jesse Villarreal - TI
2. Requirements
2.1. Functions
2.1.1. vxCreateObjectArrayFromROI
Creates an object array or virtual object array of images from another object array of images given a rectangle. The original object array may be virtual or non-virtual.
Function signature:
vx_object_array vxCreateObjectArrayFromROI(vx_object_array image_array, const vx_rectangle_t* rect);Parameters
-
[in] image_array the reference to the parent object array
-
[in] rect - The region of interest rectangle. Must contain points within the parent image pixel space.
The input object array image_array must be a non-virtual or virtual object array of images with width, height and format all defined.
The rectangle rect must be defined within the pixel space of the parent images.
For VX_DF_IMAGE_U1-type images there are some restrictions for the rectangle that can be used to create a images using vxCreateObjectArrayFromROI. Namely, the rectangle needs to have its left edge aligned to a byte boundary in the parent image, i.e., _start_x in the vx_rectangle_t must be a multiple of 8 (including 0). This is because images of type VX_DF_IMAGE_U1 must start on a byte boundary and sub-images created by vxCreateObjectArrayFromROI points to data in the original images.
Returns
A reference to the array of sub-images; any possible errors preventing a successful creation may be checked using vxGetStatus().
Possible causes of errors are:
-
Invalid input reference
-
Input reference is not to an object array
-
Input object array does not contain images
-
Input images do not have their width, height or format specified
-
Input object array images bounds are not defined, do not contain the region described by rect or are not supported for the image format
-
rect is NULL
-
Out of resources
The new reference refers to data in the original array, so that updates to the new images update the parent images, and updates to the parent images in the region of interest update the sub-images.
If the input object array is virtual, the new reference returned is to a virtual object array of sub-images. If the input object array is non-virtual, the new reference returned is to a non-virtual object array of sub-images.
2.1.2. vxCreateObjectArrayFromChannel
Creates an object array or virtual object array of images from a single plane channel of another object array of images. The original object array may be virtual or non-virtual.
Function signature:
vx_object_array vxCreateObjectArrayFromChannel(vx_object_array image_array, vx_enum channel);Parameters
-
[in] image_array the reference to the parent object array
-
[in] channel - The vx_channel to use.
The input object array image_array is a non-virtual or virtual object array of images with a defined format.
The function supports channels that occupy an entire plane of multi-planar images in image_array. Image formats and channels shall be supported as described in the following table:
| Supported image format | Supported channel(s) | Sub-image format |
|---|---|---|
NV12 |
VX_CHANNEL_Y |
VX_DF_IMAGE_U8 |
NV21 |
VX_CHANNEL_Y |
VX_DF_IMAGE_U8 |
IYUV |
VX_CHANNEL_Y |
VX_DF_IMAGE_U8 |
VX_CHANNEL_U |
VX_DF_IMAGE_U8 |
|
VX_CHANNEL_V |
VX_DF_IMAGE_U8 |
|
YUV4 |
VX_CHANNEL_Y |
VX_DF_IMAGE_U8 |
VX_CHANNEL_U |
VX_DF_IMAGE_U8 |
|
VX_CHANNEL_V |
VX_DF_IMAGE_U8 |
Returns
A reference to the array of sub-images of format described in the previous table; any possible errors preventing a successful creation may be checked using vxGetStatus().
Possible causes of errors are:
-
Invalid input reference
-
Input reference is not to an object array
-
Input object array does not contain images
-
Input images do not have their format specified
-
Input images are not in a supported format
-
channel is not a supported channel for the image format
-
Out of resources
The new reference refers to data in the original array, so that updates to the new images update the parent images, and updates to the specified channel of the parent images update the sub-images.
If the input object array is virtual, the new reference returned is to a virtual object array of sub-images. If the input object array is non-virtual, the new reference returned is to a non-virtual object array of sub-images.