RV_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:        RV_Instance.h ( RV Library, C++)
 *
 * COMMENTS:
 *      Main interface to Vulkan
 */
#ifndef RV_Instance_h
#define RV_Instance_h

#include "RV_API.h"

#include "RV_Type.h"
#include "RV_Tracing.h"

#include <VE/VE_VK.h>

#include <UT/UT_Array.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Function.h>

#include <VE/VE_PhysicalDeviceFeatures.h>

class rv_InstanceData;

class RV_DescriptorAllocator;
class RV_Render;
class RV_VKQueue;
class RV_VKCommandPool;
class RV_VKCommandBuffer;
class RV_VKCommandBufferAllocator;
class RV_VKExt;
class RV_VKMemAllocator;
class UT_WorkBuffer;

class RV_VKBuffer;
class RV_VKImage;
class RV_VKAccelerationStructure;
class RV_VKDescriptorSet;
class RV_ShaderVariableSet;

class RE_Render;

/// Handle to the main interface of Vulkan
class RV_API RV_Instance
{
public:
    /// The global vulkan instance, creating it if it hasn't been created yet.
    static RV_Instance* getInstance(bool *created = nullptr);
    /// Optional SwiftShader instance (separate from the GPU singleton)
    static RV_Instance* getSwiftShaderInstance(bool *created = nullptr);
    
    /// used internally
    static RV_Instance* getInstanceForViewport(RE_Render *r, bool *created = nullptr);

    /// Returns whether the global vulkan instance exists
    static bool         hasInstance();
    /// Destroy the global instance. For system exit.
    static void         destroyInstance();
    /// Destroy the SwiftShader instance. For system exit.
    static void         destroySwiftShaderInstance();

    /// The callback that's called on app exit to destroy the global instance
    static void         exitCallback(void*);

    /// add callbacks to be called as soon as instance is created
    static void         addPostCreateCB(bool (*cb)(RV_Instance*));
    static bool         hasPostCreateCBs();

    /// add callbacks to be called before the instance is destroyed.
    /// the list is cleared after the instance is destroyed, so they
    /// must be re-added for a new instance
    static void         addPreDestroyCB(bool (*cb)(RV_Instance*));
    static bool         hasPreDestroyCBs();

    /// @brief Request extensions or features to be enabled on the Vulkan device
    /// Can be called before the RV_Instance is created to add extra device
    /// extensions to be enabled, if supported on the selected device.
    /// Can pass in a feature struct with the extension, to enable
    /// extension-specific features
    ///
    /// Core features can be also requested by passing the appropriate struct
    /// (e.g. VkPhysicalDeviceFeatures2, VkPhysicalDeviceVulkan11Features, etc.)
    /// with `nullptr` as the name. Features from any extensions promoted to
    /// Core in Vulkan 1.1, 1.2, or 1.3 should be requested using the Core
    /// Vulkan features struct, NOT the extension specific struct.
    ///
    /// After the instance is created, it should be queried wtih `extEnabled()`
    /// and 'getFeatureStruct()' to confirm whether the requested extensions and
    /// features were supported
    ///
    /// @param ext_name          the name of the extension
    /// @param feature_struct    The feature struct for the extension, with
    ///                          desired features flags enabled. It can be
    ///                          'nullptr' if the extension doesn't have
    ///                          features
    /// @param struct_size_bytes the size in bytes of the feature struct
    static void addExtraDeviceExtension(
            const char* ext_name,
            VkBaseOutStructure* feature_struct = nullptr,
            exint struct_size_bytes = 0);

    /// Query if an extension has been added to the Extra Extension list. If the
    /// appropriate feature struct is supplied, it will be filled with requested
    /// features. Parameters same as 'addExtraDeviceExtension()'
    static bool hasExtraDeviceExtension(
            const char* ext_name,
            VkBaseOutStructure* feature_struct = nullptr,
            exint feature_struct_size_bytes = 0);

    /// Can be called before the RV_Instance is created to add extra instance
    /// extensions to be enabled (if supported) on the selected device
    static void addExtraInstanceExtension(const char* ext_name);

