RV_ShaderVariableSet.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_ShaderVariableSet.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to handle creating a set of Variables to be bound alongisde a 
 *      shader, i.e. a Descriptor Set
  */

#ifndef RV_ShaderVariableSet_h
#define RV_ShaderVariableSet_h

#include "RV_API.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>

#include <utility>

#include "RV_VKDescriptorSet.h"

class RV_Instance;
class RV_Render;
class RV_ShaderBlock;
class RV_ShaderProgramBase;
class RV_VKBuffer;
class RV_VKImage;
class RV_VKSampler;
class RV_VKAccelerationStructure;

// ~~~~~~~~~~
// RV_ShaderVariableSet
//
// High level class for variable bindings used in shaders (i.e. desciptor sets)
// Stores the layout, the values. 
//
// Mutable and not thread safe

/// A collection of Vulkan UBO, SSBO, and Image shader bindings (descriptor set)
class RV_API RV_ShaderVariableSet
{
public:
    RV_ShaderVariableSet(
            RV_Instance* inst,
            const RV_VKDescriptorSetInfo* layout,
            UT_UniquePtr<RV_VKDescriptorLayout> desc_layout,
            const UT_StringHolder &name = UT_StringHolder());
    ~RV_ShaderVariableSet();

    static UT_UniquePtr<RV_ShaderVariableSet> create(
            RV_Instance* inst,
            const RV_VKDescriptorSetInfo* layout,
            const RV_ShaderVariableSet* opt_base = nullptr,
            const UT_StringHolder &name = UT_StringHolder());

    /// Returns true if binding named 'name' exists
    bool hasBinding(const UT_StringRef& name) const;
    
    /// Returns true if binding exists
    bool hasBinding(uint32_t binding_num) const
            {
              return myBindingResourceIdx.isValidIndex(binding_num) &&
                     myBindingResourceIdx[binding_num] != -1;
            }

    /// The list of bindings
    const UT_Array<RV_VKDescriptorBinding>& getBindings() const;
    /// Return a single binding by index
    const RV_VKDescriptorBinding& getBinding(uint32_t binding_num) const;
    /// Return a single binding by name
    RV_VKDescriptorBinding getBinding(const UT_StringRef& name) const;

    /// The raw Vulkan descriptor set which this set represents.
    VkDescriptorSet getVkDescriptorSet();

    RV_VKDescriptorSet *getRVDescriptorSet()
            { return myDescriptorSet.get(); };

    const RV_ResourceID &getDescriptorSetId() const;

    /// The raw Vulkan descritor set create info
    const RV_VKDescriptorSetInfo& getSetInfo() const 
            { return *myLayout.get(); }

    /// Label for debugging
    const UT_StringHolder &getName() const { return myName; }

    // --------------------------------
    // Bound Resources
    // TODO: make return value ptr, instead of output var?

    /// Fetch a bound UBO or SSBO with the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer object.
    bool getBufferBlock(const UT_StringRef& name, RV_ShaderBlock*& out_block);
    /// Fetch a bound UBO or SSBO with the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer object.
    bool getBufferBlock(const UT_StringRef& name, const RV_ShaderBlock*&) const;
    /// Fetch a bound UBO or SSBO by index  (may be null).
    /// Return false if the binding doesn't exist or isn't a buffer object.
    bool getBufferBlock(int binding_num, RV_ShaderBlock*& out_block);
    /// Fetch a bound UBO or SSBO by index (may be null).
    /// Return false if the binding doesn't exist or isn't a buffer object.
    bool getBufferBlock(int binding_num, const RV_ShaderBlock*& out_block)
            const;

    /// Fetch a bound texture with the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a texture.
    bool getTexture(const UT_StringRef& name, RV_VKImage*& out_image);
    /// Fetch a bound texture with the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a texture.
    bool getTexture(const UT_StringRef& name, const RV_VKImage*&) const;
    /// Fetch a bound texture by index (may be null)
    /// Return false if the binding doesn't exist or isn't a texture.
    bool getTexture(int binding_num, RV_VKImage*& out_image);
    /// Fetch a bound texture by index (may be null)
    /// Return false if the binding doesn't exist or isn't a texture.
    bool getTexture(int binding_num, const RV_VKImage*& out_image) const;

