RV_VKPipeline.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_VKPipeline.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to handle creating Vulkan Pipeline Objects
 */

#ifndef RV_VKPipeline_h
#define RV_VKPipeline_h

#include "RV_API.h"

#include <utility>

#include <UT/UT_Array.h>
#include <UT/UT_Assert.h>
#include <UT/UT_FixedArray.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Set.h>
#include <UT/UT_SmallArray.h>
#include <UT/UT_Span.h>
#include <UT/UT_Tuple.h>

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

class RV_VKCommandBuffer;
class RV_VKImage;
class RV_VKPipelineLayout;
class RV_VKShaderModule;

typedef std::pair<float, float> RV_DepthRange;

inline  VkViewport
RVmakeViewport(
        const UT_DimRect& view_rect,
        RV_DepthRange depth_range = {0.f, 1.f})
{
    return VkViewport{
        (float)view_rect.x(), 
        (float)view_rect.y(),
        (float)view_rect.width(),
        (float)view_rect.height(),
        depth_range.first,
        depth_range.second
    };
}
inline VkRect2D RVmakeVkRect(const UT_DimRect& rect)
{
    return VkRect2D {
        {(int32_t)rect.x(),
        (int32_t)rect.y()},
        {(uint32_t)rect.width(),
        (uint32_t)rect.height()}
    };
}

// PipelineStateInfo tracks the rest of the info needed to create a pipeline object such as:
//      - which proerties are in dynamic state
//      - Final Ouptut formats (e.g. UINT vs FLOAT, and Multisamples)
//      - multiview sate
//      - specialization constants
//      - etc.  
//
// Where possible, will try to keep properties in dynamic state.
// Unlinke OpenGL there are still some Rendering Properties that cannot be set dynamically
//      and must be baked into the pipeline:
//              - Blend Function
//              - Output buffer Format

inline RV_TopologyClass RVgetTopologyClass(VkPrimitiveTopology t)
{
    switch (t) 
    {
        case VK_PRIMITIVE_TOPOLOGY_POINT_LIST :
            return RV_TOPOLOGY_POINT;
        case VK_PRIMITIVE_TOPOLOGY_LINE_LIST:
        case VK_PRIMITIVE_TOPOLOGY_LINE_STRIP:
        case VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY:
        case VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY: 
            return RV_TOPOLOGY_LINE;
        case VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST:
        case VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP:
        case VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN:
        case VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY:
        case VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY:
            return RV_TOPOLOGY_TRIANGLE;
        case VK_PRIMITIVE_TOPOLOGY_PATCH_LIST:
            return RV_TOPOLOGY_PATCH;
        default: break;
    }
    UT_ASSERT(false && "Unrecognized Topology Type used for Pipeline");
    return RV_TOPOLOGY_UNKNOWN;
}

inline bool RVisSameTopologyClass(VkPrimitiveTopology lhs, VkPrimitiveTopology rhs)
{
   return RVgetTopologyClass(lhs) == RVgetTopologyClass(rhs);
}


// Generally you will:
// 1) bind vertex buffers
// 2) bind output targets
// 3) set rendering state (e.g. blend mode)
//
// 4) and 5) will need separate info/object classes
//      e.g.
//      i.e. info that describes the format (needed for creation)
//      

// d) bind pipeline_layout to draw
//     when you go to draw the fully realized pipeline will be found or created

// Output Targets must be specified as:
//      a) Renderpass + subpass
//      b) DynamicRendering info during creation
//      The actual info needed is:
//      - Array of Color Format
//      - Depth/stencil/DepthStencil Format
//      - ResolveAttachment
//      - MultiSampleState

// Using explicit members rather than VkStructs so
// that it's more obvious which parameters are used
//

