RV_Render.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_Render.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to do render work with RV library
 *      Represents the set of resources and render state
 *      for a single frame/thread
 */

#ifndef RV_Render_h
#define RV_Render_h

#include "RV_API.h"

#include <UT/UT_FixedArray.h>
#include <UT/UT_Map.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Set.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_ThreadSpecificValue.h>
#include <UT/UT_UniquePtr.h>
#include <RE/RE_Types.h>
#include <SYS/SYS_Compiler.h>

#include <UT/UT_Function.h>

#include <utility>

#include <VE/VE_VK.h>
#include "RV_Instance.h"
#include "RV_ShaderBlock.h"
#include "RV_Type.h"
#include "RV_VKCommandBuffer.h"
#include "RV_VKDescriptorSet.h"
#include "RV_VKPipeline.h"

class GR_GeoRenderVK;

class RV_Instance;
class RV_Geometry;
class RV_ShaderProgramBase;
class RV_ShaderProgram;
class RV_ShaderCompute;
class RV_ShaderVariableSet;
class RV_OcclusionQuery;

class RV_VKBuffer;
class RV_VKCommandBufferAllocator;
class RV_VKCommandBuffer;
class RV_Framebuffer;
class RV_VKImage;
class RV_VKPipelineStateInfo;

class rv_ThreadedRenders;

struct VkImageMemoryBarrier;
struct VkBufferMemoryBarrier;

typedef std::pair<VkPipelineStageFlags,VkPipelineStageFlags> RV_BarrierScope;

RV_StageGroup RVgetStageGroup(VkPipelineStageFlags stage_bits);

/// Per-thread object for rendering Vulkan objects, which maintains the state
/// and a cache of various Vulkan entities
class RV_API RV_Render
{
public:
    RV_Render(RV_Instance* inst);
    ~RV_Render();

    RV_Render(const RV_Render&) = delete;
    RV_Render(RV_Render&&) = delete;

    /// The instance associated with this render
    RV_Instance* instance() { return myInst; }
    /// The raw vulkan device
    VkDevice     device()   { return myInst->getDevice(); }

    // Current Command buffer
    //  - separate Compute + Transfer + Main CB?
    //          - functions to start command buffer
    //          - functions to flush command buffer
    //          - function to get command buffer
    /// The currently recording command buffer
    RV_VKCommandBuffer* getCurrentCB();

    /// Start rendering a single frame, returns the current nesting level
    /// See `RV_RenderAutoFrame` for RAII wrapper
    int     beginFrame();
    /// End rendering a single frame, takes the nesting level returned from begin
    /// for error checking
    void    endFrame(int frame_depth);
    /// Returns true if currently rendering a frame
    bool    isInFrame() { return myFrameDepth > 0; }

    /// Begin rendering to the current framebuffer. 'img_op' can be LOAD (keep
    /// contents), CLEAR (discard and set to a constant) or DONT_CARE.
    bool    beginRendering(RV_ImageOp img_op = RV_IMAGE_LOAD);
    /// End rendering. 
    void    endRendering();
    /// Query if Vulkan is rendering. Cannot upload buffers or textures while
    /// rendering.
    bool    isRendering();
    
    // --------------------------------
    // Render State
    // helper class to hold the required render state
    // Includes (TODO):
    // - current command buffer
    // - pipeline state (all elements provided in pipeline creation
    // - current bound pipeline
    // - current descriptor sets
    // - current framebuffer + render pass
    // - current vertex state (i.e. which vert buffers bound)
    // - current clear color / clear depth

    /// Reset the cached render state in this object to Vulkan defaults.
    void                    resetRenderState();

    /// Copy render state from another RV_Render
    void                    copyRenderState(RV_Render* other);

    /// Return the current pipeline State
    RV_VKPipelineStateInfo* getPipelineState() { return &pipeState(); }

    // shader state

    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Pipeline State

    // state management

