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 "RV_VK.h"
#include "RV_Type.h"
#include "RV_VKDescriptorSet.h"
#include "RV_VKPipeline.h"
#include "RV_VKPipelineLayout.h"

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

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

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_VKPipelineLayout* 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;

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

    /// The number of descriptor sets in the shader
    int getMaxSetNumber() const 
    {
        return myLayout->getInfo().myDescriptorSets.size() - 1;
    }
    /// Query if set 'set_num' is used by the shader
    bool hasSet(int set_num) const
    {
        return set_num >= 0 
            && set_num < myLayout->getInfo().myDescriptorSets.size()
            && myLayout->getInfo().myDescriptorSets[set_num].isValid();
    }
    /// 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
    {
        return hasSet(set_num) 
                ? &getLayout().getInfo().myDescriptorSets[set_num]
                : nullptr;
    }
    /// Create a shader varaible 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_VKPipelineLayout* loadShaderProgram(
            RV_Instance* inst,
            const char* program,
            const char* extra_defines = nullptr);

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

    // Create Shader using list of SPIR-V binary filenames
    static RV_VKPipelineLayout* createShaderProgram(
            RV_Instance* inst,
            const UT_StringArray& filenames,
            const char* name = 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;

    // -------------------------------
    // 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 module filenames
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            UT_Array<UT_UniquePtr<RV_VKShaderModule>>& rv_modules,
            const char* name = nullptr);

    /// 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_Instance* inst,
            RV_VKCommandBuffer* cb,
            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:
    static RV_ShaderProgram* createShaderProgram(
            RV_Instance* inst,
            RV_VKPipelineLayout* layout);
            
    RV_ShaderProgram(RV_Instance* inst, RV_VKPipelineLayout* 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;

    UT_Array<std::pair<
            PipelineCreateInfo,
            UT_UniquePtr<RV_VKPipeline>>>
                    myPipelineCache;
    // Lock for accessing pipeline cache accross multiple threads
    // TODO: add "immutable" pipeline-cache for lock-free accesss
    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 module filenames
    static RV_ShaderCompute* createShaderProgram(
            RV_Instance* inst,
            UT_Array<UT_UniquePtr<RV_VKShaderModule>>& rv_modules);

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

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

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

protected:
    static RV_ShaderCompute* createShaderProgram(
        RV_Instance* inst,
        RV_VKPipelineLayout* layout);

    RV_ShaderCompute(
            RV_Instance* inst,
            RV_VKPipelineLayout* pipe_layout,
            RV_VKPipeline* pipeline);

    UT_UniquePtr<RV_VKPipeline> myPipeline;
};

#endif