// Will be used in three places:
//      1) Generated from the current Rendering state
//      2) Storing the current CommandBuffer state
//      3) in the creation/cache of pipeline objects 
//  1 and 2 will usually be in sync, except in cases
//  where the CB state is overwritten (e.g. applying a pipeline
//  with static state, or begining a new CB recording)
//
// the isXXXDynamic flags mean different things in context:
//  1) - It is part of the availible dynamic state. We always
//       try to keep as much state as we can dynamic
//  2) - It has been set as part of the dynamic state in the
//       CB. It may be undefined when the CB begins recording,
//       or if it is clobbered by the static state of a pipeline
//  3) - It is part of the dynamic state of the pipeline, 
//       so value will be ignored during pipeline creation
//
// Push/Set commands in the RenderState will update the current state
// Just before drawing, a pipeline is selected/built from cache using
// Just before drawing, the state in the CB is updated using the current
// render state
// 
class RV_API RV_VKPipelineStateInfo
{
public:
    RV_VKPipelineStateInfo() = default;
        
    RV_VKPipelineStateInfo (const RV_VKPipelineStateInfo&) = default;
    RV_VKPipelineStateInfo& operator=(const RV_VKPipelineStateInfo&) = default;

    // Set all state which can be dynamic, to be dynamic
    // Uses inst to check which Dynamic states are
    // supported
    // Used to initilaize Rendering State
    void initDynamicState(const RV_Instance* inst);

    // Write the state to a commandBuffer
    // TODO: maybe should be a func for the CB instead?
    void updateCBRenderingState(RV_VKCommandBuffer& cb);

    // ~~~~
    // Renderpass State
    // ~~~~
    void setRenderPassInfo(const RV_RenderPassFormatInfo& info)
            {
                myRenderPassInfo = info;
                mySampleCount = info.mySamples;
            }

    void setRenderRegion(const UT_DimRect& region)
            { 
                myViewport = region;
                myScissor = region;
            }

    RV_RenderPassFormatInfo myRenderPassInfo;
    
    // ~~~~
    // Vertex Input State
    // ~~~~

    //  NOTE: the input layout (i.e. the location, names, types) is 
    //        part of the pipeline layout, so the location + names 
    //        here must match those
    // Requires `VK_EXT_vertex_input_dynamic_state` to set dynamically
    //   uses `VK_DYNAMIC_STATE_VERTEX_INPUT_EXT`
    //
    // Can also set JUST the binding stride dynamically 
    //          using `VK_EXT_extended_dynamic_state`
    bool myIsVertexInputDynamic = false;

    // ~~~~ 
    // Input Assembly
    // ~~~~

    // from `VkPipelineInputAssemblyStateCreateInfo`
    bool            myIsTopologyDynamic = false;
    VkPrimitiveTopology myTopologyType = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST;

    bool            myIsPrimRestartDynamic = false;
    bool            myPrimitiveRestartEnable =
#ifndef MBSD
                                                false;
#else // keep enabled on MacOS, doesn't support disabling
                                                true;
#endif

    // from `VkPipelineTesselationStateCreateInfo`
    bool            myHasTesselation    = false;
    bool            myIsControlPointsDynamic = false;
    uint32_t        myTessControlPoints = 4;

    // ~~~~
    // Viewport State
    // ~~~~

    // From `ViewportStateCreateInfo`
    bool            myIsViewportDynamic = false;
    UT_DimRect      myViewport;
    RV_DepthRange   myDepthRange = {0.f ,1.f};

    bool            myIsScissorDynamic = false;
    UT_DimRect      myScissor;

    // ~~~~
    // Rasterization State
    // ~~~~

    // From `VkPipelineRasterizationStateCreateInfo`
    bool            myDepthClamp        = false;
    VkPolygonMode   myPolygonMode       = VK_POLYGON_MODE_FILL;
    
    bool            myIsRasterDiscardDynamic = false;
    bool            myRasterDiscard     = false;

    bool            myIsCullModeDynamic = false;
    VkCullModeFlags myCullMode          = VK_CULL_MODE_NONE;
    
    bool            myIsFrontFaceDynamic= false;
    VkFrontFace     myFrontFace         = VK_FRONT_FACE_COUNTER_CLOCKWISE;

    bool            myIsBiasDynamic     = false;
    bool            myDepthBiasEnable   = false;

    bool            myIsBiasParamDynamic= false;
    float           myBiasConst         = 0.f;
    float           myBiasClamp         = 0.f;
    float           myBiasSlope         = 0.f;

    bool            myIslineWidthDynamic = false;
    float           myLineWidth = 1.f;

