Merge pull request #20238 from dmatveev:dm/gframe_docs

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

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<GMat,GMat>;
     using GMat3 = std::tuple<GMat,GMat,GMat>; // FIXME: how to avoid this?

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 @@ class GCPUStKernelImpl: public cv::detail::KernelTag
 #define GAPI_OCV_KERNEL_ST(Name, API, State)                   \
     struct Name: public cv::GCPUStKernelImpl<Name, API, State> \
 
-
+/// @private
 class gapi::cpu::GOCVFunctor : public gapi::GFunctor
 {
 public:

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
 {
     /**

modules/gapi/include/opencv2/gapi/garray.hpp

@@ -340,21 +340,79 @@ namespace detail
 /** \addtogroup gapi_data_objects
  * @{
  */
-
+/**
+ * @brief `cv::GArray<T>` template class represents a list of objects
+ * of class `T` in the graph.
+ *
+ * `cv::GArray<T>` describes a functional relationship between
+ * operations consuming and producing arrays of objects of class
+ * `T`. The primary purpose of `cv::GArray<T>` 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<cv::Point>`), object detection
+ * and tracking  results (`cv::GArray<cv::Rect>`). Programmers can use
+ * their own types with `cv::GArray<T>` in the custom operations.
+ *
+ * Similar to `cv::GScalar`, `cv::GArray<T>` may be value-initialized
+ * -- in this case a graph-constant value is associated with the object.
+ *
+ * `GArray<T>` is a virtual counterpart of `std::vector<T>`, which is
+ * usually used to represent the `GArray<T>` data in G-API during the
+ * execution.
+ *
+ * @sa `cv::GOpaque<T>`
+ */
 template<typename T> class GArray
 {
 public:
     // Host type (or Flat type) - the type this GArray is actually
     // specified to.
+    /// @private
     using HT = typename detail::flatten_g<typename std::decay<T>::type>::type;
 
+    /**
+     * @brief Constructs a value-initialized `cv::GArray<T>`
+     *
+     * `cv::GArray<T>` objects  may have their values
+     * be associated at graph construction time. It is useful when
+     * some operation has a `cv::GArray<T>` 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<T>` as a graph input.
+     *
+     * @note The value of `cv::GArray<T>` may be overwritten by assigning some
+     * other `cv::GArray<T>` to the object using `operator=` -- on the
+     * assigment, the old association or value is discarded.
+     *
+     * @param v a std::vector<T> to associate with this
+     * `cv::GArray<T>` object. Vector data is copied into the
+     * `cv::GArray<T>` (no reference to the passed data is held).
+     */
     explicit GArray(const std::vector<HT>& v) // Constant value constructor
         : m_ref(detail::GArrayU(detail::VectorRef(v))) { putDetails(); }
+
+    /**
+     * @overload
+     * @brief Constructs a value-initialized `cv::GArray<T>`
+     *
+     * @param v a std::vector<T> to associate with this
+     * `cv::GArray<T>` object. Vector data is moved into the `cv::GArray<T>`.
+     */
     explicit GArray(std::vector<HT>&& 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<T>`
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty `cv::GArray<T>` 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 {

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 {
 
 /**

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<GOrigin> m_priv;

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:

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<T>`) 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<T>`    | std::vector<T>
  *    `cv::GOpaque<T>`   | 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:

modules/gapi/include/opencv2/gapi/gopaque.hpp

@@ -307,15 +307,40 @@ namespace detail
 /** \addtogroup gapi_data_objects
  * @{
  */
-
+/**
+ * @brief `cv::GOpaque<T>` template class represents an object of
+ * class `T` in the graph.
+ *
+ * `cv::GOpaque<T>` describes a functional relationship between operations
+ * consuming and producing object of class `T`. `cv::GOpaque<T>` 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<T>` as a return type,
+ * e.g. cv::gapi::streaming::timestamp() or cv::gapi::streaming::size().
+ *
+ * @sa `cv::GArray<T>`
+ */
 template<typename T> class GOpaque
 {
 public:
     // Host type (or Flat type) - the type this GOpaque is actually
     // specified to.
+    /// @private
     using HT = typename detail::flatten_g<util::decay_t<T>>::type;
 
+    /**
+     * @brief Constructs an empty `cv::GOpaque<T>`
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty `cv::GOpaque<T>` 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)