VE_Memory.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: VE_Memory.h ( VE Library, C++)
 *
 * COMMENTS:
 */

#ifndef __VE_MEMORY_H__
#define __VE_MEMORY_H__

#include "VE_API.h"
#include "VE_Result.h"
#include "VE_Instance.h"

#include <vk_mem_alloc.h>

#include <SYS/SYS_Handle.h>
#include <UT/UT_NonCopyable.h>

class VE_Ext;

enum VE_MemType
{
    VE_MEM_AUTO = 0,
    VE_MEM_MAPPABLE_UPLOAD,
    VE_MEM_MAPPABLE_UPLOAD_DEVICE_LOCAL,
    VE_MEM_MAPPABLE_HOST_CACHED,
    VE_MEM_OPENGL_EXPORTABLE,
};

enum VE_MemFlagBits {
    FLAG_COHERENT  = 1 << 0,
    FLAG_DEDICATED = 1 << 1,
};

using VE_MemFlags = uint32_t;

class VE_API VE_VmaAllocation
{
public:
    const VmaAllocationInfo &info() const { return myInfo; }

    bool isValid() const { return myAllocation != nullptr; }

    void free(VmaAllocator allocator);


protected:
    friend class VE_VmaMemoryAllocator;

    VmaAllocation myAllocation = VK_NULL_HANDLE;
    VmaAllocationInfo myInfo;
};

class VE_API VE_VmaMappableAllocation : public VE_VmaAllocation
{
protected:
    VE_Result<void *> map(VmaAllocator allocator);
    void unmap(VmaAllocator allocator);
};

class VE_API VE_VmaMemoryAllocator
{
public:
    static VE_Result<VE_VmaMemoryAllocator> create(
        VkInstance,
        VkPhysicalDevice,
        VkDevice,
        uint32_t req_ver,
        VmaAllocatorCreateFlags flags);

    void destroy();

    template <typename R>
    struct Allocation {
        R resource;
        VE_VmaAllocation allocation;
    };

    template <typename R>
    struct MappableAllocation {
        R resource;
        VE_VmaMappableAllocation allocation;
    };

    using ImageAllocation = Allocation<VkImage>;
    using BufferAllocation = Allocation<VkBuffer>;
    using MappableImageAllocation = MappableAllocation<VkImage>;
    using MappableBufferAllocation = MappableAllocation<VkBuffer>;

    VE_Result<VE_VmaAllocation> allocateMemory(const VkMemoryRequirements&, const VmaAllocationCreateInfo &info);
    VE_Result<ImageAllocation> allocateImage(const VkImageCreateInfo&, const VmaAllocationCreateInfo &info);
    VE_Result<BufferAllocation> allocateBuffer(const VkBufferCreateInfo&, const VmaAllocationCreateInfo &info);

    VE_Result<VE_VmaMappableAllocation> allocateMappableMemory(const VkMemoryRequirements&, const VmaAllocationCreateInfo &info);
    VE_Result<MappableBufferAllocation> allocateMappableBuffer(const VkBufferCreateInfo&, const VmaAllocationCreateInfo &info, exint alignment = 0);
    VE_Result<MappableImageAllocation> allocateMappableImage(const VkImageCreateInfo&, const VmaAllocationCreateInfo &info);

protected:
    VE_VoidResult init(
        VkInstance,
        VkPhysicalDevice,
        VkDevice,
        uint32_t req_ver,
        VmaAllocatorCreateFlags flags);

    VmaAllocator myAllocator = VK_NULL_HANDLE;
};

/// A block of memory as allocated by VE_MemoryAllocator. Will free itself when
/// it goes out of scope.
/// It represents a block of bytes, and should in general be used to as a
/// backing member in some higher level, resource-like class, such as a Buffer
/// or Image class.
class VE_API VE_Memory : private VE_VmaMappableAllocation
{
public:
    VkDeviceMemory getVkMem() const { return allocInfo().deviceMemory; }
    VkDeviceSize getOffset() const { return allocInfo().offset; }
    VkDeviceSize getSize() const { return allocInfo().size; }

    const VmaAllocationInfo &allocInfo() const { return info(); }

    // Copying a block of memory should be done with an explicit copy method,
    // and that method should exist at the resource level instead of here.
    UT_NON_COPYABLE(VE_Memory);

    VE_MemType getType() const { return myData.type; }

    void *mapMemory();
    void unmapMemory();

    void *mappedPointer() { return myData.mappedPtr; }
    const void *mappedPointer() const { return myData.mappedPtr; }

    bool isCoherent() const { return myData.flags & FLAG_COHERENT; }
    bool isDedicated() const { return myData.flags & FLAG_DEDICATED; }

    VE_Memory(VE_Memory &&other) noexcept
    {
        *this = std::move(other);
    }

    VE_Memory &operator=(VE_Memory &&other) noexcept
    {
        std::swap(myAllocation, other.myAllocation);
        std::swap(myInfo, other.myInfo);
        std::swap(myAllocator, other.myAllocator);
        std::swap(myData, other.myData);
        std::swap(myExternalHandle, other.myExternalHandle);
        return *this;
    }

