Skip to content

Commit ea4b491

Browse files
Ruslan Garnovanton-potapov
Ruslan Garnov
and
anton-potapov
authored
Merge pull request opencv#18213 from rgarnov:rg/rmat_api
Basic RMat implementation * Added basic RMat implementation * Fix typos in basic RMat implementation Co-authored-by: Anton Potapov <[email protected]>
1 parent 3b00ee2 commit ea4b491

File tree

3 files changed

+442
-0
lines changed

3 files changed

+442
-0
lines changed

‎modules/gapi/include/opencv2/gapi/rmat.hpp

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
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) 2020 Intel Corporation
6+
7+
#ifndef OPENCV_GAPI_RMAT_HPP
8+
#define OPENCV_GAPI_RMAT_HPP
9+
10+
#include <opencv2/gapi/gmat.hpp>
11+
12+
namespace cv {
13+
14+
// "Remote Mat", a general class which provides an abstraction layer over the data
15+
// storage and placement (host, remote device etc) and allows to access this data.
16+
//
17+
// The device specific implementation is hidden in the RMat::Adapter class
18+
//
19+
// The basic flow is the following:
20+
// * Backend which is aware of the remote device:
21+
// - Implements own AdapterT class which is derived from RMat::Adapter
22+
// - Wraps device memory into RMat via make_rmat utility function:
23+
// cv::RMat rmat = cv::make_rmat<AdapterT>(args);
24+
//
25+
// * End user:
26+
// - Writes the code which works with RMats without any knowledge of the remote device:
27+
// void func(const cv::RMat& in_rmat, cv::RMat& out_rmat) {
28+
// // Fetch input data from the device, get mapped memory for output
29+
// cv::RMat::View in_view = in_rmat.access(Access::R);
30+
// cv::RMat::View out_view = out_rmat.access(Access::W);
31+
// performCalculations(in_view, out_view);
32+
// // data from out_view is transferred to the device when out_view is destroyed
33+
// }
34+
class RMat
35+
{
36+
public:
37+
// A lightweight wrapper on image data:
38+
// - Doesn't own the memory;
39+
// - Doesn't implement copy semantics (it's assumed that a view is created each time
40+
// wrapped data is being accessed);
41+
// - Has an optional callback which is called when the view is destroyed.
42+
class View
43+
{
44+
public:
45+
using DestroyCallback = std::function<void()>;
46+
47+
View() = default;
48+
View(const GMatDesc& desc, uchar* data, size_t step = 0u, DestroyCallback&& cb = nullptr)
49+
: m_desc(desc), m_data(data), m_step(step == 0u ? elemSize()*cols() : step), m_cb(cb)
50+
{}
51+
52+
View(const View&) = delete;
53+
View(View&&) = default;
54+
View& operator=(const View&) = delete;
55+
View& operator=(View&&) = default;
56+
~View() { if (m_cb) m_cb(); }
57+
58+
cv::Size size() const { return m_desc.size; }
59+
const std::vector<int>& dims() const { return m_desc.dims; }
60+
int cols() const { return m_desc.size.width; }
61+
int rows() const { return m_desc.size.height; }
62+
int type() const { return CV_MAKE_TYPE(depth(), chan()); }
63+
int depth() const { return m_desc.depth; }
64+
int chan() const { return m_desc.chan; }
65+
size_t elemSize() const { return CV_ELEM_SIZE(type()); }
66+
67+
template<typename T = uchar> T* ptr(int y = 0, int x = 0) {
68+
return reinterpret_cast<T*>(m_data + m_step*y + x*CV_ELEM_SIZE(type()));
69+
}
70+
template<typename T = uchar> const T* ptr(int y = 0, int x = 0) const {
71+
return reinterpret_cast<const T*>(m_data + m_step*y + x*CV_ELEM_SIZE(type()));
72+
}
73+
size_t step() const { return m_step; }
74+
75+
private:
76+
GMatDesc m_desc;
77+
uchar* m_data = nullptr;
78+
size_t m_step = 0u;
79+
DestroyCallback m_cb = nullptr;
80+
};
81+
82+
enum class Access { R, W };
83+
class Adapter
84+
{
85+
public:
86+
virtual ~Adapter() = default;
87+
virtual GMatDesc desc() const = 0;
88+
// Implementation is responsible for setting the appropriate callback to
89+
// the view when accessed for writing, to ensure that the data from the view
90+
// is transferred to the device when the view is destroyed
91+
virtual View access(Access) const = 0;
92+
};
93+
using AdapterP = std::shared_ptr<Adapter>;
94+
95+
RMat() = default;
96+
RMat(AdapterP&& a) : m_adapter(std::move(a)) {}
97+
GMatDesc desc() const { return m_adapter->desc(); }
98+
99+
// Note: When accessed for write there is no guarantee that returned view
100+
// will contain actual snapshot of the mapped device memory
101+
// (no guarantee that fetch from a device is performed). The only
102+
// guaranty is that when the view is destroyed, its data will be
103+
// transferred to the device
104+
View access(Access a) const { return m_adapter->access(a); }
105+
106+
// Cast underlying RMat adapter to the particular adapter type,
107+
// return nullptr if underlying type is different
108+
template<typename T> T* get() const
109+
{
110+
static_assert(std::is_base_of<Adapter, T>::value, "T is not derived from Adapter!");
111+
GAPI_Assert(m_adapter != nullptr);
112+
return dynamic_cast<T*>(m_adapter.get());
113+
}
114+
115+
private:
116+
AdapterP m_adapter = nullptr;
117+
};
118+
119+
template<typename T, typename... Ts>
120+
RMat make_rmat(Ts&&... args) { return { std::make_shared<T>(std::forward<Ts>(args)...) }; }
121+
122+
} //namespace cv
123+
124+
#endif /* OPENCV_GAPI_RMAT_HPP */

