RV_VKImage.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_VKImage.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Class for creating Vulkan Image object
 *      Includes Vulkan Handle and memory allocation bound to it
 */
#ifndef RV_VKImage_h
#define RV_VKImage_h

#include "RV_API.h"
#include "RV_Instance.h"
#include "RV_Render.h"
#include "RV_Type.h"
#include "RV_TypePtrs.h"

#include <VE/VE_Result.h>
#include <VE/VE_VK.h>

#include <UT/UT_Assert.h>
#include <UT/UT_Swap.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Handle.h>
#include <SYS/SYS_Math.h>
#include <SYS/SYS_Types.h>

#include <limits>

class RV_Instance;
class RV_Render;
class RV_VKCommandBuffer;
class RV_VKImage;
class RV_VKMemAllocInfo;
class RV_VKQueue;
class RV_VKMemory;

#define RV_MAX_MIP_LEVEL (std::numeric_limits<int>::max())

/// Class for Setting up Image Info
///     Should be trivially copiable, 
///     so it can be duplicated or passed around
/// Once a VkImage is created, it is immutable
///     so changing a parameter means creating
///     a new image
class RV_API RV_VKImageCreateInfo
{
public:
    // set Vulkan Image Creation parameters

    /// Define if the image is 1D, 2D, or 3D
    void setImageType(RV_ImageDim img_type);
    /// The Vulkan image type
    VkImageType getImageType() const { return myVkCreateInfo.imageType; }
    /// The RV image type
    RV_ImageDim getRVImageType() const { return myRVImageType; }

    // TODO: use similar abstraction to RE_Texture ..
    //          setFormatType (i.e. Depth, vs. Color vs Stencil)
    //          setFormatDataType (int vs signed int vs float vs ...)
    //          setFormatVecSize (1, 2, 3, 4)
    /// Set the vulkan image format. RV
    void     setFormat(VkFormat format) { myVkCreateInfo.format = format; }
    VkFormat getFormat() const { return myVkCreateInfo.format; } 

    /// Returns a vulkan subresource object for the full image
    VkImageSubresourceRange getFullSubRes() const;

    /// Defines the size of the image (width, height, depth). 1D and 2D images
    /// ignore some of the sizes.
    void setSize(int w, int h, int d)
    {
        UT_ASSERT(w >= 1);
        UT_ASSERT(h >= 1);
        UT_ASSERT(d >= 1);

        myVkCreateInfo.extent.width = w;
        myVkCreateInfo.extent.height = h;
        myVkCreateInfo.extent.depth = d;
    }
    int getWidth() const 
        { return myVkCreateInfo.extent.width; }
    int getHeight() const 
        { return myVkCreateInfo.extent.height; }
    int getDepth() const 
        { return myVkCreateInfo.extent.depth; }

    /// Define the number of samples in a multisampled 2D image.
    void setSamples(int samples)
        { 
            UT_ASSERT(samples >= 1);
            mySamples = samples;
        }
    int getSamples() const 
        { return mySamples; }

    /// Define the number of layers in a 1D or 2D array.
    void setLayerCount(int count )
        {   
            UT_ASSERT(count >= 1);
            myVkCreateInfo.arrayLayers = count;
        }
    int getLayerCount() const
        { return myVkCreateInfo.arrayLayers; }

    /// Set the maximum number of mipmap levels.
    void setMaxLevelCount(int count)
        {
            UT_ASSERT( count >= 1);
            myMaxLevels = SYSmax(count, 1);
        }
    int getMaxLevelCount() const
        { return myMaxLevels; }

    int getLevelCount() const 
        {
            exint max_dim = SYSmax(SYSmax(getWidth(), getHeight()), getDepth());
            int max_level = SYSfloorLog2(max_dim) + 1;
            return SYSmin(max_level, getMaxLevelCount());
        }

    /// Set the texture filter for texture scales above 1.
    void setTextureMagFilter(RV_TextureFilter filter)
        { myMagFilterMode = filter; }
    /// Set the texture filter for texture scales below 1.
    void setTextureMinFilter(RV_TextureFilter filter)
        { myMinFilterMode = filter; }
    /// Set the mipmapping mode - DISABLED, NEAREST mipmap, or LINEAR blend
    void setTextureMipMode(RV_TextureMipMode mode)
        { myMipMode = mode; }

