Merge pull request #7681 from apavlenko:ivx-docs

OpenVX C++ wrappers docs (#7681)

* adding wrapper headers to the project to see them in IDE project explorer

* readme

* doxygen: toplevel brief-s

* more doxygen

* more doxygen

3rdparty/openvx/CMakeLists.txt

-add_library(openvx_hal STATIC include/openvx_hal.hpp src/openvx_hal.cpp)
+add_library(openvx_hal STATIC src/openvx_hal.cpp include/openvx_hal.hpp include/ivx.hpp include/ivx_lib_debug.hpp)
 target_include_directories(openvx_hal PUBLIC
   ${CMAKE_CURRENT_SOURCE_DIR}/include
   ${CMAKE_SOURCE_DIR}/modules/core/include

3rdparty/openvx/README.md

+# C++ wrappers for OpenVX-1.x C API
+
+## Core ideas:
+
+* lightweight - minimal overhead vs standard C API
+* automatic references counting
+* exceptions instead of return codes
+* object-oriented design
+* (NYI) helpers for user-defined kernels & nodes
+* C++ 11 friendly
+
+## Quick start sample
+
+The following short sample gives basic knowledges on the wrappers usage:
+
+```cpp
+#include "ivx.hpp"
+#include "ivx_lib_debug.hpp" // ivx::debug::*
+
+int main()
+{
+	vx_uint32 width = 640, height = 480;
+	try
+	{
+		ivx::Context context = ivx::Context::create();
+		ivx::Graph graph = ivx::Graph::create(context);
+		ivx::Image
+		    gray = ivx::Image::create(context, width, height, VX_DF_IMAGE_U8),
+		    gb   = ivx::Image::createVirtual(graph),
+		    res  = ivx::Image::create(context, width, height, VX_DF_IMAGE_U8);
+
+		context.loadKernels("openvx-debug");  // ivx::debug::*
+
+		ivx::debug::fReadImage(context, inputPath, gray);
+
+		ivx::Node::create(graph, VX_KERNEL_GAUSSIAN_3x3, gray, gb);
+		ivx::Node::create(
+		    graph,
+		    VX_KERNEL_THRESHOLD,
+		    gb,
+		    ivx::Threshold::createBinary(context, VX_TYPE_UINT8, 50),
+		    res
+		);
+
+		graph.verify();
+		graph.process();
+
+		ivx::debug::fWriteImage(context, res, "ovx-res-cpp.pgm");
+    }
+    catch (const ivx::RuntimeError& e)
+    {
+        printf("ErrorRuntime: code = %d(%x), message = %s\n", e.status(), e.status(), e.what());
+        return e.status();
+    }
+    catch (const ivx::WrapperError& e)
+    {
+        printf("ErrorWrapper: message = %s\n", e.what());
+        return -1;
+    }
+    catch(const std::exception& e)
+    {
+        printf("runtime_error: message = %s\n", e.what());
+        return -1;
+    }
+
+    return 0;
+}
+	
+```
+## C++ API overview
+
+The wrappers have **header-only** implementation that simplifies their integration to projects.
+All the API is inside `ivx` namespace (E.g. `class ivx::Graph`).
+
+While the C++ API is pretty much the same for underlying OpenVX version **1.0** and **1.1**, there are alternative code branches for some features implementation  that are selected at **compile time** via `#ifdef` preprocessor directives.
+E.g. external ref-counting is implemented for 1.0 version and native OpenVX one is used (via  `vxRetainReference()` and `vxReleaseXYZ()`) for version 1.1.
+
+Also there are some **C++ 11** features are used (e.g. rvalue ref-s) when their availability is detected at ***compile time***.
+
+C++ exceptions are used for errors indication instead of return codes. There are two types of exceptions are defined:  `RuntimeError` is thrown when OpenVX C call returned unsuccessful result and `WrapperError` is thrown when a problem is occured in the wrappers code. Both exception calsses are derived from `std::exception` (actually from its inheritants).
+
+The so called **OpenVX objects** (e.g. `vx_image`) are represented as C++ classes in wrappers.
+All these classes use automatic ref-counting that allows development of exception-safe code.
+All these classes have `create()` or `createXYZ()` `static` methods for instances creation. (E.g. `Image::create()`, `Image::createVirtual()` and  `Image::createFromHandle()`)
+Most of the wrapped OpenVX functions are represented as methods of the corresponding C++ classes, but in most cases they still accept C "object" types (e.g. `vx_image` or `vx_context`) that allows mixing of C and C++ OpenVX API use. 
+E.g.:
+```cpp
+class Image
+{
+    static Image create(vx_context context, vx_uint32 width, vx_uint32 height, vx_df_image format);
+    static Image createVirtual(vx_graph graph, vx_uint32 width = 0, vx_uint32 height = 0, vx_df_image format = VX_DF_IMAGE_VIRT);
+    // ...
+}
+```
+All the classes instances can automatically be converted to the corresponding C "object" types.
+
+For more details please refer to C++ wrappers reference manual or directly to their source code.