    // From VkPipelineMultisampleStateCreateInfo 
    int             mySampleCount = -1;
    uint32          mySampleMask = 0xffffffff;

    // ~~~~
    // Depth Stencil State
    // ~~~~

    // From VkPipelineDepthStencilStateCreateInfo
    bool            myIsDepthTestDynamic = false;
    bool            myDepthTest = true;

    bool            myIsDepthWriteDynamic = false;
    bool            myDepthWrite = true;

    bool            myIsDepthOpDynamic = false;
    VkCompareOp     myDepthOp = VK_COMPARE_OP_LESS;

    bool            myIsDepthBoundsEnableDynamic = false;
    bool            myDepthBoundsTest = false;

    bool            myIsDepthBoundsDynamic = false;
    float           myMinDepth = 0.f;
    float           myMaxDepth = 1.f;

    bool            myIsStencilTestDynamic = false;
    bool            myStencilTest = false;

    bool            myIsStencilOpDynamic = false;
    bool            myIsStencilWriteMaskDynamic = false;
    bool            myIsStencilCompMaskDynamic = false;
    bool            myIsStencilRefDynamic = false;

    VkStencilOpState myStencilOpFront =
    {
        VK_STENCIL_OP_KEEP,     /* failOp */
        VK_STENCIL_OP_KEEP,     /* passOp */
        VK_STENCIL_OP_KEEP,     /* depthFailOp */
        VK_COMPARE_OP_ALWAYS,   /* compareOp */
        0xffffffff,             /* compareMask */
        0xffffffff,             /* writeMask */
        0                       /* reference */
    };
    VkStencilOpState myStencilOpBack =
    {
        VK_STENCIL_OP_KEEP,     /* failOp */
        VK_STENCIL_OP_KEEP,     /* passOp */
        VK_STENCIL_OP_KEEP,     /* depthFailOp */
        VK_COMPARE_OP_ALWAYS,   /* compareOp */
        0xffffffff,             /* compareMask */
        0xffffffff,             /* writeMask */
        0                       /* reference */
    };

    // ~~~~
    // Blend State
    // ~~~~
    // From VkPipelineColorBlendStateCreateInfo 
    bool myLogicOpEnable = false;
    VkLogicOp myLogicOp = VK_LOGIC_OP_NO_OP;

    VkPipelineColorBlendAttachmentState myBlendInfo = {
        VK_FALSE,                   /* blendEnable */
        VK_BLEND_FACTOR_ONE,        /* srcColorBlendFactor */
        VK_BLEND_FACTOR_ZERO,       /* dstColorBlendFactor */
        VK_BLEND_OP_ADD,            /* colorBlendOp */
        VK_BLEND_FACTOR_ONE,        /* srcAlphaBlendFactor */
        VK_BLEND_FACTOR_ZERO,       /* dstAlphaBlendFactor */
        VK_BLEND_OP_ADD,            /* alphaBlendOp */
        VK_COLOR_COMPONENT_R_BIT |
        VK_COLOR_COMPONENT_G_BIT |
        VK_COLOR_COMPONENT_B_BIT |
        VK_COLOR_COMPONENT_A_BIT ,  /* colorWriteMask */
    };

    bool myIsBlendConstDynamic = false;
    float myBlendConst[4] = {0.f, 0.f, 0.f, 0.f};

    // ~~~~~~
    // Operators
    // ~~~~~~

    friend bool operator==(
            const RV_VKPipelineStateInfo& lhs,
            const RV_VKPipelineStateInfo& rhs);

    ~RV_VKPipelineStateInfo();
};

struct RV_VKPipelineInputInfo
{
    RV_VKPipelineInputInfo()
    {
        myInputBindings.setCapacity(16);
        myInputAttributes.setCapacity(16);
    }

    UT_Array<VkVertexInputBindingDescription>   myInputBindings;
    UT_Array<VkVertexInputAttributeDescription> myInputAttributes;

