RV_VKDescriptorSet.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_VKDescriptorSet.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Descriptor Sets for Vulkan Pipelines
 *
 *      Note on naming: trying to keep the naming a little less
 *      confusing than the Vulkan types:
 *      A Descriptor is a single resource in the shader
 *      A Descriptor Binding is a named binding point for
 *              a set of  descriptors with the same type
 *              e.g. for array bindings, each element is a descriptor,
 *              for non-arrays the binding is 1 descriptor
 *      A Descriptor [Set/Layout] is a collection of bindings
 *          A Descriptor Set Layout is just an object descibing the layout
 *          A Descriptor Set is the actual object bindable to the pipeline
 *      A Pipeline Layout is a collection of Sets (+ Push Constant ranges)
 *
 *      Trying to use these terms consistently, as they are less verboase than
 *      the Vulkan types:
 *                [RV Name]               [Vulkan Name]
 *              PipelineLayout     ->    PipelineLayout
 *              DescriptorSet      ->    DescriptorSet
 *              DescriptorLayout   ->    DescriptorSetLayout
 *              DescriptorBinding* ->    DescriptorSetLayoutBinding*
 *
 *          * VkDescriptorSetLayoutBinding struct describes binding,
 *            (i.e. is the layout info). There is no object representing
 *            a binding itself, only whole sets
 *
 *      ALSO adding the uniform, which isn't part of the spec. Uniform refers
 *      struct members for UBO and SSBO types, or the binding itself for other
 *      types: but with extra type info (e.g. the type of sampler/image)
 *
 *  */

#ifndef RV_VKDescriptorSet_h
#define RV_VKDescriptorSet_h

#include "RV_API.h"

#include <SYS/SYS_Hash.h>
#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Map.h>
#include <UT/UT_Lock.h>
#include <UT/UT_Set.h>
#include <UT/UT_SmallArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_RWLock.h>

#include <VE/VE_VK.h>
#include "RV_Type.h"
#include "RV_TypePtrs.h"

class RV_Instance;
class RV_VKCommandBuffer;
class RV_VKPipelineLayout;

void
RVgetUniformSize(RV_UniformType type,
                int &out_typesize,  // size of base type in bytes (e.g 4 or 8)
                bool &out_is_int,   // whether base type is int or float
                int &out_size,      // size of vector type (must do: out_size * out_col_num for matrix size)
                int &out_align,     // alignment of vector elment
                int &out_vec_num,   // number of vector elements
                int &out_col_num    // number of columns
                );

// -----------------
// RV_Uniform
//
// Will be used for UBO members, push constants, opaque-type bindings, etc.
/// Type info for a single variable in a shader
class RV_API RV_Uniform
{
public:
    RV_Uniform() = default;

    // ctor for opaque type
    RV_Uniform(
        const UT_StringHolder &name,
        RV_UniformType type,
        uint32_t count,
        uint32_t set,
        uint32_t binding)
    : RV_Uniform(name, type, count, set, binding,
                 0, 0, 0, 0, UT_Array<RV_Uniform>(), false)
    {}

    // ctor for struct members
    RV_Uniform(
            const UT_StringHolder &name,
            RV_UniformType type,
            uint32_t count,
            uint32_t set,
            uint32_t binding,
            uint32_t offset,
            uint32_t base_size,
            uint32_t array_stride,
            uint32_t matrix_stride,
            const UT_Array<RV_Uniform>& members,
            bool is_active)
        : myName(name)
        , myType(type)
        , arraySize(count)
        , set(set)
        , binding(binding)
        , offset(offset)
        , baseSize(base_size)
        , arrayStride(array_stride)
        , matrixStride(matrix_stride)
        , members(members)
        , myIsActive(is_active)
    {}

    /// Returns true if there is an SSBO array size for the variable 
    bool isRuntimeArray() const { return arraySize == 0; }

    // General properties
    UT_StringHolder     myName;
    RV_UniformType      myType = RV_UNIFORM_INVALID;
    uint32_t            arraySize = 1;

    // Locational info within set
    uint32_t set = 0;
    uint32_t binding = 0;

    // Properties only for Struct Members
    /// byte offset of member in buffer block
    uint32_t offset = 0;
    /// size of base type. Will be raw size for vector/scalar/struct 
    /// and column vec size for matrix
    uint32_t baseSize = 0;
    /// offset between elements in an array
    uint32_t arrayStride = 0;
    /// offset between columns in a matrix
    uint32_t matrixStride = 0;
    /// list of members for struct types
    UT_Array<RV_Uniform> members;
    // Whether or not the uniform is accessed in shader
    bool     myIsActive = true;
};

