RV_ShaderBlock.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        RV_ShaderBlock.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to handle Shader SSBO and UBO blocks
 */

#ifndef RV_ShaderBlock_h
#define RV_ShaderBlock_h

#include "RV_API.h"
#include "RV_Instance.h"
#include "RV_VKBuffer.h"
#include "RV_VKDescriptorSet.h"
#include "RV_VKShaderModule.h"

#include <VE/VE_VK.h>

#include <UT/UT_Array.h>
#include <UT/UT_Map.h>
#include <UT/UT_Matrix2.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Span.h>
#include <UT/UT_String.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_Vector2.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_Vector4.h>
#include <UT/UT_VectorTypes.h>
#include <UT/UT_WorkBuffer.h>

#include <typeinfo>
#include <utility>


class RV_Render;
class RV_ShaderProgram;
class GR_Uniforms;

#if 0
struct UniformLocation
{
    // name lookup
    UniformLocation(const char* name)
    : owned_stringref(name), name(&owned_stringref)
    {
    }
    UniformLocation(const UT_StringRef& name)
    : name(&name)
    {
    }

    // index lookup
    UniformLocation(int idx)
    : owned_idx(idx), idx(&owned_idx)
    {
    }

    // name lookup and store index
    UniformLocation(const char* name, int* idx)
    : owned_stringref(name), name(&owned_stringref), idx(idx)
    {
    }
    UniformLocation(const UT_StringRef& name, int* idx)
    : name(&name), idx(idx)
    {
    }

    UT_StringRef owned_stringref;
    const UT_StringRef* name = nullptr;
    int owned_idx;
    int* idx = nullptr;
};
#endif

// Helper class to hold type-checked bind functions for the RV_Uniform class
// and RV_PushConstants
// Must be inherited by a child class to be used
// Relies on the child class implementing:
//  - getUniform(): to return the uniform
//  - copyToBuffer(): to set data of the uniform if checks pass
//  - copyToBufferStride(): to set uniforms that need to have 
//                  padding between elements (e.g. vec3 arrays, mat3)

/// Helper tie-in class for binding functions for UBOs and SSBOs
class RV_API RV_ShaderBindFuncs
{
public:

    UT_NON_COPYABLE(RV_ShaderBindFuncs)

    /// Set the value of the uniform 'name' with a block of memory
    bool                bindUniform(const UT_StringRef& name, 
                                RV_UniformType type, 
                                const void* data, exint data_size, 
                                int array_index = 0,
                                int array_range = 1,
                                int* opt_idx = nullptr);

    /// Copy the data for uniform 'name' into the buffer. If name does not
    /// exist in the buffer, or its type/array size doesn't match,
    /// bind...() will return false. If its value is not different from the
    /// current value in the block, it will not cause an upload.
    /// Shader Storage Blocks can have open-ended arrays, and variables within
    /// those arrays can specify their array index with 'array_index'.
    bool                bindInt(const UT_StringRef& name, int v,
                                int array_index = 0,
                                int* opt_idx = nullptr);
    /// Bind a single float value.
    bool                bindFloat(const UT_StringRef& name, fpreal32 v,
                                int array_index = 0,
                                int* opt_idx = nullptr);
    /// Bind a single double value. GPU must support native FP64 values.
    bool                bindDouble(const UT_StringRef& name, fpreal64 v,
                                int array_index = 0,
                                int* opt_idx = nullptr);
    /// Bind a single handle value to a sampler. GPU must support bindless
    /// textures.
    bool                bindUint64(const UT_StringRef& name,
                                uint64 v,
                                int array_index = 0,
                                int* opt_idx = nullptr);

