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

#ifndef __VE_PHYSICAL_DEVICE_H__
#define __VE_PHYSICAL_DEVICE_H__

#include "VE_VK.h"

#include "VE_API.h"
#include "VE_Result.h"
#include "VE_PhysicalDeviceFeatures.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringSet.h>
#include <UT/UT_Optional.h>

constexpr uint32_t VE_SWIFT_SHADER_DEVICE_ID = 0xC0DE;

/// A enum of common device extensions. These can be used in lieu of passing
/// the names themselves into functions, making it a bit hard
/// to make typos and a bit easier to remember what extensions exist.
///
/// To map from extension name to enum member, just remove the capitalized
/// prefix from the the extension name.
/// For example
/// VK_KHR_external_fence_capabilities -> external_fence_capabilities
enum class VE_DeviceExtension {
    dynamic_rendering,
    maintenance4,
    external_semaphore,
    external_memory,
    external_memory_win32,
    external_semaphore_win32,
    external_memory_fd,
    external_semaphore_fd,
    ray_tracing_pipeline,
    acceleration_structure,
    ray_query,
    deferred_host_operations,
#ifdef VULKAN_PRESENTATION
    swapchain,
#endif
    metal_objects,

    count, // used to mark the size of this enum
};

/// This class maintains the actual Vulkan API structures used to inspect and
/// enable various possible device features.
class VE_API VE_PhysicalDeviceFeatureChain
{
public:
    VE_PhysicalDeviceFeatureChain();

    VE_PhysicalDeviceFeatureChain(const VE_PhysicalDeviceFeatureChain&);
    VE_PhysicalDeviceFeatureChain(const VE_PhysicalDeviceFeatures &features);
    VE_PhysicalDeviceFeatureChain(const VE_PhysicalDeviceFeatures &features,
            const UT_ArrayStringSet &deviceextensions);
    VE_PhysicalDeviceFeatureChain(VkPhysicalDevice dev,
            const UT_ArrayStringSet &deviceextensions);

    VE_PhysicalDeviceFeatureChain &operator=(const VE_PhysicalDeviceFeatureChain&);
    
    /// Returns a linked list of Vulkan structures, chained through pNext
    /// members, that can be passed into various API calls.
    /// This pointer must not outlive the VE_PhysicalDeviceFeatureChain instance
    /// it was returned from.
    const VkPhysicalDeviceFeatures2 *pFeatures() const { return &my0; }

    // Returns a filled `VE_PhysicalDeviceFeatures` struct, with the features
    // enabled in this linked feature chain
    VE_PhysicalDeviceFeatures featuresStruct() const;

    bool containsAll(
            const VE_PhysicalDeviceFeatures &features,
            UT_WorkBuffer *feature_list = nullptr) const;

    bool hasBufferDeviceAddress() const
        { return my2.bufferDeviceAddress; }

    bool hasMultiviewTessellationShader() const
        { return my1.multiviewTessellationShader; }

    bool hasAccelerationStructure() const
        { return my6.accelerationStructure; }
    
    bool hasRayQuery() const
        { return my4.rayQuery; }

    VkPhysicalDeviceFeatures2 *pFeatures() { return &my0; }

private:
    void linkMembers();
    void linkMembers(const UT_ArrayStringSet &deviceextensions);
    void linkMembers(const VE_PhysicalDeviceFeatureChain &other);

    VkPhysicalDeviceFeatures2 my0;
    VkPhysicalDeviceVulkan11Features my1;
    VkPhysicalDeviceVulkan12Features my2;
    VkPhysicalDeviceVulkan13Features my3;
    VkPhysicalDeviceRayQueryFeaturesKHR my4;
    VkPhysicalDeviceRayTracingPipelineFeaturesKHR my5;
    VkPhysicalDeviceAccelerationStructureFeaturesKHR my6;
};

/// A wrapper around a VkPhysicalDevice object that also contains useful
/// information about that physical device.
/// Due to caching information from the driver, this object is rather hefty.
/// Consider allocating it on the heap.
class VE_API VE_PhysicalDevice
{
public:
    static VE_Result<VE_PhysicalDevice> create(VkPhysicalDevice);
    
    static VE_Result<UT_Array<VE_PhysicalDevice>> findAll(VkInstance instance);

    VkPhysicalDevice getVkPhysicalDevice() const { return myHandle; }