    /// Reset the pipeline state to Vulkan defaults.
    void resetPipeState();
    /// Send the current pipeline state to the GPU.
    void commitPipeState();
    /// Save the existing state so that the state can be modified, then restored
    /// to its previous state with popPipeState()
    void pushPipeState();
    /// Restore the pipeline state from a previous pushPipeState().
    void popPipeState();

    // Poly Raster + Sample State
    /// Set the sample mask for multisample rendering
    void setSampleMask(uint32 mask);
    /// Set the color channel mask
    void setColorMask(bool red, bool green, bool blue, bool alpha);
    /// Set the primitive culling mode, for backface or frontface culling
    void setCullMode(bool enable, bool back_face = true, bool is_ccw = true);
    /// Set the width of line primitives (may not be supported on all platforms)
    void setLineWidth(float width);
    /// Set the polygon draw mode - FILL (normal), LINES (outline),
    /// POINTS (vertices).
    void setPolygonMode(RV_PolygonMode mode);

    // Depth State

    /// Set the depth state for zbuffer operations.
    void setDepthState(
            bool enable,
            RE_ZFunction func = RE_ZLESS,
            bool writing = true,
            float near = 0.0,
            float far = 1.0,
            bool clamp = false);
    /// Set the polygon depth bias to reduce z-fighting for overlapping objects
    void setDepthBias(bool enable, float zconst, float zslope, float clamp = 0.f);

    /// Whether there is a depth bias set
    bool isDepthBiasEnabled() const;

    // If true, depth is reversed (near at 1.0, far at 0.0). Any calls to set
    // depth state will reverse the z function.

    /// Convenience method to map near to 1.0 and far to 0.0 so that the depth
    /// state will be converted to the correct comparisons (LESS -> GREATER)
    void setReverseDepth(bool reverse);
    /// Query if reverse depth mapping is enabled.
    bool isReverseDepth() const { return myIsReverseDepth; }               

    /// return the current near and far plane in NDC space,
    /// based on if reverse Depth is enabled
    int  getNDCNearPlane() const { return isReverseDepth() ? 1.0 : 0.0; }
    int  getNDCFarPlane() const { return isReverseDepth() ? 0.0 : 1.0; }

    // Stencil State

    /// Enable stencil buffer rendering. Framebuffer must have a stencil buffer.
    void setStencilEnable(bool enable);
    /// Define the stencil test
    void setStencilTest(
            RE_SFunction func,
            uint8 ref,
            uint8 compare_mask,
            bool set_back = true);
    /// Define the stencil operation based on the stencil test result. If
    /// 'set_back' is true, also set the same values for backfacing polygons.
    void setStencilOp(
            RE_SOperation stencil_fail,
            RE_SOperation depth_fail,
            RE_SOperation pass,
            uint8 write_mask,
            bool set_back = true);
    /// Define the stencil test for backfacing polygons
    void setStencilBackTest(
            RE_SFunction func, 
            uint8 ref,
            uint8 compare_mask);
    /// Define the stencil operation for backfacing polygons
    void setStencilBackOp(
            RE_SOperation stencil_fail,
            RE_SOperation depth_fail,
            RE_SOperation pass,
            uint8 write_mask);

    // TODO: logic state set

    /// Define the viewport for rendering
    void setViewport2DI(bool enable, const UT_DimRect &rect);

    /// Define the scissor (clip) area
    void setScissor2DI(bool enable, const UT_DimRect &rect);

    /// Enable logic operations instead of color, plus the operation (AND,OR,etc)
    void setLogicOp(bool enable, RV_LogicOp = RV_LOGIC_NO_OP);

    // Blend State
    /// Enable framebuffer blending
    void setBlendEnable(bool blend);
    
    // functions to set color/alpha separately

    /// Set the blending weights for color and alpha
    void setBlendFunction(RE_BlendSourceFactor source_factor,
                          RE_BlendDestFactor dest_factor);
    /// Set the blending weights for color only
    void setColorBlendFunction(RE_BlendSourceFactor source_factor,
                               RE_BlendDestFactor   dest_factor);
    /// Set the blending weights for alpha only
    void setAlphaBlendFunction(RE_BlendSourceFactor source_factor,
                               RE_BlendDestFactor   dest_factor);
    /// Set the blending operator (add, subtract, multiply, etc)
    void setBlendEquation(RE_BlendEquation eq);


    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Command Buffer Binding State 

