RV_ShaderProgram.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_ShaderProgram.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to handle creating Shaders, a collection of
 *      Vulkan Pipeline Objects
 */

#ifndef RV_ShaderProgram_h
#define RV_ShaderProgram_h

#include <typeinfo>

#include "RV_API.h"

#include <utility>

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Lock.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_Tuple.h>
#include <UT/UT_UniquePtr.h>

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

class RV_Render;
class RV_Geometry;
class RV_Instance;
class RV_ShaderVariableSet;
class RV_VKCommandBuffer;
class RV_VKShader;
class RV_VKShaderModule;

class RV_VKAttributeInfo;
class RV_VKPushConstantInfo;
class RV_VKPipelineLayoutInfo;
class RV_VKPipelineLayout;
struct RV_VKPushConstantRange;

class RV_Uniform;
class RV_VKDescriptorSet;
class RV_VKDescriptorLayout;
class RV_VKDescriptorSetInfo;
class RV_VKDescriptorSetUpdates;
struct RV_VKDescriptorBinding;

// load definition of a UBO from a .blk file
extern RV_API RV_VKDescriptorBinding loadShaderBlock(
        RV_Instance* inst,
        const char* block,
        int set = 0,
        int binding_num = 0);

// Convenience function for loading definitions of shader blocks
// compile a shader with the src code in `code`, and returns the descriptor
// binding at set 0, binding num 0
extern RV_API RV_VKDescriptorBinding loadShaderSnippet(
        RV_Instance* inst,
        const char* code,
        const char* name,
        int set = 0,
        int binding_num = 0);

class RV_API RV_ShaderInput
{
public:
    RV_ShaderInput(const UT_StringHolder &name, int location,
                       RV_GPUType type, int vec_size)
    : myName(name), myLocation(location)
    , myType(type), myVecSize(vec_size)
    {}

    UT_StringHolder   myName;
    int               myLocation;
    RV_GPUType        myType;
    int               myVecSize;
};

class RV_API RV_ShaderInputState
{
public:
    RV_ShaderInputState() 
    : myDefaultAttributes(0)
    {}

    // Bitfield of which attributes match the default definition
    int32                    myDefaultAttributes;

    // Full info for custom attribs
    UT_Array<RV_ShaderInput> myCustomInputs;
    UT_ArrayStringMap<int>   myInputTable;
};

// ~~~~~~~~~~~
// RV_ShaderProgramBase
//
/// class for shared functionality between different types of shaders:
/// mainly accessing the the pipeline layout. Other shader types
/// can build on extra functionality, e.g. input attributes for Graphics
class RV_API RV_ShaderProgramBase
{
public: 
    RV_ShaderProgramBase(RV_Instance* inst, RV_VKPipelineLayoutPtr pipe_layout);
    virtual ~RV_ShaderProgramBase();

    /// Set a descriptive name for the shader
    void setName(const UT_StringHolder &name) { myName = name; }
    /// Descriptive name of the shader
    const UT_StringHolder &name() const { return myName; }

    /// Type of shader - graphics or compute
    virtual RV_ShaderType getShaderType() const = 0;

    /// Get list of the descriptor set layout IDs in this shader, with -1
    /// for indices that don't have a set
    const UT_Array<exint> &layoutIds() const { return mySetLayoutIds; }

    // ------------------------------------
    // Sets

    /// The number of descriptor sets in the shader
    int getMaxSetNumber() const;

    /// Query if set 'set_num' is used by the shader
    bool hasSet(int set_num) const;

    /// Return true if 'set' is compatable with the set layout in this shader.
    bool isSetCompatible(const RV_ShaderVariableSet& set) const;

    /// Query information on set 'set_num'
    const RV_VKDescriptorSetInfo* getSetInfo(int set_num) const;

    /// Create a shader variable set (descriptor set) for set 'set_num'
    UT_UniquePtr<RV_ShaderVariableSet> createSet(RV_Instance* inst, int set_num)
            const;

    // ------------------------------------
    // Full Layout

    /// The layout of all sets and inputs of the shader
    const RV_VKPipelineLayout& getLayout() const { return *myLayout; }

    // ------------------------------------
    // Bindings

    /// Query if a binding named 'name' exists
    bool hasBinding(const UT_StringRef& name) const;
    /// Return a binding at index 'binding' for set index 'set'
    const RV_VKDescriptorBinding* getBinding(int set, int binding) const;
    /// Return a binding for 'name'
    const RV_VKDescriptorBinding* getBinding(const UT_StringRef& name) const;
    /// Return the list of set bindings
    const UT_Array<const RV_VKDescriptorBinding*>& getBindingList() const;

