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_VKCommandBuffer;
class RV_VKBuffer;
class RV_VKImage;
class RV_VKSampler;

// ~~~~~~~~~~
// 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 char* name = nullptr);
    ~RV_ShaderVariableSet();

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

    /// 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();
    /// The raw Vulkan descritor set create info
    const RV_VKDescriptorSetInfo& getSetInfo() const 
            { return *myLayout.get(); }

    // --------------------------------
    // 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;

    // 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 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);

    /// 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_Instance* inst, RV_VKCommandBuffer* cb);

    // 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
    inline bool isDirty() const;

    // 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_Instance* r,
            RV_VKCommandBuffer* cb,
            const RV_ShaderProgramBase* shader);

    bool bindSet(
            RV_Instance* r,
            RV_VKCommandBuffer* cb,
            const RV_ShaderProgramBase* shader) const;

    /// Pipeline Layout for shader
    UT_UniquePtr<RV_VKDescriptorSetInfo> myLayout;
    UT_StringHolder myName;
    int mySetNumber;
    exint mySetID;
    
    // Uniform Blocks:
    /// Mapping of uniform names, to indices in myUniforms
    UT_ArrayStringMap<int>         myUniformTable;
    UT_Array<const RV_Uniform*>    myUniforms;

    // 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*, exint>               BufferBlockResource;
    typedef std::pair<RV_VKBuffer*, exint>                  BufferResource;
    typedef std::tuple<RV_VKImage*, exint, RV_VKSampler*>   TextureResource;

    UT_Array<BufferBlockResource>   myBufferBlocks;
    UT_Array<BufferResource>        myBufferViews;
    UT_Array<TextureResource>       myTextures;

    enum RV_BindingType
    {
        RV_BINDING_UNKNOWN = 0,
        RV_BINDING_BLOCK,
        RV_BINDING_BUFFER,
        RV_BINDING_IMAGE,
    };

    // 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)
        , myBlock(v)
        {}

        BindingResource(RV_VKBuffer* v)
        : myType(RV_BINDING_BUFFER)
        , myBuffer(v)
        {}

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

        RV_BindingType      myType = RV_BINDING_UNKNOWN;
        RV_ShaderBlock*     myBlock = nullptr;
        RV_VKBuffer*        myBuffer = nullptr;
        RV_VKImage*         myTexture = nullptr;
        RV_VKSampler*       mySampler = 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