    /// Set the wrapping mode when uv is outside [0,1]:REPEAT,CLAMP,BORDER,MIRROR
    void setTextureWrap(RV_TextureWrap u, RV_TextureWrap v, RV_TextureWrap w)
        { myWrapU = u; myWrapV = v; myWrapW = w; }
    
    RV_TextureWrap getTextureWrapU() const
        { return myWrapU; }
    RV_TextureWrap getTextureWrapV() const
        { return myWrapV; }
    RV_TextureWrap getTextureWrapW() const
        { return myWrapW; }

    /// Set the texture swizzle for each component, when sampled in a shader
    /// Cannot be combined with storage images or framebuffer attachment images
    void setTextureSwizzle(RV_TextureSwizzle r,
                           RV_TextureSwizzle g,
                           RV_TextureSwizzle b,
                           RV_TextureSwizzle a)
        {
            myTextureSwizzle[0] = r;
            myTextureSwizzle[1] = g;
            myTextureSwizzle[2] = b;
            myTextureSwizzle[3] = a;
        }

    RV_TextureSwizzle getTextureSwizzleR() const
        { return myTextureSwizzle[0]; }
    RV_TextureSwizzle getTextureSwizzleG() const
        { return myTextureSwizzle[1]; }
    RV_TextureSwizzle getTextureSwizzleB() const
        { return myTextureSwizzle[2]; }
    RV_TextureSwizzle getTextureSwizzleA() const
        { return myTextureSwizzle[3]; }

    void setUsageAttachmentBit(bool b)
        { myUsageAttachmentBit = b; }
    bool getUsageAttachmentBit() const
        { return myUsageAttachmentBit; }

    void setUsageSampledBit(bool b)
        { myUsageSampledBit = b; }
    bool getUsageSampledBit() const
        { return myUsageSampledBit; }

    void setUsageStorageBit(bool b)
        { myUsageStorageBit = b; }
    bool getUsageStorageBit() const
        { return myUsageStorageBit; }

    /// Use linear tiling (true) or optimal tiling. Not all types support linear.
    void setUseLinearTiling(bool use)
        { myUseLinearTiling = use; }
    bool getUseLinearTiling() const
        { return myUseLinearTiling; }

    void setMemoryType(RV_MemType type)
        { myMemType = type; }
    RV_MemType getMemoryType() const
        { return myMemType; }
        
    void setCompareEnable(bool compare_enable)
        { myCompareEnable = compare_enable; }
    bool getCompareEnable() const
        { return myCompareEnable; }

    void setCompareOp(RE_ZFunction compare_op)
        { myCompareOp = compare_op; }
    RE_ZFunction getCompareOp() const
        { return myCompareOp; }

    /// Access the vulkan creation structure for this image.
    const VkImageCreateInfo* getVkInfo() const
        { return &myVkCreateInfo; }

    /// Finalize Create Info struct before being passed to
    /// Vulkan API, and perform any final checks. 
    /// To Be called by Vulkan Image allocate function.
    /// Returns false if any checks fail
    virtual bool fillCreateInfo();

    // Constructors
    RV_VKImageCreateInfo() = default;
    virtual UT_UniquePtr<RV_VKImageCreateInfo> clone() const
    {
        return UT_UniquePtr<RV_VKImageCreateInfo>(
                    new RV_VKImageCreateInfo(*this));
    }

    virtual ~RV_VKImageCreateInfo();

protected:
    RV_VKImageCreateInfo(const RV_VKImageCreateInfo&) = default;
    RV_VKImageCreateInfo &operator=(const RV_VKImageCreateInfo&) = delete;

    bool isValidForLinearTiling() const;

    /// Extend Image Create Info struct. 
    /// Used by subclasses to create different
    /// types of images
    void addNext(VkBaseOutStructure* p)
    {
        UT_ASSERT(p);
        p->pNext = (VkBaseOutStructure*)myVkCreateInfo.pNext;
        myVkCreateInfo.pNext = p;
    }