    /// On linux, the returned handle is owned by the caller, and the caller is
    /// fully responsible for it. No operations are allowed on the file
    /// descriptor after a successful import into OpenCL (section 5.5.2.1 of the
    /// OpenCL spec). Likewise, performing any operation on the file descriptor
    /// after an import into OpenGL results in undefined behaviour (documented
    /// in description of the EXT_external_objects_fd extension). As a result,
    /// different callers will potentially get different handles.
    /// On windows, the returned handle is NOT owned by the caller! The caller
    /// can use the handle to import the Vulkan memory, but should not close it.
    /// See section 5.5.2.2 of the OpenCL spec and documentation for extension
    /// EXT_external_objects_win32 for more information. Every caller of this
    /// function thus shares the same handle.
    /// On mac, this function returns extension_unavailable error.
    VE_Result<SYS_Handle> getExternalHandle(VkDevice device, const VE_Ext* ext);

    virtual ~VE_Memory();

private:
    VE_Memory(
            VmaAllocator allocator,
            VE_VmaMappableAllocation block,
            VE_MemType type,
            VE_MemFlags flags)
        : VE_VmaMappableAllocation(block)
        , myAllocator(allocator)
    {
        myData.type = type;
        myData.flags = flags;
        myData.mappedPtr = nullptr;
    }

    friend class VE_MemoryAllocator;

    VmaAllocator myAllocator;

    // External handle for sharing this memory object with other APIs. Only used
    // on windows.
    SYS_Handle myExternalHandle;

    struct
    {
        VE_MemType type;
        void *mappedPtr;
        VE_MemFlags flags;
    } myData;
};

/// General purpose allocator for vulkan backed memory blocks that tries to
/// balance convenience, safety, and performance.
///
/// The main convenience offered is that memory blocks allocated from this
/// object will free themselves when they go out of scope. The caller does not
/// need to explicity free them. This makes this class well suited for
/// allocating lots of resources that would be difficult to keep track of
/// manually.
///
/// However, the memory blocks do this by maintaining references to the
/// underlying VmaAllocator object handle, which is owned by and cleaned up by
/// this class. Therefore, care must be taken to ensure this object's life time
/// extends beyond its allocated blocks. If the memory blocks and this allocator
/// are kept as members of a larger structure, ensure proper member ordering so
/// that the blocks are destroyed before the allocator.
///
/// Thread safety:
/// This allocator contains no locks and attempts no cross thread
/// synchronization. If you need memory allocations in different threads, you
/// should give those threads their own allocator.
class VE_API VE_MemoryAllocator : private VE_VmaMemoryAllocator
{
public:
    static VE_Result<VE_MemoryAllocator> create(
            VkInstance,
            VkPhysicalDevice,
            VkDevice,
            uint32_t req_ver,
            VmaAllocationCreateFlags flags);
    static VE_Result<VE_MemoryAllocator> create(
            const VE_Instance &,
            VkPhysicalDevice,
            VkDevice,
            VmaAllocationCreateFlags flags);

    static VkExternalMemoryHandleTypeFlags getExternMemHandleType();

    const VkPhysicalDeviceMemoryProperties &physicalDeviceMemoryProperties()
            const
    {
        return myMemoryProperties;
    };

    UT_Array<VmaBudget> heapInfos() const;

    // prints memory heap info and usage statistics
    void printMemoryInfo() const;
    void printMemoryInfo(std::ostream* out = nullptr) const;

    // get simplified memory usage statistics
    void getMemoryUsage(exint* out_device_vma_alloc_size,
                        exint* out_device_vk_alloc_size,
                        exint* out_device_total_size,
                        exint* out_shared_vma_alloc_size,
                        exint* out_shared_vk_alloc_size,
                        exint* out_shared_total_size) const;

    VE_Result<VE_Memory> allocateImage(
            VE_MemType type,
            const VkImageCreateInfo &img_info,
            VkImage &vk_img);
    VE_Result<VE_Memory> allocateBuffer(
            VE_MemType type,
            const VkBufferCreateInfo &buf_info,
            VkBuffer &vk_buf,
            exint alignment = 0);
    VE_Result<VE_Memory> allocateMemory(
            VE_MemType type,
            const VkMemoryRequirements &info);

    VE_MemoryAllocator() = default;
    ~VE_MemoryAllocator();

    UT_NON_COPYABLE(VE_MemoryAllocator);

    VE_MemoryAllocator(VE_MemoryAllocator &&other) noexcept
    {
        *this = std::move(other);
    }

    VE_MemoryAllocator &operator=(VE_MemoryAllocator &&other) noexcept
    {
        std::swap(myAllocator, other.myAllocator);
        std::swap(myMemoryProperties, other.myMemoryProperties);
        std::swap(myGLExportPool, other.myGLExportPool);
        std::swap(myGLSharedExportPool, other.myGLSharedExportPool);
        return *this;
    }

private:
    void createGLExportPool(VkDevice);

    VE_MemFlags memoryFlags(const VmaAllocationInfo &vma_info, VE_MemType type) const;

    VkPhysicalDeviceMemoryProperties myMemoryProperties;
    VmaPool myGLExportPool = VK_NULL_HANDLE;
    VmaPool myGLSharedExportPool = VK_NULL_HANDLE;
};

/// This is a low level function to create a raw VmaAllocator object, in case the
/// caller wants direct access to the Vma API.
/// It is recommended to use VE_MemoryAllocator unless you have good reason not
/// to.
VE_API
VE_Result<VmaAllocator> VEcreateVmaAllocator(
        VkInstance,
        VkPhysicalDevice,
        VkDevice,
        uint32_t req_ver,
        VmaAllocatorCreateFlags flags);

VE_API
void VEdestroyVmaAllocator(VmaAllocator);

/// Returns the platform specific external memory handle type
VE_API VkExternalMemoryHandleTypeFlags
VEgetExternalMemoryHandleType();

#endif