    /// Set values for a fixed-length integer array. 
    bool                bindInts(const UT_StringRef& name,
                                 const int *valarray,
                                 int array_size,
                                 int array_index = 0,
                                 int* opt_idx = nullptr);
    /// Set values for a fixed-length float array. 
    bool                bindFloats(const UT_StringRef& name,
                                   const fpreal32 *valarray,
                                   int array_size,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set values for a fixed-length double array. 
    bool                bindDoubles(const UT_StringRef& name,
                                    const fpreal64 *valarray,
                                    int array_size,
                                    int array_index = 0,
                                    int* opt_idx = nullptr);
    /// Set values for a uint64 handle array.
    bool                bindUint64s(const UT_StringRef& name,
                                    const uint64 *valarray,
                                    int array_size,
                                    int array_index = 0,
                                    int* opt_idx = nullptr);

    /// vec3 is a little different, as it is padded to vec4 in uniform blocks.
    /// SSBOs with std420 packing should use bindVector().

    /// bind a series of ivec3s, using std140 packing (padded to ivec4)
    bool                bindIntVector3(const UT_StringRef& name,
                                       const int *valarray,
                                       int array_size,
                                       int array_index = 0,
                                       int* opt_idx = nullptr);

    /// bind a series of vec3s, using std140 packing (padded to ivec4)
    bool                bindVector3(const UT_StringRef& name,
                                    const fpreal32 *valarray,
                                    int array_size,
                                    int array_index = 0,
                                    int* opt_idx = nullptr);

    /// bind a series of dvec3s, using std140 packing (padded to ivec4)
    bool                bindDVector3(const UT_StringRef& name,
                                     const fpreal64 *valarray,
                                     int array_size,
                                     int array_index = 0,
                                     int* opt_idx = nullptr);

    /// Bind a single vec2 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector2F &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);
    /// Bind a single vec3 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector3F &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);
    /// Bind a single vec4 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector4F &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Bind a single dvec2 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector2D &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single dvec3 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector3D &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);
    /// Set a single dvec4 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector4D &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Bind a single ivec2 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector2i &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single ivec3 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector3i &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);
    /// Set a single ivec4 uniform value.
    bool                bindVector(const UT_StringRef& name,
                                   const UT_Vector4i &v,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single 2x2 matrix value.
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix2F &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);
    /// Set a single 3x3 matrix value.
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix3F &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single 4x4 matrix value.
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix4F &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single 2x2 matrix value (dmat2).
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix2D &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single 3x3 matrix value (dmat3).
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix3D &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

    /// Set a single 4x4 matrix value (dmat4).
    bool                bindMatrix(const UT_StringRef& name,
                                   const UT_Matrix4D &m,
                                   int array_index = 0,
                                   int* opt_idx = nullptr);

protected:
    virtual const RV_Uniform *getUniform(
                                    const UT_StringRef& name,
                                    int* opt_idx) = 0;

    // Debug Print functions
    static void printMemberValue(
            UT_WorkBuffer &out_msg,
            const RV_Uniform& u,
            int base_offset,  int fixed_size, void *data,
            RV_ShaderProgram *opt_shr = nullptr);
    static void printMemberList(
            const UT_Array<RV_Uniform>& u,
            int indent, int base_offset, int array_length, int fixed_size,
            void *data, RV_ShaderProgram *opt_shr = nullptr);
    
    // Virtual Interface for child classes

    /// Copy array of data into the CPU buffer
    virtual void copyToBuffer(
            const void *data,
            int size, int offset,
            const char* name)
            = 0;

    /// Copy data into the CPU buffer with a specified stride. 
    /// incoming data is tightly packed, with padding added in
    /// the buffer to match stride
    virtual void copyToBufferStride(
            const void *data,
            int len,
            int size,
            int stride,
            int offset,
            const char* name)
            = 0;

    // Protected ctor and dtor so base class can't be instantiated
    // And static asserts so it MUST be inherited by BLOCK_T
    RV_ShaderBindFuncs() = default;
    virtual ~RV_ShaderBindFuncs();
};

// Class Representing a Shader variable block, either UBO or SSBO 
//
// Manages buffer and provides interface for querying, and setting
// uniforms. Requires DescriptorBinding description to initialize,
// but only manages buffer. Must be bound into Descriptor Set separately
//
class RV_API RV_ShaderBlock : public RV_ShaderBindFuncs
{
public:
    friend RV_ShaderBindFuncs;

