VE_Instance.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_Instance.h ( VE Library, C++)
 *
 */

#ifndef __VE_INSTANCE_H__
#define __VE_INSTANCE_H__

#include "VE_API.h"
#include "VE_PhysicalDevice.h"
#include "VE_Result.h"
#include "VE_PhysicalDevice.h"

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

enum class VE_VulkanAPIVersion
{
    version_1_0,
    version_1_1,
    version_1_2,
    version_1_3,
};

/// A enum of common instance 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_InstanceExtension {
    external_fence_capabilities = 0,
    external_memory_capabilities,
    external_semaphore_capabilities,
    surface,
    win32_surface,
    device_group_creation,
    get_physical_device_properties2,
    get_surface_capabilities2,
    debug_utils,

    count,
};

/// A enum of common instance layers. 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 layers exist.
///
/// To map from layer name to enum member, just remove the VK_LAYER
/// prefix from the the layer name and lower case the rest.
/// For example:
/// VK_LAYER_LUNARG_standard_validation -> lunarg_standard_validation
enum class VE_InstanceLayer {
    khronos_validation = 0,
    renderdoc_capture,

    count,
};

/// Low level wrapper around a VkInstance.
/// Users must be explicit call destroy() when done with this.
class VE_API VE_Instance
{
    UT_ArrayStringSet myEnabledExtensions;
    VE_VulkanAPIVersion myApiVersion;
    VkInstance myHandle;

    VE_Instance(
            VkInstance inst,
            VE_VulkanAPIVersion version,
            UT_ArrayStringSet ext_names)
    : myHandle(inst)
    , myApiVersion(version)
    , myEnabledExtensions(ext_names)
    {}

public:
    static VE_Result<VE_Instance> create(
            VE_VulkanAPIVersion version,
            uint32_t extension_count = 0,
            const char *const extension_names[] = nullptr);
    static VE_Result<VE_Instance> create(
            VE_VulkanAPIVersion version,
            uint32_t extension_count,
            const VE_InstanceExtension extensions[]);

    VE_Instance() = default;
    /// Destroys the underlying vulkan instance. Must not be called until all
    /// VkDevice objects that this was used to create have been destroyed.
    void destroy();

    VkInstance handle() const { return myHandle; }

    VE_VulkanAPIVersion apiVersion() const { return myApiVersion; }
    /// The more opaque form of the api version that is used for Vulkan API calls.
    uint32_t apiVersionNumber() const;

    bool extensionEnabled(VE_InstanceExtension ext) const;

    bool extensionEnabled(const char *ext) const { return myEnabledExtensions.contains(ext); }

    const UT_ArrayStringSet &enabledExtensions() const { return myEnabledExtensions; }

    /// Returns a list of physical devices (such as GPUs) avaiable to the
    /// instance. The list can be scanned for a suitable physical device, which
    /// can then be used to create logical device objects.
    VE_Result<UT_Array<VE_PhysicalDevice>> physicalDevices() const;

};

/// NOTE: These are low-level calls and it is recommended to use a higher-level
/// interface to Vulkan if possible.
///
/// Create a Vulkan instance object, which is the primary handle into the Vulkan
/// loader. The instance object is mainly used to query for and inspect
/// available system drivers and physical devices, and create VkDevice
/// objects from particular physical devices.
///
/// It is the caller's responsibily to pass the returned VkInstance to
/// ve_destroyVulkanInstance once it is no longer needed.
VE_API
VE_Result<VkInstance> VEcreateVulkanInstance(
        VE_VulkanAPIVersion version,
        uint32_t extension_count,
        const char *const extension_names[],
        uint32_t layer_count,
        const char *const layer_names[]);
VE_API
VE_Result<VkInstance> VEcreateVulkanInstance(
        VE_VulkanAPIVersion version,
        uint32_t extension_count,
        VE_InstanceExtension extensions[],
        uint32_t layer_count,
        VE_InstanceLayer layers[]);
/// This version of the call will automatically enabled the validation layers in
/// debug mode.
VE_API
VE_Result<VkInstance> VEcreateVulkanInstance(
        VE_VulkanAPIVersion version,
        uint32_t extension_count,
        const char *const extension_names[]);

/// Query Support of the Instance Layer in the Vulkan Instance
VE_API
bool VEsupportsInstanceLayer(VE_InstanceLayer extension);
VE_API
bool VEsupportsInstanceLayer(const char* extension);

/// Query Support of the Instance Extension in the Vulkan Instance
VE_API
bool VEsupportsInstanceExtension(VE_InstanceExtension extension);
VE_API
bool VEsupportsInstanceExtension(const char* extension);

/// Clean up the instance resource. This likely will simply call
/// vkDestroyInstance.
VE_API
void VEdestroyVulkanInstance(VkInstance);


/// Return the Vulkan major, minor, and patch version bit-crammed into the
/// unsigned int.
VE_API
uint32_t VEgetInstanceVersion();

#endif