    /// Returns true if the Extra Extensions used during instance creation
    /// match the currently set one, i.e. if any have been added since the
    /// instance was created
    bool extraExtensionsChanged() const;

    /// add callback to be called when current rendering is finished.
    /// Typed as a UT_Function instead of function ptr , so
    /// capturing lambdas can be used as callbacks
    using RenderCallback = UT_Function<void(RV_Instance*)>;
    void addPostRenderCB(const RenderCallback &callback);

    /// notification from active RV_Render that current rendering tasks
    /// are about to flushed
    void finishRendering(RV_Render* r);

    /// Create the global vulkan instance. Used only at startup.
    static RV_Instance* create(bool use_swiftshader = false);
    
    ~RV_Instance();

    /// Set up Vulkan once the instance is created
    bool                initializeDevice();

    /// Get the raw vulkan device assocated with this instance.
    VkDevice            getDevice();
    /// Get the raw vulkan physical device assocated with this instance.
    VkPhysicalDevice    getPhysicalDevice();
    /// Get the raw vulkan instance.
    VkInstance          getVkInst();

    /// Raw Vulkan memory properties of the physical device
    const VkPhysicalDeviceMemoryProperties* getMemoryProps() const;

    /// Raw Vulkan acceleration structure properties of the physical device
    const VkPhysicalDeviceAccelerationStructurePropertiesKHR* getAccelStructProps() const;

    /// Raw Vulkan device properties from physical device
    const VkPhysicalDeviceLimits* getVulkanDeviceLimits() const;
    const VkPhysicalDeviceVulkan11Properties* getVulkan11DeviceProps() const;
    const VkPhysicalDeviceVulkan12Properties* getVulkan12DeviceProps() const;

    /// Vulkan device UUID, used to match devices for cross-API interop
    void          getDeviceUUID(uint8 (&uuid)[16]) const;

    /// Main Queue supporting graphics, compute and transfer
    RV_VKQueue&              getGraphicsQueue() { return *myGraphicsQueue; }

    /// Raw Vulkan handle for Main Queue supporting graphics, compute and transfer
    VkQueue                  getVkGraphicsQueue();

    /// Our Vulkan memory allocator implementation
    RV_VKMemAllocator&       getMemAllocator() { return *myAllocator; }
    /// Our Vulkan descriptor set allocator
    RV_DescriptorAllocator&  getDescAllocator(){return *myDescriptorAllocator;}

    rvTraceCtx               getTraceContext(){  return myTraceCtx; };

    /// Get text information about the current driver and device
    void                     fetchDriverInfo(UT_WorkBuffer &info);

    static uint32_t     getInstanceVersion();

    /// The Vulkan version as implemented by the device driver
    uint32_t            getDeviceVersion();
    /// The vendor of the device (AMD, Intel, NVIDIA, MoltenVK)
    RV_GraphicsDevice   getDeviceVendor() const;

    const UT_StringHolder &deviceName() const { return myDeviceName; }
    bool                  isSwiftShader() const { return myUseSwiftShader; }

    /// True if the debug validation layers are active
    static bool         usingDebugValidation();

    /// True if Vulkan multithreading env var is set to true
    static bool         usingVulkanMultithreading();

    /// Maximum supported number of color samples in a multisample framebuffer
    int                 getMaxColorSamples() const;

    /// Maximum supported number of depth samples in a multisample framebuffer
    int                 getMaxDepthSamples() const;

    /// Maximum size of 2D texture
    int                 getMaxTextureSize2D() const;

    /// Maximum size of 3D texture
    int                 getMaxTextureSize3D() const;

    /// Granularity of Line width setting
    float               getLineWidthGranularity() const;

    /// Range of Line width setting
    UT_Vector2F         getLineWidthRange() const;

    /// Granularity of Point Size setting
    float               getPointSizeGranularity() const;

    /// Range of Point Size setting
    UT_Vector2F         getPointSizeRange() const;

    /// Object containing function pointers to Vulkan extensions
    RV_VKExt*           getExt() { return myExtensions.get(); }

    /// Query if the given Vulkan extension is enabled in the device
    bool                extEnabled( const char* vk_ext_name ) const;

