From 415668ecf04561959aca6a020e4f5c1390120225 Mon Sep 17 00:00:00 2001 From: Dmitry Matveev Date: Mon, 31 May 2021 22:02:05 +0300 Subject: [PATCH] G-API: Documentation updates 1) Document GFrame/MediaFrame (and also other G-API types) - Added doxygen comments for GMat, GScalar, GArray, GOpaque classes; - Documented GFrame and its host-side counterpart MediaFrame; - Added some more notes to the data type classes. 2) Give @brief descriptions to most of the cv::gapi::* namespaces 3) Make some symbols private - These structures are mainly internal and shouldn't be used directly --- doc/Doxyfile.in | 2 +- modules/gapi/include/opencv2/gapi/core.hpp | 4 + .../include/opencv2/gapi/cpu/gcpukernel.hpp | 6 +- .../opencv2/gapi/fluid/gfluidkernel.hpp | 3 + modules/gapi/include/opencv2/gapi/garray.hpp | 66 +++++++- .../include/opencv2/gapi/gasync_context.hpp | 7 + modules/gapi/include/opencv2/gapi/gframe.hpp | 50 +++++- modules/gapi/include/opencv2/gapi/gkernel.hpp | 2 + modules/gapi/include/opencv2/gapi/gmat.hpp | 38 ++++- modules/gapi/include/opencv2/gapi/gopaque.hpp | 27 ++- modules/gapi/include/opencv2/gapi/gscalar.hpp | 73 +++++++- .../gapi/include/opencv2/gapi/gstreaming.hpp | 8 + modules/gapi/include/opencv2/gapi/imgproc.hpp | 4 + modules/gapi/include/opencv2/gapi/infer.hpp | 3 +- .../gapi/include/opencv2/gapi/infer/ie.hpp | 5 + .../gapi/include/opencv2/gapi/infer/onnx.hpp | 4 + modules/gapi/include/opencv2/gapi/media.hpp | 156 ++++++++++++++++-- .../include/opencv2/gapi/ocl/goclkernel.hpp | 3 + .../gapi/include/opencv2/gapi/own/types.hpp | 5 + .../include/opencv2/gapi/plaidml/plaidml.hpp | 5 + .../include/opencv2/gapi/python/python.hpp | 9 + .../include/opencv2/gapi/render/render.hpp | 4 + modules/gapi/include/opencv2/gapi/rmat.hpp | 4 + .../gapi/include/opencv2/gapi/s11n/base.hpp | 5 + modules/gapi/include/opencv2/gapi/stereo.hpp | 5 + modules/gapi/include/opencv2/gapi/video.hpp | 4 + modules/gapi/samples/api_ref_snippets.cpp | 12 +- modules/gapi/samples/gaze_estimation.cpp | 10 +- 28 files changed, 486 insertions(+), 38 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 26ad42b1e5..ce207d3e31 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -106,7 +106,7 @@ RECURSIVE = YES EXCLUDE = @CMAKE_DOXYGEN_EXCLUDE_LIST@ EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = *.inl.hpp *.impl.hpp *_detail.hpp */cudev/**/detail/*.hpp *.m */opencl/runtime/* */legacy/* *_c.h @DOXYGEN_EXCLUDE_PATTERNS@ -EXCLUDE_SYMBOLS = cv::DataType<*> cv::traits::* int void CV__* T __CV* +EXCLUDE_SYMBOLS = cv::DataType<*> cv::traits::* int void CV__* T __CV* cv::gapi::detail* EXAMPLE_PATH = @CMAKE_DOXYGEN_EXAMPLE_PATH@ EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = YES diff --git a/modules/gapi/include/opencv2/gapi/core.hpp b/modules/gapi/include/opencv2/gapi/core.hpp index cb8a6127d7..b7f65b6719 100644 --- a/modules/gapi/include/opencv2/gapi/core.hpp +++ b/modules/gapi/include/opencv2/gapi/core.hpp @@ -29,6 +29,10 @@ */ namespace cv { namespace gapi { +/** + * @brief This namespace contains G-API Operation Types for OpenCV + * Core module functionality. + */ namespace core { using GMat2 = std::tuple; using GMat3 = std::tuple; // FIXME: how to avoid this? diff --git a/modules/gapi/include/opencv2/gapi/cpu/gcpukernel.hpp b/modules/gapi/include/opencv2/gapi/cpu/gcpukernel.hpp index 5539e244ba..009c19688b 100644 --- a/modules/gapi/include/opencv2/gapi/cpu/gcpukernel.hpp +++ b/modules/gapi/include/opencv2/gapi/cpu/gcpukernel.hpp @@ -40,6 +40,10 @@ namespace gimpl namespace gapi { +/** + * @brief This namespace contains G-API CPU backend functions, + * structures, and symbols. + */ namespace cpu { /** @@ -492,7 +496,7 @@ public: #define GAPI_OCV_KERNEL_ST(Name, API, State) \ struct Name: public cv::GCPUStKernelImpl \ - +/// @private class gapi::cpu::GOCVFunctor : public gapi::GFunctor { public: diff --git a/modules/gapi/include/opencv2/gapi/fluid/gfluidkernel.hpp b/modules/gapi/include/opencv2/gapi/fluid/gfluidkernel.hpp index dbb36d801d..53b68c4e21 100644 --- a/modules/gapi/include/opencv2/gapi/fluid/gfluidkernel.hpp +++ b/modules/gapi/include/opencv2/gapi/fluid/gfluidkernel.hpp @@ -25,6 +25,9 @@ namespace cv { namespace gapi { +/** + * @brief This namespace contains G-API Fluid backend functions, structures, and symbols. + */ namespace fluid { /** diff --git a/modules/gapi/include/opencv2/gapi/garray.hpp b/modules/gapi/include/opencv2/gapi/garray.hpp index 32799bc07e..d7b365f7f9 100644 --- a/modules/gapi/include/opencv2/gapi/garray.hpp +++ b/modules/gapi/include/opencv2/gapi/garray.hpp @@ -340,21 +340,79 @@ namespace detail /** \addtogroup gapi_data_objects * @{ */ - +/** + * @brief `cv::GArray` template class represents a list of objects + * of class `T` in the graph. + * + * `cv::GArray` describes a functional relationship between + * operations consuming and producing arrays of objects of class + * `T`. The primary purpose of `cv::GArray` is to represent a + * dynamic list of objects -- where the size of the list is not known + * at the graph construction or compile time. Examples include: corner + * and feature detectors (`cv::GArray`), object detection + * and tracking results (`cv::GArray`). Programmers can use + * their own types with `cv::GArray` in the custom operations. + * + * Similar to `cv::GScalar`, `cv::GArray` may be value-initialized + * -- in this case a graph-constant value is associated with the object. + * + * `GArray` is a virtual counterpart of `std::vector`, which is + * usually used to represent the `GArray` data in G-API during the + * execution. + * + * @sa `cv::GOpaque` + */ template class GArray { public: // Host type (or Flat type) - the type this GArray is actually // specified to. + /// @private using HT = typename detail::flatten_g::type>::type; + /** + * @brief Constructs a value-initialized `cv::GArray` + * + * `cv::GArray` objects may have their values + * be associated at graph construction time. It is useful when + * some operation has a `cv::GArray` input which doesn't change during + * the program execution, and is set only once. In this case, + * there is no need to declare such `cv::GArray` as a graph input. + * + * @note The value of `cv::GArray` may be overwritten by assigning some + * other `cv::GArray` to the object using `operator=` -- on the + * assigment, the old association or value is discarded. + * + * @param v a std::vector to associate with this + * `cv::GArray` object. Vector data is copied into the + * `cv::GArray` (no reference to the passed data is held). + */ explicit GArray(const std::vector& v) // Constant value constructor : m_ref(detail::GArrayU(detail::VectorRef(v))) { putDetails(); } + + /** + * @overload + * @brief Constructs a value-initialized `cv::GArray` + * + * @param v a std::vector to associate with this + * `cv::GArray` object. Vector data is moved into the `cv::GArray`. + */ explicit GArray(std::vector&& v) // Move-constructor : m_ref(detail::GArrayU(detail::VectorRef(std::move(v)))) { putDetails(); } - GArray() { putDetails(); } // Empty constructor - explicit GArray(detail::GArrayU &&ref) // GArrayU-based constructor - : m_ref(ref) { putDetails(); } // (used by GCall, not for users) + + /** + * @brief Constructs an empty `cv::GArray` + * + * Normally, empty G-API data objects denote a starting point of + * the graph. When an empty `cv::GArray` is assigned to a result + * of some operation, it obtains a functional link to this + * operation (and is not empty anymore). + */ + GArray() { putDetails(); } // Empty constructor + + /// @private + explicit GArray(detail::GArrayU &&ref) // GArrayU-based constructor + : m_ref(ref) { putDetails(); } // (used by GCall, not for users) /// @private detail::GArrayU strip() const { diff --git a/modules/gapi/include/opencv2/gapi/gasync_context.hpp b/modules/gapi/include/opencv2/gapi/gasync_context.hpp index 69ce530fc9..f49b59822d 100644 --- a/modules/gapi/include/opencv2/gapi/gasync_context.hpp +++ b/modules/gapi/include/opencv2/gapi/gasync_context.hpp @@ -17,6 +17,13 @@ namespace cv { namespace gapi{ + +/** + * @brief This namespace contains experimental G-API functionality, + * functions or structures in this namespace are subjects to change or + * removal in the future releases. This namespace also contains + * functions which API is not stabilized yet. + */ namespace wip { /** diff --git a/modules/gapi/include/opencv2/gapi/gframe.hpp b/modules/gapi/include/opencv2/gapi/gframe.hpp index 13fd5d6d29..96913dc4cc 100644 --- a/modules/gapi/include/opencv2/gapi/gframe.hpp +++ b/modules/gapi/include/opencv2/gapi/gframe.hpp @@ -28,14 +28,54 @@ struct GOrigin; /** \addtogroup gapi_data_objects * @{ */ +/** + * @brief GFrame class represents an image or media frame in the graph. + * + * GFrame doesn't store any data itself, instead it describes a + * functional relationship between operations consuming and producing + * GFrame objects. + * + * GFrame is introduced to handle various media formats (e.g., NV12 or + * I420) under the same type. Various image formats may differ in the + * number of planes (e.g. two for NV12, three for I420) and the pixel + * layout inside. GFrame type allows to handle these media formats in + * the graph uniformly -- the graph structure will not change if the + * media format changes, e.g. a different camera or decoder is used + * with the same graph. G-API provides a number of operations which + * operate directly on GFrame, like `infer<>()` or + * renderFrame(); these operations are expected to handle different + * media formats inside. There is also a number of accessor + * operations like BGR(), Y(), UV() -- these operations provide + * access to frame's data in the familiar cv::GMat form, which can be + * used with the majority of the existing G-API operations. These + * accessor functions may perform color space converion on the fly if + * the image format of the GFrame they are applied to differs from the + * operation's semantic (e.g. the BGR() accessor is called on an NV12 + * image frame). + * + * GFrame is a virtual counterpart of cv::MediaFrame. + * + * @sa cv::MediaFrame, cv::GFrameDesc, BGR(), Y(), UV(), infer<>(). + */ class GAPI_EXPORTS_W_SIMPLE GFrame { public: - GAPI_WRAP GFrame(); // Empty constructor - GFrame(const GNode &n, std::size_t out); // Operation result constructor - - GOrigin& priv(); // Internal use only - const GOrigin& priv() const; // Internal use only + /** + * @brief Constructs an empty GFrame + * + * Normally, empty G-API data objects denote a starting point of + * the graph. When an empty GFrame is assigned to a result of some + * operation, it obtains a functional link to this operation (and + * is not empty anymore). + */ + GAPI_WRAP GFrame(); // Empty constructor + + /// @private + GFrame(const GNode &n, std::size_t out); // Operation result constructor + /// @private + GOrigin& priv(); // Internal use only + /// @private + const GOrigin& priv() const; // Internal use only private: std::shared_ptr m_priv; diff --git a/modules/gapi/include/opencv2/gapi/gkernel.hpp b/modules/gapi/include/opencv2/gapi/gkernel.hpp index f70e50253d..cfac552bfe 100644 --- a/modules/gapi/include/opencv2/gapi/gkernel.hpp +++ b/modules/gapi/include/opencv2/gapi/gkernel.hpp @@ -372,6 +372,7 @@ namespace gapi { // Prework: model "Device" API before it gets to G-API headers. // FIXME: Don't mix with internal Backends class! + /// @private class GAPI_EXPORTS GBackend { public: @@ -412,6 +413,7 @@ namespace std namespace cv { namespace gapi { + /// @private class GFunctor { public: diff --git a/modules/gapi/include/opencv2/gapi/gmat.hpp b/modules/gapi/include/opencv2/gapi/gmat.hpp index 11c3071f03..7bea97bbc5 100644 --- a/modules/gapi/include/opencv2/gapi/gmat.hpp +++ b/modules/gapi/include/opencv2/gapi/gmat.hpp @@ -30,29 +30,57 @@ struct GOrigin; * @brief G-API data objects used to build G-API expressions. * * These objects do not own any particular data (except compile-time - * associated values like with cv::GScalar) and are used to construct - * graphs. + * associated values like with cv::GScalar or `cv::GArray`) and are + * used only to construct graphs. * * Every graph in G-API starts and ends with data objects. * * Once constructed and compiled, G-API operates with regular host-side * data instead. Refer to the below table to find the mapping between - * G-API and regular data types. + * G-API and regular data types when passing input and output data + * structures to G-API: * * G-API data type | I/O data type * ------------------ | ------------- - * cv::GMat | cv::Mat + * cv::GMat | cv::Mat, cv::UMat, cv::RMat * cv::GScalar | cv::Scalar * `cv::GArray` | std::vector * `cv::GOpaque` | T + * cv::GFrame | cv::MediaFrame + */ +/** + * @brief GMat class represents image or tensor data in the + * graph. + * + * GMat doesn't store any data itself, instead it describes a + * functional relationship between operations consuming and producing + * GMat objects. + * + * GMat is a virtual counterpart of Mat and UMat, but it + * doesn't mean G-API use Mat or UMat objects internally to represent + * GMat objects -- the internal data representation may be + * backend-specific or optimized out at all. + * + * @sa Mat, GMatDesc */ class GAPI_EXPORTS_W_SIMPLE GMat { public: + /** + * @brief Constructs an empty GMat + * + * Normally, empty G-API data objects denote a starting point of + * the graph. When an empty GMat is assigned to a result of some + * operation, it obtains a functional link to this operation (and + * is not empty anymore). + */ GAPI_WRAP GMat(); // Empty constructor - GMat(const GNode &n, std::size_t out); // Operation result constructor + /// @private + GMat(const GNode &n, std::size_t out); // Operation result constructor + /// @private GOrigin& priv(); // Internal use only + /// @private const GOrigin& priv() const; // Internal use only private: diff --git a/modules/gapi/include/opencv2/gapi/gopaque.hpp b/modules/gapi/include/opencv2/gapi/gopaque.hpp index 00f0718422..979a9db8c4 100644 --- a/modules/gapi/include/opencv2/gapi/gopaque.hpp +++ b/modules/gapi/include/opencv2/gapi/gopaque.hpp @@ -307,15 +307,40 @@ namespace detail /** \addtogroup gapi_data_objects * @{ */ - +/** + * @brief `cv::GOpaque` template class represents an object of + * class `T` in the graph. + * + * `cv::GOpaque` describes a functional relationship between operations + * consuming and producing object of class `T`. `cv::GOpaque` is + * designed to extend G-API with user-defined data types, which are + * often required with user-defined operations. G-API can't apply any + * optimizations to user-defined types since these types are opaque to + * the framework. However, there is a number of G-API operations + * declared with `cv::GOpaque` as a return type, + * e.g. cv::gapi::streaming::timestamp() or cv::gapi::streaming::size(). + * + * @sa `cv::GArray` + */ template class GOpaque { public: // Host type (or Flat type) - the type this GOpaque is actually // specified to. + /// @private using HT = typename detail::flatten_g>::type; + /** + * @brief Constructs an empty `cv::GOpaque` + * + * Normally, empty G-API data objects denote a starting point of + * the graph. When an empty `cv::GOpaque` is assigned to a result + * of some operation, it obtains a functional link to this + * operation (and is not empty anymore). + */ GOpaque() { putDetails(); } // Empty constructor + + /// @private explicit GOpaque(detail::GOpaqueU &&ref) // GOpaqueU-based constructor : m_ref(ref) { putDetails(); } // (used by GCall, not for users) diff --git a/modules/gapi/include/opencv2/gapi/gscalar.hpp b/modules/gapi/include/opencv2/gapi/gscalar.hpp index d4af2cab5d..c6edc33b75 100644 --- a/modules/gapi/include/opencv2/gapi/gscalar.hpp +++ b/modules/gapi/include/opencv2/gapi/gscalar.hpp @@ -25,18 +25,83 @@ struct GOrigin; /** \addtogroup gapi_data_objects * @{ */ - +/** + * @brief GScalar class represents cv::Scalar data in the graph. + * + * GScalar may be associated with a cv::Scalar value, which becomes + * its constant value bound in graph compile time. cv::GScalar describes a + * functional relationship between operations consuming and producing + * GScalar objects. + * + * GScalar is a virtual counterpart of cv::Scalar, which is usually used + * to represent the GScalar data in G-API during the execution. + * + * @sa Scalar + */ class GAPI_EXPORTS_W_SIMPLE GScalar { public: - GAPI_WRAP GScalar(); // Empty constructor - explicit GScalar(const cv::Scalar& s); // Constant value constructor from cv::Scalar + /** + * @brief Constructs an empty GScalar + * + * Normally, empty G-API data objects denote a starting point of + * the graph. When an empty GScalar is assigned to a result of some + * operation, it obtains a functional link to this operation (and + * is not empty anymore). + */ + GAPI_WRAP GScalar(); + + /** + * @brief Constructs a value-initialized GScalar + * + * In contrast with GMat (which can be either an explicit graph input + * or a result of some operation), GScalars may have their values + * be associated at graph construction time. It is useful when + * some operation has a GScalar input which doesn't change during + * the program execution, and is set only once. In this case, + * there is no need to declare such GScalar as a graph input. + * + * @note The value of GScalar may be overwritten by assigning some + * other GScalar to the object using `operator=` -- on the + * assigment, the old GScalar value is discarded. + * + * @param s a cv::Scalar value to associate with this GScalar object. + */ + explicit GScalar(const cv::Scalar& s); + + /** + * @overload + * @brief Constructs a value-initialized GScalar + * + * @param s a cv::Scalar value to associate with this GScalar object. + */ explicit GScalar(cv::Scalar&& s); // Constant value move-constructor from cv::Scalar + /** + * @overload + * @brief Constructs a value-initialized GScalar + * + * @param v0 A `double` value to associate with this GScalar. Note + * that only the first component of a four-component cv::Scalar is + * set to this value, with others remain zeros. + * + * This constructor overload is not marked `explicit` and can be + * used in G-API expression code like this: + * + * @snippet modules/gapi/samples/api_ref_snippets.cpp gscalar_implicit + * + * Here operator+(GMat,GScalar) is used to wrap cv::gapi::addC() + * and a value-initialized GScalar is created on the fly. + * + * @overload + */ GScalar(double v0); // Constant value constructor from double - GScalar(const GNode &n, std::size_t out); // Operation result constructor + /// @private + GScalar(const GNode &n, std::size_t out); // Operation result constructor + /// @private GOrigin& priv(); // Internal use only + /// @private const GOrigin& priv() const; // Internal use only private: diff --git a/modules/gapi/include/opencv2/gapi/gstreaming.hpp b/modules/gapi/include/opencv2/gapi/gstreaming.hpp index 371581345f..5bbed5e12d 100644 --- a/modules/gapi/include/opencv2/gapi/gstreaming.hpp +++ b/modules/gapi/include/opencv2/gapi/gstreaming.hpp @@ -372,6 +372,14 @@ protected: /** @} */ namespace gapi { + +/** + * @brief This namespace contains G-API functions, structures, and + * symbols related to the Streaming execution mode. + * + * Some of the operations defined in this namespace (e.g. size(), + * BGR(), etc.) can be used in the traditional execution mode too. + */ namespace streaming { /** * @brief Specify queue capacity for streaming execution. diff --git a/modules/gapi/include/opencv2/gapi/imgproc.hpp b/modules/gapi/include/opencv2/gapi/imgproc.hpp index 2dbe626ff1..5c4c6f7031 100644 --- a/modules/gapi/include/opencv2/gapi/imgproc.hpp +++ b/modules/gapi/include/opencv2/gapi/imgproc.hpp @@ -47,6 +47,10 @@ void validateFindingContoursMeta(const int depth, const int chan, const int mode namespace cv { namespace gapi { +/** + * @brief This namespace contains G-API Operation Types for OpenCV + * ImgProc module functionality. + */ namespace imgproc { using GMat2 = std::tuple; using GMat3 = std::tuple; // FIXME: how to avoid this? diff --git a/modules/gapi/include/opencv2/gapi/infer.hpp b/modules/gapi/include/opencv2/gapi/infer.hpp index eb9b9768c9..93701856bb 100644 --- a/modules/gapi/include/opencv2/gapi/infer.hpp +++ b/modules/gapi/include/opencv2/gapi/infer.hpp @@ -653,6 +653,7 @@ namespace gapi { // A type-erased form of network parameters. // Similar to how a type-erased GKernel is represented and used. +/// @private struct GAPI_EXPORTS GNetParam { std::string tag; // FIXME: const? GBackend backend; // Specifies the execution model @@ -664,7 +665,7 @@ struct GAPI_EXPORTS GNetParam { */ /** * @brief A container class for network configurations. Similar to - * GKernelPackage.Use cv::gapi::networks() to construct this object. + * GKernelPackage. Use cv::gapi::networks() to construct this object. * * @sa cv::gapi::networks */ diff --git a/modules/gapi/include/opencv2/gapi/infer/ie.hpp b/modules/gapi/include/opencv2/gapi/infer/ie.hpp index 5b614de363..610a2061af 100644 --- a/modules/gapi/include/opencv2/gapi/infer/ie.hpp +++ b/modules/gapi/include/opencv2/gapi/infer/ie.hpp @@ -24,6 +24,11 @@ namespace cv { namespace gapi { // FIXME: introduce a new sub-namespace for NN? + +/** + * @brief This namespace contains G-API OpenVINO backend functions, + * structures, and symbols. + */ namespace ie { GAPI_EXPORTS cv::gapi::GBackend backend(); diff --git a/modules/gapi/include/opencv2/gapi/infer/onnx.hpp b/modules/gapi/include/opencv2/gapi/infer/onnx.hpp index 3a4e35fb09..cfef0cc758 100644 --- a/modules/gapi/include/opencv2/gapi/infer/onnx.hpp +++ b/modules/gapi/include/opencv2/gapi/infer/onnx.hpp @@ -20,6 +20,10 @@ namespace cv { namespace gapi { + +/** + * @brief This namespace contains G-API ONNX Runtime backend functions, structures, and symbols. + */ namespace onnx { GAPI_EXPORTS cv::gapi::GBackend backend(); diff --git a/modules/gapi/include/opencv2/gapi/media.hpp b/modules/gapi/include/opencv2/gapi/media.hpp index 61a7098b55..aa7d6d6a1f 100644 --- a/modules/gapi/include/opencv2/gapi/media.hpp +++ b/modules/gapi/include/opencv2/gapi/media.hpp @@ -17,28 +17,107 @@ namespace cv { +/** \addtogroup gapi_data_structures + * @{ + * + * @brief Extra G-API data structures used to pass input/output data + * to the graph for processing. + */ +/** + * @brief cv::MediaFrame class represents an image/media frame + * obtained from an external source. + * + * cv::MediaFrame represents image data as specified in + * cv::MediaFormat. cv::MediaFrame is designed to be a thin wrapper over some + * external memory of buffer; the class itself provides an uniform + * interface over such types of memory. cv::MediaFrame wraps data from + * a camera driver or from a media codec and provides an abstraction + * layer over this memory to G-API. MediaFrame defines a compact interface + * to access and manage the underlying data; the implementation is + * fully defined by the associated Adapter (which is usually + * user-defined). + * + * @sa cv::RMat + */ class GAPI_EXPORTS MediaFrame { public: - enum class Access { R, W }; + /// This enum defines different types of cv::MediaFrame provided + /// access to the underlying data. Note that different flags can't + /// be combined in this version. + enum class Access { + R, ///< Access data for reading + W, ///< Access data for writing + }; class IAdapter; class View; using AdapterPtr = std::unique_ptr; + /** + * @brief Constructs an empty MediaFrame + * + * The constructed object has no any data associated with it. + */ MediaFrame(); - explicit MediaFrame(AdapterPtr &&); - template static cv::MediaFrame Create(Args&&...); - View access(Access) const; + /** + * @brief Constructs a MediaFrame with the given + * Adapter. MediaFrame takes ownership over the passed adapter. + * + * @param p an unique pointer to instance of IAdapter derived class. + */ + explicit MediaFrame(AdapterPtr &&p); + + /** + * @overload + * @brief Constructs a MediaFrame with the given parameters for + * the Adapter. The adapter of type `T` is costructed on the fly. + * + * @param args list of arguments to construct an adapter of type + * `T`. + */ + template static cv::MediaFrame Create(Args&&... args); + + /** + * @brief Obtain access to the underlying data with the given + * mode. + * + * Depending on the associated Adapter and the data wrapped, this + * method may be cheap (e.g., the underlying memory is local) or + * costly (if the underlying memory is external or device + * memory). + * + * @param mode an access mode flag + * @return a MediaFrame::View object. The views should be handled + * carefully, refer to the MediaFrame::View documentation for details. + */ + View access(Access mode) const; + + /** + * @brief Returns a media frame descriptor -- the information + * about the media format, dimensions, etc. + * @return a cv::GFrameDesc + */ cv::GFrameDesc desc() const; // FIXME: design a better solution // Should be used only if the actual adapter provides implementation + /// @private -- exclude from the OpenCV documentation for now. cv::util::any blobParams() const; - // Cast underlying MediaFrame adapter to the particular adapter type, - // return nullptr if underlying type is different - template T* get() const - { + /** + * @brief Casts and returns the associated MediaFrame adapter to + * the particular adapter type `T`, returns nullptr if the type is + * different. + * + * This method may be useful if the adapter type is known by the + * caller, and some lower level access to the memory is required. + * Depending on the memory type, it may be more efficient than + * access(). + * + * @return a pointer to the adapter object, nullptr if the adapter + * type is different. + */ + template T* get() const { static_assert(std::is_base_of::value, "T is not derived from cv::MediaFrame::IAdapter!"); auto* adapter = getAdapter(); @@ -58,6 +137,43 @@ inline cv::MediaFrame cv::MediaFrame::Create(Args&&... args) { return cv::MediaFrame(std::move(ptr)); } +/** + * @brief Provides access to the MediaFrame's underlying data. + * + * This object contains the necessary information to access the pixel + * data of the associated MediaFrame: arrays of pointers and strides + * (distance between every plane row, in bytes) for every image + * plane, as defined in cv::MediaFormat. + * There may be up to four image planes in MediaFrame. + * + * Depending on the MediaFrame::Access flag passed in + * MediaFrame::access(), a MediaFrame::View may be read- or + * write-only. + * + * Depending on the MediaFrame::IAdapter implementation associated + * with the parent MediaFrame, writing to memory with + * MediaFrame::Access::R flag may have no effect or lead to + * undefined behavior. Same applies to reading the memory with + * MediaFrame::Access::W flag -- again, depending on the IAdapter + * implementation, the host-side buffer the view provides access to + * may have no current data stored in (so in-place editing of the + * buffer contents may not be possible). + * + * MediaFrame::View objects must be handled carefully, as an external + * resource associated with MediaFrame may be locked for the time the + * MediaFrame::View object exists. Obtaining MediaFrame::View should + * be seen as "map" and destroying it as "unmap" in the "map/unmap" + * idiom (applicable to OpenCL, device memory, remote + * memory). + * + * When a MediaFrame buffer is accessed for writing, and the memory + * under MediaFrame::View::Ptrs is altered, the data synchronization + * of a host-side and device/remote buffer is not guaranteed until the + * MediaFrame::View is destroyed. In other words, the real data on the + * device or in a remote target may be updated at the MediaFrame::View + * destruction only -- but it depends on the associated + * MediaFrame::IAdapter implementation. + */ class GAPI_EXPORTS MediaFrame::View final { public: static constexpr const size_t MAX_PLANES = 4; @@ -65,19 +181,38 @@ public: using Strides = std::array; // in bytes using Callback = std::function; + /// @private View(Ptrs&& ptrs, Strides&& strs, Callback &&cb = [](){}); + + /// @private View(const View&) = delete; + + /// @private View(View&&) = default; + + /// @private View& operator = (const View&) = delete; + ~View(); - Ptrs ptr; - Strides stride; + Ptrs ptr; ///< Array of image plane pointers + Strides stride; ///< Array of image plane strides, in bytes. private: Callback m_cb; }; +/** + * @brief An interface class for MediaFrame data adapters. + * + * Implement this interface to wrap media data in the MediaFrame. It + * makes sense to implement this class if there is a custom + * cv::gapi::wip::IStreamSource defined -- in this case, a stream + * source can produce MediaFrame objects with this adapter and the + * media data may be passed to graph without any copy. For example, a + * GStreamer-based stream source can implement an adapter over + * `GstBuffer` and G-API will transparently use it in the graph. + */ class GAPI_EXPORTS MediaFrame::IAdapter { public: virtual ~IAdapter() = 0; @@ -87,6 +222,7 @@ public: // The default implementation does nothing virtual cv::util::any blobParams() const; }; +/** @} */ } //namespace cv diff --git a/modules/gapi/include/opencv2/gapi/ocl/goclkernel.hpp b/modules/gapi/include/opencv2/gapi/ocl/goclkernel.hpp index 8ec388d588..6a2f1df769 100644 --- a/modules/gapi/include/opencv2/gapi/ocl/goclkernel.hpp +++ b/modules/gapi/include/opencv2/gapi/ocl/goclkernel.hpp @@ -29,6 +29,9 @@ namespace gimpl namespace gapi { +/** + * @brief This namespace contains G-API OpenCL backend functions, structures, and symbols. + */ namespace ocl { /** diff --git a/modules/gapi/include/opencv2/gapi/own/types.hpp b/modules/gapi/include/opencv2/gapi/own/types.hpp index c77a62ca53..53bb867e32 100644 --- a/modules/gapi/include/opencv2/gapi/own/types.hpp +++ b/modules/gapi/include/opencv2/gapi/own/types.hpp @@ -15,6 +15,11 @@ namespace cv { namespace gapi { + +/** + * @brief This namespace contains G-API own data structures used in + * its standalone mode build. + */ namespace own { diff --git a/modules/gapi/include/opencv2/gapi/plaidml/plaidml.hpp b/modules/gapi/include/opencv2/gapi/plaidml/plaidml.hpp index bd12d25832..3207a8cb2e 100644 --- a/modules/gapi/include/opencv2/gapi/plaidml/plaidml.hpp +++ b/modules/gapi/include/opencv2/gapi/plaidml/plaidml.hpp @@ -15,6 +15,11 @@ namespace cv { namespace gapi { + +/** + * @brief This namespace contains G-API PlaidML backend functions, + * structures, and symbols. + */ namespace plaidml { diff --git a/modules/gapi/include/opencv2/gapi/python/python.hpp b/modules/gapi/include/opencv2/gapi/python/python.hpp index 1c85d69d9f..0e20bbbb59 100644 --- a/modules/gapi/include/opencv2/gapi/python/python.hpp +++ b/modules/gapi/include/opencv2/gapi/python/python.hpp @@ -13,6 +13,15 @@ namespace cv { namespace gapi { + +/** + * @brief This namespace contains G-API Python backend functions, + * structures, and symbols. + * + * This functionality is required to enable G-API custom operations + * and kernels when using G-API from Python, no need to use it in the + * C++ form. + */ namespace python { GAPI_EXPORTS cv::gapi::GBackend backend(); diff --git a/modules/gapi/include/opencv2/gapi/render/render.hpp b/modules/gapi/include/opencv2/gapi/render/render.hpp index a84c26c810..6bfe92388a 100644 --- a/modules/gapi/include/opencv2/gapi/render/render.hpp +++ b/modules/gapi/include/opencv2/gapi/render/render.hpp @@ -169,6 +169,10 @@ GAPI_EXPORTS GFrame renderFrame(const GFrame& m_frame, } // namespace draw } // namespace wip +/** + * @brief This namespace contains G-API CPU rendering backend functions, + * structures, and symbols. See @ref gapi_draw for details. + */ namespace render { namespace ocv diff --git a/modules/gapi/include/opencv2/gapi/rmat.hpp b/modules/gapi/include/opencv2/gapi/rmat.hpp index f50bd08b65..cc27f48664 100644 --- a/modules/gapi/include/opencv2/gapi/rmat.hpp +++ b/modules/gapi/include/opencv2/gapi/rmat.hpp @@ -42,6 +42,9 @@ namespace cv { // performCalculations(in_view, out_view); // // data from out_view is transferred to the device when out_view is destroyed // } +/** \addtogroup gapi_data_structures + * @{ + */ class GAPI_EXPORTS RMat { public: @@ -146,6 +149,7 @@ private: template RMat make_rmat(Ts&&... args) { return { std::make_shared(std::forward(args)...) }; } +/** @} */ } //namespace cv diff --git a/modules/gapi/include/opencv2/gapi/s11n/base.hpp b/modules/gapi/include/opencv2/gapi/s11n/base.hpp index d9335ee9f7..b8ec8cfaff 100644 --- a/modules/gapi/include/opencv2/gapi/s11n/base.hpp +++ b/modules/gapi/include/opencv2/gapi/s11n/base.hpp @@ -12,6 +12,11 @@ namespace cv { namespace gapi { + +/** + * @brief This namespace contains G-API serialization and + * deserialization functions and data structures. + */ namespace s11n { struct IOStream; struct IIStream; diff --git a/modules/gapi/include/opencv2/gapi/stereo.hpp b/modules/gapi/include/opencv2/gapi/stereo.hpp index 908045d4c7..b573dbf0db 100644 --- a/modules/gapi/include/opencv2/gapi/stereo.hpp +++ b/modules/gapi/include/opencv2/gapi/stereo.hpp @@ -21,6 +21,11 @@ enum class StereoOutputFormat { DISPARITY_FIXED16_12_4 }; + +/** + * @brief This namespace contains G-API Operation Types for Stereo and + * related functionality. + */ namespace calib3d { G_TYPED_KERNEL(GStereo, , "org.opencv.stereo") { diff --git a/modules/gapi/include/opencv2/gapi/video.hpp b/modules/gapi/include/opencv2/gapi/video.hpp index 10965b0aa6..4dcc1d4182 100644 --- a/modules/gapi/include/opencv2/gapi/video.hpp +++ b/modules/gapi/include/opencv2/gapi/video.hpp @@ -42,6 +42,10 @@ struct GAPI_EXPORTS KalmanParams Mat controlMatrix; }; +/** + * @brief This namespace contains G-API Operations and functions for + * video-oriented algorithms, like optical flow and background subtraction. + */ namespace video { using GBuildPyrOutput = std::tuple, GScalar>; diff --git a/modules/gapi/samples/api_ref_snippets.cpp b/modules/gapi/samples/api_ref_snippets.cpp index 9c3e73a17c..6c660fb8fa 100644 --- a/modules/gapi/samples/api_ref_snippets.cpp +++ b/modules/gapi/samples/api_ref_snippets.cpp @@ -9,6 +9,14 @@ #include #include +static void gscalar_example() +{ + //! [gscalar_implicit] + cv::GMat a; + cv::GMat b = a + 1; + //! [gscalar_implicit] +} + static void typed_example() { const cv::Size sz(32, 32); @@ -116,7 +124,9 @@ int main(int argc, char *argv[]) >(); //! [kernels_snippet] - // Just call typed example with no input/output + // Just call typed example with no input/output - avoid warnings about + // unused functions typed_example(); + gscalar_example(); return 0; } diff --git a/modules/gapi/samples/gaze_estimation.cpp b/modules/gapi/samples/gaze_estimation.cpp index 6396d500c1..96b2ebf163 100644 --- a/modules/gapi/samples/gaze_estimation.cpp +++ b/modules/gapi/samples/gaze_estimation.cpp @@ -16,13 +16,13 @@ const std::string keys = "{ h help | | Print this help message }" "{ input | | Path to the input video file }" "{ facem | face-detection-retail-0005.xml | Path to OpenVINO face detection model (.xml) }" - "{ faced | CPU | Target device for the face detection (e.g. CPU, GPU, VPU, ...) }" + "{ faced | CPU | Target device for the face detection (e.g. CPU, GPU, ...) }" "{ landm | facial-landmarks-35-adas-0002.xml | Path to OpenVINO landmarks detector model (.xml) }" - "{ landd | CPU | Target device for the landmarks detector (e.g. CPU, GPU, VPU, ...) }" + "{ landd | CPU | Target device for the landmarks detector (e.g. CPU, GPU, ...) }" "{ headm | head-pose-estimation-adas-0001.xml | Path to OpenVINO head pose estimation model (.xml) }" - "{ headd | CPU | Target device for the head pose estimation inference (e.g. CPU, GPU, VPU, ...) }" + "{ headd | CPU | Target device for the head pose estimation inference (e.g. CPU, GPU, ...) }" "{ gazem | gaze-estimation-adas-0002.xml | Path to OpenVINO gaze vector estimaiton model (.xml) }" - "{ gazed | CPU | Target device for the gaze vector estimation inference (e.g. CPU, GPU, VPU, ...) }" + "{ gazed | CPU | Target device for the gaze vector estimation inference (e.g. CPU, GPU, ...) }" ; namespace { @@ -338,7 +338,7 @@ int main(int argc, char *argv[]) cv::GMat in; cv::GMat faces = cv::gapi::infer(in); - cv::GOpaque sz = custom::Size::on(in); // FIXME + cv::GOpaque sz = cv::gapi::streaming::size(in); cv::GArray faces_rc = custom::ParseSSD::on(faces, sz, true); cv::GArray angles_y, angles_p, angles_r; std::tie(angles_y, angles_p, angles_r) = cv::gapi::infer(faces_rc, in);