openpilot_comma/third_party/snpe/include/DlSystem/IUserBuffer.hpp

//==============================================================================
//
// Copyright (c) 2017-2020 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
//
//==============================================================================

#ifndef _IUSER_BUFFER_HPP
#define _IUSER_BUFFER_HPP

#include "TensorShape.hpp"
#include "ZdlExportDefine.hpp"
#include <math.h>

namespace zdl {
namespace DlSystem {

/** @addtogroup c_plus_plus_apis C++
@{ */


/**
  * @brief .
  *
  * A base class buffer encoding type
  */
class ZDL_EXPORT UserBufferEncoding {
public:

    /**
      * @brief .
      *
      * An enum class of all supported element types in a IUserBuffer
      */
    enum class ElementType_t
    {
        /// Unknown element type.
        UNKNOWN         = 0,

        /// Each element is presented by float.
        FLOAT           = 1,

        /// Each element is presented by an unsigned int.
        UNSIGNED8BIT    = 2,

        /// Each element is presented by an 8-bit quantized value.
        TF8             = 10,

        /// Each element is presented by an 16-bit quantized value.
        TF16            = 11
    };

    /**
      * @brief Retrieves the size of the element, in bytes.
      *
      * @return Size of the element, in bytes.
     */
    virtual size_t getElementSize() const noexcept = 0;

    /**
      * @brief Retrieves the element type
      *
      * @return Element type
     */
    ElementType_t getElementType() const noexcept {return m_ElementType;};

    virtual ~UserBufferEncoding() {}

protected:
    UserBufferEncoding(ElementType_t  elementType) : m_ElementType(elementType) {};
private:
    const ElementType_t  m_ElementType;
};

/**
  * @brief .
  *
  * A base class buffer source type
  *
  * @note User buffer from CPU support all kinds of runtimes;
  *       User buffer from GLBUFFER support only GPU runtime.
  */
class ZDL_EXPORT UserBufferSource {
public:
   enum class SourceType_t
   {
      /// Unknown buffer source type.
      UNKNOWN = 0,

      /// The network inputs are from CPU buffer.
      CPU = 1,

      /// The network inputs are from OpenGL buffer.
      GLBUFFER = 2
   };

   /**
     * @brief Retrieves the source type
     *
     * @return Source type
    */
   SourceType_t getSourceType() const noexcept {return m_SourceType;};

protected:
   UserBufferSource(SourceType_t sourceType): m_SourceType(sourceType) {};
private:
   const SourceType_t m_SourceType;
};

/**
  * @brief .
  *
  * An source type where input data is delivered from OpenGL buffer
  */
class ZDL_EXPORT UserBufferSourceGLBuffer : public UserBufferSource{
public:
   UserBufferSourceGLBuffer() : UserBufferSource(SourceType_t::GLBUFFER) {};
};

/**
  * @brief .
  *
  * An encoding type where each element is represented by an unsigned int
  */
class ZDL_EXPORT UserBufferEncodingUnsigned8Bit : public UserBufferEncoding {
public:
    UserBufferEncodingUnsigned8Bit() : UserBufferEncoding(ElementType_t::UNSIGNED8BIT) {};
    size_t getElementSize() const noexcept override;

protected:
    UserBufferEncodingUnsigned8Bit(ElementType_t  elementType) : UserBufferEncoding(elementType) {};

};

/**
  * @brief .
  *
  * An encoding type where each element is represented by a float
  */
class ZDL_EXPORT UserBufferEncodingFloat : public UserBufferEncoding {
public:
    UserBufferEncodingFloat() : UserBufferEncoding(ElementType_t::FLOAT) {};
    size_t getElementSize() const noexcept override;

};

/**
  * @brief .
  *
  * An encoding type where each element is represented by tf8, which is an
  * 8-bit quantizd value, which has an exact representation of 0.0
  */

class ZDL_EXPORT UserBufferEncodingTf8 : public UserBufferEncodingUnsigned8Bit {
public:
    UserBufferEncodingTf8() = delete;
    UserBufferEncodingTf8(unsigned char stepFor0, float stepSize) :
            UserBufferEncodingUnsigned8Bit(ElementType_t::TF8),
            m_StepExactly0(stepFor0),
            m_QuantizedStepSize(stepSize) {};

