diff --git a/modules/gapi/doc/00-root.markdown b/modules/gapi/doc/00-root.markdown index cb99495c1b..5006df26b8 100644 --- a/modules/gapi/doc/00-root.markdown +++ b/modules/gapi/doc/00-root.markdown @@ -69,7 +69,9 @@ A very basic example of G-API pipeline is shown below: @include modules/gapi/samples/api_example.cpp - +The numbered flow in the sample is straightforward: the first block +opens the video source, the second block declares the G-API graph, and +the last block repeatedly compiles and runs that graph on each frame. G-API is a separate OpenCV module so its header files have to be included explicitly. The first four lines of `main()` create and @@ -91,14 +93,14 @@ input/output data references (in this example, `in` and `out` cv::GMat objects, respectively) as parameters and reconstructs the call graph based on all the data flow between `in` and `out`. -cv::GComputation is a thin object in sense that it just captures which +cv::GComputation is a thin object in the sense that it just captures which operations form up a computation. However, it can be used to execute computations -- in the following processing loop, every captured frame (a cv::Mat `input_frame`) is passed to cv::GComputation::apply(). ![Example pipeline running on sample video 'vtest.avi'](pics/demo.jpg) -cv::GComputation::apply() is a polimorphic method which accepts a +cv::GComputation::apply() is a polymorphic method which accepts a variadic number of arguments. Since this computation is defined on one input, one output, a special overload of cv::GComputation::apply() is used to pass input data and get output data. @@ -107,19 +109,18 @@ Internally, cv::GComputation::apply() compiles the captured graph for the given input parameters and executes the compiled graph on data immediately. -There is a number important concepts can be outlines with this example: +Several important concepts are illustrated by this example: * Graph declaration and graph execution are distinct steps; * Graph is built implicitly from a sequence of G-API expressions; * G-API supports function-like calls -- e.g. cv::gapi::resize(), and - operators, e.g operator|() which is used to compute bitwise OR; + operators, e.g. @ref cv::operator|(const cv::GMat& lhs, const cv::GMat& rhs) "operator|()", which is used to compute bitwise OR; * G-API syntax aims to look pure: every operation call within a graph yields a new result, thus forming a directed acyclic graph (DAG); * Graph declaration is not bound to any data -- real data objects (cv::Mat) come into picture after the graph is already declared. - - See [tutorials and porting examples](@ref tutorial_table_of_content_gapi) to learn more on various G-API features and concepts. - +Future revisions may split this introduction into dedicated chapters for +declaration, compilation, and execution. diff --git a/modules/gapi/doc/20-kernel-api.markdown b/modules/gapi/doc/20-kernel-api.markdown index 9a7cf39f67..235fdadbbd 100644 --- a/modules/gapi/doc/20-kernel-api.markdown +++ b/modules/gapi/doc/20-kernel-api.markdown @@ -118,7 +118,10 @@ computation from inputs to outputs and infer metadata of internal for further pipeline optimizations, memory allocation, and other operations done by G-API framework during graph compilation. - +For example, a kernel that blurs an image can use `outMeta()` to copy +the input image size to the output metadata while keeping the pixel +type unchanged. A kernel that changes geometry, such as resize, updates +the output dimensions accordingly before the graph is compiled. # Implementing a kernel {#gapi_kernel_implementing} @@ -134,10 +137,10 @@ Every backend defines its own way to implement a kernel interface. This way is regular, though -- whatever plugin is, its kernel implementation must be "derived" from a kernel interface type. -Kernel implementation are then organized into _kernel -packages_. Kernel packages are passed to cv::GComputation::compile() -as compile arguments, with some hints to G-API on how to select proper -kernels (see more on this in "Heterogeneity"[TBD]). +Kernel implementations are then organized into _kernel packages_. +Kernel packages are passed to cv::GComputation::compile() as compile +arguments, with some hints to G-API on how to select proper kernels +according to the available backends and compilation hints. For example, the aforementioned `Filter2D` is implemented in "reference" CPU (OpenCV) plugin this way (*NOTE* -- this is a @@ -176,8 +179,11 @@ macro GAPI_COMPOUND_KERNEL(): @snippet samples/cpp/tutorial_code/gapi/doc_snippets/kernel_api_snippets.cpp compound - - +Compound kernels can simplify dispatching because a backend may expand +them into several smaller kernels only when that backend needs the +decomposition. In practice, `expand()` is called during compilation, +when G-API resolves the compound implementation into a backend-specific +subgraph before execution. It is important to distinguish a compound kernel from G-API high-order function, i.e. a C++ function which looks like a kernel but in fact