    /// Fetch a bound buffer view (TBO in GL) by the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer view.
    bool getBufferView(const UT_StringRef& name, RV_VKBuffer*& out_buffer);
    /// Fetch a bound buffer view (TBO in GL) by the given name (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer view.
    bool getBufferView(const UT_StringRef& name, const RV_VKBuffer*&) const;
    /// Fetch a bound buffer view (TBO in GL) by index (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer view.
    bool getBufferView(int binding_num, RV_VKBuffer*& out_buffer);
    /// Fetch a bound buffer view (TBO in GL) by index (may be null)
    /// Return false if the binding doesn't exist or isn't a buffer view.
    bool getBufferView(int binding_num, const RV_VKBuffer*& out_buffer) const;

    /// Fetch a bound acceleration structure by the given name (may be null)
    /// Return false if the binding doesn't exist or isn't an acceleration structure.
    bool getAccelStruct(const UT_StringRef& name, RV_VKAccelerationStructure*& out_as);
    /// Fetch a bound acceleration structure by the given name (may be null)
    /// Return false if the binding doesn't exist or isn't an acceleration structure.
    bool getAccelStruct(const UT_StringRef& name, const RV_VKAccelerationStructure*& out_as) const;
    /// Fetch a bound acceleration structure by the given index (may be null)
    /// Return false if the binding doesn't exist or isn't an acceleration structure.
    bool getAccelStruct(int binding_num, RV_VKAccelerationStructure*& out_as);
    /// Fetch a bound acceleration structure by the given index (may be null)
    /// Return false if the binding doesn't exist or isn't an acceleration structure.
    bool getAccelStruct(int binding_num, const RV_VKAccelerationStructure*& out_as) const;

    // Must attach buffers before using to draw
    //   Marks the buffer as used by the Descriptor Set
    //   Will wait until used for a draw to actually update the set

    /// Attach a UBO or SSBO to this variable set. Returns false if the binding
    /// name doesn't exist, the block is null, or it isn't compatible with the
    /// layout of the binding.
    bool attachBufferBlock(
            RV_Instance* inst,
            const UT_StringRef& name,
            RV_ShaderBlock* buffer_block,
            int index = 0);
    /// Attach a UBO or SSBO to this variable set. Returns false if the binding
    /// index doesn't exist, the block is null, or it isn't compatible with the
    /// layout of the binding.
    bool attachBufferBlock(
            RV_Instance* inst,
            int binding_num,
            RV_ShaderBlock* buffer_block,
            int index = 0);

    /// Attach a buffer view (TBO in GL) to this variable set. Returns false if
    /// the binding name doesn't exist, the buffer is null, or it isn't
    /// compatible with the layout of the binding.
    bool attachBufferView(
            RV_Instance* inst,
            const UT_StringRef& name,
            RV_VKBuffer* buffer,
            int index = 0);
    /// Attach a buffer view (TBO in GL) to this variable set. Returns false if
    /// the binding index doesn't exist, the buffer is null, or it isn't
    /// compatible with the layout of the binding.
    bool attachBufferView(
            RV_Instance* inst,
            int binding_num,
            RV_VKBuffer* buffer,
            int index = 0);

    /// Attach a buffer view (TBO in GL) to this variable set. Returns false if
    /// the binding name doesn't exist, the buffer is null, or it isn't
    /// compatible with the layout of the binding.
    bool attachBuffer(
        RV_Instance* inst,
        const UT_StringRef& name,
        RV_VKBuffer* buffer,
        int index = 0);
    /// Attach a buffer view (TBO in GL) to this variable set. Returns false if
    /// the binding index doesn't exist, the buffer is null, or it isn't
    /// compatible with the layout of the binding.
    bool attachBuffer(
            RV_Instance* inst,
            int binding_num,
            RV_VKBuffer* buffer,
            int index = 0);