// -----------------
// RV_VKDescriptorBinding
//
// A single named binding point in a descriptor set
// Also contains RV_Uniforms with extra type info
struct RV_API RV_VKDescriptorBinding
{
    RV_VKDescriptorBinding() = default;

    RV_VKDescriptorBinding(
            const UT_StringHolder& name,
            VkDescriptorType type,
            uint32_t count,
            VkShaderStageFlags stages,
            uint32_t binding,
            uint32_t set,
            RV_UniformType uniform_type);

    RV_VKDescriptorBinding(
            const UT_StringHolder& name,
            VkDescriptorType type,
            uint32_t count,
            VkShaderStageFlags stages,
            uint32_t binding,
            uint32_t set,
            uint32_t buffer_size,
            const UT_Array<RV_Uniform>& members);

    bool compare(
            const RV_VKDescriptorBinding& other,
            bool compare_uniforms_types,
            bool compare_uniforms_names,
            bool compare_binding_location,
            bool compare_binding_stages,
            UT_WorkBuffer *msg = nullptr) const;

    void merge(const RV_VKDescriptorBinding& other);

    inline bool isValid() const
    {
        return myCount > 0;
    }

    // Basic Descriptor Type info
    VkDescriptorType myType;
    uint32_t myCount = 0;
    
    // Locational info, required for set creation
    VkShaderStageFlags myStages;
    uint32_t myBindingNumber;
    
    // Extra info Provided by reflection
    uint32_t mySetNumber;
    UT_StringHolder myName;
    uint32_t myBufferSize;
    UT_Array<RV_Uniform> myUniforms;
};

// -----------------
// RV_VKDescriptorSetInfo
//
// Info used to create a DescriptorSetLayout object
class RV_API RV_VKDescriptorSetInfo
{
public:
    RV_VKDescriptorSetInfo() = default;
    RV_VKDescriptorSetInfo(int set);
    RV_VKDescriptorSetInfo(
            int set,
            const UT_Array<RV_VKDescriptorBinding>& bindings);

    // Non-const modifiers MUST invalidate hash
    bool mergeDescriptorSet(const RV_VKDescriptorSetInfo &set);
    void addBinding(const RV_VKDescriptorBinding& binding);

    bool isValid() const;

    // Fill Vulkan create info
    void fillCreateInfo(
            VkDescriptorSetLayoutCreateInfo& info,
            UT_Array<VkDescriptorSetLayoutBinding>& bindings) const;

    bool isCompatibleToBind(const RV_VKDescriptorSetInfo& other) const;
    bool isCompatibleToMerge(const RV_VKDescriptorSetInfo& other) const;
    bool isCompatibleToCopy(const RV_VKDescriptorSetInfo& other) const;

    bool compare( const RV_VKDescriptorSetInfo& other,
                  bool allow_missing_bindings,
                  bool allow_different_stages,
                  bool allow_different_names,
                  UT_WorkBuffer* msg) const;

    int  getSetNumber() const { return mySet; }

    exint getLayoutID() const { return myLayoutId; }

    bool hasBinding(uint32_t b_num) const
        {
            return b_num < myBindings.size() && 
                   myBindings(b_num).isValid();
        }
    const UT_Array<RV_VKDescriptorBinding>& getBindings() const { return myBindings; }

    void print() const;
    void printDiff(const RV_VKDescriptorSetInfo& other, const char* label="") const;

    bool operator== (const RV_VKDescriptorSetInfo& other) const
        { return compare(other, false, false, false, nullptr); }

public:
    // Saves hash AND fetches unique ID for layoud from global ID cache
    void                saveHash(RV_Instance* inst);
    bool                isHashValid() const { return myHashValid; }

    SYS_HashType calcHash() const;
    SYS_HashType getHash() const;
private:
    int mySet = -1;
    UT_Array<RV_VKDescriptorBinding> myBindings;
    VkDescriptorSetLayoutCreateFlags myFlags = 0;

    friend class RV_VKDescriptorSet;
    
private:
    bool    myHashValid = false;
    size_t  myHash;
    exint   myLayoutId;
};

inline SYS_HashType hash_value(const RV_VKDescriptorSetInfo& in)
{
    return in.getHash();
}

// -----------------
// RV_VKDescriptorLayout
//
// RAII wrapper for VKDescriptorSetLayout
class RV_API RV_VKDescriptorLayout
{
public:
    VkDescriptorSetLayout getVkDescriptorSetLayout() const
    {
            return myVkDescriptorSetLayout;
    }

    static RV_VKDescriptorLayoutPtr create(
            RV_Instance* inst,
            const RV_VKDescriptorSetInfo* info);

