gkernel.hpp 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727
  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-2020 Intel Corporation
  6. #ifndef OPENCV_GAPI_GKERNEL_HPP
  7. #define OPENCV_GAPI_GKERNEL_HPP
  8. #include <functional>
  9. #include <iostream>
  10. #include <string> // string
  11. #include <type_traits> // false_type, true_type
  12. #include <unordered_map> // map (for GKernelPackage)
  13. #include <utility> // tuple
  14. #include <opencv2/gapi/gcommon.hpp> // CompileArgTag
  15. #include <opencv2/gapi/util/util.hpp> // Seq
  16. #include <opencv2/gapi/gcall.hpp>
  17. #include <opencv2/gapi/garg.hpp> // GArg
  18. #include <opencv2/gapi/gmetaarg.hpp> // GMetaArg
  19. #include <opencv2/gapi/gtype_traits.hpp> // GTypeTraits
  20. #include <opencv2/gapi/util/compiler_hints.hpp> //suppress_unused_warning
  21. #include <opencv2/gapi/gtransform.hpp>
  22. namespace cv {
  23. struct GTypeInfo
  24. {
  25. GShape shape;
  26. cv::detail::OpaqueKind kind;
  27. };
  28. using GShapes = std::vector<GShape>;
  29. using GKinds = std::vector<cv::detail::OpaqueKind>;
  30. using GCtors = std::vector<detail::HostCtor>;
  31. using GTypesInfo = std::vector<GTypeInfo>;
  32. // GKernel describes kernel API to the system
  33. // FIXME: add attributes of a kernel, (e.g. number and types
  34. // of inputs, etc)
  35. struct GAPI_EXPORTS GKernel
  36. {
  37. using M = std::function<GMetaArgs(const GMetaArgs &, const GArgs &)>;
  38. std::string name; // kernel ID, defined by its API (signature)
  39. std::string tag; // some (implementation-specific) tag
  40. M outMeta; // generic adaptor to API::outMeta(...)
  41. GShapes outShapes; // types (shapes) kernel's outputs
  42. GKinds inKinds; // kinds of kernel's inputs (fixme: below)
  43. GCtors outCtors; // captured constructors for template output types
  44. };
  45. // TODO: It's questionable if inKinds should really be here. Instead,
  46. // this information could come from meta.
  47. // GKernelImpl describes particular kernel implementation to the system
  48. struct GAPI_EXPORTS GKernelImpl
  49. {
  50. util::any opaque; // backend-specific opaque info
  51. GKernel::M outMeta; // for deserialized graphs, the outMeta is taken here
  52. };
  53. template<typename, typename> class GKernelTypeM;
  54. namespace detail
  55. {
  56. ////////////////////////////////////////////////////////////////////////////
  57. // yield() is used in graph construction time as a generic method to obtain
  58. // lazy "return value" of G-API operations
  59. //
  60. template<typename T> struct Yield;
  61. template<> struct Yield<cv::GMat>
  62. {
  63. static inline cv::GMat yield(cv::GCall &call, int i) { return call.yield(i); }
  64. };
  65. template<> struct Yield<cv::GMatP>
  66. {
  67. static inline cv::GMatP yield(cv::GCall &call, int i) { return call.yieldP(i); }
  68. };
  69. template<> struct Yield<cv::GScalar>
  70. {
  71. static inline cv::GScalar yield(cv::GCall &call, int i) { return call.yieldScalar(i); }
  72. };
  73. template<typename U> struct Yield<cv::GArray<U> >
  74. {
  75. static inline cv::GArray<U> yield(cv::GCall &call, int i) { return call.yieldArray<U>(i); }
  76. };
  77. template<typename U> struct Yield<cv::GOpaque<U> >
  78. {
  79. static inline cv::GOpaque<U> yield(cv::GCall &call, int i) { return call.yieldOpaque<U>(i); }
  80. };
  81. template<> struct Yield<GFrame>
  82. {
  83. static inline cv::GFrame yield(cv::GCall &call, int i) { return call.yieldFrame(i); }
  84. };
  85. ////////////////////////////////////////////////////////////////////////////
  86. // Helper classes which brings outputMeta() marshalling to kernel
  87. // implementations
  88. //
  89. // 1. MetaType establishes G#Type -> G#Meta mapping between G-API dynamic
  90. // types and its metadata descriptor types.
  91. // This mapping is used to transform types to call outMeta() callback.
  92. template<typename T> struct MetaType;
  93. template<> struct MetaType<cv::GMat> { using type = GMatDesc; };
  94. template<> struct MetaType<cv::GMatP> { using type = GMatDesc; };
  95. template<> struct MetaType<cv::GFrame> { using type = GFrameDesc; };
  96. template<> struct MetaType<cv::GScalar> { using type = GScalarDesc; };
  97. template<typename U> struct MetaType<cv::GArray<U> > { using type = GArrayDesc; };
  98. template<typename U> struct MetaType<cv::GOpaque<U> > { using type = GOpaqueDesc; };
  99. template<typename T> struct MetaType { using type = T; }; // opaque args passed as-is
  100. // FIXME: Move it to type traits?
  101. // 2. Hacky test based on MetaType to check if we operate on G-* type or not
  102. template<typename T> using is_nongapi_type = std::is_same<T, typename MetaType<T>::type>;
  103. // 3. Two ways to transform input arguments to its meta - for G-* and non-G* types:
  104. template<typename T>
  105. typename std::enable_if<!is_nongapi_type<T>::value, typename MetaType<T>::type>
  106. ::type get_in_meta(const GMetaArgs &in_meta, const GArgs &, int idx)
  107. {
  108. return util::get<typename MetaType<T>::type>(in_meta.at(idx));
  109. }
  110. template<typename T>
  111. typename std::enable_if<is_nongapi_type<T>::value, T>
  112. ::type get_in_meta(const GMetaArgs &, const GArgs &in_args, int idx)
  113. {
  114. return in_args.at(idx).template get<T>();
  115. }
  116. // 4. The MetaHelper itself: an entity which generates outMeta() call
  117. // based on kernel signature, with arguments properly substituted.
  118. // 4.1 - case for multiple return values
  119. // FIXME: probably can be simplified with std::apply or analogue.
  120. template<typename, typename, typename>
  121. struct MetaHelper;
  122. template<typename K, typename... Ins, typename... Outs>
  123. struct MetaHelper<K, std::tuple<Ins...>, std::tuple<Outs...> >
  124. {
  125. template<int... IIs, int... OIs>
  126. static GMetaArgs getOutMeta_impl(const GMetaArgs &in_meta,
  127. const GArgs &in_args,
  128. detail::Seq<IIs...>,
  129. detail::Seq<OIs...>)
  130. {
  131. // FIXME: decay?
  132. using R = std::tuple<typename MetaType<Outs>::type...>;
  133. const R r = K::outMeta( get_in_meta<Ins>(in_meta, in_args, IIs)... );
  134. return GMetaArgs{ GMetaArg(std::get<OIs>(r))... };
  135. }
  136. // FIXME: help users identify how outMeta must look like (via default impl w/static_assert?)
  137. static GMetaArgs getOutMeta(const GMetaArgs &in_meta,
  138. const GArgs &in_args)
  139. {
  140. return getOutMeta_impl(in_meta,
  141. in_args,
  142. typename detail::MkSeq<sizeof...(Ins)>::type(),
  143. typename detail::MkSeq<sizeof...(Outs)>::type());
  144. }
  145. };
  146. // 4.1 - case for a single return value
  147. // FIXME: How to avoid duplication here?
  148. template<typename K, typename... Ins, typename Out>
  149. struct MetaHelper<K, std::tuple<Ins...>, Out >
  150. {
  151. template<int... IIs>
  152. static GMetaArgs getOutMeta_impl(const GMetaArgs &in_meta,
  153. const GArgs &in_args,
  154. detail::Seq<IIs...>)
  155. {
  156. // FIXME: decay?
  157. using R = typename MetaType<Out>::type;
  158. const R r = K::outMeta( get_in_meta<Ins>(in_meta, in_args, IIs)... );
  159. return GMetaArgs{ GMetaArg(r) };
  160. }
  161. // FIXME: help users identify how outMeta must look like (via default impl w/static_assert?)
  162. static GMetaArgs getOutMeta(const GMetaArgs &in_meta,
  163. const GArgs &in_args)
  164. {
  165. return getOutMeta_impl(in_meta,
  166. in_args,
  167. typename detail::MkSeq<sizeof...(Ins)>::type());
  168. }
  169. };
  170. ////////////////////////////////////////////////////////////////////////////
  171. // Helper class to introduce tags to calls. By default there's no tag
  172. struct NoTag {
  173. static constexpr const char *tag() { return ""; }
  174. };
  175. } // namespace detail
  176. // GKernelType and GKernelTypeM are base classes which implement typed ::on()
  177. // method based on kernel signature. GKernelTypeM stands for multiple-return-value kernels
  178. //
  179. // G_TYPED_KERNEL and G_TYPED_KERNEL_M macros inherit user classes from GKernelType and
  180. // GKernelTypeM respectively.
  181. template<typename K, typename... R, typename... Args>
  182. class GKernelTypeM<K, std::function<std::tuple<R...>(Args...)> >
  183. : public detail::MetaHelper<K, std::tuple<Args...>, std::tuple<R...>>
  184. , public detail::NoTag
  185. {
  186. template<int... IIs>
  187. static std::tuple<R...> yield(cv::GCall &call, detail::Seq<IIs...>)
  188. {
  189. return std::make_tuple(detail::Yield<R>::yield(call, IIs)...);
  190. }
  191. public:
  192. using InArgs = std::tuple<Args...>;
  193. using OutArgs = std::tuple<R...>;
  194. // TODO: Args&&... here?
  195. static std::tuple<R...> on(Args... args)
  196. {
  197. cv::GCall call(GKernel{ K::id()
  198. , K::tag()
  199. , &K::getOutMeta
  200. , {detail::GTypeTraits<R>::shape...}
  201. , {detail::GTypeTraits<Args>::op_kind...}
  202. , {detail::GObtainCtor<R>::get()...}});
  203. call.pass(args...); // TODO: std::forward() here?
  204. return yield(call, typename detail::MkSeq<sizeof...(R)>::type());
  205. }
  206. };
  207. template<typename, typename> class GKernelType;
  208. template<typename K, typename R, typename... Args>
  209. class GKernelType<K, std::function<R(Args...)> >
  210. : public detail::MetaHelper<K, std::tuple<Args...>, R>
  211. , public detail::NoTag
  212. {
  213. public:
  214. using InArgs = std::tuple<Args...>;
  215. using OutArgs = std::tuple<R>;
  216. static R on(Args... args)
  217. {
  218. cv::GCall call(GKernel{ K::id()
  219. , K::tag()
  220. , &K::getOutMeta
  221. , {detail::GTypeTraits<R>::shape}
  222. , {detail::GTypeTraits<Args>::op_kind...}
  223. , {detail::GObtainCtor<R>::get()}});
  224. call.pass(args...);
  225. return detail::Yield<R>::yield(call, 0);
  226. }
  227. };
  228. namespace detail {
  229. // This tiny class eliminates the semantic difference between
  230. // GKernelType and GKernelTypeM.
  231. template<typename, typename> class KernelTypeMedium;
  232. template<typename K, typename... R, typename... Args>
  233. class KernelTypeMedium<K, std::function<std::tuple<R...>(Args...)>> :
  234. public cv::GKernelTypeM<K, std::function<std::tuple<R...>(Args...)>> {};
  235. template<typename K, typename R, typename... Args>
  236. class KernelTypeMedium<K, std::function<R(Args...)>> :
  237. public cv::GKernelType<K, std::function<R(Args...)>> {};
  238. } // namespace detail
  239. } // namespace cv
  240. // FIXME: I don't know a better way so far. Feel free to suggest one
  241. // The problem is that every typed kernel should have ::id() but body
  242. // of the class is defined by user (with outMeta, other stuff)
  243. //! @cond IGNORED
  244. #define G_ID_HELPER_CLASS(Class) Class##IdHelper
  245. #define G_ID_HELPER_BODY(Class, Id) \
  246. struct G_ID_HELPER_CLASS(Class) \
  247. { \
  248. static constexpr const char * id() {return Id;} \
  249. }; \
  250. //! @endcond
  251. #define GET_G_TYPED_KERNEL(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, NAME, ...) NAME
  252. #define COMBINE_SIGNATURE(...) __VA_ARGS__
  253. // Ensure correct __VA_ARGS__ expansion on Windows
  254. #define __WRAP_VAARGS(x) x
  255. /**
  256. * Helper for G_TYPED_KERNEL declares a new G-API Operation. See [Kernel API](@ref gapi_kernel_api)
  257. * for more details.
  258. *
  259. * @param Class type name for this operation.
  260. * @param API an `std::function<>`-like signature for the operation;
  261. * return type is a single value or a tuple of multiple values.
  262. * @param Id string identifier for the operation. Must be unique.
  263. */
  264. #define G_TYPED_KERNEL_HELPER(Class, API, Id) \
  265. G_ID_HELPER_BODY(Class, Id) \
  266. struct Class final: public cv::detail::KernelTypeMedium<Class, std::function API >, \
  267. public G_ID_HELPER_CLASS(Class)
  268. // {body} is to be defined by user
  269. #define G_TYPED_KERNEL_HELPER_2(Class, _1, _2, Id) \
  270. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2), Id)
  271. #define G_TYPED_KERNEL_HELPER_3(Class, _1, _2, _3, Id) \
  272. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3), Id)
  273. #define G_TYPED_KERNEL_HELPER_4(Class, _1, _2, _3, _4, Id) \
  274. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4), Id)
  275. #define G_TYPED_KERNEL_HELPER_5(Class, _1, _2, _3, _4, _5, Id) \
  276. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5), Id)
  277. #define G_TYPED_KERNEL_HELPER_6(Class, _1, _2, _3, _4, _5, _6, Id) \
  278. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5, _6), Id)
  279. #define G_TYPED_KERNEL_HELPER_7(Class, _1, _2, _3, _4, _5, _6, _7, Id) \
  280. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5, _6, _7), Id)
  281. #define G_TYPED_KERNEL_HELPER_8(Class, _1, _2, _3, _4, _5, _6, _7, _8, Id) \
  282. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5, _6, _7, _8), Id)
  283. #define G_TYPED_KERNEL_HELPER_9(Class, _1, _2, _3, _4, _5, _6, _7, _8, _9, Id) \
  284. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5, _6, _7, _8, _9), Id)
  285. #define G_TYPED_KERNEL_HELPER_10(Class, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, Id) \
  286. G_TYPED_KERNEL_HELPER(Class, COMBINE_SIGNATURE(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10), Id)
  287. /**
  288. * Declares a new G-API Operation. See [Kernel API](@ref gapi_kernel_api)
  289. * for more details.
  290. *
  291. * @param Class type name for this operation.
  292. */
  293. #define G_TYPED_KERNEL(Class, ...) __WRAP_VAARGS(GET_G_TYPED_KERNEL(__VA_ARGS__, \
  294. G_TYPED_KERNEL_HELPER_10, \
  295. G_TYPED_KERNEL_HELPER_9, \
  296. G_TYPED_KERNEL_HELPER_8, \
  297. G_TYPED_KERNEL_HELPER_7, \
  298. G_TYPED_KERNEL_HELPER_6, \
  299. G_TYPED_KERNEL_HELPER_5, \
  300. G_TYPED_KERNEL_HELPER_4, \
  301. G_TYPED_KERNEL_HELPER_3, \
  302. G_TYPED_KERNEL_HELPER_2, \
  303. G_TYPED_KERNEL_HELPER)(Class, __VA_ARGS__)) \
  304. /**
  305. * Declares a new G-API Operation. See [Kernel API](@ref gapi_kernel_api) for more details.
  306. *
  307. * @deprecated This macro is deprecated in favor of `G_TYPED_KERNEL` that is used for declaring any
  308. * G-API Operation.
  309. *
  310. * @param Class type name for this operation.
  311. */
  312. #define G_TYPED_KERNEL_M G_TYPED_KERNEL
  313. #define G_API_OP G_TYPED_KERNEL
  314. #define G_API_OP_M G_API_OP
  315. namespace cv
  316. {
  317. namespace gapi
  318. {
  319. // Prework: model "Device" API before it gets to G-API headers.
  320. // FIXME: Don't mix with internal Backends class!
  321. class GAPI_EXPORTS GBackend
  322. {
  323. public:
  324. class Priv;
  325. // TODO: make it template (call `new` within??)
  326. GBackend();
  327. explicit GBackend(std::shared_ptr<Priv> &&p);
  328. Priv& priv();
  329. const Priv& priv() const;
  330. std::size_t hash() const;
  331. bool operator== (const GBackend &rhs) const;
  332. private:
  333. std::shared_ptr<Priv> m_priv;
  334. };
  335. inline bool operator != (const GBackend &lhs, const GBackend &rhs)
  336. {
  337. return !(lhs == rhs);
  338. }
  339. } // namespace gapi
  340. } // namespace cv
  341. namespace std
  342. {
  343. template<> struct hash<cv::gapi::GBackend>
  344. {
  345. std::size_t operator() (const cv::gapi::GBackend &b) const
  346. {
  347. return b.hash();
  348. }
  349. };
  350. } // namespace std
  351. namespace cv {
  352. namespace gapi {
  353. class GFunctor
  354. {
  355. public:
  356. virtual cv::GKernelImpl impl() const = 0;
  357. virtual cv::gapi::GBackend backend() const = 0;
  358. const char* id() const { return m_id; }
  359. virtual ~GFunctor() = default;
  360. protected:
  361. GFunctor(const char* id) : m_id(id) { };
  362. private:
  363. const char* m_id;
  364. };
  365. /** \addtogroup gapi_compile_args
  366. * @{
  367. */
  368. // FIXME: Hide implementation
  369. /**
  370. * @brief A container class for heterogeneous kernel
  371. * implementation collections and graph transformations.
  372. *
  373. * GKernelPackage is a special container class which stores kernel
  374. * _implementations_ and graph _transformations_. Objects of this class
  375. * are created and passed to cv::GComputation::compile() to specify
  376. * which kernels to use and which transformations to apply in the
  377. * compiled graph. GKernelPackage may contain kernels of
  378. * different backends, e.g. be heterogeneous.
  379. *
  380. * The most easy way to create a kernel package is to use function
  381. * cv::gapi::kernels(). This template functions takes kernel
  382. * implementations in form of type list (variadic template) and
  383. * generates a kernel package atop of that.
  384. *
  385. * Kernel packages can be also generated programmatically, starting
  386. * with an empty package (created with the default constructor)
  387. * and then by populating it with kernels via call to
  388. * GKernelPackage::include(). Note this method is also a template
  389. * one since G-API kernel and transformation implementations are _types_,
  390. * not objects.
  391. *
  392. * Finally, two kernel packages can be combined into a new one
  393. * with function cv::gapi::combine().
  394. */
  395. class GAPI_EXPORTS_W_SIMPLE GKernelPackage
  396. {
  397. /// @private
  398. using M = std::unordered_map<std::string, std::pair<GBackend, GKernelImpl>>;
  399. /// @private
  400. M m_id_kernels;
  401. /// @private
  402. std::vector<GTransform> m_transformations;
  403. protected:
  404. /// @private
  405. // Remove ALL implementations of the given API (identified by ID)
  406. void removeAPI(const std::string &id);
  407. /// @private
  408. // Partial include() specialization for kernels
  409. template <typename KImpl>
  410. typename std::enable_if<(std::is_base_of<cv::detail::KernelTag, KImpl>::value), void>::type
  411. includeHelper()
  412. {
  413. auto backend = KImpl::backend();
  414. auto kernel_id = KImpl::API::id();
  415. auto kernel_impl = GKernelImpl{KImpl::kernel(), &KImpl::API::getOutMeta};
  416. removeAPI(kernel_id);
  417. m_id_kernels[kernel_id] = std::make_pair(backend, kernel_impl);
  418. }
  419. /// @private
  420. // Partial include() specialization for transformations
  421. template <typename TImpl>
  422. typename std::enable_if<(std::is_base_of<cv::detail::TransformTag, TImpl>::value), void>::type
  423. includeHelper()
  424. {
  425. m_transformations.emplace_back(TImpl::transformation());
  426. }
  427. public:
  428. void include(const GFunctor& functor)
  429. {
  430. m_id_kernels[functor.id()] = std::make_pair(functor.backend(), functor.impl());
  431. }
  432. /**
  433. * @brief Returns total number of kernels
  434. * in the package (across all backends included)
  435. *
  436. * @return a number of kernels in the package
  437. */
  438. std::size_t size() const;
  439. /**
  440. * @brief Returns vector of transformations included in the package
  441. *
  442. * @return vector of transformations included in the package
  443. */
  444. const std::vector<GTransform>& get_transformations() const;
  445. /**
  446. * @brief Test if a particular kernel _implementation_ KImpl is
  447. * included in this kernel package.
  448. *
  449. * @sa includesAPI()
  450. *
  451. * @note cannot be applied to transformations
  452. *
  453. * @return true if there is such kernel, false otherwise.
  454. */
  455. template<typename KImpl>
  456. bool includes() const
  457. {
  458. static_assert(std::is_base_of<cv::detail::KernelTag, KImpl>::value,
  459. "includes() can be applied to kernels only");
  460. auto kernel_it = m_id_kernels.find(KImpl::API::id());
  461. return kernel_it != m_id_kernels.end() &&
  462. kernel_it->second.first == KImpl::backend();
  463. }
  464. /**
  465. * @brief Remove all kernels associated with the given backend
  466. * from the package.
  467. *
  468. * Does nothing if there's no kernels of this backend in the package.
  469. *
  470. * @param backend backend which kernels to remove
  471. */
  472. void remove(const GBackend& backend);
  473. /**
  474. * @brief Remove all kernels implementing the given API from
  475. * the package.
  476. *
  477. * Does nothing if there's no kernels implementing the given interface.
  478. */
  479. template<typename KAPI>
  480. void remove()
  481. {
  482. removeAPI(KAPI::id());
  483. }
  484. // FIXME: Rename to includes() and distinguish API/impl case by
  485. // statically?
  486. /**
  487. * Check if package contains ANY implementation of a kernel API
  488. * by API type.
  489. */
  490. template<typename KAPI>
  491. bool includesAPI() const
  492. {
  493. return includesAPI(KAPI::id());
  494. }
  495. /// @private
  496. bool includesAPI(const std::string &id) const;
  497. // FIXME: The below comment is wrong, and who needs this function?
  498. /**
  499. * @brief Find a kernel (by its API)
  500. *
  501. * Returns implementation corresponding id.
  502. * Throws if nothing found.
  503. *
  504. * @return Backend which hosts matching kernel implementation.
  505. *
  506. */
  507. template<typename KAPI>
  508. GBackend lookup() const
  509. {
  510. return lookup(KAPI::id()).first;
  511. }
  512. /// @private
  513. std::pair<cv::gapi::GBackend, cv::GKernelImpl>
  514. lookup(const std::string &id) const;
  515. // FIXME: No overwrites allowed?
  516. /**
  517. * @brief Put a new kernel implementation or a new transformation
  518. * KImpl into the package.
  519. */
  520. template<typename KImpl>
  521. void include()
  522. {
  523. includeHelper<KImpl>();
  524. }
  525. /**
  526. * @brief Lists all backends which are included into package
  527. *
  528. * @return vector of backends
  529. */
  530. std::vector<GBackend> backends() const;
  531. // TODO: Doxygen bug -- it wants me to place this comment
  532. // here, not below.
  533. /**
  534. * @brief Create a new package based on `lhs` and `rhs`.
  535. *
  536. * @param lhs "Left-hand-side" package in the process
  537. * @param rhs "Right-hand-side" package in the process
  538. * @return a new kernel package.
  539. */
  540. friend GAPI_EXPORTS GKernelPackage combine(const GKernelPackage &lhs,
  541. const GKernelPackage &rhs);
  542. };
  543. /**
  544. * @brief Create a kernel package object containing kernels
  545. * and transformations specified in variadic template argument.
  546. *
  547. * In G-API, kernel implementations and transformations are _types_.
  548. * Every backend has its own kernel API (like GAPI_OCV_KERNEL() and
  549. * GAPI_FLUID_KERNEL()) but all of that APIs define a new type for
  550. * each kernel implementation.
  551. *
  552. * Use this function to pass kernel implementations (defined in
  553. * either way) and transformations to the system. Example:
  554. *
  555. * @snippet modules/gapi/samples/api_ref_snippets.cpp kernels_snippet
  556. *
  557. * Note that kernels() itself is a function returning object, not
  558. * a type, so having `()` at the end is important -- it must be a
  559. * function call.
  560. */
  561. template<typename... KK> GKernelPackage kernels()
  562. {
  563. // FIXME: currently there is no check that transformations' signatures are unique
  564. // and won't be any intersection in graph compilation stage
  565. static_assert(cv::detail::all_unique<typename KK::API...>::value, "Kernels API must be unique");
  566. GKernelPackage pkg;
  567. // For those who wonder - below is a trick to call a number of
  568. // methods based on parameter pack (zeroes just help hiding these
  569. // calls into a sequence which helps to expand this parameter pack).
  570. // Just note that `f(),a` always equals to `a` (with f() called!)
  571. // and parentheses are used to hide function call in the expanded sequence.
  572. // Leading 0 helps to handle case when KK is an empty list (kernels<>()).
  573. int unused[] = { 0, (pkg.include<KK>(), 0)... };
  574. cv::util::suppress_unused_warning(unused);
  575. return pkg;
  576. };
  577. template<typename... FF>
  578. GKernelPackage kernels(FF&... functors)
  579. {
  580. GKernelPackage pkg;
  581. int unused[] = { 0, (pkg.include(functors), 0)... };
  582. cv::util::suppress_unused_warning(unused);
  583. return pkg;
  584. };
  585. /** @} */
  586. // FYI - this function is already commented above
  587. GAPI_EXPORTS GKernelPackage combine(const GKernelPackage &lhs,
  588. const GKernelPackage &rhs);
  589. /**
  590. * @brief Combines multiple G-API kernel packages into one
  591. *
  592. * @overload
  593. *
  594. * This function successively combines the passed kernel packages using a right fold.
  595. * Calling `combine(a, b, c)` is equal to `combine(a, combine(b, c))`.
  596. *
  597. * @return The resulting kernel package
  598. */
  599. template<typename... Ps>
  600. GKernelPackage combine(const GKernelPackage &a, const GKernelPackage &b, Ps&&... rest)
  601. {
  602. return combine(a, combine(b, rest...));
  603. }
  604. /** \addtogroup gapi_compile_args
  605. * @{
  606. */
  607. /**
  608. * @brief cv::use_only() is a special combinator which hints G-API to use only
  609. * kernels specified in cv::GComputation::compile() (and not to extend kernels available by
  610. * default with that package).
  611. */
  612. struct GAPI_EXPORTS use_only
  613. {
  614. GKernelPackage pkg;
  615. };
  616. /** @} */
  617. } // namespace gapi
  618. namespace detail
  619. {
  620. template<> struct CompileArgTag<cv::gapi::GKernelPackage>
  621. {
  622. static const char* tag() { return "gapi.kernel_package"; }
  623. };
  624. template<> struct CompileArgTag<cv::gapi::use_only>
  625. {
  626. static const char* tag() { return "gapi.use_only"; }
  627. };
  628. } // namespace detail
  629. } // namespace cv
  630. #endif // OPENCV_GAPI_GKERNEL_HPP