    /// Attach a texture or image to this variable set. Returns false if
    /// the binding name doesn't exist, the image is null, or it isn't
    /// compatible with the sampler type of the binding.
    bool attachTexture(
            RV_Instance* inst,
            const UT_StringRef& name,
            RV_VKImage* image,
            RV_VKSampler* opt_sampler,
            int index = 0);
    /// Attach a texture or image to this variable set. Returns false if
    /// the binding index doesn't exist, the image is null, or it isn't
    /// compatible with the sampler type of the binding.
    bool attachTexture(
            RV_Instance* inst,
            int binding_num,
            RV_VKImage* image,
            RV_VKSampler* opt_sampler,
            int index = 0);
    /// Attach a texture or image to this variable set. Returns false if
    /// the binding name doesn't exist, the image is null, or it isn't
    /// compatible with the sampler type of the binding.
    bool attachTexture(
            RV_Instance* inst,
            const UT_StringRef& name,
            RV_VKImage* image,
            int index = 0);
    /// Attach a texture or image to this variable set. Returns false if
    /// the binding index doesn't exist, the image is null, or it isn't
    /// compatible with the sampler type of the binding.
    bool attachTexture(
            RV_Instance* inst,
            int binding_num,
            RV_VKImage* image,
            int index = 0);

    /// Attach an acceleration structure to this variable set. Returns
    /// false if the binding name doesn't exist or the acceleration
    /// structure is null
    bool attachAccelStruct(
        RV_Instance* inst,
        const UT_StringRef& name,
        RV_VKAccelerationStructure* accel_struct,
        int index = 0);
    /// Attach an acceleration structure to this variable set. Returns
    /// false if the binding index doesn't exist or the acceleration
    /// structure is null
    bool attachAccelStruct(
        RV_Instance* inst,
        int binding_num,
        RV_VKAccelerationStructure* accel_struct,
        int index = 0);

    /// Clear a bound UBO, SSBO, buffer view, or texture from binding 'name'
    void clearBinding(const UT_StringRef& name);
    void clearBinding(RV_Render* r, const UT_StringRef& name);

    /// Clear a bound UBO, SSBO, buffer view, or texture from the binding index
    void clearBinding(int binding_num);
    void clearBinding(RV_Render* r, int binding_num);

    void clearExtraBindings();

    /// Take any pending bindings and write them to the descriptor set
    void commitBindings(RV_Render* r);

    bool validateBinding(RV_Instance* inst, int binding_num);
    bool validateBinding(RV_Instance* inst, int binding_num) const;
    bool validateBindings(RV_Instance* inst) const;

    void recordBindings(RV_VKCommandBuffer *cb) const;

    // check that all bindings have been assigned
    //  -- also must check that all buffers/images are valid (have memory backing them, have not been deleted)
    //

    /// Return true if all bindings have been assigned to the set
    bool isReady(RV_Instance* inst) const;

    /// Return true if the set has been modified since the last commit
    bool isDirty() const
            {
                UT_ASSERT_P(myIsSetDirty == !myDirtyBindings.isEmpty());
                return myIsSetDirty;
            }

    // Shader Layout info

    /// Return if this variable set is compatible with the given pipeline binding
    /// layout of the shader.
    bool isCompatibleToBind(const RV_VKDescriptorSetInfo& pipe_layout) const
            { return pipe_layout.isCompatibleToBind(*myLayout); }


    /// Return the binding number of the set that this set was created with.
    inline int getSetNumber() const
            { return mySetNumber; }

    /// Return the layout ID of the set that this set was created with.
    inline int getLayoutID() const
            { return mySetID; }

    // -------------------------------------------------------------------
    // DEBUG

    /// Debug dump to stderr all information about the bindings
    void    print() const;

private:
    friend class RV_Render;

    // Returns true if binding exists and has a resource bound to it
    bool isValidBinding(uint32_t binding_num, int index=0) const;

    bool privGetBinding(
            const UT_StringRef& name,
            int& out_binding_num,
            const RV_VKDescriptorBinding*& out_binding) const;

    UT_UniquePtr<RV_VKDescriptorSet> 
         privWriteNewSet(
            RV_Instance* inst,
            const RV_ShaderVariableSet* opt_base);


    // Only called by RV_Render
    bool bindSet(RV_Render* r,
            const RV_ShaderProgramBase* shader);

    bool bindSet(RV_Render* r,
            const RV_ShaderProgramBase* shader) const;