    UserBufferEncodingTf8(const zdl::DlSystem::UserBufferEncoding &ubEncoding) : UserBufferEncodingUnsigned8Bit(ubEncoding.getElementType()){
            const zdl::DlSystem::UserBufferEncodingTf8* ubEncodingTf8
                            = dynamic_cast <const zdl::DlSystem::UserBufferEncodingTf8*> (&ubEncoding);
            if (ubEncodingTf8) {
                m_StepExactly0 = ubEncodingTf8->getStepExactly0();
                m_QuantizedStepSize = ubEncodingTf8->getQuantizedStepSize();
            }
    }

/**
      * @brief Sets the step value that represents 0
      *
      * @param[in] stepExactly0 The step value that represents 0
      *
     */

    void setStepExactly0(const unsigned char stepExactly0) {
        m_StepExactly0 = stepExactly0;
    }


/**
      * @brief Sets the float value that each step represents
      *
      * @param[in] quantizedStepSize The float value of each step size
      *
     */

    void setQuantizedStepSize(const float quantizedStepSize) {
        m_QuantizedStepSize = quantizedStepSize;
    }


/**
      * @brief Retrieves the step that represents 0.0
      *
      * @return Step value
     */

    unsigned char getStepExactly0() const {
        return m_StepExactly0;
    }


/**
     * Calculates the minimum floating point value that
     * can be represented with this encoding.
     *
     * @return Minimum representable floating point value
     */

    float getMin() const {
        return m_QuantizedStepSize * (0 - m_StepExactly0);
    }


/**
     * Calculates the maximum floating point value that
     * can be represented with this encoding.
     *
     * @return Maximum representable floating point value
     */

    float getMax() const {
        return m_QuantizedStepSize * (255 - m_StepExactly0);
    }


/**
      * @brief Retrieves the step size
      *
      * @return Step size
     */

    float getQuantizedStepSize() const {
        return m_QuantizedStepSize;
    }

private:
    unsigned char m_StepExactly0;

    float m_QuantizedStepSize;
};



class ZDL_EXPORT UserBufferEncodingTfN : public UserBufferEncoding {
public:
   UserBufferEncodingTfN() = delete;
   UserBufferEncodingTfN(uint64_t stepFor0, float stepSize, uint8_t bWidth=8):
                                           UserBufferEncoding(getTypeFromWidth(bWidth)),
                                           bitWidth(bWidth),
                                           m_StepExactly0(stepFor0),
                                           m_QuantizedStepSize(stepSize){};

   UserBufferEncodingTfN(const zdl::DlSystem::UserBufferEncoding &ubEncoding) : UserBufferEncoding(ubEncoding.getElementType()){
            const zdl::DlSystem::UserBufferEncodingTfN* ubEncodingTfN
                            = dynamic_cast <const zdl::DlSystem::UserBufferEncodingTfN*> (&ubEncoding);
            if (ubEncodingTfN) {
                m_StepExactly0 = ubEncodingTfN->getStepExactly0();
                m_QuantizedStepSize = ubEncodingTfN->getQuantizedStepSize();
                bitWidth = ubEncodingTfN->bitWidth;
            }
   }

   size_t getElementSize() const noexcept override;
   /**
      * @brief Sets the step value that represents 0
      *
      * @param[in] stepExactly0 The step value that represents 0
      *
     */
   void setStepExactly0(uint64_t stepExactly0) {
      m_StepExactly0 = stepExactly0;
   }

   /**
     * @brief Sets the float value that each step represents
     *
     * @param[in] quantizedStepSize The float value of each step size
     *
    */
   void setQuantizedStepSize(const float quantizedStepSize) {
      m_QuantizedStepSize = quantizedStepSize;
   }