    RV_VKDescriptorLayout(RV_VKDescriptorLayout&& other)
    : myInst(other.myInst)
    , myVkDescriptorSetLayout(other.myVkDescriptorSetLayout)
    {
        other.myVkDescriptorSetLayout = nullptr;
        other.myVkDescriptorSetLayout = VK_NULL_HANDLE;
    }

    RV_VKDescriptorLayout(const RV_VKDescriptorLayout&) = delete;
    RV_VKDescriptorLayout &operator=(const RV_VKDescriptorLayout&) = delete;
    RV_VKDescriptorLayout &operator=(const RV_VKDescriptorLayout&&) = delete;

    ~RV_VKDescriptorLayout();

private:
    struct PassKey {};
public:
    RV_VKDescriptorLayout(
            RV_Instance* inst,
            VkDescriptorSetLayout vk_layout,
            const PassKey&)
        : myInst(inst), myVkDescriptorSetLayout(vk_layout)
    {
    }

private:
    RV_Instance* myInst = nullptr;
    VkDescriptorSetLayout myVkDescriptorSetLayout = VK_NULL_HANDLE;
};

// ------------------------
// RV_VKDescriptorSetUpdates
// 
// Grouped set of updates to apply to a descriptor set
// Doesn't have any knowledge of the DescriptorSetLayout
class RV_API RV_VKDescriptorSetUpdates
{
public:
    bool hasBinding(uint32_t binding, uint32_t element = 0);

    // NOTE: specific descriptor type for buffer are left out
    //       They will be set from the layout when the updates
    //       are committed
    void bindBuffer(
            uint32_t binding,
            uint32_t element,
            VkBuffer vk_buf,
            VkDescriptorType type,
            VkDeviceSize offset = 0,
            VkDeviceSize size = VK_WHOLE_SIZE);

    void bindImage(
            uint32_t binding,
            uint32_t element,
            VkImageView img,
            VkSampler sampler,
            VkImageLayout layout,
            VkDescriptorType type);

    void bindBufferView(
            uint32_t binding,
            uint32_t element,
            VkBufferView buffer_view,
            VkDescriptorType type);
    
    void bindAccelStruct(
            uint32_t binding,
            uint32_t element,
            VkAccelerationStructureKHR accel_struct);

    void copyBinding(
            uint32_t dst_binding,
            uint32_t dst_element,
            uint32_t src_binding,
            uint32_t src_element,
            uint32_t count = 1);

    bool isDirty() const;

    void clear();

    RV_VKDescriptorSetUpdates(const RV_VKDescriptorSetUpdates&) = delete;
    RV_VKDescriptorSetUpdates(RV_VKDescriptorSetUpdates&&) = delete;
    RV_VKDescriptorSetUpdates() = default;
    ~RV_VKDescriptorSetUpdates();
private:
    // Vk Descriptor Set Updaate Descriptions
    UT_Array<VkWriteDescriptorSet>      myWrites;
    UT_Array<VkCopyDescriptorSet>       myCopies;

    // 
    // stored as arrays to ptrs, so the memory locations can't move
    // if the array grows
    UT_Array<UT_UniquePtr<VkDescriptorBufferInfo>>     myBufferWrites;
    UT_Array<UT_UniquePtr<VkDescriptorImageInfo>>      myImageWrites;
    UT_Array<UT_UniquePtr<VkBufferView>>               myBufferViewWrites;
    UT_Array<UT_UniquePtr<VkAccelerationStructureKHR>> myVkAccelStructs;
    UT_Array<UT_UniquePtr<VkWriteDescriptorSetAccelerationStructureKHR>> myAccelStructWrites;

    friend class RV_VKDescriptorSet;
};

// --------------------
// RV_VKDescriptorSet
//
// RAII Wrapper for VkDescriptorSet object
// and also contains RV_VKDescriptorSetInfo used to create it
class RV_API RV_VKDescriptorSet
{
public:
    static UT_UniquePtr<RV_VKDescriptorSet> create(
            RV_Instance* inst,
            class RV_DescriptorAllocator& allocator,
            const RV_VKDescriptorSetInfo& info,
            RV_VKDescriptorSetUpdates& descriptor_writes,
            const RV_VKDescriptorLayout *layout = nullptr,
            const RV_VKDescriptorSet *copy_src = nullptr,
            const char* name = nullptr);

    RV_VKDescriptorSet(
            RV_Instance* inst,
            VkDescriptorSet vk_set,
            const RV_VKDescriptorSetInfo& info,
            UT_UniquePtr<RV_VKDescriptorLayout> layout,
            exint pool_index);

    ~RV_VKDescriptorSet();

    RV_VKDescriptorSet(const RV_VKDescriptorSet&) = delete;
    RV_VKDescriptorSet(RV_VKDescriptorSet&&) = delete;