    // ------------------------------------
    // Uniforms

    /// Query if the uniform named 'name' exists
    bool  hasUniform(const UT_StringRef& name) const;
    /// Return type, size, and offset information about the uniform
    const RV_Uniform* getUniform(const UT_StringRef& name) const;
    /// Return a list of all uniforms in this shader
    const UT_Array<const RV_Uniform*>& getUniformList() const;

    // ------------------------------------
    // Push Constants

    /// Query if push constant with 'name' exists
    bool  hasPushConstant(const UT_StringRef& name) const;
    /// Fetch the push constant 'name' with an optional array index
    const RV_Uniform* getPushConstant(const UT_StringRef& name, int* opt_idx) const;
    const UT_Array<RV_VKPushConstantRange>& getPushConstantRanges() const;

    /// Debug print message
    virtual void print() const {};
protected:
    // ~~~~~~~~~~~~~
    // Helper functions to load pipeline layouts

    // Create Shader from prog file, using pre-compiled spir-v if found
    // or compiling if no spir-v found, and sources have been copied to hfs
    // NOTE: providing extra defines forces compilation
    static RV_VKPipelineLayoutPtr loadShaderProgram(
            RV_Instance* inst,
            const char* program,
            const char* extra_defines = nullptr);

    // -------------------------------
    // Attributes
    // info shared between shader program, geometry, descriptor set, pipeline
    UT_Array<RV_ShaderInput>    myInputs;
    // mapping of input name to place in table
    UT_ArrayStringMap<int>      myInputTable;

    // -------------------------------
    // Layout info:   
    // Pipeline Layout for shader
    UT_UniquePtr<const RV_VKPipelineLayout> myLayout;
    UT_SmallArray<exint, 8*sizeof(exint)>   mySetLayoutIds;

    // -------------------------------
    // Uniforms
    UT_Array<const RV_Uniform*>    myUniforms;
    /// Mapping of uniform names, to indices in myUniforms
    UT_ArrayStringMap<int>         myUniformTable;

    // -------------------------------
    // Bindings
    UT_Array<const RV_VKDescriptorBinding*> myBindings;
    /// mapping of binding name to set + binding number
    UT_ArrayStringMap<std::pair<int, int>>  myBindingTable;

    // -------------------------------
    // Push Constants:
    UT_Array<const RV_Uniform*>    myPushConstants;
    UT_ArrayStringMap<int>         myPushConstTable;

    UT_StringHolder myName;

    friend RV_Geometry;
    friend RV_ShaderVariableSet;
};

// ~~~~~~~~~~~
// RV_ShaderProgram
//
// Represents a single shader program that can be bound to the render state
// Holds pipeline layout and collection of cached pipeline objects
//
// Creates pipeline objects just before use, since actually pipeline construction
// requires knowledge of render state.
//
// Must be thread-safe (so the same pipeline can be used in multiple threads)
// 
// Does not store active descriptorsets, but has helper functions to bind them,
// check them, and commit them to the render state
//
// Usually used with an RV_Geometry object to draw geometry

// Shader works with lazy binding. Setting shader writes it to render state
// but no changes made to command buffer state until `commitBinding()` called
//  -- usually called just before usage

// Commit the shader to the Command Buffer. Must:
//  - build final pipeline
//  - commit descriptor set writes
//  - bind shader
//  - bind descriptor sets
//

/// A single graphics shader program that can be bound to the render state
/// Holds pipeline layout and collection of cached pipeline objects
class RV_API RV_ShaderProgram : public RV_ShaderProgramBase
{
public:
    /// Create Shader from prog file, using pre-compiled spir-v if found
    /// or compiling if no spir-v found, and sources have been copied to hfs
    /// NOTE: providing extra defines forces compilation
    static RV_ShaderProgram* loadShaderProgram(
            RV_Instance* inst,
            const char* program,
            const char* extra_defines = nullptr);

