data_provider_interface.hpp 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  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) 2021 Intel Corporation
  6. #ifndef GAPI_STREAMING_ONEVPL_ONEVPL_DATA_PROVIDER_INTERFACE_HPP
  7. #define GAPI_STREAMING_ONEVPL_ONEVPL_DATA_PROVIDER_INTERFACE_HPP
  8. #include <exception>
  9. #include <memory>
  10. #include <string>
  11. #include <opencv2/gapi/own/exports.hpp> // GAPI_EXPORTS
  12. namespace cv {
  13. namespace gapi {
  14. namespace wip {
  15. namespace onevpl {
  16. struct GAPI_EXPORTS DataProviderException : public std::exception {
  17. DataProviderException(const std::string& descr);
  18. DataProviderException(std::string&& descr);
  19. virtual ~DataProviderException() = default;
  20. virtual const char* what() const noexcept override;
  21. private:
  22. std::string reason;
  23. };
  24. struct GAPI_EXPORTS DataProviderSystemErrorException final : public DataProviderException {
  25. DataProviderSystemErrorException(int error_code, const std::string& description = std::string());
  26. ~DataProviderSystemErrorException() = default;
  27. };
  28. struct GAPI_EXPORTS DataProviderUnsupportedException final : public DataProviderException {
  29. DataProviderUnsupportedException(const std::string& description);
  30. ~DataProviderUnsupportedException() = default;
  31. };
  32. struct GAPI_EXPORTS DataProviderImplementationException : public DataProviderException {
  33. DataProviderImplementationException(const std::string& description);
  34. ~DataProviderImplementationException() = default;
  35. };
  36. /**
  37. * @brief Public interface allows to customize extraction of video stream data
  38. * used by onevpl::GSource instead of reading stream from file (by default).
  39. *
  40. * Interface implementation constructor MUST provide consistency and creates fully operable object.
  41. * If error happened implementation MUST throw `DataProviderException` kind exceptions
  42. *
  43. * @note Interface implementation MUST manage stream and other constructed resources by itself to avoid any kind of leak.
  44. * For simple interface implementation example please see `StreamDataProvider` in `tests/streaming/gapi_streaming_tests.cpp`
  45. */
  46. struct GAPI_EXPORTS IDataProvider {
  47. using Ptr = std::shared_ptr<IDataProvider>;
  48. using mfx_codec_id_type = uint32_t;
  49. /**
  50. * NB: here is supposed to be forward declaration of mfxBitstream
  51. * But according to current oneVPL implementation it is impossible to forward
  52. * declare untagged struct mfxBitstream.
  53. *
  54. * IDataProvider makes sense only for HAVE_VPL is ON and to keep IDataProvider
  55. * interface API/ABI compliant between core library and user application layer
  56. * let's introduce wrapper mfx_bitstream which inherits mfxBitstream in private
  57. * G-API code section and declare forward for wrapper mfx_bitstream here
  58. */
  59. struct mfx_bitstream;
  60. virtual ~IDataProvider() = default;
  61. /**
  62. * The function is used by onevpl::GSource to extract codec id from data
  63. *
  64. */
  65. virtual mfx_codec_id_type get_mfx_codec_id() const = 0;
  66. /**
  67. * The function is used by onevpl::GSource to extract binary data stream from @ref IDataProvider
  68. * implementation.
  69. *
  70. * It MUST throw `DataProviderException` kind exceptions in fail cases.
  71. * It MUST return MFX_ERR_MORE_DATA in EOF which considered as not-fail case.
  72. *
  73. * @param in_out_bitsream the input-output reference on MFX bitstream buffer which MUST be empty at the first request
  74. * to allow implementation to allocate it by itself and to return back. Subsequent invocation of `fetch_bitstream_data`
  75. * MUST use the previously used in_out_bitsream to avoid skipping rest of frames which haven't been consumed
  76. * @return true for fetched data, false on EOF and throws exception on error
  77. */
  78. virtual bool fetch_bitstream_data(std::shared_ptr<mfx_bitstream> &in_out_bitsream) = 0;
  79. /**
  80. * The function is used by onevpl::GSource to check more binary data availability.
  81. *
  82. * It MUST return TRUE in case of EOF and NO_THROW exceptions.
  83. *
  84. * @return boolean value which detects end of stream
  85. */
  86. virtual bool empty() const = 0;
  87. };
  88. } // namespace onevpl
  89. } // namespace wip
  90. } // namespace gapi
  91. } // namespace cv
  92. #endif // GAPI_STREAMING_ONEVPL_ONEVPL_DATA_PROVIDER_INTERFACE_HPP