@@ -27,35 +27,190 @@ namespace cv {
2727// FIXME: In future, there should be a way to name I/O objects and specify it
2828// to GCompiled externally (for example, when it is loaded on the target system).
2929
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+ */
3064class GAPI_EXPORTS GCompiled
3165{
3266public:
67+ // / @private
3368 class GAPI_EXPORTS Priv;
3469
70+ /* *
71+ * @brief Constructs an empty object
72+ */
3573 GCompiled ();
3674
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+ */
3794 void operator () (GRunArgs &&ins, GRunArgsP &&outs); // Generic arg-to-arg
3895#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+ */
39105 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+ */
40115 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+ */
41126 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+ */
42137 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+ */
43152 void operator () (const std::vector<cv::Mat> &ins, // Compatibility overload
44153 const std::vector<cv::Mat> &outs);
45154#endif // !defined(GAPI_STANDALONE)
155+ // / @private
46156 Priv& priv ();
47157
48- explicit operator bool () const ; // Check if GCompiled is runnable or empty
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 ;
49164
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+ */
50174 const GMetaArgs& metas () const ; // Meta passed to compile()
51- const GMetaArgs& outMetas () const ; // Inferred output metadata
52175
53- bool canReshape () const ; // is reshape mechanism supported by GCompiled
54- void reshape (const GMetaArgs& inMetas, const GCompileArgs& args); // run reshape procedure
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);
55208
56209protected:
210+ // / @private
57211 std::shared_ptr<Priv> m_priv;
58212};
213+ /* * @} */
59214
60215}
61216
0 commit comments