     /// Setup allocation info for memory
    virtual RV_MemType getAllocType(RV_Instance* inst);

    // ~~~~ Data Members ~~~~
    // Image format
    uint32_t mySamples = 0;
    int      myMaxLevels = 1;

    bool myUseLinearTiling = false;
    RV_MemType  myMemType = RV_MEM_AUTO;
    RV_ImageDim myRVImageType = RV_IMAGE_2D;
    RV_TextureSwizzle myTextureSwizzle[4] =
        {
            RV_SWIZZLE_IDENTITY,
            RV_SWIZZLE_IDENTITY,
            RV_SWIZZLE_IDENTITY,
            RV_SWIZZLE_IDENTITY
        };

    // Sampler Info 
    fpreal32            myMinLOD = 0.0;
    fpreal32            myMaxLOD = VK_LOD_CLAMP_NONE;
    bool                myIsNormalized = false;
    bool                myIsTexelSampled = false;
    bool                myUsageAttachmentBit = true;
    bool                myUsageSampledBit = true;
    bool                myUsageStorageBit = false;
    bool                myCompareEnable = false;
    RE_ZFunction        myCompareOp = RE_ZALWAYS;
    RV_TextureFilter    myMagFilterMode = RV_FILTER_LINEAR;
    RV_TextureFilter    myMinFilterMode = RV_FILTER_LINEAR;
    RV_TextureMipMode   myMipMode = RV_MIPMAP_LINEAR;
    RV_TextureWrap      myWrapU = RV_TEX_WRAP_REPEAT;
    RV_TextureWrap      myWrapV = RV_TEX_WRAP_REPEAT;
    RV_TextureWrap      myWrapW = RV_TEX_WRAP_REPEAT;
    UT_Vector4F         myBorderColor = {0.f, 0.f, 0.f, 0.f};

    // Vk Image Creation Info struct
    VkImageCreateInfo myVkCreateInfo = {
        VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO,
        nullptr,
        0,                      /* flags */
        VK_IMAGE_TYPE_2D,       /* imageType */
        VK_FORMAT_UNDEFINED,    /* format */
        {0, 0, 0},              /* extent */
        1,                      /* mipLevels */
        1,                      /* arrayLayers */
        VK_SAMPLE_COUNT_1_BIT,  /* samples */
        VK_IMAGE_TILING_OPTIMAL,/* tiling */
        0,                      /* usage */
        VK_SHARING_MODE_EXCLUSIVE,  /* sharingMode */
        0,                      /* queueFamilyIndexCount */
        nullptr,                /* pQueueFamilyIndices */
        VK_IMAGE_LAYOUT_UNDEFINED,  /* initialLayout */
        };
    
    friend class RV_VKImage;
};

/// RAII wrapper class for VkImageView
class RV_VKImageView
{
public:
    /// Access the vulkan resource for the view
    VkImageView getVkView() { return myVkView; }

    // CAN have null state
    RV_VKImageView() 
        : myInst(nullptr), myVkView(VK_NULL_HANDLE)
    {}
    RV_VKImageView(RV_Instance* inst, VkImageView vk_view)
        : myInst(inst), myVkView(vk_view)
    {}

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

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

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

private:
    RV_Instance* myInst = nullptr;
    VkImageView myVkView = VK_NULL_HANDLE;
};

// RAII wrapper for sampler
class RV_VKSampler
{
public:
    /// Access the vulkan resource for the sampler
    VkSampler getVkSampler() { return myVkSampler; }

    // CAN have null state
    RV_VKSampler() 
        : myInst(nullptr), myVkSampler(VK_NULL_HANDLE)
    {}
    RV_VKSampler(RV_Instance* inst, VkSampler vk_sampler)
        : myInst(inst), myVkSampler(vk_sampler)
    {}

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