    /// Create the shader block (either a UBO or SSBO) for the binding in a set.
    static RV_ShaderBlock* create(
            RV_Instance* inst,
            const RV_VKDescriptorBinding& binding_layout,
            const char* name = nullptr,
            uint32_t array_size = 0,
            VkBufferUsageFlags additional_usage_flag = 0x00);

    /// Create the shader block (either a UBO or SSBO) for the binding in a set.
    static RV_ShaderBlock* createCPUMapped(
            RV_Instance* inst,
            const RV_VKDescriptorBinding& binding_layout,
            const char* name = nullptr,
            uint32_t array_size = 0,
            bool cpu_mapped = false,
            VkBufferUsageFlags additional_usage_flag = 0x00);

    ~RV_ShaderBlock() override;

    /// Return the buffer object that backs this UBO or SSBO
    RV_VKBuffer*    getBufferObject() { return myBufferObject.get(); }

    /// Return the ptr to the CPU copy of buffer data, which must be downloaded
    /// with downloadBuffer to see the most recent value
    const void*     getCPUBuffer() { return myData; }

    /// commits any changes to the buffer object, creating the buffer object
    /// if required.
    bool            uploadBuffer(RV_Render* r);

    /// Fetches the contents of the GL buffer into the main mem block contained
    /// by this class.
    void            downloadBuffer(RV_Render *r);

    /// returns the size of the buffer for UBO blocks and the 
    /// non-dynamically-sized part of the buffer for SSBOs
    int             getFixedSize() { return myFixedSize; }

    /// returns the size of the buffer for UBO blocks and the 
    /// dynamically-sized part of the buffer for SSBOs
    exint           getSize() const;

    // Whether this block requires uploading to the GPU.
    bool            isDirty() const { return myDirtyFlag; }

    /// compare whether this block is compatible with a shader's binding
    bool            isCompatible(const RV_VKDescriptorBinding& binding) const;

    /// get the binding location of the binding used to create this block
    int             getBindingNum() const { return myBindingNum; }

    /// Copy a bunch of bytes to the buffer. If size=0, it assumes the full
    /// buffer size (or remaining size if ofset!=-0)
    bool            fillBuffer(const void *data, int offset=0, int size=0);


    /// Array length of variably sized arrays for SSBOs.
    int             getArrayLength() const { return myArrayLength; }
    
    /// Offset in buffer of variably sized arrays for SSBOs.
    int             getArrayOffset() const { return myUniforms.last().offset; }

    /// Copy a bunch of bytes to the variable array component of the SSBO
    bool            uploadArray(RV_Render* r,
                                const void* data,
                                exint size,
                                exint offset = 0);

    /// Download bytes from the buffer variable array component of the SSBO
    bool            downloadArray(RV_Render* r,
                                  void* data,
                                  exint size,
                                  exint offset = 0);

    /// Copy a bunch of bytes to the variable array component of the SSBO
    /// where data can be any type used to construct a span
                    template<typename T>
    bool            uploadArray(RV_Render* r,
                                const T &data,
                                exint offset = 0)
            {
                // `T` must be a `UT_Span` or convertable into a `UT_Span`
                auto span = TCB_SPAN_NAMESPACE_NAME::make_span(data);
                return uploadArray(r, span.data(), span.size_bytes(), offset);
            }

    /// Download bytes from the buffer variable array component of the SSBO
    /// where data can be any type used to construct a span
                    template<typename T>
    bool            downloadArray(RV_Render* r,
                                  T &data,
                                  exint offset = 0)
            {
                // `T` must be a `UT_Span` or convertable into a `UT_Span`
                auto span = TCB_SPAN_NAMESPACE_NAME::make_span(data);
                return downloadArray(r, span.data(), span.size_bytes(), offset);
            }