‎modules/gapi/test/rmat/rmat_tests.cpp

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
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) 2020 Intel Corporation
6+
7+
#include "../test_precomp.hpp"
8+
#include <opencv2/gapi/rmat.hpp>
9+
10+
namespace opencv_test {
11+
namespace {
12+
class RMatAdapterRef : public RMat::Adapter {
13+
cv::Mat& m_mat;
14+
bool& m_callbackCalled;
15+
public:
16+
RMatAdapterRef(cv::Mat& m, bool& callbackCalled)
17+
: m_mat(m), m_callbackCalled(callbackCalled)
18+
{}
19+
virtual RMat::View access(RMat::Access access) const override {
20+
if (access == RMat::Access::W) {
21+
return RMat::View(cv::descr_of(m_mat), m_mat.data, m_mat.step,
22+
[this](){
23+
EXPECT_FALSE(m_callbackCalled);
24+
m_callbackCalled = true;
25+
});
26+
} else {
27+
return RMat::View(cv::descr_of(m_mat), m_mat.data, m_mat.step);
28+
}
29+
}
30+
virtual cv::GMatDesc desc() const override { return cv::descr_of(m_mat); }
31+
};
32+
33+
class RMatAdapterCopy : public RMat::Adapter {
34+
cv::Mat& m_deviceMat;
35+
cv::Mat m_hostMat;
36+
bool& m_callbackCalled;
37+
38+
public:
39+
RMatAdapterCopy(cv::Mat& m, bool& callbackCalled)
40+
: m_deviceMat(m), m_hostMat(m.clone()), m_callbackCalled(callbackCalled)
41+
{}
42+
virtual RMat::View access(RMat::Access access) const override {
43+
if (access == RMat::Access::W) {
44+
return RMat::View(cv::descr_of(m_hostMat), m_hostMat.data, m_hostMat.step,
45+
[this](){
46+
EXPECT_FALSE(m_callbackCalled);
47+
m_callbackCalled = true;
48+
m_hostMat.copyTo(m_deviceMat);
49+
});
50+
} else {
51+
m_deviceMat.copyTo(m_hostMat);
52+
return RMat::View(cv::descr_of(m_hostMat), m_hostMat.data, m_hostMat.step);
53+
}
54+
}
55+
virtual cv::GMatDesc desc() const override { return cv::descr_of(m_hostMat); }
56+
};
57+
58+
void randomizeMat(cv::Mat& m) {
59+
auto ref = m.clone();
60+
while (cv::norm(m, ref, cv::NORM_INF) == 0) {
61+
cv::randu(m, cv::Scalar::all(127), cv::Scalar::all(40));
62+
}
63+
}
64+
65+
template <typename RMatAdapterT>
66+
struct RMatTest {
67+
using AdapterT = RMatAdapterT;
68+
RMatTest()
69+
: m_deviceMat(8,8,CV_8UC1)
70+
, m_rmat(make_rmat<RMatAdapterT>(m_deviceMat, m_callbackCalled)) {
71+
randomizeMat(m_deviceMat);
72+
expectNoCallbackCalled();
73+
}
74+
75+
RMat& rmat() { return m_rmat; }
76+
cv::Mat cloneDeviceMat() { return m_deviceMat.clone(); }
77+
void expectCallbackCalled() { EXPECT_TRUE(m_callbackCalled); }
78+
void expectNoCallbackCalled() { EXPECT_FALSE(m_callbackCalled); }
79+
80+
void expectDeviceDataEqual(const cv::Mat& mat) {
81+
EXPECT_EQ(0, cv::norm(mat, m_deviceMat, NORM_INF));
82+
}
83+
void expectDeviceDataNotEqual(const cv::Mat& mat) {
84+
EXPECT_NE(0, cv::norm(mat, m_deviceMat, NORM_INF));
85+
}
86+
87+
private:
88+
cv::Mat m_deviceMat;
89+
bool m_callbackCalled = false;
90+
cv::RMat m_rmat;
91+
};
92+
} // anonymous namespace
93+
94+
template<typename T>
95+
struct RMatTypedTest : public ::testing::Test, public T { using Type = T; };
96+
97+
using RMatTestTypes = ::testing::Types< RMatTest<RMatAdapterRef>
98+
, RMatTest<RMatAdapterCopy>
99+
>;
100+
101+
TYPED_TEST_CASE(RMatTypedTest, RMatTestTypes);
102+
103+
TYPED_TEST(RMatTypedTest, Smoke) {
104+
auto view = this->rmat().access(RMat::Access::R);
105+
auto matFromDevice = cv::Mat(view.size(), view.type(), view.ptr());
106+
EXPECT_TRUE(cv::descr_of(this->cloneDeviceMat()) == this->rmat().desc());
107+
this->expectDeviceDataEqual(matFromDevice);
108+
}
109+
110+
static Mat asMat(RMat::View& view) {
111+
return Mat(view.size(), view.type(), view.ptr(), view.step());
112+
}
113+
114+
TYPED_TEST(RMatTypedTest, BasicWorkflow) {
115+
{
116+
auto view = this->rmat().access(RMat::Access::R);
117+
this->expectDeviceDataEqual(asMat(view));
118+
}
119+
this->expectNoCallbackCalled();
120+
121+
cv::Mat dataToWrite = this->cloneDeviceMat();
122+
randomizeMat(dataToWrite);
123+
this->expectDeviceDataNotEqual(dataToWrite);
124+
{
125+
auto view = this->rmat().access(RMat::Access::W);
126+
dataToWrite.copyTo(asMat(view));
127+
}
128+
this->expectCallbackCalled();
129+
this->expectDeviceDataEqual(dataToWrite);
130+
}
131+
132+
TEST(RMat, TestEmptyAdapter) {
133+
RMat rmat;
134+
EXPECT_ANY_THROW(rmat.get<RMatAdapterCopy>());
135+
}
136+
137+
TYPED_TEST(RMatTypedTest, CorrectAdapterCast) {
138+
using T = typename TestFixture::Type::AdapterT;
139+
EXPECT_NE(nullptr, this->rmat().template get<T>());
140+
}
141+
142+
class DummyAdapter : public RMat::Adapter {
143+
virtual RMat::View access(RMat::Access) const override { return {}; }
144+
virtual cv::GMatDesc desc() const override { return {}; }
145+
};
146+
147+
TYPED_TEST(RMatTypedTest, IncorrectAdapterCast) {
148+
EXPECT_EQ(nullptr, this->rmat().template get<DummyAdapter>());
149+
}
150+
151+
class RMatAdapterForBackend : public RMat::Adapter {
152+
int m_i;
153+
public:
154+
RMatAdapterForBackend(int i) : m_i(i) {}
155+
virtual RMat::View access(RMat::Access) const override { return {}; }
156+
virtual GMatDesc desc() const override { return {}; }
157+
int deviceSpecificData() const { return m_i; }
158+
};
159+
160+
// RMat's usage scenario in the backend:
161+
// we have some specific data hidden under RMat,
162+
// test that we can obtain it via RMat.as<T>() method
163+
TEST(RMat, UsageInBackend) {
164+
int i = std::rand();
165+
auto rmat = cv::make_rmat<RMatAdapterForBackend>(i);
166+
167+
auto adapter = rmat.get<RMatAdapterForBackend>();
168+
EXPECT_NE(nullptr, adapter);
169+
EXPECT_EQ(i, adapter->deviceSpecificData());
170+
}
171+
} // namespace opencv_test

0 commit comments

Comments
 (0)