    struct DrawTask : UT_NonCopyable
    {
        DrawTask() = default;
        virtual ~DrawTask() {};

        virtual bool runDraw(RV_Render* r) = 0;
    };

    struct DrawState
    {
        // Bound sets
        UT_Array<RV_ShaderVariableSet*> mySets;

        // Bound pipeline
        RV_ShaderProgram*               myShader;
        RV_VKPipelineStateInfo          myPipelineState;

        // TODO: convert to use UT_Function object
        UT_UniquePtr<DrawTask>          myTask;
    };

    struct RV_API DefaultDrawTask : public DrawTask
    {
        DefaultDrawTask(RV_Geometry* geo,
            int connect,
            const RV_OverrideList* override_list,
            int inst = -1)
        : myGeo(geo)
        , myConnectGroup(connect)
        , myConnectRange(1)
        , myInstanceGroup(inst)
        , myOverrides(override_list ? *override_list : RV_OverrideList())
        {
        }

        DefaultDrawTask(RV_Geometry* geo,
            int connect,
            int connect_num,
            const RV_OverrideList* override_list,
            int inst = -1)
        : myGeo(geo)
        , myConnectGroup(connect)
        , myConnectRange(connect_num)
        , myInstanceGroup(inst)
        , myOverrides(override_list ? *override_list : RV_OverrideList())
        {
        }

        ~DefaultDrawTask() override {}

        bool runDraw(RV_Render* r) override;

        // Bound Vertex state + Input State
        // plus draw params needed for geo to get vert + idx buffers
        RV_Geometry*                    myGeo;
        int                             myConnectGroup;
        int                             myConnectRange;
        int                             myInstanceGroup;
        RV_OverrideList                 myOverrides;
    };
// WIP: allow recording bind state for deferring draws
#define WIP_VULKAN_DEFER_DRAW
#ifdef WIP_VULKAN_DEFER_DRAW
    UT_Array<DrawState> myRecordedDraws;
    bool myIsDeferring = false;

    bool isDeferringDraws() const { return myIsDeferring; }
    void clearDraws();
    void queueDraw(
            RV_Geometry* geo,
            int connect,
            int connect_num,
            const RV_OverrideList* override_list,
            int inst = -1);
    void queueDraw(UT_UniquePtr<DrawTask> task);
    void runDraws();
#endif

    // call vkCmdBind functions for all bound state
    void refreshBindings();

    // should be called before a draw
    bool prepareForDraw();

    RV_PushConstants& getPushConstants()
            {
#ifdef WIP_VULKAN_DEFER_DRAW
                UT_ASSERT_MSG(!myIsDeferring, "RV_Render::getPushConstants "
                    "Called while in deferred mode, bound values will likely "
                    "be lost");
#endif
                 return myPushConstants;
            }

    const RV_PushConstants &pushConstants() const { return myPushConstants; }

    /// Return the bound variable set at index 'set_num'
    RV_ShaderVariableSet* getSet(int set_num);
    /// Remove a bound variable set by index
    void                  unbindSet(int set_num);
    /// Remove a bound variable set by object
    void                  unbindSet(const RV_ShaderVariableSet* set);
    /// Bind a variable set to the specific shader program
    bool                  bindSet(RV_ShaderVariableSet* set,
                                  const RV_ShaderProgramBase* shr);
    /// Bind a variable set to the current shader program
    bool                  bindSet(const UT_UniquePtr<RV_ShaderVariableSet> &set);
    /// Store the current shader
    void                    pushShader();
    /// Store the current shader and set the new shader to 'sh'
    void                    pushShader(RV_ShaderProgramBase* sh);
    /// Restore the previous shader saved by pushShader()
    void                    popShader();
    /// Set the current shader to 'sh'
    void                    setShader(RV_ShaderProgramBase* sh);
    /// Get the current shader.
    RV_ShaderProgramBase*   getShader();
    /// Get the current graphics shader. If the current shader is compute, return
    /// null.
    RV_ShaderCompute*       getComputeShader();
    /// Get the current compute shader. If the current shader is graphics, return
    /// null.
    RV_ShaderProgram*       getGraphicsShader();

