From 06d493dcc1cc7c62425d98830b01af1ab56df142 Mon Sep 17 00:00:00 2001 From: Chip Davis Date: Fri, 29 Dec 2023 04:42:17 -0700 Subject: [PATCH] Add a configuration parameter to control the use of Metal SPIs. With the new `MVK_CONFIG_USE_METAL_PRIVATE_API`, the user can prevent their use at run time without recompiling MoltenVK. This may be useful for troubleshooting purposes. The extra member is because the compiler adds tail padding to make the struct aligned on an 8-byte boundary, so the `static_assert()` fails without it. --- Docs/MoltenVK_Configuration_Parameters.md | 13 +++++++++++++ MoltenVK/MoltenVK/API/mvk_private_api.h | 2 ++ MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm | 2 +- MoltenVK/MoltenVK/Utility/MVKConfigMembers.def | 2 ++ MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp | 3 +++ MoltenVK/MoltenVK/Utility/MVKEnvironment.h | 11 +++++++++++ README.md | 7 ++++--- 7 files changed, 36 insertions(+), 4 deletions(-) diff --git a/Docs/MoltenVK_Configuration_Parameters.md b/Docs/MoltenVK_Configuration_Parameters.md index 8852020f..5e02256d 100644 --- a/Docs/MoltenVK_Configuration_Parameters.md +++ b/Docs/MoltenVK_Configuration_Parameters.md @@ -663,3 +663,16 @@ Determines the style used to implement _Vulkan_ semaphore (`VkSemaphore`) functi In the special case of `VK_SEMAPHORE_TYPE_TIMELINE` semaphores, **MoltenVK** will always use `MTLSharedEvent` if it is available on the platform, regardless of the value of this parameter. + +--------------------------------------- +#### MVK_CONFIG_USE_METAL_PRIVATE_API + +##### Type: Boolean +##### Default: Value of `MVK_USE_METAL_PRIVATE_API` + +If enabled, **MoltenVK** will _use_ private interfaces exposed by _Metal_ to implement _Vulkan_ +features that are difficult to support otherwise. + +Unlike `MVK_USE_METAL_PRIVATE_API`, this setting may be overridden at run time. + +This option is not available unless MoltenVK were built with `MVK_USE_METAL_PRIVATE_API` set to `1`. diff --git a/MoltenVK/MoltenVK/API/mvk_private_api.h b/MoltenVK/MoltenVK/API/mvk_private_api.h index 38ec2f3d..4a6ae35e 100644 --- a/MoltenVK/MoltenVK/API/mvk_private_api.h +++ b/MoltenVK/MoltenVK/API/mvk_private_api.h @@ -240,6 +240,8 @@ typedef struct { MVKConfigCompressionAlgorithm shaderSourceCompressionAlgorithm; /**< MVK_CONFIG_SHADER_COMPRESSION_ALGORITHM */ VkBool32 shouldMaximizeConcurrentCompilation; /**< MVK_CONFIG_SHOULD_MAXIMIZE_CONCURRENT_COMPILATION */ float timestampPeriodLowPassAlpha; /**< MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA */ + VkBool32 useMetalPrivateAPI; /**< MVK_CONFIG_USE_METAL_PRIVATE_API */ + uint32_t _unused_struct_padding; } MVKConfiguration; // Legacy support for renamed struct elements. diff --git a/MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm b/MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm index ac5c38c9..ab4cf58c 100644 --- a/MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm +++ b/MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm @@ -2341,7 +2341,7 @@ void MVKPhysicalDevice::initFeatures() { _features.depthBiasClamp = true; _features.fillModeNonSolid = true; _features.largePoints = true; - _features.wideLines = static_cast(MVK_USE_METAL_PRIVATE_API); + _features.wideLines = getMVKConfig().useMetalPrivateAPI; _features.alphaToOne = true; _features.samplerAnisotropy = true; _features.shaderImageGatherExtended = true; diff --git a/MoltenVK/MoltenVK/Utility/MVKConfigMembers.def b/MoltenVK/MoltenVK/Utility/MVKConfigMembers.def index 82ad7824..88416938 100644 --- a/MoltenVK/MoltenVK/Utility/MVKConfigMembers.def +++ b/MoltenVK/MoltenVK/Utility/MVKConfigMembers.def @@ -81,6 +81,8 @@ MVK_CONFIG_MEMBER(useMetalArgumentBuffers, MVKUseMetalArgumentBuf MVK_CONFIG_MEMBER(shaderSourceCompressionAlgorithm, MVKConfigCompressionAlgorithm, SHADER_COMPRESSION_ALGORITHM) MVK_CONFIG_MEMBER(shouldMaximizeConcurrentCompilation, VkBool32, SHOULD_MAXIMIZE_CONCURRENT_COMPILATION) MVK_CONFIG_MEMBER(timestampPeriodLowPassAlpha, float, TIMESTAMP_PERIOD_LOWPASS_ALPHA) +MVK_CONFIG_MEMBER(useMetalPrivateAPI, VkBool32, USE_METAL_PRIVATE_API) +MVK_CONFIG_MEMBER(_unused_struct_padding, uint32_t, _UNUSED_STRUCT_PADDING) #undef MVK_CONFIG_MEMBER #undef MVK_CONFIG_MEMBER_STRING diff --git a/MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp b/MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp index f8ec3e16..e6b93ff9 100644 --- a/MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp +++ b/MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp @@ -66,6 +66,9 @@ void mvkSetConfig(MVKConfiguration& dstMVKConfig, const MVKConfiguration& srcMVK // Clamp timestampPeriodLowPassAlpha between 0.0 and 1.0. dstMVKConfig.timestampPeriodLowPassAlpha = mvkClamp(dstMVKConfig.timestampPeriodLowPassAlpha, 0.0f, 1.0f); + // Only allow useMetalPrivateAPI to be enabled if we were built with support for it. + dstMVKConfig.useMetalPrivateAPI = dstMVKConfig.useMetalPrivateAPI && MVK_USE_METAL_PRIVATE_API; + // For each string member of the destination MVKConfiguration, store the contents // in a std::string, then repoint the member to the contents of the std::string. #define MVK_CONFIG_MEMBER(member, mbrType, name) diff --git a/MoltenVK/MoltenVK/Utility/MVKEnvironment.h b/MoltenVK/MoltenVK/Utility/MVKEnvironment.h index 295e466a..cab61ac5 100644 --- a/MoltenVK/MoltenVK/Utility/MVKEnvironment.h +++ b/MoltenVK/MoltenVK/Utility/MVKEnvironment.h @@ -348,3 +348,14 @@ void mvkSetConfig(MVKConfiguration& dstMVKConfig, const MVKConfiguration& srcMVK #ifndef MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA # define MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA 1.0 #endif + +/** + * Enable the use of Metal private interfaces, also known as "Service Provider Interfaces" (SPIs), + * to support Vulkan features. Enabled by default if support is included. + */ +#ifndef MVK_CONFIG_USE_METAL_PRIVATE_API +# define MVK_CONFIG_USE_METAL_PRIVATE_API MVK_USE_METAL_PRIVATE_API +#endif + +#undef MVK_CONFIG__UNUSED_STRUCT_PADDING +#define MVK_CONFIG__UNUSED_STRUCT_PADDING 0 diff --git a/README.md b/README.md index 76735c23..d686a33a 100644 --- a/README.md +++ b/README.md @@ -317,9 +317,10 @@ _Vulkan_ API calls as function pointers. ### Accessing _Metal_ Private API calls -You can optionally build **MoltenVK** with access to private _Metal_ API calls. -Doing so will allow **MoltenVK** to extend its functionality by using certain private _Metal_ -API calls, but it will also disqualify the app from being distributed via _Apple_ App Stores. +You can optionally build **MoltenVK** with access to private _Metal_ API calls, also known +as "Service Provider Interfaces" (SPIs). Doing so will allow **MoltenVK** to extend its +functionality by using certain private _Metal_ API calls, but it will also disqualify the +app from being distributed via _Apple_ App Stores. To do so, when building **MoltenVK**, set the build setting `MVK_USE_METAL_PRIVATE_API=1`. This build setting can be set in the `MoltenVK.xcodeproj` *Xcode* project, or it can be