Merge pull request #20163 from smirnov-alexey:as/gapi_serialization_docs

G-API: add documentation on serialization functionality

* Add documentation on serialization/deserialization

* Add docs on bind() methods

* Fix typo

* Docs refactoring

* Fix s11n docs

* Fix deserialize() docs

* Change deserialize docs

* Fix warning

* Address review comments

* Fix sample

* Fix warnings and errors

* Fix docs warnings

* Fix warnings

* Address review comments

* Add prefixes to snippets and fix indentation

* Address review comments and move snippets to a single file

modules/gapi/samples/api_ref_snippets.cpp

@@ -4,6 +4,10 @@
 #include <opencv2/gapi/core.hpp>
 #include <opencv2/gapi/imgproc.hpp>
 
+#include <opencv2/gapi/s11n.hpp>
+#include <opencv2/gapi/garg.hpp>
+#include <opencv2/gapi/gcommon.hpp>
+
 #include <opencv2/gapi/cpu/gcpukernel.hpp>
 
 #include <opencv2/gapi/fluid/core.hpp>
@@ -55,6 +59,120 @@ static void typed_example()
     //! [Typed_Example]
 }
 
+static void bind_serialization_example()
+{
+    // ! [bind after deserialization]
+    cv::GCompiled compd;
+    std::vector<char> bytes;
+    auto graph = cv::gapi::deserialize<cv::GComputation>(bytes);
+    auto meta = cv::gapi::deserialize<cv::GMetaArgs>(bytes);
+
+    compd = graph.compile(std::move(meta), cv::compile_args());
+    auto in_args  = cv::gapi::deserialize<cv::GRunArgs>(bytes);
+    auto out_args = cv::gapi::deserialize<cv::GRunArgs>(bytes);
+    compd(std::move(in_args), cv::gapi::bind(out_args));
+    // ! [bind after deserialization]
+}
+
+static void bind_deserialization_example()
+{
+    // ! [bind before serialization]
+    std::vector<cv::GRunArgP> graph_outs;
+    cv::GRunArgs out_args;
+
+    for (auto &&out : graph_outs) {
+        out_args.emplace_back(cv::gapi::bind(out));
+    }
+    const auto sargsout = cv::gapi::serialize(out_args);
+    // ! [bind before serialization]
+}
+
+struct SimpleCustomType {
+    bool val;
+    bool operator==(const SimpleCustomType& other) const {
+        return val == other.val;
+    }
+};
+
+struct SimpleCustomType2 {
+    int val;
+    std::string name;
+    std::vector<float> vec;
+    std::map<int, uint64_t> mmap;
+    bool operator==(const SimpleCustomType2& other) const {
+        return val == other.val && name == other.name &&
+               vec == other.vec && mmap == other.mmap;
+    }
+};
+
+// ! [S11N usage]
+namespace cv {
+namespace gapi {
+namespace s11n {
+namespace detail {
+template<> struct S11N<SimpleCustomType> {
+    static void serialize(IOStream &os, const SimpleCustomType &p) {
+        os << p.val;
+    }
+    static SimpleCustomType deserialize(IIStream &is) {
+        SimpleCustomType p;
+        is >> p.val;
+        return p;
+    }
+};
+
+template<> struct S11N<SimpleCustomType2> {
+    static void serialize(IOStream &os, const SimpleCustomType2 &p) {
+        os << p.val << p.name << p.vec << p.mmap;
+    }
+    static SimpleCustomType2 deserialize(IIStream &is) {
+        SimpleCustomType2 p;
+        is >> p.val >> p.name >> p.vec >> p.mmap;
+        return p;
+    }
+};
+} // namespace detail
+} // namespace s11n
+} // namespace gapi
+} // namespace cv
+// ! [S11N usage]
+
+namespace cv {
+namespace detail {
+template<> struct CompileArgTag<SimpleCustomType> {
+    static const char* tag() {
+        return "org.opencv.test.simple_custom_type";
+    }
+};
+
+template<> struct CompileArgTag<SimpleCustomType2> {
+    static const char* tag() {
+        return "org.opencv.test.simple_custom_type_2";
+    }
+};
+} // namespace detail
+} // namespace cv
+
+static void s11n_example()
+{
+    SimpleCustomType  customVar1 { false };
+    SimpleCustomType2 customVar2 { 1248, "World", {1280, 720, 640, 480},
+                                   { {5, 32434142342}, {7, 34242432} } };
+
+    std::vector<char> sArgs = cv::gapi::serialize(
+        cv::compile_args(customVar1, customVar2));
+
+    cv::GCompileArgs dArgs = cv::gapi::deserialize<cv::GCompileArgs,
+                                                   SimpleCustomType,
+                                                   SimpleCustomType2>(sArgs);
+
+    SimpleCustomType  dCustomVar1 = cv::gapi::getCompileArg<SimpleCustomType>(dArgs).value();
+    SimpleCustomType2 dCustomVar2 = cv::gapi::getCompileArg<SimpleCustomType2>(dArgs).value();
+
+    (void) dCustomVar1;
+    (void) dCustomVar2;
+}
+
 G_TYPED_KERNEL(IAdd, <cv::GMat(cv::GMat)>, "test.custom.add") {
     static cv::GMatDesc outMeta(const cv::GMatDesc &in) { return in; }
 };
@@ -128,5 +246,8 @@ int main(int argc, char *argv[])
     // unused functions
     typed_example();
     gscalar_example();
+    bind_serialization_example();
+    bind_deserialization_example();
+    s11n_example();
     return 0;
 }