    const VkPhysicalDeviceProperties &properties() const
    {
        return myProperties.properties;
    }

    const VkPhysicalDeviceIDProperties &idProperties() const
    {
        return myIdProperties;
    }

    const VkPhysicalDeviceVulkan11Properties &vulkan11Properties() const
    {
        UT_ASSERT(VK_API_VERSION_MINOR(properties().apiVersion) >= 2);
        return myProperties11;
    }

    const VkPhysicalDeviceVulkan12Properties &vulkan12Properties() const
    {
        UT_ASSERT(VK_API_VERSION_MINOR(properties().apiVersion) >= 2);
        return myProperties12;
    }

    const VkPhysicalDeviceAccelerationStructurePropertiesKHR &accelStructProperties() const
    {
        return myAccelStructProperties;
    }

    const VE_PhysicalDeviceFeatureChain &features() const { return myFeatures; }

    bool extensionAvailable(const char *name) const;
    bool extensionAvailable(VE_DeviceExtension ext) const;

    const UT_Array<VkQueueFamilyProperties> &queueFamiltyProperties() const
    {
        return myQueueFamilyProperties;
    }

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

    // Print out device information. Mainly for debugging.
    void printInfo() const;

    /// Methods for retrieving a memory type index.
    ///
    /// Vulkan resources can be created before any memory is actually allocated for
    /// them. This memory-less resource handle acts as a kind of meta-data object. One
    /// of the reasons for this is so the memory requirements for the resource can be
    /// queried before the resource is actually allocated, allowing us to merge the
    /// resources requirements with the applications needs and preferences.
    ///
    /// The resource's requirements are expressed as memory type bits.  The
    /// applications requirements or preferences are expressed as
    /// VkMemoryPropertyFlags.  You can pass both of these to these new methods to
    /// retrieve the actually memory type index, which is all you need to actually
    /// allocate the memory.
    ///
    /// Usage:
    ///
    ///     VkMemoryRequirements reqs;
    ///
    ///     vkGetBufferMemoryRequirements(device, buffer, &reqs);
    ///
    ///     uint32_t memory_type_index;
    ///
    ///     auto r = physical_device.findMemoryTypeIndex(reqs.memoryTypeBits,
    ///             preferred_flags | required_flags);
    ///     if (!r)
    ///         r = physical_device.findMemoryTypeIndex(reqs.memoryTypeBits,
    ///             required_flags);
    ///
    ///     memory_type_index = *r;
    ///
    UT_Optional<uint32_t> findMemoryTypeIndex(uint32_t memory_type_bits, VkMemoryPropertyFlags required_properties) const;

    /// Returns the memory type index satisfying the given flags, or none. This
    /// is equivalent to the above call with memory_type_bits == 0xFFFFFFFF
    UT_Optional<uint32_t> findMemoryTypeIndex(VkMemoryPropertyFlags flags) const;

    // TODO extensions do not get enabled on the physical device but the logical
    // one. these methods should there for be on the logical device object
    const UT_ArrayStringSet &availableExtensions() const
    {
        return myAvailableExtensions;
    }

    UT_Optional<uint32_t>
    findQueueFamilyIndex(VkQueueFlags flags) const;

    VkFormatProperties formatProperties(const VkFormat format) const;

    VE_Result<VkImageFormatProperties2> imageFormatProperties(const VkImageCreateInfo &info) const;

    VE_PhysicalDevice() = default;

private:
    VkPhysicalDevice myHandle;
    VkPhysicalDeviceProperties2 myProperties;
    VkPhysicalDeviceIDProperties myIdProperties;
    VkPhysicalDeviceVulkan11Properties myProperties11;
    VkPhysicalDeviceVulkan12Properties myProperties12;
    VkPhysicalDeviceAccelerationStructurePropertiesKHR myAccelStructProperties;
    VkPhysicalDeviceMemoryProperties myMemoryProperties;
    VE_PhysicalDeviceFeatureChain myFeatures;
    UT_Array<VkQueueFamilyProperties> myQueueFamilyProperties;

    UT_ArrayStringSet myAvailableExtensions;

    VE_PhysicalDevice(VkPhysicalDevice);
};

UT_Array<const char*> VE_API
VEextensionNamesToStrings(uint32_t count, const VE_DeviceExtension extensions[]);

uint32_t VE_API VEgetPhysicalDeviceVersion(VkPhysicalDevice phy_dev);

#endif