    // enable move semantics
    RV_VKSampler(RV_VKSampler&& other) noexcept
        : myInst(other.myInst), myVkSampler(other.myVkSampler)
    {
        other.myInst = nullptr;
        other.myVkSampler = VK_NULL_HANDLE;
    }
    RV_VKSampler& operator=(RV_VKSampler&& other) noexcept = delete;
    // Destroy Resource Handle on destruction
    ~RV_VKSampler()
    {
        if (myVkSampler != VK_NULL_HANDLE)
        {
            VkDevice vk_dev = myInst->getDevice();
            ::vkDestroySampler(vk_dev, myVkSampler, nullptr);
        }
    }

private:
    RV_Instance* myInst = nullptr;
    VkSampler myVkSampler = VK_NULL_HANDLE;
};

/// Class hodling VkImage handle and bound Memory allocation
/// cleans up resources on destruction 
class RV_API RV_VKImage
{
public:
    /// Creates new Image based on create info
    static RV_VKImagePtr allocateImage(
            RV_Instance* inst,
            RV_VKImageCreateInfo* info,
            const char* name = nullptr);

    /// Creates an image from an already existing VkImage, and
    /// takes ownership of the VkImage but not the memory object
    static RV_VKImagePtr createFromImage(
        RV_Instance* inst,
        VkImage vk_image,
        const VkImageCreateInfo* info,
        const char* name = nullptr
    );

    /// Allocate a new Image Sampler using parameters from img_info,
    /// ignoring non-sampler parameters
    static UT_UniquePtr<RV_VKSampler> allocateSampler(
            RV_Instance* inst,
            const RV_VKImageCreateInfo* img_info);

    /// check whether the format info in pInfo can create
    /// a valid Vulkan image
    static bool queryIsUsable(
            RV_Instance* inst,
            RV_VKImageCreateInfo* info);

    /// The image properties
    const RV_VKImageCreateInfo& getInfo() const { return *myCreateInfo; }

    // Getters for image members
    VkImage         getVkImage() { return myVkImg; }
    RV_VKMemory&    getMemory() { return *myMemory; }
    RV_VKSampler*   getSampler() { return mySampler.get(); }
    VkImageLayout   getLayout() const { return myLastLayout; }
    const RV_ResourceID &getID() const { return myId; }
    const UT_StringHolder &getName() const { return myName; }

    /// On linux, the returned handle is owned by the caller. The caller can
    /// either use it to import the texture into another API; or they must close
    /// it when they're done with it. On windows, the returned handle can only
    /// be used to import the texture into another API--the caller must never
    /// close it themself!
    /// See documentation for VE_Memory::getExternalHandle() for more
    /// information.
    VE_Result<SYS_Handle> getExternalHandle();

    RV_VKImageView& getFullView() { return *myView; }
    RV_VKImageView& getPrimaryView()
                            { return myPrimaryView ? *myPrimaryView :*myView;}

    // Functions to create Image View for image
    /// Create new VkImageView for whole VkImage range
    RV_VKImageView createView();
    /// Create new VkImageView for specific VkImage subresource range
    RV_VKImageView createView(const VkImageSubresourceRange &subres);
    /// Create new VkImageView for specific VkImage subresource range, with type
    RV_VKImageView createView(const VkImageSubresourceRange &subres, VkImageViewType type);
    /// Create new VkImageView for specific type, trying to use full subresource range
    RV_VKImageView createView(VkImageViewType type);

    /// Record a command to transition image into new layout
    void transitionImage(
            RV_VKCommandBuffer* cb,
            VkImageLayout new_layout,
            VkImageUsageFlags new_usage, // TODO: new struct to encapsulate access, stage, usage
                                        // want to be able to specify extra params 
                                        // (e.g. read vs write access, and specific pipeline shader stage)
                                        // without cluttering the function signature
            bool keep_data = true,
            VkImageSubresourceRange subres = VkImageSubresourceRange{});

    /// Record a command to transition the image for sampling in a shader
    void transitionToSampling(RV_VKCommandBuffer *cb, bool force = false)
        {
            if (force || myLastLayout != VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL)
                transitionImage(cb, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
                            VK_IMAGE_USAGE_SAMPLED_BIT);
        }

    /// Upload data to the image. Must be in a state for upload.
    template<typename T, typename std::enable_if<!std::is_pointer<T>::value, int>::type =0>
    bool uploadData(RV_Render* r, const T &data, int level = 0, int index = 0)
            {
                // `T` must be a `UT_Span` or convertable into a `UT_Span`
                auto span = TCB_SPAN_NAMESPACE_NAME::make_span(data);
                return uploadData(
                    r->instance(), r->getCurrentCB(),
                    span.data(), span.size_bytes(),
                    level, index);
            }