    /// Save the current render framebuffer 
    void                pushDrawFramebuffer();
    /// Save the current render framebuffer and make a new framebuffer active
    void                pushDrawFramebuffer(RV_Framebuffer* fb);
    /// Restore the previously pushed framebuffer from pushDrawFramebuffer().
    void                popDrawFramebuffer();
    /// Make a new framebuffer active
    void                bindDrawFramebuffer(RV_Framebuffer* fb);
    /// Get the current framebuffer (may be null)
    RV_Framebuffer*     getDrawFramebuffer();

    /// Return the currently active occlusion query
    const RV_OcclusionQuery* getQuery() const { return myCurOccludeQuery; }
    /// Make occlusion query 'q' the active query (only 1 can be active at once)
    void                     setQuery(RV_OcclusionQuery* q)
                                { myCurOccludeQuery = q; }

    /// get the number of parallel command buffers within our pool
    int                 getNumCommandBuffers() const;

    // TODO:
    // void bindVertexState();

    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Actions

    /// End the current command buffer and start a new one. Wait until it is
    /// executed if 'wait_for_finish' is true.
    void flush(bool wait_for_finish);

    /// Run the current compute shader with explicit workgroup sizes. Returns
    /// false if there is no compute shader bound.
    bool runCompute(int wg_x, int wg_y, int wg_z);
    /// Run the current compute shader with workgroup sizes stored in the given
    /// buffer. Returns false if there is no compute shader bound.
    bool runComputeIndirect(RV_VKBuffer* buf, exint offset = 0);

    /// Draw the geometry 'geo' with the given connectivity group
    void draw(
            RV_Geometry* geo,
            int connect_index,
            const RV_OverrideList* override_list = nullptr);
    /// Draw the geometry 'geo' with instancing with the given connectivity group
    /// abd given instance group
    void drawInstanced(
            RV_Geometry* geo,
            int connect_index,
            int instance_group,
            const RV_OverrideList* override_list = nullptr);

    /// Draw a range of connectivity groups
    void drawRange(
            RV_Geometry* geo,
            int connect_index,
            int connect_num,
            const RV_OverrideList* override_list = nullptr);

    /// Draw using instancing a range of connectivity groups 
    void drawInstancedRange(
            RV_Geometry* geo,
            int connect_index,
            int connect_num,
            int inst_group,
            const RV_OverrideList* override_list= nullptr);

    /// Render a deferred draw task
    void draw(UT_UniquePtr<DrawTask> task);

    /// Render deferred draw using lambda
    void draw(const UT_Function<bool(RV_Render*)> &task);

    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Thread-local Renders
    
    /// Get desired number of threads to use for parallel rendering
    int            getNumRenderThreads() const;
    /// Call before using `getThreadedRender` and rendering from a new thread
    void           enableThreadedRender();
    /// Associate a unique RV_Render with the current thread and return it
    RV_Render*     getThreadedRender();
    /// Finish rendering with multiple threads, and disassociates all per-thread
    /// RV_Renders from the thread they were used on
    void           endThreadedRender();


    void           dumpBoundState();

    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Sync
#define WIP_VULKAN_DEFER_BARRIERS
#ifdef WIP_VULKAN_DEFER_BARRIERS

    /// Add debug barrier that waits for all previous events
    void addDebugBarrier();

    /// Add a barrier for buffer synchronization
    void addBufferBarrier(
            RV_BarrierScope scope,
            const VkBufferMemoryBarrier& barrier,
            RV_VKBuffer* buf);
    /// Add a barrier for image synchronization
    void addImageBarrier(
            RV_BarrierScope scope,
            const VkImageMemoryBarrier& barrier,
            RV_VKImage* img);