    VkDescriptorSet  getVkDescriptorSet() { return myVkDescriptorSet; }
    const RV_ResourceID &getID() const { return myId; }
    const RV_VKDescriptorSetInfo* getInfo() const { return  myInfo; };

    bool bindSet(
           RV_Instance* inst,
           RV_VKCommandBuffer* cb,
           const RV_VKPipelineLayout* pipe_layout) const;

private:
    // UpdateSet should only be called once after creation, to simplify.
    // If some descriptors need to be changes, a new set must be allocated
    void updateSet(
            RV_VKDescriptorSetUpdates& set_updates,
            const RV_VKDescriptorSet* copy_src = nullptr);

    RV_Instance* myInst;
    VkDescriptorSet myVkDescriptorSet;
    const RV_VKDescriptorSetInfo* myInfo;
    RV_ResourceID myId;

    exint myPoolIdx;
    exint myLayoutId;

    // NOTE: DON'T directly access, may be NULL if set created
    //       with externally owned layout. Shouldn't need to access,
    //       but `vkUpdateDescriptorSets()` CAN implicity access the
    //       layout used to create dst/src arguments, so we need
    //       to keep it around, instead of destroying immediately,
    //       if it was created just-in-time during our creation
    // TODO: probably just always provide externally
    UT_UniquePtr<RV_VKDescriptorLayout> myOwnedLayout;
};

// --------------------
// RV_VKDescriptorPool
//
// Wrapper for VkDescriptorPool object used to allocate sets
class RV_API RV_VKDescriptorPool
{
public:
    RV_VKDescriptorPool(
            RV_Instance* inst,
            const UT_Array<VkDescriptorPoolSize>& sizes,
            VkDescriptorPool vk_desc_pool)
        : myInst(inst), mySizes(sizes), myVkDescPool(vk_desc_pool)
    {}

    ~RV_VKDescriptorPool();

    VkResult allocateSet(VkDescriptorSetLayout layout, VkDescriptorSet& set);
    VkResult freeSet(VkDescriptorSet set);
    bool     containsSet(VkDescriptorSet set) const;

    static RV_VKDescriptorPoolPtr createPool(
            RV_Instance* inst,
            uint32_t max_sets,
            const UT_Array<VkDescriptorPoolSize>& sizes);

    // create with random size ratios
    static RV_VKDescriptorPoolPtr createPool(
            RV_Instance* inst,
            uint32_t max_sets);
    
    bool myHasSpace = true;
    exint mySetCount = 0;
    exint mySetUpperLimit = 0;
private:
    UT_Lock  myLock;
    VkDescriptorPool myVkDescPool = VK_NULL_HANDLE;
    RV_Instance* myInst = nullptr;
    UT_Array<VkDescriptorPoolSize> mySizes;
    UT_Set<VkDescriptorSet>        mySets;

    friend RV_DescriptorAllocator;
};

// ------------------------
// RV_DescriptorAllocator
// 
// Higher level object to handle descriptor set allocations
// Used by RV_VKDescriptorSet::create to create Sets, and
// allocates more Descriptor Pools as needed
//
// TODO: track owned allocations for cleanup ?
class RV_API RV_DescriptorAllocator
{
public:

    RV_DescriptorAllocator(RV_Instance* inst);

    std::pair<VkDescriptorSet, exint> allocateVkDescriptorSet(
            VkDescriptorSetLayout vk_layout);

    void freeVkDescriptorSet(VkDescriptorSet vk_set, int pool_idx = -1);

    ~RV_DescriptorAllocator();

    RV_DescriptorAllocator() = delete;
    RV_DescriptorAllocator(const RV_DescriptorAllocator &) = delete;
    RV_DescriptorAllocator(RV_DescriptorAllocator &&) = delete;

    exint   getIdForSetLayout(const RV_VKDescriptorSetInfo& info);
    const RV_VKDescriptorSetInfo* getSetLayoutFromId(exint id);

    exint getNumPools() const { return myPools.size(); }

private:
    bool  allocateNewPool();

    RV_Instance* myInst;
    UT_Array<VkDescriptorPoolSize> mySizes;
    uint32_t mySetSize;

    UT_Lock                                     myPoolLock;
    UT_Array<UT_UniquePtr<RV_VKDescriptorPool>> myPools;

    UT_Array<int>                               myPoolsWithSpace;

    // Lock access of `layoutIdCache` and `myNextId` behind `myIdCacheLock`
    // TODO: look into using more general cache class?
    UT_Lock                                        myIdCacheLock2;
    exint                                          myNextId = 1;
    UT_Map<RV_VKDescriptorSetInfo, exint>          myLayoutIdCache;
    UT_Array<UT_UniquePtr<RV_VKDescriptorSetInfo>> mySetLayouts;
};

#endif