    bool uploadData(
            RV_Render* r,
            const void* data,
            exint data_size,
            int level = 0, 
            int index = 0);

    bool uploadData(
            RV_Instance* inst,
            RV_VKCommandBuffer* cb,
            const void* data,
            exint data_size,
            int level = 0, 
            int index = 0);

    /// Copy image data to this image from `buffer`.
    bool uploadData(RV_Render* r,
            RV_VKBuffer* buf,
            int level = 0, 
            int index = 0,
            exint buf_offset = 0,
            exint buf_size = -1);

    bool uploadData(
            RV_Instance* inst,
            RV_VKCommandBuffer* cb,
            RV_VKBuffer* buf,
            int level = 0, 
            int index = 0,
            exint buf_offset = 0,
            exint buf_size = -1);

    // TODO: add options for level, layer, separate aspects, offsets
    /// Copy image data from `other` into this image.
    /// images MUST have same size and format
    bool copyData(RV_Render* r, RV_VKImage* other);

    /// Resolves image data from Multisample `other` into this image.
    /// images MUST have same size and format, and MUST be color images,
    /// and this MUST be a single-sample image
    bool resolveData(RV_Render* r, RV_VKImage* other);

    /// Generate higher mipmap levels from the base level
    void generateMipmaps(RV_Render* r);

    /// Download image data into `data`. 
    bool downloadData(
        RV_Render* r,
        void* data,
        exint data_size,
        int level = 0, 
        int index = 0,
        bool primary_aspect = true);

    /// Download image data into `buf`. 
    bool downloadData(
        RV_Render* r,
        RV_VKBuffer* buf,
        int level = 0, 
        int index = 0,
        bool primary_aspect = true);

#ifdef VULKAN_PRESENTATION
    bool isSwapchainImage() const
        { return myIsSwapchainImage; }
    void setIsSwapchainImage(bool is_swapchain_img)
        { myIsSwapchainImage = is_swapchain_img; }
#endif
    
    virtual ~RV_VKImage();

    /// Debug print out of image properties (not image data).
    void print() const;

protected:
    RV_VKImage(
            RV_Instance* inst,
            const RV_VKImageCreateInfo* img_info,
            VkImage vk_img,
            RV_VKMemoryPtr mem,
            RV_VKImageViewPtr view,
            RV_VKImageViewPtr primary_view,
            RV_VKSamplerPtr sampler);

    static RV_VKImagePtr createRVImage(
            RV_Instance*   inst,
            VkImage        vk_img,
            RV_VKMemoryPtr mem,
            const RV_VKImageCreateInfo* info,
            const char* name = nullptr);

    static void deleteImage(
            RV_Instance* inst,
            VkImage* img,
            VkDeviceMemory* mem);

    // basic resource handles
    RV_Instance*    myInst = nullptr;
    VkImage         myVkImg = VK_NULL_HANDLE;
    RV_ResourceID   myId;
    UT_UniquePtr<const RV_VKImageCreateInfo> myCreateInfo;

    UT_UniquePtr<RV_VKImageView> myView;
    UT_UniquePtr<RV_VKImageView> myPrimaryView;
    UT_UniquePtr<RV_VKMemory>  myMemory;
    UT_UniquePtr<RV_VKSampler> mySampler;

#ifdef VULKAN_PRESENTATION
    bool myIsSwapchainImage = false;
#endif

public: // wip
    UT_StringHolder myName;

    // Vulkan Resource Usage
    VkImageLayout        myLastLayout = VK_IMAGE_LAYOUT_UNDEFINED;
    VkAccessFlags        myLastAccess = 0;
    VkImageUsageFlags    myLastUsage = 0;
    VkPipelineStageFlags myLastStage = 0;
    uint32_t             myLastQueueFam = 0;

    RV_StageGroup myWaitingBarrierStage = RV_STAGE_NONE;

    friend class RV_VKImageCreateInfo;
};

#endif