    /// Remove all currently added barriers
    void clearBarriers();
    /// Execute all commands with barriers
    void executeAllBarriers();
    /// Execute all commands on some queues (graphics, compute, transfer).
    void executeBarriers(RV_StageGroup stages);
 
    // called when setting up render for a frame
    void initBarriers();

    struct rv_MemoryBarriers
    {
        RV_BarrierScope       myScope = {VK_PIPELINE_STAGE_NONE,VK_PIPELINE_STAGE_NONE};
        VkMemoryBarrier       myGenBarrier = 
        {
            VK_STRUCTURE_TYPE_MEMORY_BARRIER,
            nullptr,
            VK_ACCESS_NONE,
            VK_ACCESS_NONE,
        };
    };

    // List of barriers waiting to be added to the commandbuffer
    // -- any barrier MUST be added before a command in its DST stage is run
    // inserted by DST RV_STAGE_GROUP
    UT_FixedArray<rv_MemoryBarriers, RV_STAGE_NUM>       myWaitingBarriers;

    // List of barriers that have been added, and were added later than ALL
    // cmds included from their src stage -- inserted by SRC RV_STAGE_GROUP
    UT_FixedArray<RV_BarrierScope, RV_STAGE_NUM>         myActiveBarriers;

    // List of IDs for each batch of barriers that was submitted
    UT_FixedArray<exint, RV_STAGE_NUM>                   myBarrierGroupID = {};

    // counters for debugging
    int myFrameExecBarrierCount = 0;
    int myFrameMemBarrierCount = 0;
#endif

private:
    void privInitCB();
    void privSubmitCB(bool wait_for_finish);

    // Vulkan Instance used to create this render
    RV_Instance* myInst;

    UT_UniquePtr<RV_VKCommandBufferAllocator> myGraphicsCBAlloc;
    RV_VKCommandBuffer* myCurrentCB = nullptr;

    // Pipeline state -- i.e. state that is part of dynamic state 
    //  compiled into graphics pipeline
    UT_Array<RV_VKPipelineStateInfo> myPipeStateStack;
    RV_VKPipelineStateInfo& pipeState();
    const RV_VKPipelineStateInfo& pipeState() const;

    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Binding State 
    static const int theMaxSets = 8;
    UT_Array<RV_ShaderVariableSet*>  myBoundSets;
    UT_Array<bool>                   myDirtySetFlags;

    UT_Array<RV_ShaderProgramBase*> myShaderStack;
    UT_Array<RV_Framebuffer*>       myFramebufferStack;
    RV_OcclusionQuery* myCurOccludeQuery = nullptr;

    RV_PushConstants myPushConstants;

    exint myFrameDepth = 0;
    bool  myIsRendering = false;
    bool  myIsReverseDepth = false;
    
    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    // Multi-Threading
    int                                 myRenderThreads;
    RV_Render*                          myMainRender = nullptr;
    UT_UniquePtr<rv_ThreadedRenders>    myThreadedRenders;
    friend       rv_ThreadedRenders;

    bool isMainRender() const;
};

/// RAII wrapper for RV_Render beginFrame/EndFrame calls
class SYS_NO_DISCARD_RESULT RV_RenderAutoFrame
{
public:
    RV_RenderAutoFrame(RV_Render& r) : myR(r)
    {
        myFrameDepth = myR.beginFrame();
    }
    ~RV_RenderAutoFrame()
    {
        myR.endFrame(myFrameDepth);
    }
private:
    RV_Render& myR;
    int myFrameDepth;
}; 

/// Destroy VK resource after command buffer is executed,
/// when it will no longer be in-use by the GPU
template<class T>
void RVdestroyVKPtr(RV_Render* r, UT_UniquePtr<T> v)
{
    if (v)
        r->getCurrentCB()->addCompletionCallback(
                RVmakeDestroyPtrTask(std::move(v)));
}

#endif