ie_layouts.h
Go to the documentation of this file.
1 // Copyright (C) 2018-2021 Intel Corporation
2 // SPDX-License-Identifier: Apache-2.0
3 //
4 
5 /**
6  * @brief A header file for data layouts and conversion between them
7  *
8  * @file ie_layouts.h
9  */
10 #pragma once
11 
12 #include <algorithm>
13 
14 #include "ie_api.h"
15 #include "ie_common.h"
16 #include "ie_precision.hpp"
17 
18 namespace InferenceEngine {
19 
20 /**
21  * @brief This class describes blocking layouts
22  */
23 class INFERENCE_ENGINE_API_CLASS(BlockingDesc) {
24 public:
25  /**
26  * @brief The default constructor which creates empty blocking descriptor
27  */
29  /**
30  * @brief The constructor which allows to create blocking descriptors for standard layouts
31  *
32  * @param dims real dimensions
33  * @param layout memory layout
34  */
35  BlockingDesc(const SizeVector& dims, Layout layout);
36  /**
37  * @brief The constructor allows to create blocking descriptors for blocked memory
38  *
39  * @param blocked_dims blocked dimensions
40  * @param order the order of dimensions
41  */
42  BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order);
43  /**
44  * @brief The constructor allows to create blocking descriptors for blocked memory
45  *
46  * @param blocked_dims blocked dimensions
47  * @param order the order of dimensions
48  * @param offset offset to the current memory block
49  */
50  BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset);
51  /**
52  * @brief The constructor allows to create blocking descriptors for blocked memory
53  *
54  * @param blocked_dims blocked dimensions
55  * @param order the order of dimensions
56  * @param offset offset to the current memory block
57  * @param dimOffsets per-dimension offset from the padding to actual data,
58  */
59  BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset, const SizeVector& dimOffsets);
60  /**
61  * @brief The constructor allows to create blocking descriptors for blocked memory
62  *
63  * @param blocked_dims blocked dimensions
64  * @param order the order of dimensions
65  * @param offset offset to the current memory block
66  * @param dimOffsets per-dimension offset from the padding to actual data,
67  * @param strides strides for each dimension
68  */
69  BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset,
70  const SizeVector& dimOffsets, const SizeVector& strides);
71 
72  /**
73  * @brief Returns the blocked dimensions vector
74  *
75  * @return blocked dimensions
76  */
77  const SizeVector& getBlockDims() const {
78  return blockedDims;
79  }
80 
81  /**
82  * @brief Returns the vector of order
83  *
84  * @return order
85  */
86  const SizeVector& getOrder() const {
87  return order;
88  }
89 
90  /**
91  * @brief Returns the per-dimension offset vector
92  *
93  * @return offsets
94  */
96  return offsetPaddingToData;
97  }
98 
99  /**
100  * @brief Returns the offset to the current memory block
101  *
102  * @return offset
103  */
104  size_t getOffsetPadding() const {
105  return offsetPadding;
106  }
107 
108  /**
109  * @brief Returns strides for each dimension
110  *
111  * @return strides
112  */
113  const SizeVector& getStrides() const {
114  return strides;
115  }
116 
117  /**
118  * @brief The comparison operator for the BlockingDesc
119  *
120  * @param rhs object to compare
121  * @return true if objects are equal
122  */
123  bool operator==(const BlockingDesc& rhs) const;
124  /**
125  * @brief The comparison operator for the BlockingDesc
126  *
127  * @param rhs object to compare
128  * @return true if objects aren't equal
129  */
130  bool operator!=(const BlockingDesc& rhs) const;
131 
132 protected:
133  /**
134  * @brief Fills tensor descriptor based on blocking dimensions and specific order
135  * @param blocked_dims A vector representing blocking dimensions
136  * @param order A vector with specific dims order
137  */
138  void fillDesc(const SizeVector& blocked_dims, const SizeVector& order);
139 
140 private:
141  /** Blocked dimensions. */
142  SizeVector blockedDims;
143  /** Strides for blocked dimensions */
144  SizeVector strides;
145  /** The order of blocked dimensions **/
146  SizeVector order;
147  /** Per-dimension offset from the padding to actual data, the top-level
148  * tensor with offsets applied must lie within the padding area. */
149  SizeVector offsetPaddingToData;
150  /** Offset from memory origin to the current block, non-zero only in
151  * a description of a memory sub-block. */
152  size_t offsetPadding;
153 };
154 
155 /**
156  * @brief This class defines Tensor description
157  */
158 class INFERENCE_ENGINE_API_CLASS(TensorDesc) {
159 public:
160  /**
161  * @brief The constructor creates the tensor descriptor using blocking descriptor
162  *
163  * @param precision memory precision
164  * @param dims memory dimensions
165  * @param blockDesc blocking descriptor
166  */
167  TensorDesc(const Precision& precision, const SizeVector& dims, const BlockingDesc& blockDesc);
168  /**
169  * @brief The constructor creates the tensor descriptor using standard layout
170  *
171  * @param precision memory precision
172  * @param dims memory dimensions
173  * @param layout memory layout
174  */
175  TensorDesc(const Precision& precision, const SizeVector& dims, Layout layout);
176  /**
177  * @brief The constructor creates the empty tensor descriptor with precision and layout
178  *
179  * @param precision memory precision
180  * @param layout memory layout
181  */
182  TensorDesc(const Precision& precision, Layout layout);
183  /**
184  * @brief The default constructor which creates empty tensor descriptor
185  */
187 
188  /**
189  * @brief Reshapes the tensor descriptor
190  *
191  * @param dims new dimensions
192  * @param layout new layout if it is necessary
193  */
194  void reshape(const SizeVector& dims, Layout layout = Layout::ANY);
195  /**
196  * @brief Reshapes the tensor descriptor
197  *
198  * @param dims new dimensions
199  * @param blockDesc new blocking descriptor
200  */
201  void reshape(const SizeVector& dims, const BlockingDesc& blockDesc);
202 
203  /**
204  * @brief Returns the vector of dimensions
205  *
206  * @return dimensions
207  */
209  return dims;
210  }
211  /**
212  * @brief Returns the constant vector of dimensions
213  *
214  * @return dimensions
215  */
216  const SizeVector& getDims() const noexcept {
217  return dims;
218  }
219  /**
220  * @brief Sets dimensions
221  *
222  * @param dims new dimensions
223  */
224  void setDims(const SizeVector& dims);
225 
226  /**
227  * @brief Returns the memory layout
228  *
229  * @return layout
230  */
231  Layout getLayout() const {
232  return layout;
233  }
234 
235  /**
236  * @brief Sets the layout
237  *
238  * @param l memory layout
239  */
240  void setLayout(Layout l);
241 
242  /**
243  * @brief Returns the memory precision
244  *
245  * @return precision
246  */
247  const Precision& getPrecision() const {
248  return precision;
249  }
250 
251  /**
252  * @brief Sets the memory precision
253  *
254  * @param p precision
255  */
256  void setPrecision(const Precision& p) {
257  precision = p;
258  }
259 
260  /**
261  * @brief Returns the blocking descriptor
262  *
263  * @return blocking descriptor
264  */
265  const BlockingDesc& getBlockingDesc() const {
266  return blockingDesc;
267  }
268 
269  /**
270  * @brief The comparison operator for the TensorDesc
271  *
272  * @param rhs object to compare
273  * @return true if objects are equal
274  */
275  bool operator==(const TensorDesc& rhs) const;
276  /**
277  * @brief The comparison operator for the TensorDesc
278  *
279  * @param rhs object to compare
280  * @return true if objects aren't equal
281  */
282  bool operator!=(const TensorDesc& rhs) const;
283 
284  /**
285  * @brief Calculates offset for the vector of dimensions
286  *
287  * @param v vector of dimensions
288  * @return offset
289  */
290  size_t offset(const SizeVector& v) const;
291  /**
292  * @brief Calculates offset for the local offset
293  *
294  * @param l local offset
295  * @return offset
296  */
297  size_t offset(size_t l) const;
298 
299  /**
300  * @brief Returns the standard layout for dimensions
301  *
302  * @param dims the vector of dimensions
303  * @return the standard memory layout
304  */
305  static Layout getLayoutByDims(const SizeVector& dims);
306 
307 private:
308  /**
309  * Memory layout
310  */
311  Layout layout;
312  /**
313  * @brief blob's dimensions
314  */
315  SizeVector dims;
316  /**
317  * @brief memory precision
318  */
319  Precision precision;
320  /**
321  * Detailed information about layout construction
322  */
323  BlockingDesc blockingDesc;
324 };
325 
326 /**
327  * @brief This structure describes ROI data for image-like tensors.
328  */
329 struct ROI {
330  size_t id = 0; //!< ID of a ROI (offset over batch dimension)
331  size_t posX = 0; //!< W upper left coordinate of ROI
332  size_t posY = 0; //!< H upper left coordinate of ROI
333  size_t sizeX = 0; //!< W size of ROI
334  size_t sizeY = 0; //!< H size of ROI
335 
336  ROI() = default;
337 
338  /**
339  * @brief Creates a ROI objects with given parameters
340  * @param id ID of a ROI (offset over batch dimension)
341  * @param posX W upper left coordinate of ROI
342  * @param posY H upper left coordinate of ROI
343  * @param sizeX W size of ROI
344  * @param sizeY H size of ROI
345  */
346  ROI(size_t id, size_t posX, size_t posY, size_t sizeX, size_t sizeY) :
347  id(id), posX(posX), posY(posY), sizeX(sizeX), sizeY(sizeY) {
348  }
349 };
350 
351 /**
352  * @brief Creates a TensorDesc object for ROI.
353  *
354  * @param origDesc original TensorDesc object.
355  * @param roi An image ROI object inside of the original object.
356  * @param useOrigMemDesc Flag to use original memory description (strides/offset).
357  * Should be set if the new TensorDesc describes shared memory.
358  *
359  * @return A newly created TensorDesc object representing ROI.
360  */
361 INFERENCE_ENGINE_API_CPP(TensorDesc) make_roi_desc(
362  const TensorDesc& origDesc,
363  const ROI& roi,
364  bool useOrigMemDesc);
365 
366 } // namespace InferenceEngine
This class describes blocking layouts.
Definition: ie_layouts.h:23
size_t getOffsetPadding() const
Returns the offset to the current memory block.
Definition: ie_layouts.h:104
const SizeVector & getBlockDims() const
Returns the blocked dimensions vector.
Definition: ie_layouts.h:77
BlockingDesc(const SizeVector &blocked_dims, const SizeVector &order)
The constructor allows to create blocking descriptors for blocked memory.
const SizeVector & getStrides() const
Returns strides for each dimension.
Definition: ie_layouts.h:113
BlockingDesc(const SizeVector &blocked_dims, const SizeVector &order, size_t offset, const SizeVector &dimOffsets)
The constructor allows to create blocking descriptors for blocked memory.
bool operator!=(const BlockingDesc &rhs) const
The comparison operator for the BlockingDesc.
BlockingDesc(const SizeVector &blocked_dims, const SizeVector &order, size_t offset, const SizeVector &dimOffsets, const SizeVector &strides)
The constructor allows to create blocking descriptors for blocked memory.
BlockingDesc(const SizeVector &blocked_dims, const SizeVector &order, size_t offset)
The constructor allows to create blocking descriptors for blocked memory.
const SizeVector & getOffsetPaddingToData() const
Returns the per-dimension offset vector.
Definition: ie_layouts.h:95
bool operator==(const BlockingDesc &rhs) const
The comparison operator for the BlockingDesc.
const SizeVector & getOrder() const
Returns the vector of order.
Definition: ie_layouts.h:86
BlockingDesc()
The default constructor which creates empty blocking descriptor.
BlockingDesc(const SizeVector &dims, Layout layout)
The constructor which allows to create blocking descriptors for standard layouts.
void fillDesc(const SizeVector &blocked_dims, const SizeVector &order)
Fills tensor descriptor based on blocking dimensions and specific order.
This class holds precision value and provides precision related operations.
Definition: ie_precision.hpp:24
This class defines Tensor description.
Definition: ie_layouts.h:158
const BlockingDesc & getBlockingDesc() const
Returns the blocking descriptor.
Definition: ie_layouts.h:265
TensorDesc(const Precision &precision, const SizeVector &dims, const BlockingDesc &blockDesc)
The constructor creates the tensor descriptor using blocking descriptor.
Layout getLayout() const
Returns the memory layout.
Definition: ie_layouts.h:231
void reshape(const SizeVector &dims, Layout layout=Layout::ANY)
Reshapes the tensor descriptor.
bool operator==(const TensorDesc &rhs) const
The comparison operator for the TensorDesc.
void reshape(const SizeVector &dims, const BlockingDesc &blockDesc)
Reshapes the tensor descriptor.
void setLayout(Layout l)
Sets the layout.
size_t offset(const SizeVector &v) const
Calculates offset for the vector of dimensions.
TensorDesc(const Precision &precision, Layout layout)
The constructor creates the empty tensor descriptor with precision and layout.
void setPrecision(const Precision &p)
Sets the memory precision.
Definition: ie_layouts.h:256
TensorDesc(const Precision &precision, const SizeVector &dims, Layout layout)
The constructor creates the tensor descriptor using standard layout.
const SizeVector & getDims() const noexcept
Returns the constant vector of dimensions.
Definition: ie_layouts.h:216
static Layout getLayoutByDims(const SizeVector &dims)
Returns the standard layout for dimensions.
void setDims(const SizeVector &dims)
Sets dimensions.
TensorDesc()
The default constructor which creates empty tensor descriptor.
SizeVector & getDims()
Returns the vector of dimensions.
Definition: ie_layouts.h:208
bool operator!=(const TensorDesc &rhs) const
The comparison operator for the TensorDesc.
size_t offset(size_t l) const
Calculates offset for the local offset.
const Precision & getPrecision() const
Returns the memory precision.
Definition: ie_layouts.h:247
The macro defines a symbol import/export mechanism essential for Microsoft Windows(R) OS.
This is a header file with common inference engine definitions.
A header file that provides class for describing precision of data.
Inference Engine C++ API.
Definition: cldnn_config.hpp:17
Layout
Layouts that the inference engine supports.
Definition: ie_common.h:70
std::vector< size_t > SizeVector
Represents tensor size.
Definition: ie_common.h:34
TensorDesc make_roi_desc(const TensorDesc &origDesc, const ROI &roi, bool useOrigMemDesc)
Creates a TensorDesc object for ROI.
This structure describes ROI data for image-like tensors.
Definition: ie_layouts.h:329
ROI(size_t id, size_t posX, size_t posY, size_t sizeX, size_t sizeY)
Creates a ROI objects with given parameters.
Definition: ie_layouts.h:346