    /// @brief Query the features enabled on the RV_Instance's VkDevice.
    /// Copies the feature flags used in device creation into `out_feature_struct`
    /// and returns true, if a feature struct with the matching `sType` was used.
    /// If a matching struct wasn't used, returns false
    bool                getFeatureStruct(
                           VkBaseOutStructure* out_feature_struct,
                           exint feature_struct_size_bytes) const;

    /// Query restriction for GL to Vulkan interop texture. If true, must use linear textures
    bool                useLinearTilingForGLInterop() const;

    /// Query restriction for GL to Vulkan interop texture. If false, cannot use semaphores for sync
    bool                useSemaphoreForGLInterop() const;

    /// Query if custom sample locations can be used for the given MSAA level
    bool                supportsSampleLocations(int aa) const;

    /// Block until the device has finished all commands (Call with care!)
    void                 waitDeviceIdle();

    /// Returns the physical device features that have been enabled on our
    /// device
    const VE_PhysicalDeviceFeatures &getPhysicalDeviceFeatures() const;
    
    // WIP: Resource tracking
    // functions used in VK Resource classes to register their existance
    // with the Instance and track details about them:
    /// `register` - called on creation, to get a Unique ID for the resource
    /// `clear`    - called on destruction 
    /// `validate` - can be called to check if the ID's resource is still valid
    /// `setDeletePending` - flags the resource as being queued for deletion by
    //           `RVdestroyVKPtr`. They will be treated as invalid since
    //           they will be deleted once their Command Buffer is executed
    // Shouldn't be manually called
    RV_ResourceID registerImage(RV_VKImage* img);
    void          clearImage(RV_VKImage* img);
    void          clearImage(RV_ResourceID id);
    bool          validateImage(RV_ResourceID id, bool allow_pending_delete = false) const;
    void          setDeletePending(RV_VKImage* img);

    RV_ResourceID registerBuffer(RV_VKBuffer* buf);
    void          clearBuffer(RV_VKBuffer* buf);
    void          clearBuffer(RV_ResourceID id);
    bool          validateBuffer(RV_ResourceID id, bool allow_pending_delete = false) const;
    void          setDeletePending(RV_VKBuffer* buf);

    RV_ResourceID registerAccelStruct(RV_VKAccelerationStructure* accel_struct);
    void          clearAccelStruct(RV_ResourceID id);
    void          clearAccelStruct(RV_VKAccelerationStructure* accel_struct);
    bool          validateAccelStruct(RV_ResourceID id, bool allow_pending_delete = false) const;
    void          setDeletePending(RV_VKAccelerationStructure* accel_struct);

    RV_ResourceID registerSet(RV_VKDescriptorSet* set);
    void          clearSet(RV_ResourceID id);
    void          clearSet(RV_VKDescriptorSet* set);
    bool          validateSet(RV_ResourceID id, bool allow_pending_delete = false) const;
    void          setDeletePending(RV_VKDescriptorSet* set);

    RV_ResourceID registerVarSet(RV_ShaderVariableSet* set);
    void          clearVarSet(RV_ResourceID id);
    void          clearVarSet(RV_ShaderVariableSet* set);
    bool          validateVarSet(RV_ResourceID id, bool allow_pending_delete = false) const;
    void          setDeletePending(RV_ShaderVariableSet* set);

    // DEBUG: Prints the list of active resource IDs
    void printIDs() const;

private:
    RV_Instance();


    UT_UniquePtr<rv_InstanceData> myInstance;
    UT_UniquePtr<RV_VKMemAllocator> myAllocator;
    UT_UniquePtr<RV_DescriptorAllocator> myDescriptorAllocator;
    UT_UniquePtr<RV_VKQueue> myGraphicsQueue;
    rvTraceCtx myTraceCtx;

    UT_UniquePtr<RV_VKExt> myExtensions;

    VE_PhysicalDeviceFeatures myEnabledDeviceFeatures;
    UT_Array<const char*> myEnabledDevExtensions;
    UT_Array<const char*> myEnabledInstExtensions;
    UT_StringHolder myDeviceName;
    bool myUseSwiftShader = false;
};

#endif