   /**
     * @brief Retrieves the step that represents 0.0
     *
     * @return Step value
    */
   uint64_t getStepExactly0() const {
      return m_StepExactly0;
   }

   /**
    * Calculates the minimum floating point value that
    * can be represented with this encoding.
    *
    * @return Minimum representable floating point value
    */
   float getMin() const {
      return static_cast<float>(m_QuantizedStepSize * (0 - (double)m_StepExactly0));
   }

   /**
    * Calculates the maximum floating point value that
    * can be represented with this encoding.
    *
    * @return Maximum representable floating point value
    */
   float getMax() const{
       return static_cast<float>(m_QuantizedStepSize * (pow(2,bitWidth)-1 - (double)m_StepExactly0));
   };

   /**
     * @brief Retrieves the step size
     *
     * @return Step size
    */
   float getQuantizedStepSize() const {
      return m_QuantizedStepSize;
   }

   ElementType_t getTypeFromWidth(uint8_t width);

   uint8_t bitWidth;
private:
   uint64_t m_StepExactly0;
   float m_QuantizedStepSize;
};


/**
 * @brief UserBuffer contains a pointer and info on how to walk it and interpret its content.
 */
class ZDL_EXPORT IUserBuffer {
public:
    virtual ~IUserBuffer() = default;
    
    /**
      * @brief Retrieves the total number of bytes between elements in each dimension if
      * the buffer were to be interpreted as a multi-dimensional array.
      *
      * @return Number of bytes between elements in each dimension.
      * e.g. A tightly packed tensor of floats with dimensions [4, 3, 2] would
      * return strides of [24, 8, 4].
     */
    virtual const TensorShape& getStrides() const = 0;

    /**
      * @brief Retrieves the size of the buffer, in bytes.
      *
      * @return Size of the underlying buffer, in bytes.
     */
    virtual size_t getSize() const = 0;

    /**
      * @brief Retrieves the size of the inference data in the buffer, in bytes.
      *
      * The inference results from a dynamic-sized model may not be exactly the same size
      * as the UserBuffer provided to SNPE. This function can be used to get the amount
      * of output inference data, which may be less or greater than the size of the UserBuffer.
      *
      * If the inference results fit in the UserBuffer, getOutputSize() would be less than
      * or equal to getSize(). But if the inference results were more than the capacity of
      * the provided UserBuffer, the results would be truncated to fit the UserBuffer. But,
      * getOutputSize() would be greater than getSize(), which indicates a bigger buffer
      * needs to be provided to SNPE to hold all of the inference results.
      *
      * @return Size required for the buffer to hold all inference results, which can be less
      * or more than the size of the buffer, in bytes.
    */
    virtual size_t getOutputSize() const = 0;

    /**
      * @brief Changes the underlying memory that backs the UserBuffer.
      *
      * This can be used to avoid creating multiple UserBuffer objects
      * when the only thing that differs is the memory location.
      *
      * @param[in] buffer Pointer to the memory location
      *
      * @return Whether the set succeeds.
     */
    virtual bool setBufferAddress(void *buffer) noexcept = 0;

    /**
      * @brief Gets a const reference to the data encoding object of
      *        the underlying buffer
      *
      * This is necessary when the UserBuffer is filled by SNPE with
      * data types such as TF8, where the caller needs to know the quantization
      * parameters in order to interpret the data properly
      *
      * @return A read-only encoding object
     */
    virtual const UserBufferEncoding& getEncoding() const noexcept = 0;

    /**
      * @brief Gets a reference to the data encoding object of
      *        the underlying buffer
      *
      * This is necessary when the UserBuffer is re-used, and the encoding
      * parameters can change.  For example, each input can be quantized with
      * different step sizes.
      *
      * @return Data encoding meta-data
     */
    virtual UserBufferEncoding& getEncoding() noexcept = 0;

};

/** @} */ /* end_addtogroup c_plus_plus_apis C++ */

}
}

#endif