modules/gapi/include/opencv2/gapi/gstreaming.hpp

   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
   7
   8 #ifndef OPENCV_GAPI_GSTREAMING_COMPILED_HPP
   9 #define OPENCV_GAPI_GSTREAMING_COMPILED_HPP
  10
  11 #include <vector>
  12
  13 #include <opencv2/gapi/opencv_includes.hpp>
  14 #include <opencv2/gapi/own/assert.hpp>
  15 #include <opencv2/gapi/garg.hpp>
  16 #include <opencv2/gapi/streaming/source.hpp>
  17
  18 namespace cv {
  19
  20 /**
  21  * \addtogroup gapi_main_classes
  22  * @{
  23  */
  24 /**
  25  * @brief Represents a computation (graph) compiled for streaming.
  26  *
  27  * This class represents a product of graph compilation (calling
  28  * cv::GComputation::compileStreaming()). Objects of this class
  29  * actually do stream processing, and the whole pipeline execution
  30  * complexity is incapsulated into objects of this class. Execution
  31  * model has two levels: at the very top, the execution of a
  32  * heterogeneous graph is aggressively pipelined; at the very bottom
  33  * the execution of every internal block is determined by its
  34  * associated backend. Backends are selected based on kernel packages
  35  * passed via compilation arguments ( see @ref gapi_compile_args,
  36  * GNetworkPackage, GKernelPackage for details).
  37  *
  38  * GStreamingCompiled objects have a "player" semantics -- there are
  39  * methods like start() and stop(). GStreamingCompiled has a full
  40  * control over a videostream and so is stateful. You need to specify the
  41  * input stream data using setSource() and then call start() to
  42  * actually start processing. After that, use pull() or try_pull() to
  43  * obtain next processed data frame from the graph in a blocking or
  44  * non-blocking way, respectively.
  45  *
  46  * Currently a single GStreamingCompiled can process only one video
  47  * streat at time. Produce multiple GStreamingCompiled objects to run the
  48  * same graph on multiple video streams.
  49  *
  50  * @sa GCompiled
  51  */
  52 class GAPI_EXPORTS GStreamingCompiled
  53 {
  54 public:
  55     class GAPI_EXPORTS Priv;
  56     GStreamingCompiled();
  57
  58     // FIXME: More overloads?
  59     /**
  60      * @brief Specify the input data to GStreamingCompiled for
  61      * processing, a generic version.
  62      *
  63      * Use gin() to create an input parameter vector.
  64      *
  65      * Input vectors must have the same number of elements as defined
  66      * in the cv::GComputation protocol (at the moment of its
  67      * construction). Shapes of elements also must conform to protocol
  68      * (e.g. cv::Mat needs to be passed where cv::GMat has been
  69      * declared as input, and so on). Run-time exception is generated
  70      * on type mismatch.
  71      *
  72      * In contrast with regular GCompiled, user can also pass an
  73      * object of type GVideoCapture for a GMat parameter of the parent
  74      * GComputation.  The compiled pipeline will start fetching data
  75      * from that GVideoCapture and feeding it into the
  76      * pipeline. Pipeline stops when a GVideoCapture marks end of the
  77      * stream (or when stop() is called).
  78      *
  79      * Passing a regular Mat for a GMat parameter makes it "infinite"
  80      * source -- pipeline may run forever feeding with this Mat until
  81      * stopped explicitly.
  82      *
  83      * Currently only a single GVideoCapture is supported as input. If
  84      * the parent GComputation is declared with multiple input GMat's,
  85      * one of those can be specified as GVideoCapture but all others
  86      * must be regular Mat objects.
  87      *
  88      * Throws if pipeline is already running. Use stop() and then
  89      * setSource() to run the graph on a new video stream.
  90      *
  91      * @note This method is not thread-safe (with respect to the user
  92      * side) at the moment. Protect the access if
  93      * start()/stop()/setSource() may be called on the same object in
  94      * multiple threads in your application.
  95      *
  96      * @param ins vector of inputs to process.
  97      * @sa gin
  98      */
  99     void setSource(GRunArgs &&ins);
 100
 101     /**
 102      * @brief Specify an input video stream for a single-input
 103      * computation pipeline.
 104      *
 105      * Throws if pipeline is already running. Use stop() and then
 106      * setSource() to run the graph on a new video stream.
 107      *
 108      * @overload
 109      * @param s a shared pointer to IStreamSource representing the
 110      * input video stream.
 111      */
 112     void setSource(const gapi::wip::IStreamSource::Ptr& s);
 113
 114     /**
 115      * @brief Start the pipeline execution.
 116      *
 117      * Use pull()/try_pull() to obtain data. Throws an exception if
 118      * a video source was not specified.
 119      *
 120      * setSource() must be called first, even if the pipeline has been
 121      * working already and then stopped (explicitly via stop() or due
 122      * stream completion)
 123      *
 124      * @note This method is not thread-safe (with respect to the user
 125      * side) at the moment. Protect the access if
 126      * start()/stop()/setSource() may be called on the same object in
 127      * multiple threads in your application.
 128      */
 129     void start();
 130
 131     /**
 132      * @brief Get the next processed frame from the pipeline.
 133      *
 134      * Use gout() to create an output parameter vector.
 135      *
 136      * Output vectors must have the same number of elements as defined
 137      * in the cv::GComputation protocol (at the moment of its
 138      * construction). Shapes of elements also must conform to protocol
 139      * (e.g. cv::Mat needs to be passed where cv::GMat has been
 140      * declared as output, and so on). Run-time exception is generated
 141      * on type mismatch.
 142      *
 143      * This method writes new data into objects passed via output
 144      * vector.  If there is no data ready yet, this method blocks. Use
 145      * try_pull() if you need a non-blocking version.
 146      *
 147      * @param outs vector of output parameters to obtain.
 148      * @return true if next result has been obtained,
 149      *    false marks end of the stream.
 150      */
 151     bool pull(cv::GRunArgsP &&outs);
 152
 153     /**
 154      * @brief Try to get the next processed frame from the pipeline.
 155      *
 156      * Use gout() to create an output parameter vector.
 157      *
 158      * This method writes new data into objects passed via output
 159      * vector.  If there is no data ready yet, the output vector
 160      * remains unchanged and false is returned.
 161      *
 162      * @return true if data has been obtained, and false if it was
 163      *    not. Note: false here doesn't mark the end of the stream.
 164      */
 165     bool try_pull(cv::GRunArgsP &&outs);
 166
 167     /**
 168      * @brief Stop (abort) processing the pipeline.
 169      *
 170      * Note - it is not pause but a complete stop. Calling start()
 171      * will cause G-API to start processing the stream from the early beginning.
 172      *
 173      * Throws if the pipeline is not running.
 174      */
 175     void stop();
 176
 177     /**
 178      * @brief Test if the pipeline is running.
 179      *
 180      * @note This method is not thread-safe (with respect to the user
 181      * side) at the moment. Protect the access if
 182      * start()/stop()/setSource() may be called on the same object in
 183      * multiple threads in your application.
 184      *
 185      * @return true if the current stream is not over yet.
 186      */
 187     bool running() const;
 188
 189     /// @private
 190     Priv& priv();
 191
 192     /**
 193      * @brief Check if compiled object is valid (non-empty)
 194      *
 195      * @return true if the object is runnable (valid), false otherwise
 196      */
 197     explicit operator bool () const;
 198
 199     /**
 200      * @brief Vector of metadata this graph was compiled for.
 201      *
 202      * @return Unless _reshape_ is not supported, return value is the
 203      * same vector which was passed to cv::GComputation::compile() to
 204      * produce this compiled object. Otherwise, it is the latest
 205      * metadata vector passed to reshape() (if that call was
 206      * successful).
 207      */
 208     const GMetaArgs& metas() const; // Meta passed to compile()
 209
 210     /**
 211      * @brief Vector of metadata descriptions of graph outputs
 212      *
 213      * @return vector with formats/resolutions of graph's output
 214      * objects, auto-inferred from input metadata vector by
 215      * operations which form this computation.
 216      *
 217      * @note GCompiled objects produced from the same
 218      * cv::GComputiation graph with different input metas may return
 219      * different values in this vector.
 220      */
 221     const GMetaArgs& outMetas() const;
 222
 223 protected:
 224     /// @private
 225     std::shared_ptr<Priv> m_priv;
 226 };
 227 /** @} */
 228
 229 }
 230
 231 #endif // OPENCV_GAPI_GSTREAMING_COMPILED_HPP