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

#ifndef __VE_DEVICE_H__
#define __VE_DEVICE_H__

#include "VE_API.h"
#include "VE_Ext.h"
#include "VE_Instance.h"
#include "VE_Memory.h"
#include "VE_PhysicalDevice.h"
#include "VE_Result.h"

#include <SYS/SYS_Handle.h>

enum VE_QueueFlagBits {
    VE_QUEUE_GRAPHICS_BIT = VK_QUEUE_GRAPHICS_BIT,
    VE_QUEUE_COMPUTE_BIT = VK_QUEUE_COMPUTE_BIT,
    VE_QUEUE_TRANSFER_BIT = VK_QUEUE_TRANSFER_BIT,
};

struct VE_BufferAllocation
{
    VkBuffer buffer;
    VkDeviceMemory memory;
    VkDeviceSize size;
};

using VE_QueueFlags = uint32_t;

/// This class contains a VkDevice handle along with the objects that are
/// involved with the creation of it. Upon instantiation, it creates the
/// VkInstance, finds a suitable physical device, and creates the logical
/// VkDevice from that along  queue objects. It
/// cleans up everything upon calling destroy() on it.
///
/// It therefore forms a single convenient point interface into the Vulkan API,
/// and can form the bedrock of a higher level abstraction.
///
/// Keep in mind the size of the object. Heap allocation is suggested.
class VE_API VE_Device
{
    VE_PhysicalDevice myPhysicalDevice;
    VE_Instance myInstance;
    VE_Ext myExt;
    VkDevice myHandle = VK_NULL_HANDLE;

    static constexpr int UNIVERSAL_QUEUE_BITS = (VE_QUEUE_GRAPHICS_BIT | VE_QUEUE_COMPUTE_BIT | VE_QUEUE_TRANSFER_BIT);
    static constexpr int MAX_QUEUE_TYPES = UNIVERSAL_QUEUE_BITS + 1;

    /// From the spec, describing VkQueueFlagBits:
    ///
    /// " If an implementation exposes any queue family that supports graphics
    /// operations, at least one queue family of at least one physical device
    /// exposed by the implementation must support both graphics and compute
    /// operations. Furthermore, if the protected memory physical device feature is
    /// supported, then at least one queue family of at least one physical device
    /// exposed by the implementation must support graphics operations, compute
    /// operations, and protected memory operations. 
    ///
    /// Note: All commands that are allowed on a queue that supports
    /// transfer operations are also allowed on a queue that supports either
    /// graphics or compute operations. Thus, if the capabilities of a queue family
    /// include VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT,  then  reporting  the
    /// VK_QUEUE_TRANSFER_BIT  capability separately for that queue family is
    /// optional. "
    /// - Vulkan Spec. Page 108 | Chapter 5. Devices and Queues

    struct QueueFamilies {
        // Use a VE_QueueBits to index into this to retrieve the queue family index.
        // A -1 means there is no queue family satifying those bit flags
        int indices[MAX_QUEUE_TYPES];
    } myQueueFamilies;

    VE_Device(
            VE_Instance inst,
            VE_PhysicalDevice phy_dev,
            VkDevice device,
            QueueFamilies queue_families,
            uint32_t enabled_extension_count,
            const char *const *enabled_extensions)
        : myPhysicalDevice(std::move(phy_dev))
        , myInstance(std::move(inst))
        , myHandle(device)
        , myQueueFamilies(queue_families)
    {
        myExt.loadInstanceExtensionFunctions(
                myInstance.handle(), myInstance.enabledExtensions());
        myExt.loadDeviceExtensionFunctions(
                device, enabled_extension_count, enabled_extensions);
    }

public:
    VE_Device() = default;

    static VE_Result<VE_Device> 
    create(
            const VE_Instance &instance,
            const VE_PhysicalDevice &physical_device,
            VE_PhysicalDeviceFeatures device_features,
            uint32_t device_extension_count,
            const VE_DeviceExtension device_extensions[]);

    void destroy();

    VkDevice handle() const { return myHandle; }

    const VE_Ext &ext() const { return myExt; }

