Merge pull request #1886 from billhollings/reinstate-mvk-extn

Reinstate VK_MVK_moltenvk extension and add simplified config functions.

Docs/Whats_New.md

@@ -23,6 +23,8 @@ Released TBD
 - Support BC compression on iOS/tvOS where available (iOS/tvOS 16.4 and above and supported by the GPU).
 - Support separate depth and stencil attachments during dynamic rendering.
 - Deprecate the obsolete and non-standard `VK_MVK_moltenvk` extension.
+- Add `vkGetMoltenVKConfiguration2MVK()` and `vkGetMoltenVKConfiguration2MVK()` to clarify 
+ MoltenVK config does not require any Vulkan objects.
 - Fix memory leak when waiting on timeline semaphores.
 - Ensure shaders that use `PhysicalStorageBufferAddresses` encode the use of the associated `MTLBuffer`.
 - Disable pipeline cache compression prior to macOS 10.15 and iOS/tvOS 13.0.

MoltenVK/MoltenVK/API/mvk_config.h

@@ -920,8 +920,8 @@ typedef struct {
 #pragma mark -
 #pragma mark Function types
 
- typedef VkResult (VKAPI_PTR *PFN_vkGetMoltenVKConfigurationMVK)(VkInstance ignored, MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
- typedef VkResult (VKAPI_PTR *PFN_vkSetMoltenVKConfigurationMVK)(VkInstance ignored, const MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
+ typedef VkResult (VKAPI_PTR *PFN_vkGetMoltenVKConfiguration2MVK)(MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
+ typedef VkResult (VKAPI_PTR *PFN_vkSetMoltenVKConfiguration2MVK)(const MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
 
 
 #pragma mark -
@@ -936,10 +936,6 @@ typedef struct {
  * the current configuration, make changes, and call vkSetMoltenVKConfigurationMVK() to
  * update all of the values.
  *
- * The VkInstance object you provide here is ignored, and a VK_NULL_HANDLE value can be provided.
- * This function can be called before the VkInstance has been created. It is safe to call this function
- * with a VkInstance retrieved from a different layer in the Vulkan SDK Loader and Layers framework.
- *
  * To be active, some configuration settings must be set before a VkInstance or VkDevice
  * is created. See the description of the MVKConfiguration members for more information.
  *
@@ -962,8 +958,7 @@ typedef struct {
  * to NULL. In that case, this function will set *pConfigurationSize to the size that MoltenVK
  * expects MVKConfiguration to be.
  */
-VKAPI_ATTR VkResult VKAPI_CALL vkGetMoltenVKConfigurationMVK(
- VkInstance ignored,
+VKAPI_ATTR VkResult VKAPI_CALL vkGetMoltenVKConfiguration2MVK(
  MVKConfiguration* pConfiguration,
  size_t* pConfigurationSize);
 
@@ -974,10 +969,6 @@ VKAPI_ATTR VkResult VKAPI_CALL vkGetMoltenVKConfigurationMVK(
  * to retrieve the current configuration, make changes, and call
  * vkSetMoltenVKConfigurationMVK() to update all of the values.
  *
- * The VkInstance object you provide here is ignored, and a VK_NULL_HANDLE value can be provided.
- * This function can be called before the VkInstance has been created. It is safe to call this function
- * with a VkInstance retrieved from a different layer in the Vulkan SDK Loader and Layers framework.
- *
  * To be active, some configuration settings must be set before a VkInstance or VkDevice
  * is created. See the description of the MVKConfiguration members for more information.
  *
@@ -1000,8 +991,7 @@ VKAPI_ATTR VkResult VKAPI_CALL vkGetMoltenVKConfigurationMVK(
  * to NULL. In that case, this function will set *pConfigurationSize to the size that MoltenVK
  * expects MVKConfiguration to be.
  */
-VKAPI_ATTR VkResult VKAPI_CALL vkSetMoltenVKConfigurationMVK(
- VkInstance ignored,
+VKAPI_ATTR VkResult VKAPI_CALL vkSetMoltenVKConfiguration2MVK(
  const MVKConfiguration* pConfiguration,
  size_t* pConfigurationSize);
 

MoltenVK/MoltenVK/API/mvk_deprecated_api.h

@@ -23,21 +23,17 @@
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
- 
-#include <vulkan/vulkan.h>
+
+#include <MoltenVK/mvk_config.h>
 #include <IOSurface/IOSurfaceRef.h>
 
- 
+
 #define VK_MVK_MOLTENVK_SPEC_VERSION 37
 #define VK_MVK_MOLTENVK_EXTENSION_NAME "VK_MVK_moltenvk"
 
-#define MVK_DEPRECATED VKAPI_ATTR [[deprecated]]
-#define MVK_DEPRECATED_USE_MTL_OBJS VKAPI_ATTR [[deprecated("Use the VK_EXT_metal_objects extension instead.")]]
-
-
 /**
- * This header contains obsolete and deprecated MoltenVK functions, that were origionally
- * part of the obsolete and deprecated private VK_MVK_moltenvk extension.
+ * This header contains obsolete and deprecated MoltenVK functions, that were originally
+ * part of the obsolete and deprecated non-standard VK_MVK_moltenvk extension.
  *
  * NOTE: USE OF THE FUNCTIONS BELOW IS NOT RECOMMENDED. THE VK_MVK_moltenvk EXTENSION,
  * AND THE FUNCTIONS BELOW ARE NOT SUPPORTED BY THE VULKAN LOADER AND LAYERS.
@@ -53,6 +49,8 @@ extern "C" {
 #pragma mark -
 #pragma mark Function types
 
+typedef VkResult (VKAPI_PTR *PFN_vkGetMoltenVKConfigurationMVK)(VkInstance ignored, MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
+typedef VkResult (VKAPI_PTR *PFN_vkSetMoltenVKConfigurationMVK)(VkInstance ignored, const MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
 typedef void (VKAPI_PTR *PFN_vkGetVersionStringsMVK)(char* pMoltenVersionStringBuffer, uint32_t moltenVersionStringBufferLength, char* pVulkanVersionStringBuffer, uint32_t vulkanVersionStringBufferLength);
 typedef void (VKAPI_PTR *PFN_vkSetWorkgroupSizeMVK)(VkShaderModule shaderModule, uint32_t x, uint32_t y, uint32_t z);
 typedef VkResult (VKAPI_PTR *PFN_vkUseIOSurfaceMVK)(VkImage image, IOSurfaceRef ioSurface);
@@ -72,20 +70,41 @@ typedef void (VKAPI_PTR *PFN_vkGetMTLCommandQueueMVK)(VkQueue queue, id<MTLComma
 
 #ifndef VK_NO_PROTOTYPES
 
+#define MVK_DEPRECATED VKAPI_ATTR [[deprecated]]
+#define MVK_DEPRECATED_USE_MTL_OBJS VKAPI_ATTR [[deprecated("Use the VK_EXT_metal_objects extension instead.")]]
+
+
+/** DEPRECATED. Identical functionality to vkGetMoltenVKConfiguration2MVK(). */
+VKAPI_ATTR [[deprecated("Use vkGetMoltenVKConfiguration2MVK() instead.")]]
+VkResult VKAPI_CALL vkGetMoltenVKConfigurationMVK(
+ VkInstance ignored,
+ MVKConfiguration* pConfiguration,
+ size_t* pConfigurationSize);
+
+/** DEPRECATED. Identical functionality to vkSetMoltenVKConfiguration2MVK(). */
+VKAPI_ATTR [[deprecated("Use vkSetMoltenVKConfiguration2MVK() instead.")]]
+VkResult VKAPI_CALL vkSetMoltenVKConfigurationMVK(
+ VkInstance ignored,
+ const MVKConfiguration* pConfiguration,
+ size_t* pConfigurationSize);
+
 /**
+ * DEPRECATED.
  * Returns a human readable version of the MoltenVK and Vulkan versions.
  *
  * This function is provided as a convenience for reporting. Use the MVK_VERSION, 
  * VK_API_VERSION_1_0, and VK_HEADER_VERSION macros for programmatically accessing
  * the corresponding version numbers.
  */
- MVK_DEPRECATED void VKAPI_CALL vkGetVersionStringsMVK(
+MVK_DEPRECATED
+void VKAPI_CALL vkGetVersionStringsMVK(
  char* pMoltenVersionStringBuffer,
  uint32_t moltenVersionStringBufferLength,
  char* pVulkanVersionStringBuffer,
  uint32_t vulkanVersionStringBufferLength);
 
 /**
+ * DEPRECATED.
  * Sets the number of threads in a workgroup for a compute kernel.
  *
  * This needs to be called if you are creating compute shader modules from MSL source code
@@ -94,7 +113,8 @@ typedef void (VKAPI_PTR *PFN_vkGetMTLCommandQueueMVK)(VkQueue queue, id<MTLComma
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
- MVK_DEPRECATED void VKAPI_CALL vkSetWorkgroupSizeMVK(
+MVK_DEPRECATED
+void VKAPI_CALL vkSetWorkgroupSizeMVK(
  VkShaderModule shaderModule,
  uint32_t x,
  uint32_t y,
@@ -103,16 +123,19 @@ typedef void (VKAPI_PTR *PFN_vkGetMTLCommandQueueMVK)(VkQueue queue, id<MTLComma
 #ifdef __OBJC__
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
  * Returns, in the pMTLDevice pointer, the MTLDevice used by the VkPhysicalDevice.
  *
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
-MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLDeviceMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+void VKAPI_CALL vkGetMTLDeviceMVK(
  VkPhysicalDevice physicalDevice,
  id<MTLDevice>* pMTLDevice);
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
  * Sets the VkImage to use the specified MTLTexture.
  *
  * Any differences in the properties of mtlTexture and this image will modify the
@@ -125,43 +148,51 @@ MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLDeviceMVK(
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
-MVK_DEPRECATED_USE_MTL_OBJS VkResult VKAPI_CALL vkSetMTLTextureMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+VkResult VKAPI_CALL vkSetMTLTextureMVK(
  VkImage image,
  id<MTLTexture> mtlTexture);
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
  * Returns, in the pMTLTexture pointer, the MTLTexture currently underlaying the VkImage.
  *
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
-MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLTextureMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+void VKAPI_CALL vkGetMTLTextureMVK(
  VkImage image,
  id<MTLTexture>* pMTLTexture);
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
 * Returns, in the pMTLBuffer pointer, the MTLBuffer currently underlaying the VkBuffer.
 *
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
 */
-MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLBufferMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+void VKAPI_CALL vkGetMTLBufferMVK(
  VkBuffer buffer,
  id<MTLBuffer>* pMTLBuffer);
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
 * Returns, in the pMTLCommandQueue pointer, the MTLCommandQueue currently underlaying the VkQueue.
 *
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
 */
-MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLCommandQueueMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+void VKAPI_CALL vkGetMTLCommandQueueMVK(
  VkQueue queue,
  id<MTLCommandQueue>* pMTLCommandQueue);
 
 #endif // __OBJC__
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
  * Indicates that a VkImage should use an IOSurface to underlay the Metal texture.
  *
  * If ioSurface is not null, it will be used as the IOSurface, and any differences
@@ -188,19 +219,22 @@ MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetMTLCommandQueueMVK(
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
-MVK_DEPRECATED_USE_MTL_OBJS VkResult VKAPI_CALL vkUseIOSurfaceMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+VkResult VKAPI_CALL vkUseIOSurfaceMVK(
  VkImage image,
  IOSurfaceRef ioSurface);
 
 /**
+ * DEPRECATED. Use the VK_EXT_metal_objects extension instead.
  * Returns, in the pIOSurface pointer, the IOSurface currently underlaying the VkImage,
  * as set by the useIOSurfaceMVK() function, or returns null if the VkImage is not using
  * an IOSurface, or if the platform does not support IOSurfaces.
  *
  * This function is not supported by the Vulkan SDK Loader and Layers framework
  * and is unavailable when using the Vulkan SDK Loader and Layers framework.
  */
-MVK_DEPRECATED_USE_MTL_OBJS void VKAPI_CALL vkGetIOSurfaceMVK(
+MVK_DEPRECATED_USE_MTL_OBJS
+void VKAPI_CALL vkGetIOSurfaceMVK(
  VkImage image,
  IOSurfaceRef* pIOSurface);
 

MoltenVK/MoltenVK/API/vk_mvk_moltenvk.h

@@ -18,15 +18,19 @@
 
 /**
  * This header is provided for legacy compatibility only. This header contains obsolete and
- * deprecated MoltenVK functions, that were origionally part of the obsolete and deprecated
- * private VK_MVK_moltenvk extension, and use of this header is not recommended.
+ * deprecated MoltenVK functions, that were originally part of the obsolete and deprecated
+ * non-standard VK_MVK_moltenvk extension, and use of this header is not recommended.
+ *
  * Instead, in your application, use the following header file:
  *
  * #include <MoltenVK/mvk_vulkan.h>
  *
  * And if you require the MoltenVK Configuration API, also include the following header file:
  *
  * #include <MoltenVK/mvk_config.h>
+ *
+ * If you require access to Metal objects underlying equivalent Vulkan objects,
+ * use the standard Vulkan VK_EXT_metal_objects extension.
  */
 
 #include "mvk_vulkan.h"

MoltenVK/MoltenVK/GPUObjects/MVKInstance.mm

@@ -341,11 +341,6 @@
 
  initProcAddrs(); // Init function pointers
 
- setConfigurationResult(verifyLayers(pCreateInfo->enabledLayerCount, pCreateInfo->ppEnabledLayerNames));
- MVKExtensionList* pWritableExtns = (MVKExtensionList*)&_enabledExtensions;
- setConfigurationResult(pWritableExtns->enable(pCreateInfo->enabledExtensionCount,
- pCreateInfo->ppEnabledExtensionNames,
- getDriverLayer()->getSupportedInstanceExtensions()));
  logVersions(); // Log the MoltenVK and Vulkan versions
 
  // Populate the array of physical GPU devices.
@@ -367,6 +362,13 @@
  setConfigurationResult(reportError(VK_ERROR_INCOMPATIBLE_DRIVER, "To support Mac Catalyst, MoltenVK requires macOS 11.0 or above."));
  }
 
+ // Enable extensions after logging the system and GPU info, for any logging done during extension enablement.
+ setConfigurationResult(verifyLayers(pCreateInfo->enabledLayerCount, pCreateInfo->ppEnabledLayerNames));
+ MVKExtensionList* pWritableExtns = (MVKExtensionList*)&_enabledExtensions;
+ setConfigurationResult(pWritableExtns->enable(pCreateInfo->enabledExtensionCount,
+ pCreateInfo->ppEnabledExtensionNames,
+ getDriverLayer()->getSupportedInstanceExtensions()));
+
  MVKLogInfo("Created VkInstance for Vulkan version %s, as requested by app, with the following %d Vulkan extensions enabled:%s",
  mvkGetVulkanVersionString(_appInfo.apiVersion).c_str(),
  _enabledExtensions.getEnabledCount(),
@@ -505,22 +507,24 @@
 #endif
 
  // MoltenVK-specific instannce functions, not tied to a Vulkan API version or an extension.
- ADD_INST_OPEN_ENTRY_POINT(vkGetMoltenVKConfigurationMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkSetMoltenVKConfigurationMVK);
+ ADD_INST_OPEN_ENTRY_POINT(vkGetMoltenVKConfiguration2MVK);
+ ADD_INST_OPEN_ENTRY_POINT(vkSetMoltenVKConfiguration2MVK);
  ADD_INST_OPEN_ENTRY_POINT(vkGetPhysicalDeviceMetalFeaturesMVK);
  ADD_INST_OPEN_ENTRY_POINT(vkGetPerformanceStatisticsMVK);
 
  // For deprecated MoltenVK-specific functions, suppress compiler deprecation warning.
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
- ADD_INST_OPEN_ENTRY_POINT(vkGetVersionStringsMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkGetMTLDeviceMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkSetMTLTextureMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkGetMTLTextureMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkGetMTLBufferMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkUseIOSurfaceMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkGetIOSurfaceMVK);
- ADD_INST_OPEN_ENTRY_POINT(vkGetMTLCommandQueueMVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetMoltenVKConfigurationMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkSetMoltenVKConfigurationMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetVersionStringsMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetMTLDeviceMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkSetMTLTextureMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetMTLTextureMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetMTLBufferMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkUseIOSurfaceMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetIOSurfaceMVK, MVK_MOLTENVK);
+ ADD_INST_EXT_ENTRY_POINT(vkGetMTLCommandQueueMVK, MVK_MOLTENVK);
 #pragma clang diagnostic pop
 
  // Device functions.

MoltenVK/MoltenVK/Layers/MVKExtensions.def

@@ -134,6 +134,7 @@ MVK_EXTENSION(INTEL_shader_integer_functions2, INTEL_SHADER_INTEGER_FUNCTION
 MVK_EXTENSION(GOOGLE_display_timing, GOOGLE_DISPLAY_TIMING, DEVICE, 10.11, 8.0)
 MVK_EXTENSION(MVK_ios_surface, MVK_IOS_SURFACE, INSTANCE, MVK_NA, 8.0)
 MVK_EXTENSION(MVK_macos_surface, MVK_MACOS_SURFACE, INSTANCE, 10.11, MVK_NA)
+MVK_EXTENSION(MVK_moltenvk, MVK_MOLTENVK, INSTANCE, 10.11, 8.0)
 MVK_EXTENSION(NV_fragment_shader_barycentric, NV_FRAGMENT_SHADER_BARYCENTRIC, DEVICE, 10.15, 14.0)
 MVK_EXTENSION_LAST(NV_glsl_shader, NV_GLSL_SHADER, DEVICE, 10.11, 8.0)
 

MoltenVK/MoltenVK/Layers/MVKExtensions.mm

@@ -19,6 +19,7 @@
 #include "MVKExtensions.h"
 #include "MVKFoundation.h"
 #include "MVKOSExtensions.h"
+#include "mvk_deprecated_api.h"
 #include <vulkan/vulkan_ios.h>
 #include <vulkan/vulkan_macos.h>
 
@@ -164,6 +165,11 @@ static bool mvkIsSupportedOnPlatform(VkExtensionProperties* pProperties) {
  result = reportError(VK_ERROR_EXTENSION_NOT_PRESENT, "Vulkan extension %s is not supported.", extnName);
  } else {
  enable(extnName);
+ if (mvkStringsAreEqual(extnName, VK_MVK_MOLTENVK_EXTENSION_NAME)) {
+ reportMessage(MVK_CONFIG_LOG_LEVEL_WARNING, "Extension %s is deprecated. For access to Metal objects, use extension %s. "
+ "For MoltenVK configuration, use the global vkGetMoltenVKConfiguration2MVK() and vkSetMoltenVKConfiguration2MVK() functions.",
+ VK_MVK_MOLTENVK_EXTENSION_NAME, VK_EXT_METAL_OBJECTS_EXTENSION_NAME);
+ }
  }
  }
  return result;