The OpenVX Specification  2b213f9
Introduction

Abstract

OpenVX is a low-level programming framework domain to enable software developers to efficiently access computer vision hardware acceleration with both functional and performance portability. OpenVX has been designed to support modern hardware architectures, such as mobile and embedded SoCs as well as desktop systems. Many of these systems are parallel and heterogeneous: containing multiple processor types including multi-core CPUs, DSP subsystems, GPUs, dedicated vision computing fabrics as well as hardwired functionality. Additionally, vision system memory hierarchies can often be complex, distributed, and not fully coherent. OpenVX is designed to maximize functional and performance portability across these diverse hardware platforms, providing a computer vision framework that efficiently addresses current and future hardware architectures with minimal impact on applications.

OpenVX contains:

• a library of predefined and customizable vision functions,
• a graph-based execution model to combine function enabling both task and data-independent execution, and;
• a set of memory objects that abstract the physical memory.

OpenVX defines a C Application Programming Interface (API) for building, verifying, and coordinating graph execution, as well as for accessing memory objects. The graph abstraction enables OpenVX implementers to optimize the execution of the graph for the underlying acceleration architecture.

OpenVX also defines the vxu utility library, which exposes each OpenVX predefined function as a directly callable C function, without the need for first creating a graph. Applications built using the vxu library do not benefit from the optimizations enabled by graphs; however, the vxu library can be useful as the simplest way to use OpenVX and as first step in porting existing vision applications.

As the computer vision domain is still rapidly evolving, OpenVX provides an extensibility mechanism to enable developer-defined functions to be added to the application graph.

Purpose

The purpose of this document is to detail the Application Programming Interface (API) for OpenVX.

Scope of Specification

The document contains the definition of the OpenVX API. The conformance tests that are used to determine whether an implementation is consistent to this specification are defined separately.

Normative References

The section “Module Documentation” forms the normative part of the specification. Each API definition provided in that chapter has certain preconditions and post conditions specified that are normative. If these normative conditions are not met, the behavior of the function is undefined.

Version/Change History

• OpenVX 1.0 Provisional - November, 2013
• OpenVX 1.0 Provisional V2 - June, 2014
• OpenVX 1.0 - September 2014
• OpenVX 1.0.1 - April 2015
• OpenVX 1.1 - May 2016

Deprecation

Certain items that are deprecated through the evolution of this specification document are removed from it. However, to provide a backward compatibility for such items for a certain time period these items are made available via a compatibility header file available with the release of this specification document (vx_compatibility.h). The items listed in this compatibility header file are temporary only and are removed permanently when the backward compatibility is no longer supported for those items.

Requirements Language

In this specification, the words shall or must express a requirement that is binding, should expresses design goals or recommended actions, and may expresses an allowed behavior.

Typographical Conventions

The following typographical conventions are used in this specification.

• Bold words indicate warnings or strongly communicated concepts that are intended to draw attention to the text.
• Monospace words signify an API element (i.e., class, function, structure) or a filename.
• Italics denote an emphasis on a particular concept, an abstraction of a concept, or signify an argument, parameter, or member.
• Throughout this specification, code examples given to highlight a particular issue use the format as shown below:
• /* Example Code Section */
int main(int argc, char *argv[])
{
return 0;
}
• Some “mscgen” message diagrams are included in this specification. The graphical conventions for this tool can be found on its website.
http://www.mcternan.me.uk/mscgen/

Naming Conventions

The following naming conventions are used in this specification.

• Opaque objects and atomics are named as vx_object, e.g., vx_image or vx_uint8, with an underscore separating the object name from the “vx” prefix.
• Defined Structures are named as vx_struct_t, e.g., vx_imagepatch_addressing_t, with underscores separating the structure from the “vx” prefix and a “t” to denote that it is a structure.
• Defined Enumerations are named as vx_enum_e, e.g., vx_type_e, with underscores separating the enumeration from the “vx” prefix and an “e” to denote that it is an enumerated value.
• Application Programming Interfaces are named vxsomeFunction() using camel case, starting with lowercase, and no underscores, e.g., vxCreateContext().
• Vision functions also have a naming convention that follows a lower-case, inverse dotted hierarchy similar to Java Packages, e.g.,

"org.khronos.openvx.color_convert".

This minimizes the possibility of name collisions and promotes sorting and readability when querying the namespace of available vision functions. Each vision function should have a unique dotted name of the style: tld.vendor.library.function. The hierarchy of such vision function namespaces is undefined outside the subdomain “org.khronos”, but they do follow existing international standards. For OpenVX-specified vision functions, the “function” section of the unique name does not use camel case and uses underscores to separate words.

Glossary and Acronyms

• Atomic: The specification mentions atomics, which means a C primitive data type. Usages that have additional wording, such as atomic operations do not carry this meaning.
• API: Application Programming Interface that specifies how a software component interacts with another.
• Framework: A generic software abstraction in which users can override behaviors to produce application-specific functionality.
• Engine: A purpose-specific software abstraction that is tunable by users.
• Run-time: The execution phase of a program.
• Kernel: OpenVX uses the term kernel to mean an abstract computer vision function, not an Operating System kernel. Kernel may also refer to a set of convolution coefficients in some computer vision literature (e.g., the Sobel “kernel”). OpenVX does not use this meaning. OpenCL uses kernel (specifically cl_kernel) to qualify a function written in “CL” which the OpenCL may invoke directly. This is close to the meaning OpenVX uses; however, OpenVX does not define a language.

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:

• Erik Rainey - Amazon
• Susheel Gautam - QUALCOMM
• Victor Erukhimov - Itseez
• Doug Knisely - QUALCOMM
• Frank Brill - Samsung
• Kari Pulli - NVIDIA
• Thierry Lepley - NVIDIA
• Neil Trevett - NVIDIA
• Tomer Schwartz - Intel
• Shervin Emami - NVIDIA
• Olivier Pothier - STMicroelectronics International NV
• Andy Kuzma - Intel
• Mostafa Hagog - Intel
• Shorin Kyo - Huawei
• Renato Grottesi - ARM Limited
• Dave Schreiner - ARM Limited
• Chris Tseng - Texas Instruments, Inc.
• Daniel Laroche - NXP Semiconductors
• Andrew Garrard - Samsung Electronics
• Tomer Yanir - Samsung Electronics
• Erez Natan - Samsung Electronics
• Chang-Hyo Yu - Samsung Electronics
• Hans-Peter Nilsson - Axis Communications
• Stephen Neuendorffer - Xilinx, Inc.
• Amit Shoham - BDTi
• Paul Buxton - Imagination Technologies
• Yuki Kobayashi - Renesas Electronics
• Cormac Brick - Movidius Ltd
• Mikael Bourges-Sevenier - Aptina Imaging Corporation
• Tao Zhang - QUALCOMM
• Jesse Villareal - Texas Instruments, Inc.
• Vadim Pisarevsky - Itseez
• Andrey Kamaev - Itseez
• Roman Donchenko - Itseez
• Alexander Alekhin - Itseez
• Radha Giduthuri - AMD
• Xin Wang - Vivante Corporation
• Anshu Arya - MulticoreWare
• Steve Ramm - Imagination Technologies