RV_VKBuffer.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_Instance.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class to manage Vulkan Buffer object and allocated memory
 */

#ifndef RV_VKBuffer_h
#define RV_VKBuffer_h

#include "RV_API.h"

#include <UT/UT_UniquePtr.h>
#include <UT/UT_Span.h>

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

class RV_Render;
class RV_VKMemory;

// TODO: make into class ?
typedef VkBufferCreateInfo RV_VKBufferCreateInfo;

/// RAII wrapper class for VkBufferView
class RV_API RV_VKBufferView
{
public:
    VkBufferView getVkView() { return myVkView; }
    VkFormat     getVkFormat() const { return myVkFormat; }

    // CAN have null state
    RV_VKBufferView() 
        : myInst(nullptr)
        , myVkView(VK_NULL_HANDLE)
        , myVkFormat(VK_FORMAT_UNDEFINED)
    {}
    RV_VKBufferView(RV_Instance* inst, VkBufferView vk_view, VkFormat vk_format)
        : myInst(inst), myVkView(vk_view), myVkFormat(vk_format)
    {}

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

    // enable move semantics
    RV_VKBufferView(RV_VKBufferView&& other) noexcept
        : myInst(other.myInst)
        , myVkView(other.myVkView)
        , myVkFormat(other.myVkFormat)
    {
        other.myInst = nullptr;
        other.myVkView = VK_NULL_HANDLE;
        other.myVkFormat = VK_FORMAT_UNDEFINED;
    }
    RV_VKBufferView& operator=(RV_VKBufferView&& other) noexcept = delete;

    // Destroy Resource Handle on destruction
    void destroy(RV_Instance* inst);
    ~RV_VKBufferView();

private:
    RV_Instance* myInst = nullptr;
    VkBufferView myVkView = VK_NULL_HANDLE;
    VkFormat myVkFormat = VK_FORMAT_UNDEFINED;
};

/// @brief A vulkan buffer object
class RV_API RV_VKBuffer
{
public:

    /// @brief Allocate a new Buffer object
    /// Allocate a vulkan buffer
    /// `is_staging` - if true, buffer will be CPU visible
    ///
    /// `vk_format`  - if provided, a BufferView is only created --
    ///                only needed for texel buffer usage
    static RV_VKBufferPtr allocate( RV_Instance* inst,
                                  exint size,
                                  VkBufferUsageFlags usage,
                                  bool is_staging,
                                  VkFormat vk_format = VK_FORMAT_UNDEFINED,
                                  const char* name = nullptr,
                                  exint alignment = 0);

    /// @brief Allocate a new Buffer object
    /// Allocate a vulkan buffer
    /// `mem_type`  - Memory type to use
    ///
    /// `vk_format` - if provided, a BufferView is only created --
    ///               only needed for texel buffer usage
    static RV_VKBufferPtr allocate( RV_Instance* inst,
                                    exint size,
                                    VkBufferUsageFlags usage,
                                    RV_MemType mem_type,
                                    VkFormat vk_format = VK_FORMAT_UNDEFINED,
                                    const char* name = nullptr,
                                    exint alignment = 0);

    /// check whether the format and usage can be used together
    static bool queryIsUsable( RV_Instance* inst,
                               VkBufferUsageFlags vk_usage,
                               VkFormat vk_format);

    /// Get the raw vulkan buffer handle
    VkBuffer     getVkBuf() { return myVkBuf; }
    /// Get the create info the buffer was created with
    const RV_VKBufferCreateInfo& getInfo() { return *myCreateInfo; }
    /// Get the memory the buffer is backed by
    RV_VKMemory& getMemory() { return *myMemory; }
    const RV_VKMemory& getMemory() const { return *myMemory; }
    /// Return the memory size this buffer uses, in bytes
    exint gpuMemoryUsage() const; 
    /// Return unique ID for buffer object
    const RV_ResourceID &getID() const { return myId; }
    /// Return label for buffer object
    const UT_StringHolder &getName() const { return myName; }

    /// Allocate owned buffer view for use as texel Buffer. Does nothing
    /// if it is already allocated
    void generateVkView(RV_Instance* inst);

