gstreaming.hpp 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  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 Intel Corporation
  6. #ifndef OPENCV_GAPI_GSTREAMING_COMPILED_HPP
  7. #define OPENCV_GAPI_GSTREAMING_COMPILED_HPP
  8. #include <memory>
  9. #include <vector>
  10. #include <opencv2/gapi/opencv_includes.hpp>
  11. #include <opencv2/gapi/own/assert.hpp>
  12. #include <opencv2/gapi/util/optional.hpp>
  13. #include <opencv2/gapi/garg.hpp>
  14. #include <opencv2/gapi/streaming/source.hpp>
  15. namespace cv {
  16. template<class T> using optional = cv::util::optional<T>;
  17. namespace detail {
  18. template<typename T> struct wref_spec {
  19. using type = T;
  20. };
  21. template<typename T> struct wref_spec<std::vector<T> > {
  22. using type = T;
  23. };
  24. template<typename RefHolder>
  25. struct OptRef {
  26. struct OptHolder {
  27. virtual void mov(RefHolder &h) = 0;
  28. virtual void reset() = 0;
  29. virtual ~OptHolder() = default;
  30. using Ptr = std::shared_ptr<OptHolder>;
  31. };
  32. template<class T> struct Holder final: OptHolder {
  33. std::reference_wrapper<cv::optional<T> > m_opt_ref;
  34. explicit Holder(cv::optional<T>& opt) : m_opt_ref(std::ref(opt)) {
  35. }
  36. virtual void mov(RefHolder &h) override {
  37. using U = typename wref_spec<T>::type;
  38. m_opt_ref.get() = cv::util::make_optional(std::move(h.template wref<U>()));
  39. }
  40. virtual void reset() override {
  41. m_opt_ref.get().reset();
  42. }
  43. };
  44. template<class T>
  45. explicit OptRef(cv::optional<T>& t) : m_opt{new Holder<T>(t)} {}
  46. void mov(RefHolder &h) { m_opt->mov(h); }
  47. void reset() { m_opt->reset();}
  48. private:
  49. typename OptHolder::Ptr m_opt;
  50. };
  51. using OptionalVectorRef = OptRef<cv::detail::VectorRef>;
  52. using OptionalOpaqueRef = OptRef<cv::detail::OpaqueRef>;
  53. } // namespace detail
  54. // TODO: Keep it in sync with GRunArgP (derive the type automatically?)
  55. using GOptRunArgP = util::variant<
  56. optional<cv::Mat>*,
  57. optional<cv::RMat>*,
  58. optional<cv::Scalar>*,
  59. cv::detail::OptionalVectorRef,
  60. cv::detail::OptionalOpaqueRef
  61. >;
  62. using GOptRunArgsP = std::vector<GOptRunArgP>;
  63. namespace detail {
  64. template<typename T> inline GOptRunArgP wrap_opt_arg(optional<T>& arg) {
  65. // By default, T goes to an OpaqueRef. All other types are specialized
  66. return GOptRunArgP{OptionalOpaqueRef(arg)};
  67. }
  68. template<typename T> inline GOptRunArgP wrap_opt_arg(optional<std::vector<T> >& arg) {
  69. return GOptRunArgP{OptionalVectorRef(arg)};
  70. }
  71. template<> inline GOptRunArgP wrap_opt_arg(optional<cv::Mat> &m) {
  72. return GOptRunArgP{&m};
  73. }
  74. template<> inline GOptRunArgP wrap_opt_arg(optional<cv::Scalar> &s) {
  75. return GOptRunArgP{&s};
  76. }
  77. } // namespace detail
  78. // Now cv::gout() may produce an empty vector (see "dynamic graphs"), so
  79. // there may be a conflict between these two. State here that Opt version
  80. // _must_ have at least one input for this overload
  81. template<typename T, typename... Ts>
  82. inline GOptRunArgsP gout(optional<T>&arg, optional<Ts>&... args)
  83. {
  84. return GOptRunArgsP{ detail::wrap_opt_arg(arg), detail::wrap_opt_arg(args)... };
  85. }
  86. /**
  87. * \addtogroup gapi_main_classes
  88. * @{
  89. */
  90. /**
  91. * @brief Represents a computation (graph) compiled for streaming.
  92. *
  93. * This class represents a product of graph compilation (calling
  94. * cv::GComputation::compileStreaming()). Objects of this class
  95. * actually do stream processing, and the whole pipeline execution
  96. * complexity is incapsulated into objects of this class. Execution
  97. * model has two levels: at the very top, the execution of a
  98. * heterogeneous graph is aggressively pipelined; at the very bottom
  99. * the execution of every internal block is determined by its
  100. * associated backend. Backends are selected based on kernel packages
  101. * passed via compilation arguments ( see @ref gapi_compile_args,
  102. * GNetworkPackage, GKernelPackage for details).
  103. *
  104. * GStreamingCompiled objects have a "player" semantics -- there are
  105. * methods like start() and stop(). GStreamingCompiled has a full
  106. * control over a videostream and so is stateful. You need to specify the
  107. * input stream data using setSource() and then call start() to
  108. * actually start processing. After that, use pull() or try_pull() to
  109. * obtain next processed data frame from the graph in a blocking or
  110. * non-blocking way, respectively.
  111. *
  112. * Currently a single GStreamingCompiled can process only one video
  113. * streat at time. Produce multiple GStreamingCompiled objects to run the
  114. * same graph on multiple video streams.
  115. *
  116. * @sa GCompiled
  117. */
  118. class GAPI_EXPORTS_W_SIMPLE GStreamingCompiled
  119. {
  120. public:
  121. class GAPI_EXPORTS Priv;
  122. GAPI_WRAP GStreamingCompiled();
  123. // FIXME: More overloads?
  124. /**
  125. * @brief Specify the input data to GStreamingCompiled for
  126. * processing, a generic version.
  127. *
  128. * Use gin() to create an input parameter vector.
  129. *
  130. * Input vectors must have the same number of elements as defined
  131. * in the cv::GComputation protocol (at the moment of its
  132. * construction). Shapes of elements also must conform to protocol
  133. * (e.g. cv::Mat needs to be passed where cv::GMat has been
  134. * declared as input, and so on). Run-time exception is generated
  135. * on type mismatch.
  136. *
  137. * In contrast with regular GCompiled, user can also pass an
  138. * object of type GVideoCapture for a GMat parameter of the parent
  139. * GComputation. The compiled pipeline will start fetching data
  140. * from that GVideoCapture and feeding it into the
  141. * pipeline. Pipeline stops when a GVideoCapture marks end of the
  142. * stream (or when stop() is called).
  143. *
  144. * Passing a regular Mat for a GMat parameter makes it "infinite"
  145. * source -- pipeline may run forever feeding with this Mat until
  146. * stopped explicitly.
  147. *
  148. * Currently only a single GVideoCapture is supported as input. If
  149. * the parent GComputation is declared with multiple input GMat's,
  150. * one of those can be specified as GVideoCapture but all others
  151. * must be regular Mat objects.
  152. *
  153. * Throws if pipeline is already running. Use stop() and then
  154. * setSource() to run the graph on a new video stream.
  155. *
  156. * @note This method is not thread-safe (with respect to the user
  157. * side) at the moment. Protect the access if
  158. * start()/stop()/setSource() may be called on the same object in
  159. * multiple threads in your application.
  160. *
  161. * @param ins vector of inputs to process.
  162. * @sa gin
  163. */
  164. GAPI_WRAP void setSource(GRunArgs &&ins);
  165. /**
  166. * @brief Specify an input video stream for a single-input
  167. * computation pipeline.
  168. *
  169. * Throws if pipeline is already running. Use stop() and then
  170. * setSource() to run the graph on a new video stream.
  171. *
  172. * @overload
  173. * @param s a shared pointer to IStreamSource representing the
  174. * input video stream.
  175. */
  176. GAPI_WRAP void setSource(const gapi::wip::IStreamSource::Ptr& s);
  177. /**
  178. * @brief Constructs and specifies an input video stream for a
  179. * single-input computation pipeline with the given parameters.
  180. *
  181. * Throws if pipeline is already running. Use stop() and then
  182. * setSource() to run the graph on a new video stream.
  183. *
  184. * @overload
  185. * @param args arguments used to contruct and initialize a stream
  186. * source.
  187. */
  188. template<typename T, typename... Args>
  189. void setSource(Args&&... args) {
  190. setSource(cv::gapi::wip::make_src<T>(std::forward<Args>(args)...));
  191. }
  192. /**
  193. * @brief Start the pipeline execution.
  194. *
  195. * Use pull()/try_pull() to obtain data. Throws an exception if
  196. * a video source was not specified.
  197. *
  198. * setSource() must be called first, even if the pipeline has been
  199. * working already and then stopped (explicitly via stop() or due
  200. * stream completion)
  201. *
  202. * @note This method is not thread-safe (with respect to the user
  203. * side) at the moment. Protect the access if
  204. * start()/stop()/setSource() may be called on the same object in
  205. * multiple threads in your application.
  206. */
  207. GAPI_WRAP void start();
  208. /**
  209. * @brief Get the next processed frame from the pipeline.
  210. *
  211. * Use gout() to create an output parameter vector.
  212. *
  213. * Output vectors must have the same number of elements as defined
  214. * in the cv::GComputation protocol (at the moment of its
  215. * construction). Shapes of elements also must conform to protocol
  216. * (e.g. cv::Mat needs to be passed where cv::GMat has been
  217. * declared as output, and so on). Run-time exception is generated
  218. * on type mismatch.
  219. *
  220. * This method writes new data into objects passed via output
  221. * vector. If there is no data ready yet, this method blocks. Use
  222. * try_pull() if you need a non-blocking version.
  223. *
  224. * @param outs vector of output parameters to obtain.
  225. * @return true if next result has been obtained,
  226. * false marks end of the stream.
  227. */
  228. bool pull(cv::GRunArgsP &&outs);
  229. // NB: Used from python
  230. GAPI_WRAP std::tuple<bool, cv::GRunArgs> pull();
  231. /**
  232. * @brief Get some next available data from the pipeline.
  233. *
  234. * This method takes a vector of cv::optional object. An object is
  235. * assigned to some value if this value is available (ready) at
  236. * the time of the call, and resets the object to empty() if it is
  237. * not.
  238. *
  239. * This is a blocking method which guarantees that some data has
  240. * been written to the output vector on return.
  241. *
  242. * Using this method only makes sense if the graph has
  243. * desynchronized parts (see cv::gapi::desync). If there is no
  244. * desynchronized parts in the graph, the behavior of this
  245. * method is identical to the regular pull() (all data objects are
  246. * produced synchronously in the output vector).
  247. *
  248. * Use gout() to create an output parameter vector.
  249. *
  250. * Output vectors must have the same number of elements as defined
  251. * in the cv::GComputation protocol (at the moment of its
  252. * construction). Shapes of elements also must conform to protocol
  253. * (e.g. cv::optional<cv::Mat> needs to be passed where cv::GMat
  254. * has been declared as output, and so on). Run-time exception is
  255. * generated on type mismatch.
  256. *
  257. * This method writes new data into objects passed via output
  258. * vector. If there is no data ready yet, this method blocks. Use
  259. * try_pull() if you need a non-blocking version.
  260. *
  261. * @param outs vector of output parameters to obtain.
  262. * @return true if next result has been obtained,
  263. * false marks end of the stream.
  264. *
  265. * @sa cv::gapi::desync
  266. */
  267. bool pull(cv::GOptRunArgsP &&outs);
  268. /**
  269. * @brief Try to get the next processed frame from the pipeline.
  270. *
  271. * Use gout() to create an output parameter vector.
  272. *
  273. * This method writes new data into objects passed via output
  274. * vector. If there is no data ready yet, the output vector
  275. * remains unchanged and false is returned.
  276. *
  277. * @return true if data has been obtained, and false if it was
  278. * not. Note: false here doesn't mark the end of the stream.
  279. */
  280. bool try_pull(cv::GRunArgsP &&outs);
  281. /**
  282. * @brief Stop (abort) processing the pipeline.
  283. *
  284. * Note - it is not pause but a complete stop. Calling start()
  285. * will cause G-API to start processing the stream from the early beginning.
  286. *
  287. * Throws if the pipeline is not running.
  288. */
  289. GAPI_WRAP void stop();
  290. /**
  291. * @brief Test if the pipeline is running.
  292. *
  293. * @note This method is not thread-safe (with respect to the user
  294. * side) at the moment. Protect the access if
  295. * start()/stop()/setSource() may be called on the same object in
  296. * multiple threads in your application.
  297. *
  298. * @return true if the current stream is not over yet.
  299. */
  300. GAPI_WRAP bool running() const;
  301. /// @private
  302. Priv& priv();
  303. /**
  304. * @brief Check if compiled object is valid (non-empty)
  305. *
  306. * @return true if the object is runnable (valid), false otherwise
  307. */
  308. explicit operator bool () const;
  309. /**
  310. * @brief Vector of metadata this graph was compiled for.
  311. *
  312. * @return Unless _reshape_ is not supported, return value is the
  313. * same vector which was passed to cv::GComputation::compile() to
  314. * produce this compiled object. Otherwise, it is the latest
  315. * metadata vector passed to reshape() (if that call was
  316. * successful).
  317. */
  318. const GMetaArgs& metas() const; // Meta passed to compile()
  319. /**
  320. * @brief Vector of metadata descriptions of graph outputs
  321. *
  322. * @return vector with formats/resolutions of graph's output
  323. * objects, auto-inferred from input metadata vector by
  324. * operations which form this computation.
  325. *
  326. * @note GCompiled objects produced from the same
  327. * cv::GComputiation graph with different input metas may return
  328. * different values in this vector.
  329. */
  330. const GMetaArgs& outMetas() const;
  331. protected:
  332. /// @private
  333. std::shared_ptr<Priv> m_priv;
  334. };
  335. /** @} */
  336. }
  337. #endif // OPENCV_GAPI_GSTREAMING_COMPILED_HPP