inference-engine/thirdparty/fluid/modules/gapi/include/opencv2/gapi/gcompiled.hpp

   1 // This file is part of OpenCV project.
   2 // It is subject to the license terms in the LICENSE file found in the top-level directory
   3 // of this distribution and at http://opencv.org/license.html.
   4 //
   5 // Copyright (C) 2018-2019 Intel Corporation
   6
   7
   8 #ifndef OPENCV_GAPI_GCOMPILED_HPP
   9 #define OPENCV_GAPI_GCOMPILED_HPP
  10
  11 #include <vector>
  12
  13 #include "opencv2/gapi/opencv_includes.hpp"
  14 #include "opencv2/gapi/own/assert.hpp"
  15 #include "opencv2/gapi/garg.hpp"
  16
  17 namespace cv {
  18
  19 // This class represents a compiled computation.
  20 // In theory (and ideally), it can be used w/o the rest of APIs.
  21 // In theory (and ideally), it can be serialized/deserialized.
  22 // It can enable scenarious like deployment to an autonomous devince, FuSa, etc.
  23 //
  24 // Currently GCompiled assumes all GMats you used to pass data to G-API
  25 // are valid and not destroyed while you use a GCompiled object.
  26 //
  27 // FIXME: In future, there should be a way to name I/O objects and specify it
  28 // to GCompiled externally (for example, when it is loaded on the target system).
  29
  30 /**
  31  * \addtogroup gapi_main_classes
  32  * @{
  33  */
  34 /**
  35  * @brief Represents a compiled computation (graph). Can only be used
  36  * with image / data formats & resolutions it was compiled for, with
  37  * some exceptions.
  38  *
  39  * This class represents a product of graph compilation (calling
  40  * cv::GComputation::compile()). Objects of this class actually do
  41  * data processing, and graph execution is incapsulated into objects
  42  * of this class. Execution model itself depends on kernels and
  43  * backends which were using during the compilation, see @ref
  44  * gapi_compile_args for details.
  45  *
  46  * In a general case, GCompiled objects can be applied to data only in
  47  * that formats/resolutions they were compiled for (see @ref
  48  * gapi_meta_args). However, if the underlying backends allow, a
  49  * compiled object can be _reshaped_ to handle data (images) of
  50  * different resolution, though formats and types must remain the same.
  51  *
  52  * GCompiled is very similar to `std::function<>` in its semantics --
  53  * running it looks like a function call in the user code.
  54  *
  55  * At the moment, GCompiled objects are not reentrant -- generally,
  56  * the objects are stateful since graph execution itself is a stateful
  57  * process and this state is now maintained in GCompiled's own memory
  58  * (not on the process stack).
  59  *
  60  * At the same time, two different GCompiled objects produced from the
  61  * single cv::GComputation are completely independent and can be used
  62  * concurrently.
  63  */
  64 class GAPI_EXPORTS GCompiled
  65 {
  66 public:
  67     /// @private
  68     class GAPI_EXPORTS Priv;
  69
  70     /**
  71      * @brief Constructs an empty object
  72      */
  73     GCompiled();
  74
  75     /**
  76      * @brief Run the compiled computation, a generic version.
  77      *
  78      * @param ins vector of inputs to process.
  79      * @param outs vector of outputs to produce.
  80      *
  81      * Input/output vectors must have the same number of elements as
  82      * defined in the cv::GComputation protocol (at the moment of its
  83      * construction). Shapes of elements also must conform to protocol
  84      * (e.g. cv::Mat needs to be passed where cv::GMat has been
  85      * declared as input, and so on). Run-time exception is generated
  86      * otherwise.
  87      *
  88      * Objects in output vector may remain empty (like cv::Mat) --
  89      * G-API will automatically initialize output objects to proper formats.
  90      *
  91      * @note Don't construct GRunArgs/GRunArgsP objects manually, use
  92      * cv::gin()/cv::gout() wrappers instead.
  93      */
  94     void operator() (GRunArgs &&ins, GRunArgsP &&outs);          // Generic arg-to-arg
  95 #if !defined(GAPI_STANDALONE)
  96
  97     /**
  98      * @brief Execute an unary computation
  99      *
 100      * @overload
 101      * @param in input cv::Mat for unary computation
 102      * @param out output cv::Mat for unary computation
 103      * process.
 104      */
 105     void operator() (cv::Mat in, cv::Mat &out);                  // Unary overload
 106
 107     /**
 108      * @brief Execute an unary computation
 109      *
 110      * @overload
 111      * @param in input cv::Mat for unary computation
 112      * @param out output cv::Scalar for unary computation
 113      * process.
 114      */
 115     void operator() (cv::Mat in, cv::Scalar &out);               // Unary overload (scalar)
 116
 117     /**
 118      * @brief Execute a binary computation
 119      *
 120      * @overload
 121      * @param in1 first input cv::Mat for binary computation
 122      * @param in2 second input cv::Mat for binary computation
 123      * @param out output cv::Mat for binary computation
 124      * process.
 125      */
 126     void operator() (cv::Mat in1, cv::Mat in2, cv::Mat &out);    // Binary overload
 127
 128     /**
 129      * @brief Execute an binary computation
 130      *
 131      * @overload
 132      * @param in1 first input cv::Mat for binary computation
 133      * @param in2 second input cv::Mat for binary computation
 134      * @param out output cv::Scalar for binary computation
 135      * process.
 136      */
 137     void operator() (cv::Mat in1, cv::Mat in2, cv::Scalar &out); // Binary overload (scalar)
 138
 139     /**
 140      * @brief Execute a computation with arbitrary number of
 141      * inputs/outputs.
 142      *
 143      * @overload
 144      * @param ins vector of input cv::Mat objects to process by the
 145      * computation.
 146      * @param outs vector of output cv::Mat objects to produce by the
 147      * computation.
 148      *
 149      * Numbers of elements in ins/outs vectos must match numbers of
 150      * inputs/outputs which were used to define the source GComputation.
 151      */
 152     void operator() (const std::vector<cv::Mat> &ins,            // Compatibility overload
 153                      const std::vector<cv::Mat> &outs);
 154 #endif  // !defined(GAPI_STANDALONE)
 155     /// @private
 156     Priv& priv();
 157
 158     /**
 159      * @brief Check if compiled object is valid (non-empty)
 160      *
 161      * @return true if the object is runnable (valid), false otherwise
 162      */
 163     explicit operator bool () const;
 164
 165     /**
 166      * @brief Vector of metadata this graph was compiled for.
 167      *
 168      * @return Unless _reshape_ is not supported, return value is the
 169      * same vector which was passed to cv::GComputation::compile() to
 170      * produce this compiled object. Otherwise, it is the latest
 171      * metadata vector passed to reshape() (if that call was
 172      * successful).
 173      */
 174     const GMetaArgs& metas() const; // Meta passed to compile()
 175
 176     /**
 177      * @brief Vector of metadata descriptions of graph outputs
 178      *
 179      * @return vector with formats/resolutions of graph's output
 180      * objects, auto-inferred from input metadata vector by
 181      * operations which form this computation.
 182      *
 183      * @note GCompiled objects produced from the same
 184      * cv::GComputiation graph with different input metas may return
 185      * different values in this vector.
 186      */
 187     const GMetaArgs& outMetas() const;
 188
 189     /**
 190      * @brief Check if the underlying backends support reshape or not.
 191      *
 192      * @return true if supported, false otherwise.
 193      */
 194     bool canReshape() const;
 195
 196     /**
 197      * @brief Reshape a compiled graph to support new image
 198      * resolutions.
 199      *
 200      * Throws an exception if an error occurs.
 201      *
 202      * @param inMetas new metadata to reshape on. Vector size and
 203      * metadata shapes must match the computation's protocol.
 204      * @param args compilation arguments to use.
 205      */
 206     // FIXME: Why it requires compile args?
 207     void reshape(const GMetaArgs& inMetas, const GCompileArgs& args);
 208
 209 protected:
 210     /// @private
 211     std::shared_ptr<Priv> m_priv;
 212 };
 213 /** @} */
 214
 215 }
 216
 217 #endif // OPENCV_GAPI_GCOMPILED_HPP