    /// Fetch the buffer view assigned to this buffer, if any
    VkBufferView getVkView() 
    { 
        return myView ? myView->getVkView()
                      : VK_NULL_HANDLE; 
    }
    /// Return the vulkan format of the buffer.
    VkFormat     getVkFormat() const 
    {
        return myView ? myView->getVkFormat()
                      : VK_FORMAT_UNDEFINED; 
    }
    /// Return the size of the buffer, in bytes
    exint               getSize() const { return myCreateInfo->size; }
    /// return the vulkan usage of the buffer when it was created
    VkBufferUsageFlags  getUsage() const { return myCreateInfo->usage; }
    /// return the current usage of this buffer
    VkBufferUsageFlags  getLastUsage() const { return myLastUsage; }

    /// Number of elements in this buffer (eg. RGB 32b is 1 element)
    exint               entries() const;
    /// Return the RV type of the buffer
    RV_GPUType          getGPUType() const;
    /// Return the vector size of the buffer (1-4)
    int                 getVectorSize() const;
    /// Return the device address of the buffer
    VkDeviceAddress     getDeviceAddress() const;

    /// @brief Upload data to the buffer
    /// Upload data to the buffer and add a barrier based on its usage.
    /// Returns true if the size+offset doesn't exceed the allocated size.
    bool uploadData(RV_Render* r,
                    VkBufferUsageFlags new_usage,
                    const void* data,
                    exint data_size,
                    exint data_offset = 0);
    /// @brief Upload data to the buffer
    /// Upload data to the buffer. Returns true if the size+offset doesn't
    /// exceed the allocated size.
    bool uploadData(RV_Render* r,
                    const void* data,
                    exint data_size,
                    exint data_offset = 0);

    /// Span version of buffer upload
    template<typename T, typename std::enable_if<!std::is_pointer<T>::value, int>::type =0>
    bool uploadData(RV_Render* r, const T &data)
            {
                // `T` must be a `UT_Span` or convertable into a `UT_Span`
                auto span = TCB_SPAN_NAMESPACE_NAME::make_span(data);
                return uploadData(r, span.data(), span.size_bytes(), 0);
            }

    template<typename T, typename std::enable_if<!std::is_pointer<T>::value, int>::type =0>
    bool uploadData(RV_Render* r, VkBufferUsageFlags new_usage, const T &data)
            {
                // `T` must be a `UT_Span` or convertable into a `UT_Span`
                auto span = TCB_SPAN_NAMESPACE_NAME::make_span(data);
                return uploadData(r, new_usage, span.data(), span.size_bytes(), 0);
            }

    /// return whether buffer was declared as CPU visible, and mapped
    bool  isMappedMemory() const;

    /// Get a CPU mapped ptr to the raw memory. Will return nullptr
    /// if buffer wasn't declared as CPU visible
    void* getMappedMemory();

    /// Download data from the buffer into `buf`
    bool copyData(RV_Render* r,
                  RV_VKBuffer* dst_buf,
                  exint src_offset = 0,
                  exint dst_offset = 0,
                  exint sublen = -1);

    /// Donwload data from the buffer to `data`. Returns false if the operation
    /// would read data out-of-range or there was an error.
    bool downloadData( RV_Render* r,
                       void* data,
                       exint data_size,
                       exint offset = 0,
                       exint sublen = -1);

    /// Clear the buffer with 0.
    void clear(RV_Render *r);

    /// Add a barrier for using the buffer in the future
    void addBarrier(RV_Render* r, VkBufferUsageFlags new_usage)
            { addBarrier(r, myLastUsage, new_usage); }
    /// Add a barrier for using the buffer in the future, changing its usage
    void addBarrier(RV_Render* r, VkBufferUsageFlags old_usage,
                                  VkBufferUsageFlags new_usage);

    void destroy(RV_Instance* inst);

    virtual ~RV_VKBuffer();

    /// Debug output of the buffer (but not its data).
    void print() const;

private:
    struct PassKey {};
public:
    RV_VKBuffer(RV_Instance* inst,
                const RV_VKBufferCreateInfo* info,
                VkBuffer vk_buf,
                RV_VKMemoryPtr mem,
                RV_VKBufferViewPtr view,
                const PassKey&);
protected:
    RV_Instance* myInst = nullptr;

    VkBuffer myVkBuf = VK_NULL_HANDLE;
    RV_ResourceID myId;
    UT_StringHolder myName;
    UT_UniquePtr<const RV_VKBufferCreateInfo> myCreateInfo;
    
    UT_UniquePtr<RV_VKBufferView> myView;    
    UT_UniquePtr<RV_VKMemory> myMemory;

public:
    VkBufferUsageFlags myLastUsage;
    RV_StageGroup myWaitingBarrierStage = RV_STAGE_NONE;
    exint         myWaitingBarrierGroupID = -1;
};

#endif