    /// Create Shader using GLSL to SPIR-V compiler object
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            RV_VKShader& shader,
            const char* name = nullptr);

    /// Create Shader using list of SPIR-V binary filenames
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            const UT_StringArray& filenames,
            const char* name = nullptr);

    // Create Shader using list of SPIR-V modules
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            UT_Array<RV_VKShaderModuleInfoPtr>& rv_modules,
            const char* name = nullptr);

    // Create shader program directly from pipeline layout object
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            RV_VKPipelineLayoutPtr layout);

    /// Type of the shader, Graphics or Compute
    RV_ShaderType getShaderType() const override
    {
        return RV_SHADER_GRAPHICS;
    };

    ~RV_ShaderProgram() override;


    // TODO: rename: commitRenderState or compileState

    /// Finalize all set bindings in preparation for a draw
    bool prepareForDraw(
            RV_Render* r,
            const RV_VKPipelineStateInfo& pipe_state,
            const RV_VKPipelineInputInfo& pipe_input);

    // ------------------------------------
    // Attributes

    /// Query if a vertex shader input 'name' exists
    bool hasAttribute(const UT_StringRef& name) const;
    /// Query the information about a vertex shader input
    bool getAttribute(const UT_StringRef& name,
                      int&          out_location,
                      RV_GPUType&   out_type,
                      int&          out_vec_size) const;
    /// The list of vertex shader inputs (attributes)
    const UT_Array<RV_ShaderInput>& getAttributeList() const
    {
        return myInputs;
    }

    /// The list and state of vertex shader inputs (attributes)
    const RV_ShaderInputState& getInputState() const
    {
        return myInputState;
    }

    /// Debug Print function; dump all shader variable sets and inputs/outputs
    void print() const override;

private:
            
    RV_ShaderProgram(RV_Instance* inst, RV_VKPipelineLayoutPtr pipe_layout);

    // Cache of pipeline objects already created for this shader
    // and the pipeline state they were created for
    // TODO: hash pipeline state for faster lookup
    typedef UT_Tuple<RV_VKPipelineStateInfo, RV_VKPipelineInputInfo>
            PipelineCreateInfo;

    typedef UT_Array<std::pair<PipelineCreateInfo, UT_UniquePtr<RV_VKPipeline>>>
            PipelineCache;

    RV_VKPipeline* searchCache(
            const PipelineCache &cache,
            const RV_VKPipelineStateInfo& pipe_state,
            const RV_VKPipelineInputInfo& pipe_input);
    
    RV_VKPipeline* addToCache(
            PipelineCache &cache,
            const RV_VKPipelineStateInfo& pipe_state,
            const RV_VKPipelineInputInfo& pipe_input,
            UT_UniquePtr<RV_VKPipeline> new_pipe);

    PipelineCache myMainPipelineCache;
    PipelineCache myThreadedPipelineCache;

    // Lock for accessing pipeline cache accross multiple threads
    UT_Lock myPipelineCacheLock;
    
    // -------------------------------
    // Attributes
    // info shared between shader program, geometry, descriptor set, pipeline
    UT_Array<RV_ShaderInput>    myInputs;
    RV_ShaderInputState         myInputState;
    // mapping of input name to place in table
    UT_ArrayStringMap<int>      myInputTable;


    friend RV_Geometry;
    friend RV_ShaderVariableSet;
};


// ~~~~~~~~~~~
// RV_ShaderCompute
//
/// Compute shader object
class RV_API RV_ShaderCompute : public RV_ShaderProgramBase
{
public:
    // /Create Shader from prog file, using pre-compiled spir-v if found
    /// or compiling if no spir-v found, and sources have been copied to hfs
    /// NOTE: providing extra defines forces compilation
    static RV_ShaderCompute* loadShaderProgram(
            RV_Instance* inst,
            const char* program,
            const char* extra_defines = nullptr);

    /// Create Shader using GLSL to SPIR-V compiler object
    static RV_ShaderCompute* createShaderProgram(
            RV_Instance* inst,
            RV_VKShader& shader);

    /// Create Shader using list of SPIR-V binary filenames
    static RV_ShaderCompute* createShaderProgram(
            RV_Instance* inst,
            const UT_StringArray& filenames);

    /// Create Shader using list of SPIR-V modules
    static RV_ShaderCompute* createShaderProgram(
            RV_Instance* inst,
            UT_Array<RV_VKShaderModuleInfoPtr>& rv_modules);

    // Create shader program directly from pipeline layout object
    static RV_ShaderCompute* createShaderProgram(
        RV_Instance* inst,
        RV_VKPipelineLayoutPtr layout);

    RV_ShaderType getShaderType() const override
                { return RV_SHADER_COMPUTE; };

    ~RV_ShaderCompute() override;

    const UT_Vector3i &getWorkGroupSize() const;

    bool hasWorkGroupSpecializationConst() const;

    bool prepareForDraw(
            RV_Instance* inst,
            RV_VKCommandBuffer* cb);

    // Debug Print function
    void print() const override;

protected:

    RV_ShaderCompute(
            RV_Instance* inst,
            RV_VKPipelineLayoutPtr pipe_layout,
            RV_VKPipelinePtr pipeline);

    UT_UniquePtr<RV_VKPipeline> myPipeline;
};

#endif