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 <cstdint>
#include <memory>
#include <vector>
#include <optional>
#include <ifm3d/common/json.hpp>
#include <limits.h>
#include <ifm3d/fg/module_frame_grabber.h>
#include <ifm3d/device/device.h>
#include <ifm3d/fg/buffer_id.h>
 
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::pixel_format 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 bufferId_{};
 
    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(const std::uint32_t cols,
           const std::uint32_t rows,
           const std::uint32_t nchannel,
           ifm3d::pixel_format 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(const std::uint32_t cols,
                const std::uint32_t rows,
                const std::uint32_t nchannel,
                ifm3d::pixel_format format,
                ifm3d::buffer_id buffer_id);
 
    Buffer clone() const;
 
    /* getters*/
    std::uint32_t height() const;
    std::uint32_t width() const;
    std::uint32_t nchannels() const;
    ifm3d::pixel_format dataFormat() const;
    ifm3d::json metadata() const;
    ifm3d::buffer_id bufferId() const;
 
    size_t size() const;
    template <typename T = std::uint8_t>
    T* ptr(const std::uint32_t row);
 
    template <typename T = std::uint8_t>
    T const* ptr(const std::uint32_t row) const;
 
    template <typename T = std::uint8_t>
    T* ptr(const std::uint32_t row, const std::uint32_t col);
 
    template <typename T = std::uint8_t>
    T const* ptr(const std::uint32_t row, const 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(const std::size_t index);
    /*@overload considering image as 2D
      @param row 1st dimension index
      @param col 2nd dimension index
    */
    template <typename T>
    T& at(const std::uint32_t row, const 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(const 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(const std::uint32_t row, const 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(const 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(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.m_ptr == b.m_ptr;
      }
 
      friend bool
      operator!=(const Iterator& a, const Iterator& b)
      {
        return a.m_ptr != b.m_ptr;
      }
 
      bool
      operator-(const Iterator& rhs) const noexcept
      {
        // logic here
        return this->m_ptr - rhs.m_ptr; // for example
      }
 
    private:
      pointer m_ptr;
    };
 
    /*@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();
 
  }; // 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;
 
  public:
    IteratorAdapter(Buffer& it);
    auto begin();
    auto end();
  };
 
 
  template <typename Tp>
  class Buffer_ : public Buffer
  {
  public:
    /*@brief fefault constructor*/
    Buffer_();
 
    /* Similar to Buffer(cols,rows,ifm3d::formatType<Tp>::nchannel,
     * ifm3d::formatType<Tp>::format ) */
    Buffer_(const std::uint32_t cols,
            const std::uint32_t rows,
            std::optional<ifm3d::json> metadata = std::nullopt);
 
    ~Buffer_() = 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(const std::uint32_t cols,
                const std::uint32_t rows,
                ifm3d::buffer_id buffer_id);
 
    Buffer_ clone() const;
 
    /* getters*/
    std::uint32_t height() const;
    std::uint32_t width() const;
    std::uint32_t nchannels() const;
    ifm3d::pixel_format dataFormat() const;
    ifm3d::json metadata() const;
 
    Tp* ptr(const std::uint32_t row);
 
    Tp* ptr(const std::uint32_t row, const 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(const std::size_t index);
    /*@overload considering image as 2D
      @param row 1st dimension index
      @param col 2nd dimension index
    */
    Tp& at(const std::uint32_t row, const 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(const 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
  {
    T val[n];
    using value_type = 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