    // equivalent to glAttribPointer()
    /// Add Info for Attribute from Vertex Array
    /// location is the ID of the attribute set/queried from the shader
    /// Binding is the binding point of the array to pull data from
    //  Equivalent to
    void resetInputState()
    {
        myInputAttributes.clear();
        myInputBindings.clear();
    }
    void addVertexAttribute(
            uint32_t location,
            uint32_t binding,
            VkFormat format,
            uint32_t offset)
    {
        myInputAttributes.forcedRef(location)
                = VkVertexInputAttributeDescription
                        {location, binding, format, offset};
    }
    //
    // Adding a new binding is equivalent to using a new array with `glBindVertexArray`
    void addVertexBinding(
            uint32_t binding,
            uint32_t stride,
            VkVertexInputRate input_rate = VK_VERTEX_INPUT_RATE_VERTEX)
    {
        myInputBindings.forcedRef(binding)
            = VkVertexInputBindingDescription
                    { binding, stride, input_rate};
    }

    void getInputBindings(
            UT_Array<VkVertexInputBindingDescription>& final_bindings) const
    {
        // trim bindings to only used ones
        UT_Set<uint32_t> used_bindings;
        for (const auto &attr : myInputAttributes)
        {
            if (attr.format != VK_FORMAT_UNDEFINED)
                used_bindings.insert(attr.binding);
        }
        final_bindings.setCapacity(used_bindings.size());
        final_bindings.setSize(0);
        for (uint32_t binding : used_bindings)
        {
            final_bindings.append(myInputBindings[binding]);
        }
    }

    void getInputAttributes(
            UT_Array<VkVertexInputAttributeDescription>& final_attributes) const
    {
        // trim attributes to valid ones
        final_attributes = myInputAttributes;
        final_attributes.removeIf([](const VkVertexInputAttributeDescription& attr)
        {
            return attr.format == VK_FORMAT_UNDEFINED;
        });
    }

    friend bool operator==(
            const RV_VKPipelineInputInfo& lhs,
            const RV_VKPipelineInputInfo& rhs);

};

// ----------------
// RV_VKPipeline
//
/// RAII wrapper class for VkPipeline
//
// Doesn't contain the create info used to make the pipeline,
// instead an owning class  (e.g. RV_ShaderProgram) will keep that
class RV_VKPipeline
{
public:
    VkPipeline getVkPipeline() { return myVkPipeline; }

    static RV_VKPipelinePtr create(
                RV_Instance* inst,
                const RV_VKPipelineLayout& layout_info,
                const RV_VKPipelineStateInfo& state_info,
                const RV_VKPipelineInputInfo& input_info);

    static RV_VKPipelinePtr createCompute(
        RV_Instance* inst,
        const RV_VKPipelineLayout& layout);

    // CAN have null state
    RV_VKPipeline() 
        : myInst(nullptr), myVkPipeline(VK_NULL_HANDLE)
    {}
    RV_VKPipeline(RV_Instance* inst, VkPipeline vk_pipeline)
        : myInst(inst), myVkPipeline(vk_pipeline)
    {}

    // disable copy semantics
    RV_VKPipeline(const RV_VKPipeline&) = delete;
    RV_VKPipeline& operator=(RV_VKPipeline& ) = delete; 

    // enable move semantics
    RV_VKPipeline(RV_VKPipeline&& other) noexcept
        : myInst(other.myInst), myVkPipeline(other.myVkPipeline)
    {
        other.myInst = nullptr;
        other.myVkPipeline = VK_NULL_HANDLE;
    }

    // Destroy Resource Handle on destruction
    ~RV_VKPipeline()
    {
        if (myVkPipeline != VK_NULL_HANDLE)
        {
            VkDevice vk_dev = myInst->getDevice();
            ::vkDestroyPipeline(vk_dev, myVkPipeline, nullptr);
        }
    }

private:
    RV_Instance* myInst = nullptr;
    VkPipeline myVkPipeline = VK_NULL_HANDLE;
};

RV_API
void RVloadSpirvFiles(
        RV_Instance* inst,
        const UT_StringArray& filenames,
        UT_Array<RV_VKShaderModuleInfoPtr> &shader_modules);

RV_API
void RVloadSpirvFiles(
        RV_Instance* inst,
        const char* filenames,
        UT_Array<RV_VKShaderModuleInfoPtr> &shader_modules);

#endif