    // See `RV_ShaderBindFuncs` for bind functions

    // Debug Print functions
    void print(RV_ShaderProgram  *opt_shr = nullptr) const;

private:
    int               getUniformIndex(const UT_StringRef& name);
    const RV_Uniform* getUniform(const UT_StringRef& name, int* opt_idx) override;

    /// Copy array of data into the CPU buffer
    void copyToBuffer(
            const void *data,
            int size,
            int offset,
            const char* name) override;

    /// Copy data into the CPU buffer with a specified stride.
    /// incoming data is tightly packed, with padding added in
    /// the buffer to match stride
    void copyToBufferStride(
            const void *data,
            int len,
            int size,
            int stride,
            int offset,
            const char* name) override;

    RV_ShaderBlock(
            RV_VKBufferPtr buffer_object,
            void *buffer,
            int size,
            const char *instance_name,
            int32 binding_num,
            const UT_Array<RV_Uniform> &uniforms,
            uint32_t array_length,
            bool is_storage);

    /// Buffer Data 
    UT_UniquePtr<RV_VKBuffer>   myBufferObject;
    void                        *myData;
    bool                        myDirtyFlag;
    bool                        myIsStorage;

    // Uniform Reflection
    UT_StringHolder             myInstanceName;
    int                         myBindingNum = -1;
    UT_Array<RV_Uniform>        myUniforms;

    UT_StringMap<int>   myUniformsIndexMap;
    UT_StringMap<int>   myUniformsInstanceIndexMap;

    // Size of the fixed part of the buffer
    int                         myFixedSize;

    // Size of the fully allocated buffer
    int                         mySize;

    // for buffer storage objects, which can have a non-array section at the
    // beginning of the block (fixed), followed by array data at the end
    // (variable). myArrayLength determines the number of entries in the array.

    int                         myVariableSize;
    int                         myArrayLength;

    
    // =====================
    // WIP: caching builtin uniforms offsets for faster upload
public:
    bool                bindUniform(int idx, 
                            RV_UniformType type, 
                            const void* data, exint data_size, 
                            int array_index = 0);

    // Bring in interface version of `bindUniform` so it isn't hidden
    using RV_ShaderBindFuncs::bindUniform;

    UT_Array<int> myBuiltinArrayIdxToLocalIdx;
    friend GR_Uniforms;
};

/// Class Representing the Push Constants used by the pipeline
/// Will be owned by directly by the RV_Render, and gets holds
/// a ptr to the RV_Render owning it
///
/// Does not have its own layout, instead uses the layout of the
/// shader bound to RV_Render at the time 'bind' is called
class RV_PushConstants : public RV_ShaderBindFuncs
{
public:
    RV_PushConstants(RV_Render* r);
    ~RV_PushConstants() override;

    /// Write all bound values to the push constant memory
    bool upload(RV_Render* r);

    /// Whether this block requires uploading to the GPU.
    bool            isDirty() const { return myDirtyFlag; }
    /// Force the block to be re-uploaded to the GPU, even if not dirtied
    void            forceDirty() { myDirtyFlag = true; }

    /// Copy a bunch of bytes to the buffer. If size=0, it assumes the full
    /// buffer size (or remaining size if ofset!=-0)
    bool            fillBuffer(const void *data, int offset=0, int size=0);

    void            print(RV_ShaderProgramBase *sh) const;

private:
    const RV_Uniform* getUniform(const UT_StringRef& name, int* opt_idx)
            override;

    /// Copy array of data into the CPU buffer
    void copyToBuffer(
            const void *data,
            int size,
            int offset,
            const char* name) override;

    /// Copy data into the CPU buffer with a specified stride. 
    /// incoming data is tightly packed, with padding added in
    /// the buffer to match stride
    void copyToBufferStride(
            const void *data,
            int len,
            int size,
            int stride,
            int offset,
            const char* name) override;

    bool myDirtyFlag = true;
    RV_Render* myR;
    void* myData;
    int mySize;
};

#endif