arm_compute/core/TensorInfo.h

   1 /*
   2  * Copyright (c) 2016-2018 ARM Limited.
   3  *
   4  * SPDX-License-Identifier: MIT
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to
   8  * deal in the Software without restriction, including without limitation the
   9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  10  * sell copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all
  14  * copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24 #ifndef __ARM_COMPUTE_TENSORINFO_H__
  25 #define __ARM_COMPUTE_TENSORINFO_H__
  26
  27 #include "arm_compute/core/ITensorInfo.h"
  28
  29 #include "ITensorInfo.h"
  30 #include "arm_compute/core/Coordinates.h"
  31 #include "arm_compute/core/Strides.h"
  32 #include "arm_compute/core/TensorShape.h"
  33 #include "arm_compute/core/Types.h"
  34 #include "arm_compute/core/Utils.h"
  35
  36 #include <cstddef>
  37 #include <memory>
  38
  39 namespace arm_compute
  40 {
  41 class HOGInfo;
  42
  43 /** Store the tensor's metadata */
  44 class TensorInfo final : public ITensorInfo
  45 {
  46 public:
  47     /** Default constructor */
  48     TensorInfo();
  49     /** Default destructor */
  50     ~TensorInfo() = default;
  51     /** Allow instances of this class to be copy constructed */
  52     TensorInfo(const ITensorInfo &info);
  53     /** Allow instances of this class to be copy constructed */
  54     TensorInfo(const TensorInfo &) = default;
  55     /** Allow instances of this class to be copied */
  56     TensorInfo &operator=(const TensorInfo &) = default;
  57     /** Allow instances of this class to be move constructed */
  58     TensorInfo(TensorInfo &&) = default;
  59     /** Allow instances of this class to be moved */
  60     TensorInfo &operator=(TensorInfo &&) = default;
  61
  62     /** Construct a tensor info with a format.
  63      *
  64      * Can be used for automatic derivation of the shape by the function.
  65      *
  66      * @param[in] format Format of the tensor.
  67      */
  68     TensorInfo(Format format);
  69
  70     /** 2D tensor constructor
  71      *
  72      * @param[in] width  Width of the 2D tensor
  73      * @param[in] height Height of the 2D tensor
  74      * @param[in] format Single plane format of the tensor.
  75      */
  76     TensorInfo(unsigned int width, unsigned int height, Format format);
  77     /** Constructor
  78      *
  79      * @param[in] tensor_shape It specifies the size for each dimension of the tensor in number of elements.
  80      * @param[in] format       Single plane format of the tensor.
  81      */
  82     TensorInfo(const TensorShape &tensor_shape, Format format);
  83
  84     /** Construct a tensor info with a data type and number of channels.
  85      *
  86      * Can be used for automatic derivation of the shape by the function.
  87      *
  88      * @param[in] num_channels         It indicates the number of channels for each tensor element
  89      * @param[in] data_type            Data type to use for each tensor element
  90      * @param[in] fixed_point_position (Optional) It specifies the fixed point position when the tensor data type is QS8, QS16 or QS32.
  91      */
  92     TensorInfo(size_t num_channels, DataType data_type, size_t fixed_point_position = 0);
  93
  94     /** Constructor
  95      *
  96      * @param[in] tensor_shape         It specifies the size for each dimension of the tensor in number of elements.
  97      * @param[in] num_channels         It indicates the number of channels for each tensor element
  98      * @param[in] data_type            Data type to use for each tensor element
  99      * @param[in] fixed_point_position (Optional) Fixed point position that expresses the number of bits for the fractional part of the number when the tensor's data type is QS8 or QS16.
 100      */
 101     TensorInfo(const TensorShape &tensor_shape, size_t num_channels, DataType data_type, int fixed_point_position = 0);
 102
 103     /** Constructor
 104      *
 105      * @param[in] tensor_shape      It specifies the size for each dimension of the tensor in number of elements.
 106      * @param[in] num_channels      It indicates the number of channels for each tensor element
 107      * @param[in] data_type         Data type to use for each tensor element
 108      * @param[in] quantization_info The quantization settings for the tensor data.
 109      */
 110     TensorInfo(const TensorShape &tensor_shape, size_t num_channels, DataType data_type, QuantizationInfo quantization_info);
 111
 112     /** Constructor
 113      *
 114      * @param[in] hog_info HOG's metadata used to allocate normalized HOG space
 115      * @param[in] width    Width of the 2D tensor where the HOG descriptor will be computed on
 116      * @param[in] height   Height of the 2D tensor where the HOG descriptor will be computed on
 117      */
 118     TensorInfo(const HOGInfo &hog_info, unsigned int width, unsigned int height);
 119
 120     /** Initialize the tensor info with just a format.
 121      *
 122      * Can be used for automatic derivation of the shape by the function.
 123      *
 124      * @param[in] format Single plane format of the tensor.
 125      */
 126     void init(Format format);
 127
 128     /** Initialize the metadata structure with the given parameters
 129      *
 130      * @param[in] tensor_shape Size for each dimension of the tensor in number of elements.
 131      * @param[in] format       Single plane format of the tensor.
 132      */
 133     void init(const TensorShape &tensor_shape, Format format);
 134     /** Initialize the metadata structure with the given parameters
 135      *
 136      * @param[in] tensor_shape                  Size for each dimension of the tensor in number of elements.
 137      * @param[in] format                        Single plane format of the tensor.
 138      * @param[in] strides_in_bytes              Stride in bytes for accessing each dimension of the tensor.
 139      * @param[in] offset_first_element_in_bytes Offset in bytes from the beginning of memory allocation to access the first element.
 140      * @param[in] total_size_in_bytes           Size in bytes of the memory allocation (including the offset to the first element).
 141      */
 142     void init(const TensorShape &tensor_shape, Format format, const Strides &strides_in_bytes, size_t offset_first_element_in_bytes, size_t total_size_in_bytes);
 143
 144     /** Initialize the tensor info with just a format.
 145      *
 146      * Can be used for automatic derivation of the shape by the function.
 147      *
 148      * @param[in] num_channels         Desired number of channels for each tensor element.
 149      * @param[in] data_type            Data type to use for each tensor element.
 150      * @param[in] fixed_point_position (Optional) Fixed point position when the tensor data type is QS8, QS16 or QS32.
 151      */
 152     void init(size_t num_channels, DataType data_type, size_t fixed_point_position = 0);
 153
 154     /** Initialize the metadata structure with the given parameters
 155      *
 156      * @param[in] tensor_shape         Size for each dimension of the tensor in number of elements.
 157      * @param[in] num_channels         Desired number of channels for each tensor element.
 158      * @param[in] data_type            Data type to use for each tensor element.
 159      * @param[in] fixed_point_position (Optional) Fixed point position that expresses the number of bits for the fractional part of the number when the tensor's data type is QS8 or QS16.
 160      */
 161     void init(const TensorShape &tensor_shape, size_t num_channels, DataType data_type, int fixed_point_position = 0);
 162
 163     /** Initialize the metadata structure with the given parameters
 164      *
 165      * @param[in] tensor_shape                  Size for each dimension of the tensor in number of elements.
 166      * @param[in] num_channels                  Desired number of channels for each tensor element.
 167      * @param[in] data_type                     Data type to use for each tensor element.
 168      * @param[in] strides_in_bytes              Stride in bytes for accessing each dimension of the tensor.
 169      * @param[in] offset_first_element_in_bytes Offset in bytes from the beginning of memory allocation to access the first element.
 170      * @param[in] total_size_in_bytes           Size in bytes of the memory allocation (including the offset to the first element).
 171      * @param[in] fixed_point_position          (Optional) Fixed point position that expresses the number of bits for the fractional part of the number when the tensor's data type is QS8 or QS16.
 172      */
 173     void init(const TensorShape &tensor_shape, size_t num_channels, DataType data_type, const Strides &strides_in_bytes, size_t offset_first_element_in_bytes,
 174               size_t total_size_in_bytes, int fixed_point_position = 0);
 175     /** Initialize the metadata structure for the given HOG's metadata
 176      *
 177      * @param[in] hog_info HOG's metadata used to allocate normalized HOG space
 178      * @param[in] width    Width of the 2D tensor where the HOG descriptor will be computed on
 179      * @param[in] height   Height of the 2D tensor where the HOG descriptor will be computed on
 180      */
 181     void init(const HOGInfo &hog_info, unsigned int width, unsigned int height);
 182     /** Initialize the metadata structure for the given tensor shape and single-plane format, (Padding is automatically calculated)
 183      *
 184      * @note The padding used by this method is really conservative so that the tensor can be used for most functions.
 185      *
 186      * @param[in] tensor_shape It specifies the size for each dimension of the tensor in number of elements
 187      * @param[in] format       Single plane format of the image.
 188      *
 189      * @return Total allocation size including padding in bytes.
 190      */
 191     size_t init_auto_padding(const TensorShape &tensor_shape, Format format);
 192     /** Initialize the metadata structure for the given tensor shape, number of channels,
 193      *  data type and fixed point position. (Padding is automatically calculated)
 194      *
 195      * @note The padding used by this method is really conservative so that the tensor can be used for most functions.
 196      *
 197      * @param[in] tensor_shape         It specifies the size for each dimension of the tensor in number of elements
 198      * @param[in] num_channels         It indicates the number of channels for each tensor element
 199      * @param[in] data_type            Data type to use for each tensor element
 200      * @param[in] fixed_point_position (Optional) Fixed point position that expresses the number of bits for the fractional part of the number when the tensor's data type is QS8 or QS16.
 201      *
 202      * @return Total allocation size including padding in bytes.
 203      */
 204     size_t init_auto_padding(const TensorShape &tensor_shape, size_t num_channels, DataType data_type, int fixed_point_position = 0);
 205     /** Initialize the metadata structure for the given HOG's metadata
 206      *
 207      * @note init_auto_padding will be used for the tensor initialization.
 208      *
 209      * @param[in] hog_info HOG's metadata used to allocate normalized HOG space
 210      * @param[in] width    Width of the 2D tensor where the HOG descriptor will be computed on
 211      * @param[in] height   Height of the 2D tensor where the HOG descriptor will be computed on
 212      */
 213     size_t init_auto_padding(const HOGInfo &hog_info, unsigned int width, unsigned int height);
 214
 215     // Inherited methods overridden:
 216     std::unique_ptr<ITensorInfo> clone() const override;
 217     ITensorInfo &set_data_type(DataType data_type) override;
 218     ITensorInfo &set_num_channels(int num_channels) override;
 219     ITensorInfo &set_format(Format format) override;
 220     ITensorInfo &set_tensor_shape(const TensorShape &shape) override;
 221     ITensorInfo &set_fixed_point_position(int fixed_point_position) override;
 222     ITensorInfo &set_quantization_info(const QuantizationInfo &quantization_info) override;
 223     ITensorInfo &reset_padding() override;
 224     bool         auto_padding() override;
 225     bool extend_padding(const PaddingSize &padding) override;
 226     size_t dimension(size_t index) const override
 227     {
 228         return _tensor_shape[index];
 229     }
 230     const Strides &strides_in_bytes() const override
 231     {
 232         return _strides_in_bytes;
 233     }
 234     size_t offset_first_element_in_bytes() const override
 235     {
 236         return _offset_first_element_in_bytes;
 237     }
 238     size_t offset_element_in_bytes(const Coordinates &pos) const override;
 239     int fixed_point_position() const override
 240     {
 241         return _fixed_point_position;
 242     }
 243     size_t element_size() const override
 244     {
 245         return data_size_from_type(_data_type) * _num_channels;
 246     }
 247     size_t num_dimensions() const override
 248     {
 249         return _tensor_shape.num_dimensions();
 250     }
 251     size_t num_channels() const override
 252     {
 253         return _num_channels;
 254     }
 255     const TensorShape &tensor_shape() const override
 256     {
 257         return _tensor_shape;
 258     }
 259     DataType data_type() const override
 260     {
 261         return _data_type;
 262     }
 263     Format format() const override
 264     {
 265         return _format;
 266     }
 267     size_t total_size() const override
 268     {
 269         return _total_size;
 270     }
 271     PaddingSize padding() const override
 272     {
 273         return _padding;
 274     }
 275     bool has_padding() const override
 276     {
 277         return !_padding.empty();
 278     }
 279     bool is_resizable() const override
 280     {
 281         return _is_resizable;
 282     }
 283     ITensorInfo &set_is_resizable(bool is_resizable) override
 284     {
 285         _is_resizable = is_resizable;
 286         return *this;
 287     }
 288     ValidRegion valid_region() const override
 289     {
 290         return _valid_region;
 291     }
 292     void set_valid_region(const ValidRegion &valid_region) override
 293     {
 294         _valid_region = valid_region;
 295     }
 296     QuantizationInfo quantization_info() const override
 297     {
 298         return _quantization_info;
 299     }
 300
 301 private:
 302     /** Calculates strides, offset and total size resulting from the specified padding around the XY plane.
 303      *
 304      * @param[in] padding Padding around the XY plane in elements.
 305      */
 306     std::tuple<Strides, size_t, size_t> calculate_padding_requirements(const PaddingSize &padding);
 307
 308     size_t           _total_size;
 309     int              _fixed_point_position;
 310     size_t           _offset_first_element_in_bytes;
 311     Strides          _strides_in_bytes;
 312     size_t           _num_channels;
 313     TensorShape      _tensor_shape;
 314     DataType         _data_type;
 315     Format           _format;
 316     bool             _is_resizable;
 317     ValidRegion      _valid_region;
 318     PaddingSize      _padding;
 319     QuantizationInfo _quantization_info;
 320 };
 321 }
 322 #endif /*__ARM_COMPUTE_TENSORINFO_H__ */