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.
5 // Copyright (C) 2018 Intel Corporation
8 #ifndef OPENCV_GAPI_GCOMPILED_HPP
9 #define OPENCV_GAPI_GCOMPILED_HPP
13 #include "opencv2/gapi/opencv_includes.hpp"
14 #include "opencv2/gapi/own/assert.hpp"
15 #include "opencv2/gapi/garg.hpp"
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.
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.
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).
31 * \addtogroup gapi_main_classes
35 * @brief Represents a compiled computation (graph). Can only be used
36 * with image / data formats & resolutions it was compiled for, with
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.
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.
52 * GCompiled is very similar to `std::function<>` in its semantics --
53 * running it looks like a function call in the user code.
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).
60 * At the same time, two different GCompiled objects produced from the
61 * single cv::GComputation are completely independent and can be used
64 class GAPI_EXPORTS GCompiled
68 class GAPI_EXPORTS Priv;
71 * @brief Constructs an empty object
76 * @brief Run the compiled computation, a generic version.
78 * @param ins vector of inputs to process.
79 * @param outs vector of outputs to produce.
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
88 * Objects in output vector may remain empty (like cv::Mat) --
89 * G-API will automatically initialize output objects to proper formats.
91 * @note Don't construct GRunArgs/GRunArgsP objects manually, use
92 * cv::gin()/cv::gout() wrappers instead.
94 void operator() (GRunArgs &&ins, GRunArgsP &&outs); // Generic arg-to-arg
95 #if !defined(GAPI_STANDALONE)
98 * @brief Execute an unary computation
101 * @param in input cv::Mat for unary computation
102 * @param out output cv::Mat for unary computation
105 void operator() (cv::Mat in, cv::Mat &out); // Unary overload
108 * @brief Execute an unary computation
111 * @param in input cv::Mat for unary computation
112 * @param out output cv::Scalar for unary computation
115 void operator() (cv::Mat in, cv::Scalar &out); // Unary overload (scalar)
118 * @brief Execute a binary computation
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
126 void operator() (cv::Mat in1, cv::Mat in2, cv::Mat &out); // Binary overload
129 * @brief Execute an binary computation
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
137 void operator() (cv::Mat in1, cv::Mat in2, cv::Scalar &out); // Binary overload (scalar)
140 * @brief Execute a computation with arbitrary number of
144 * @param ins vector of input cv::Mat objects to process by the
146 * @param outs vector of output cv::Mat objects to produce by the
149 * Numbers of elements in ins/outs vectos must match numbers of
150 * inputs/outputs which were used to define the source GComputation.
152 void operator() (const std::vector<cv::Mat> &ins, // Compatibility overload
153 const std::vector<cv::Mat> &outs);
154 #endif // !defined(GAPI_STANDALONE)
159 * @brief Check if compiled object is valid (non-empty)
161 * @return true if the object is runnable (valid), false otherwise
163 explicit operator bool () const;
166 * @brief Vector of metadata this graph was compiled for.
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
174 const GMetaArgs& metas() const; // Meta passed to compile()
177 * @brief Vector of metadata descriptions of graph outputs
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.
183 * @note GCompiled objects produced from the same
184 * cv::GComputiation graph with different input metas may return
185 * different values in this vector.
187 const GMetaArgs& outMetas() const;
190 * @brief Check if the underlying backends support reshape or not.
192 * @return true if supported, false otherwise.
194 bool canReshape() const;
197 * @brief Reshape a compiled graph to support new image
200 * Throws an exception if an error occurs.
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.
206 // FIXME: Why it requires compile args?
207 void reshape(const GMetaArgs& inMetas, const GCompileArgs& args);
211 std::shared_ptr<Priv> m_priv;
217 #endif // OPENCV_GAPI_GCOMPILED_HPP