    /// Pipeline Layout for shader
    UT_UniquePtr<RV_VKDescriptorSetInfo> myLayout;
    UT_StringHolder myName;
    int mySetNumber;
    exint mySetID;
    
    // Bindings:
    // Mapping of Binding Names to Binding number in the layout
    UT_ArrayStringMap<int>         myBindingTable;
    UT_Array<int>                  myBindingResourceIdx;

    // lists of resources
    typedef std::pair<RV_ShaderBlock*, RV_ResourceID>       BufferBlockResource;
    typedef std::pair<RV_VKBuffer*, RV_ResourceID>          BufferResource;
    typedef std::tuple<RV_VKImage*, RV_ResourceID, RV_VKSampler*> TextureResource;
    typedef std::pair<RV_VKAccelerationStructure*, RV_ResourceID> AccelStructResource;

    // TODO: combine the resource lists for the 3 buffer types
    UT_Array<BufferBlockResource>         myBufferBlocks;
    UT_Array<BufferResource>              myBufferViews;
    UT_Array<BufferResource>              myBufferArrays;
    UT_Array<TextureResource>             myTextures;
    UT_Array<AccelStructResource>         myAccelStructs;

    enum RV_BindingType
    {
        RV_BINDING_UNKNOWN = 0,
        RV_BINDING_BLOCK_BUFFER,
        RV_BINDING_TEXEL_BUFFER,
        RV_BINDING_SSBO_ARRAY_BUFFER,
        RV_BINDING_IMAGE,
        RV_BINDING_ACCELERATION_STRUCTURE,
    };

    // Simple variant/union-like struct
    struct BindingResource
    {
        BindingResource() {}

        BindingResource(RV_BindingType type,
        RV_ShaderBlock*     block,
        RV_VKBuffer*        buffer,
        RV_VKImage*         texture)
        : myType(type)
        , myBlock(block)
        , myBuffer(buffer)
        , myTexture(texture)
        {}
        
        BindingResource(RV_ShaderBlock* v)
        : myType(RV_BINDING_BLOCK_BUFFER)
        , myBlock(v)
        {}

        // NOTE: will be created by TEXEL_BUFFER or SSBO_ARRAY_BUFFER
        BindingResource(RV_VKBuffer* v)
        : myType(RV_BINDING_TEXEL_BUFFER)
        , myBuffer(v)
        {}

        BindingResource(RV_VKImage* v, RV_VKSampler* s)
        : myType(RV_BINDING_IMAGE)
        , myTexture(v)
        , mySampler(s)
        {}

        BindingResource(RV_VKAccelerationStructure* v)
        : myType(RV_BINDING_ACCELERATION_STRUCTURE)
        , myAccelStruct(v)
        {}

        RV_BindingType              myType = RV_BINDING_UNKNOWN;
        RV_ShaderBlock*             myBlock = nullptr;
        RV_VKBuffer*                myBuffer = nullptr;
        RV_VKImage*                 myTexture = nullptr;
        RV_VKSampler*               mySampler = nullptr;
        RV_VKAccelerationStructure* myAccelStruct = nullptr;
    };

    // Extra Bindings -- Attached to the set by name but not
    // part of the layout, so will not be bound as part of our set
    // keep to copy into other sets if we transfer our resources
    void privAttachExtraResource(const UT_StringHolder& name,
                                 const BindingResource &res);
    UT_StringMap<BindingResource>  myExtraBindings;

    // Descriptor Sets:
    // - DescriptorSets:    Current descriptor sets
    // - PendingUpdates:    Updates to set that will be commited before use

    /// Our current up-to-date VK_DescriptorSet object
    UT_UniquePtr<RV_VKDescriptorSet>    myDescriptorSet;
    UT_UniquePtr<RV_VKDescriptorLayout> myDescriptorLayout;

    /// pending writes for descriptor set
    typedef std::tuple<int, int, RV_BindingType> BindingRef;
    UT_Array<BindingRef>                    myDirtyBindings;
    UT_UniquePtr<RV_VKDescriptorSetUpdates> myPendingUpdates;
    bool myIsSetDirty = false;
};

#endif