    /// TODO make sure this is available
    /// Return a queue that supports graphics, compute, and transfer operations.
    VkQueue  universalQueue() const;
    uint32_t universalQueueFamilyIndex() const;

    /// TODO make sure this is available
    /// Return a queue that supports graphics operations.
    VkQueue  graphicsQueue() const;
    uint32_t graphicsQueueFamilyIndex() const;

    const VE_PhysicalDevice &physicalDevice() const { return myPhysicalDevice; }

    const VE_Instance &instance() const { return myInstance; }

    VE_Result<VkDeviceMemory> allocateMemory(
        uint64_t size,
        uint32_t memory_type_bits,
        VkMemoryPropertyFlags mem_props,
        bool external);

    VE_Result<VE_BufferAllocation> createAndAllocateBuffer(
        VkDeviceSize size,
        VkBufferUsageFlags usage,
        VkMemoryPropertyFlags mem_props,
        bool external);

    VE_Result<SYS_Handle> createExternalMemoryHandle(VkDeviceMemory memory);

    VE_Result<VkDebugUtilsMessengerEXT> setDebugCallback(
            VkDebugUtilsMessageSeverityFlagsEXT msg_severity_flags,
            VkDebugUtilsMessageTypeFlagsEXT msg_type_flags,
            VkBool32 (*callback)(
                    VkDebugUtilsMessageSeverityFlagBitsEXT,
                    VkDebugUtilsMessageTypeFlagsEXT,
                    const VkDebugUtilsMessengerCallbackDataEXT *pCallbackData,
                    void *pUserData),
            void *pUserData);
};

/// NOTE: These are low-level calls and it is recommended to use a higher-level
/// interface to Vulkan if possible.
///
/// Create a Vulkan logical device object. It grants access to a specific device,
/// which in many cases will be a dedicated GPU. Some high-level uses of the
/// device are listed below.
///
/// • Creation of command queues.
/// • Creation and tracking of various synchronization constructs.
/// • Allocating, freeing, and managing memory.
/// • Creation and destruction of command buffers and command buffer pools.
/// • Creation, destruction, and management of graphics state.
///
/// It is the caller's responsibily to pass the returned VkDevice to
/// ve_destroyVulkanDevice once it is no longer needed.
VE_API
VE_Result<VkDevice> VEcreateVulkanDevice(VkPhysicalDevice, VkDeviceCreateInfo);
/// This call assigns equal priorities to all queues.
VE_API
VE_Result<VkDevice> VEcreateVulkanDevice(
        VkPhysicalDevice,
        const VE_PhysicalDeviceFeatures &enabled_features,
        uint32_t enabled_extension_count,
        const char *const *enabled_extensions,
        const uint32_t queue_family_count,
        const uint32_t queue_family_indices[],
        const uint32_t queue_counts[]);
/// Create a device with access to only one family of queues.
VE_API
VE_Result<VkDevice> VEcreateVulkanDevice(
        VkPhysicalDevice,
        const VE_PhysicalDeviceFeatures &enabled_features,
        uint32_t enabled_extension_count,
        const char *const *enabled_extensions,
        uint32_t queue_family_index,
        uint32_t queue_count);
/// Create a device with a single queue statisfying the given queue_flags.
VE_API
VE_Result<VkDevice> VEcreateVulkanDevice(
        const VE_PhysicalDevice &,
        const VE_PhysicalDeviceFeatures &enabled_features,
        uint32_t enabled_extension_count,
        const char *const *enabled_extensions,
        VkQueueFlags queue_flags);

/// Clean up a VkDevice. This likely will simply call vkDestroyDevice.
VE_API
void VEdestroyVulkanDevice(VkDevice);

/// Will create the system specific external memory handle
/// for the memory passed in.
/// pfn should be a function pointer with signature matching either 
/// PFN_vkGetMemoryFdKHR or PFN_vkGetMemoryWin32HandleKHR, depending on the
/// platrom.
/// memory must have been created with the
VE_API VE_Result<SYS_Handle>
VEcreateExternalMemoryHandle(
        void *pfn,
        VkDevice device,
        VkDeviceMemory memory);

#endif