buffer.h

// -*- c++ -*-
/*
 * Copyright 2021-present ifm electronic, gmbh
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef IFM3D_FG_Buffer_H
#define IFM3D_FG_Buffer_H
 
#include <climits>
#include <cstdint>
#include <ifm3d/common/json.hpp>
#include <ifm3d/device/device.h>
#include <ifm3d/fg/buffer_id.h>
#include <ifm3d/fg/module_frame_grabber.h>
#include <memory>
#include <optional>
 
namespace ifm3d
{
  class IFM3D_EXPORT Buffer
  {
  private:
    /* @ brief raw pointer to the data*/
    uint8_t* _data{};
    /*@brief number of columns in Buffer (width)*/
    std::uint32_t _cols{};
    /*@brief number of rows in Buffer (height)*/
    std::uint32_t _rows{};
    /*@brief number of channel in Buffer*/
    std::uint32_t _nchannel{};
    /* @brief data format or type*/
    ifm3d::PixelFormat _data_format{};
    /* @brief number of pixel to store one value of data*/
    std::size_t _data_size_in_bytes{};
    /* @brief size of the memory allocated*/
    size_t _size{};
    /* @brief bytes to store pixel */
    size_t _bytes_per_pixel{};
    /* @brief bytes per row */
    size_t _bytes_per_row{};
    /* @brief json formatted metadata of the chunk obtain from device*/
    json _metadata;
    /* @brief buffer id of Buffer */
    ifm3d::buffer_id _buffer_id{};
 
    class BufferAllocator;
    std::shared_ptr<BufferAllocator> _buffer_allocator;
 
  public:
    Buffer();
    /*@overload
      @param cols Number of columns in a Buffer.
      @param rows Number of rows in a Buffer.
      @param nchannel Number of channels in Buffer
      @param format value from ifm3d::pixel_format releates to data type
      need to store one value.
      @param metadata json formatted metadata of the chunk obtain from device
 
      @note This internally calls Create Method to allocates Memory
    */
    Buffer(std::uint32_t cols,
           std::uint32_t rows,
           std::uint32_t nchannel,
           ifm3d::PixelFormat format,
           const std::optional<ifm3d::json>& metadata = std::nullopt,
           ifm3d::buffer_id buffer_id = static_cast<ifm3d::buffer_id>(0));
 
    virtual ~Buffer() = default;
 
    // move semantics
    Buffer(Buffer&&) = default;
    Buffer& operator=(Buffer&&) = default;
 
    // copy ctor/assignment operator
    Buffer(const Buffer&) = default;
    Buffer& operator=(const Buffer&) = default;
 
    /*@brief allocates the memory required for storing the image data
    @param cols Number of columns in a Buffer.
    @param rows Number of rows in a Buffer.
    @param nchannel Number of channels in Buffer
    @param format value from ifm3d::pixel_format releates to data type
 
    @Note On repeated calling it will deference the old Memory
   */
    void Create(std::uint32_t cols,
                std::uint32_t rows,
                std::uint32_t nchannel,
                ifm3d::PixelFormat format,
                ifm3d::buffer_id buffer_id);
 
    [[nodiscard]] Buffer Clone() const;
 
    /* getters*/
    [[nodiscard]] std::uint32_t Height() const;
    [[nodiscard]] std::uint32_t Width() const;
    [[nodiscard]] std::uint32_t NumChannels() const;
    [[nodiscard]] ifm3d::PixelFormat DataFormat() const;
    [[nodiscard]] ifm3d::json Metadata() const;
    [[nodiscard]] ifm3d::buffer_id BufferId() const;
 
    [[nodiscard]] size_t Size() const;
    template <typename T = std::uint8_t>
    T* Ptr(std::uint32_t row);
 
    template <typename T = std::uint8_t>
    T const* Ptr(std::uint32_t row) const;
 
    template <typename T = std::uint8_t>
    T* Ptr(std::uint32_t row, std::uint32_t col);
 
    template <typename T = std::uint8_t>
    T const* Ptr(std::uint32_t row, std::uint32_t col) const;
 
    /*@brief access to the pixel for read  and write
      @param Index of the pixel considering image as 1D array
      @return refernce of the value at the index
    */
    template <typename T>
    T& At(std::size_t index);
    /*@overload considering image as 2D
      @param row 1st dimension index
      @param col 2nd dimension index
    */
    template <typename T>
    T& At(std::uint32_t row, std::uint32_t col);
 
    /*@brief access to the pixel for read  and write
      @param Index of the pixel considering image as 1D array
      @return refernce of the value at the index
    */
    template <typename T>
    T const& At(std::size_t index) const;
    /*@overload considering image as 2D
      @param row 1st dimension index
      @param col 2nd dimension index
    */
    template <typename T>
    T const& At(std::uint32_t row, std::uint32_t col) const;
 
    /*@brief set the value where mask value is 1
      @param val  value to be set
      @param mask  Binary mask
 
      @Note mask size must be same as this
    */
    template <typename T>
    void SetTo(T val, const ifm3d::Buffer& mask);
 
    /*===========================*/
    /*  Iterators */
    /*===========================*/
    template <typename T>
    struct Iterator
    {
      using iterator_category = std::random_access_iterator_tag;
      using difference_type = std::ptrdiff_t;
      using value_type = T;
      using pointer = T*;
      using reference = T&;
 
      Iterator(const std::uint8_t* ptr);
      reference operator*() const;
      pointer operator->();
      Iterator& operator++();
      Iterator operator++(std::int32_t);
 
      friend bool
      operator==(const Iterator& a, const Iterator& b)
      {
        return a._ptr == b._ptr;
      }
 
      friend bool
      operator!=(const Iterator& a, const Iterator& b)
      {
        return a._ptr != b._ptr;
      }
 
      bool
      operator-(const Iterator& rhs) const noexcept
      {
        // logic here
        return this->_ptr - rhs._ptr; // for example
      }
 
    private:
      pointer _ptr;
    };
 
    // NOLINTBEGIN(readability-identifier-naming)
    /*@brief Return the Iterator pointing to start of data*/
    template <typename T>
    Iterator<T> begin();
    /*@brief Return the Iterator pointing to end of data*/
    template <typename T>
    Iterator<T> end();
    // NOLINTEND(readability-identifier-naming)
 
  }; // end Buffer
 
  /*@brief IteratorAdapter is adapter and can be used in range based loops
 
  @code
  for (auto value : ifm3d::IteratorAdapter<unsigned short>(image))
  {
      // operation on value
  @endcode
  */
  template <typename T>
  class IteratorAdapter
  {
  private:
    Buffer& _it; // NOLINT(*-avoid-const-or-ref-data-members)
 
  public:
    IteratorAdapter(Buffer& it);
    auto begin(); // NOLINT(readability-identifier-naming)
    auto end();   // NOLINT(readability-identifier-naming)
  };
 
 
  template <typename TP>
  // NOLINTNEXTLINE(readability-identifier-naming)
  class Buffer_ : public Buffer
  {
  public:
    /*@brief fefault constructor*/
    Buffer_();
 
    /* Similar to Buffer(cols,rows,ifm3d::formatType<Tp>::nchannel,
     * ifm3d::formatType<Tp>::format ) */
    Buffer_(std::uint32_t cols,
            std::uint32_t rows,
            std::optional<ifm3d::json> metadata = std::nullopt);
 
    ~Buffer_() override = default;
 
    // move semantics
    Buffer_(Buffer_<TP>&&) = default;
    Buffer_& operator=(Buffer_<TP>&&) = default;
 
    // copy ctor/assignment operator
    Buffer_(const Buffer_<TP>&) = default;
    Buffer_& operator=(const Buffer_<TP>&) = default;
 
    Buffer_(const Buffer&);
    Buffer_& operator=(const Buffer&);
 
    /* Similar to Buffer::create(cols,rows,ifm3d::formatType<Tp>::nchannel,
     * ifm3d::formatType<Tp>::format, ifm3d::buffer_id buffer_id ) */
    void Create(std::uint32_t cols,
                std::uint32_t rows,
                ifm3d::buffer_id buffer_id);
 
    Buffer_ Clone() const;
 
    /* getters*/
    [[nodiscard]] std::uint32_t Height() const;
    [[nodiscard]] std::uint32_t Width() const;
    [[nodiscard]] std::uint32_t Nchannels() const;
    [[nodiscard]] ifm3d::PixelFormat DataFormat() const;
    [[nodiscard]] ifm3d::json Metadata() const;
 
    TP* Ptr(std::uint32_t row);
 
    TP* Ptr(std::uint32_t row, std::uint32_t col);
 
    /*@brief access to the pixel for read  and write
      @param Index of the pixel considering image as 1D array
      @return refernce of the value at the index
    */
    TP& At(std::size_t index);
    /*@overload considering image as 2D
      @param row 1st dimension index
      @param col 2nd dimension index
    */
    TP& At(std::uint32_t row, std::uint32_t col);
    /*@brief set the value where mask value is 1
      @param val  value to be set
      @param mask  Binary mask
 
      @Note mask size must be same as this
    */
    void SetTo(TP val, ifm3d::Buffer& mask);
 
    /*@brief Return the Iterator pointing to start of data*/
    Iterator<TP> begin();
    /*@brief Return the Iterator pointing to end of data*/
    Iterator<TP> end();
 
  }; // end Buffer_<Tp>
 
  template <typename T, int N>
  struct Point
  {
    std::array<T, N> val;
    using ValueType = T;
  };
 
  template <typename T>
  using Point3D = struct Point<T, 3>;
 
  template <typename T>
  using Point4D = struct Point<T, 4>;
 
  // user helper types
  using Point3D_16U = Point3D<std::uint16_t>;
  using Point3D_16S = Point3D<std::int16_t>;
  // checking for 32 bit float support
  static_assert(CHAR_BIT * sizeof(float) == 32, "32 bit float required");
  using Point3D_32F = Point3D<float>;
 
  using Point4D_16U = Point4D<std::uint16_t>;
  using Point4D_16S = Point4D<std::int16_t>;
  using Point4D_32F = Point4D<float>;
 
} // end: namespace ifm3d
 
#include <ifm3d/fg/detail/buffer.hpp>
#endif // IFM3D_FG_Buffer_H