Add Layer Settings API to framework, improve batch mode error recovery, fix macOS issues (#1084)

* Add infrastructure to support Vulkan layer settings extension and API

* shader_debugprintf: Enable debugPrintfEXT using layer settings API vs. create_instance() custom override

* descriptor_indexing: On macOS enable Metal Argument Buffers via layer settings and work-around variable descriptor counts

* Fix CMakeLists.txt find dxc logic - check for Vulkan_dxc_EXECUTABLE not DEFINED Vulkan_dxc_EXECUTABLE

* Enable VK_ENABLE_BETA_EXTENSIONS on Apple platforms for VK_KHR_portability_subset extension and features

* Batch mode: Reset target environment to default prior to each sample; permit VK_SUBOPTIMAL_KHR

* Don't create app bundle on macOS in order to match build/run documentation

* Add .DS_Store to .gitignore for macOS cleanliness

* shader_debugprintf: Override get_validation_layers() and allow layer settings to work with Release builds

* Batch mode: Improve error recovery by using throw std::runtime_error() vs. ExitCode::FatalError

* Batch mode: Improve error recovery for async_compute, fragment_shader_barycentric, and texture_mipmap_generation samples

* CMakeLists: Move project() definition before find_package(Vulkan) to setup platform default search paths for dxc

* Remove HLSL shader compilation warning when VULKAN_SDK is not found

* Modify macOS run documentation to include possibilty of arm64 hosts

* shader_debugprintf: Check for VK_EXT_layer_settings at runtime for backwards compatibilty with older SDKs

* Fix CI warnings for Doxygen and Copyright dates

* Fix CI warnings for files identified by clang-format

* Incorporate initial feedback from @asuessenbach

* Remove #if defined(VK_EXT_layer_settings) guards from layer settings code

* pipeline_cache sample: Replace VK_CHECK in destructor with explicit error handling and logging

* descriptor_indexing and shader_debugprintf: Small changes to support older Vulkan SDKs

* Incorporate subsequent feedback from @asuessenbach

* Try to fix clang-format issues with async_compute.cpp and pipeline_cache.cpp

* Use VKB_ENABLE_PORTABILITY vs. VK_ENABLE_BETA_EXTENSIONS to guard portability subset features

* Remove duplicates and reuse runtime checks for VK_KHR_portability_enumeration

* Remove descriptor_indexing sample workaround for Apple Vulkan SDKs > 1.3.283

* Update shader_debugprintf README to describe layer settings method of enabling debugPrintfEXT

* Use Vulkan_dxc_exe_FOUND where possible, use Vulkan_dxc_EXECUTABLE in sample_helper.cmake

Author: SRSaunders

.gitignore

@@ -9,6 +9,7 @@ tests/system_test/tmp
 output/*
 .mypy_cache
 tags
+.DS_Store
 
 # vim backup and temp files
 *~

CMakeLists.txt

@@ -34,32 +34,30 @@ endif()
 
 cmake_minimum_required(VERSION 3.16)
 
+project(vulkan_samples)
+
 # search for Vulkan SDK
 find_package(Vulkan)
 
-if(VULKAN_FOUND)
-    if(NOT Vulkan_dxc_EXECUTABLE)
+if(Vulkan_FOUND)
+    if(NOT Vulkan_dxc_exe_FOUND)
         find_program(Vulkan_dxc_EXECUTABLE
                     NAMES dxc
                     HINTS
                     "$ENV{VULKAN_SDK}/Bin"
                     "$ENV{VULKAN_SDK}/bin"
                     )
     endif()
-    if(DEFINED Vulkan_dxc_EXECUTABLE)
-        message("Found DirectX Shader Compiler under ${Vulkan_dxc_EXECUTABLE}")
-    elseif()
-        message("Couldn't find DirectX Shader Compiler executable, make sure it is present in Vulkan SDK or add it manually via Vulkan_dxc_EXECUTABLE env variable")
+    if(Vulkan_dxc_EXECUTABLE)
+        message(STATUS "Found DirectX Shader Compiler under ${Vulkan_dxc_EXECUTABLE}")
+    else()
+        message(STATUS "Couldn't find DirectX Shader Compiler executable, make sure it is present in Vulkan SDK or add it manually via Vulkan_dxc_EXECUTABLE cmake variable. HLSL shaders won't be compiled.")
     endif()
-else()
-    message("VULKAN_SDK path not found, HLSL shaders won't be compiled")
 endif()
 
 # globally add VKB_DEBUG for the debug build
 add_compile_definitions($<$<CONFIG:DEBUG>:VKB_DEBUG>)
 
-project(vulkan_samples)
-
 if(MSVC AND (DEFINED CMAKE_C_COMPILER_LAUNCHER))
     message(DEBUG "Setting MSVC flags to /Z7 for ccache compatibility.  Current flags: ${CMAKE_CXX_FLAGS_DEBUG}")
     string(REPLACE "/Zi" "/Z7" CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG}")

app/CMakeLists.txt

@@ -41,17 +41,15 @@ if(ANDROID)
     endif()
 
     add_library(${PROJECT_NAME} SHARED ${SRC})
-elseif (APPLE)
-    if(IOS)
-        list(REMOVE_AT SRC 0)
-        list(APPEND SRC
-                ${CMAKE_CURRENT_SOURCE_DIR}/ios/main.mm
-                ${CMAKE_CURRENT_SOURCE_DIR}/ios/AppDelegate.h
-                ${CMAKE_CURRENT_SOURCE_DIR}/ios/AppDelegate.m
-                ${CMAKE_CURRENT_SOURCE_DIR}/ios/ViewController.h
-                ${CMAKE_CURRENT_SOURCE_DIR}/ios/ViewController.mm
-        )
-    endif ()
+elseif(IOS)
+	list(REMOVE_AT SRC 0)
+	list(APPEND SRC
+			${CMAKE_CURRENT_SOURCE_DIR}/ios/main.mm
+			${CMAKE_CURRENT_SOURCE_DIR}/ios/AppDelegate.h
+			${CMAKE_CURRENT_SOURCE_DIR}/ios/AppDelegate.m
+			${CMAKE_CURRENT_SOURCE_DIR}/ios/ViewController.h
+			${CMAKE_CURRENT_SOURCE_DIR}/ios/ViewController.mm
+	)
     add_executable(${PROJECT_NAME} MACOSX_BUNDLE ${SRC})
 else()
     add_executable(${PROJECT_NAME} WIN32 ${SRC})

bldsys/cmake/global_options.cmake

@@ -33,15 +33,10 @@ endif()
 
 if(APPLE)
     cmake_minimum_required(VERSION 3.24)
+    set(VKB_ENABLE_PORTABILITY ON CACHE BOOL "Enable portability enumeration and subset features in the framework.  This is required to be set when running on Apple platforms." FORCE)
 if(IOS)
     set(CMAKE_XCODE_GENERATE_SCHEME TRUE)
-endif ()
-    find_package(Vulkan)
-    if(Vulkan_VERSION GREATER_EQUAL 1.3)
-        set(VKB_ENABLE_PORTABILITY ON CACHE BOOL "Enable portability extension enumeration in the framework.  This is required to be set if running MoltenVK and Vulkan 1.3+" FORCE)
-    else()
-        set(VKB_ENABLE_PORTABILITY OFF CACHE BOOL "Enable portability extension enumeration in the framework.  This is required to be off if running Vulkan less than 1.3" FORCE)
-    endif()
+endif()
 endif()
 
 set(VKB_WARNINGS_AS_ERRORS ON CACHE BOOL "Enable Warnings as Errors")

bldsys/cmake/sample_helper.cmake

@@ -197,7 +197,7 @@ endif()
         set_target_properties(${PROJECT_NAME} PROPERTIES CXX_CLANG_TIDY "${VKB_DO_CLANG_TIDY}")
     endif()
 
-    if(DEFINED Vulkan_dxc_EXECUTABLE AND DEFINED SHADERS_HLSL)
+    if(Vulkan_dxc_EXECUTABLE AND DEFINED SHADERS_HLSL)
         compile_hlsl_shaders(
             SHADERS_HLSL ${TARGET_SHADERS_HLSL}
             DXC_ADDITIONAL_ARGUMENTS ${TARGET_DXC_ADDITIONAL_ARGUMENTS}

docs/build.adoc

@@ -273,7 +273,7 @@ cmake --build build/mac --config Release --target vulkan_samples -j4
 `Step 3.` Run the *Vulkan Samples* application to display the help message
 
 ----
-./build/mac/app/bin/Release/x86_64/vulkan_samples --help
+./build/mac/app/bin/Release/<x86_64|arm64>/vulkan_samples --help
 ----
 
 == iOS

framework/CMakeLists.txt

@@ -501,7 +501,7 @@ if(${VKB_VULKAN_DEBUG})
 endif()
 
 if(${VKB_ENABLE_PORTABILITY})
-    message(STATUS "Vulkan Portability extension is enabled")
+    message(STATUS "Vulkan Portability Enumeration and Portability Subset extensions are enabled")
     target_compile_definitions(${PROJECT_NAME} PUBLIC VKB_ENABLE_PORTABILITY)
 endif()
 

framework/common/error.h

@@ -54,15 +54,14 @@ class VulkanException : public std::runtime_error
 }        // namespace vkb
 
 /// @brief Helper macro to test the result of Vulkan calls which can return an error.
-#define VK_CHECK(x)                                                 \
-	do                                                              \
-	{                                                               \
-		VkResult err = x;                                           \
-		if (err)                                                    \
-		{                                                           \
-			LOGE("Detected Vulkan error: {}", vkb::to_string(err)); \
-			abort();                                                \
-		}                                                           \
+#define VK_CHECK(x)                                                                    \
+	do                                                                                 \
+	{                                                                                  \
+		VkResult err = x;                                                              \
+		if (err)                                                                       \
+		{                                                                              \
+			throw std::runtime_error("Detected Vulkan error: " + vkb::to_string(err)); \
+		}                                                                              \
 	} while (0)
 
 #define ASSERT_VK_HANDLE(handle)        \

framework/common/strings.cpp

@@ -686,6 +686,13 @@ const std::string to_string(VkResult result)
 		STR(ERROR_INCOMPATIBLE_DRIVER);
 		STR(ERROR_TOO_MANY_OBJECTS);
 		STR(ERROR_FORMAT_NOT_SUPPORTED);
+		STR(ERROR_FRAGMENTED_POOL);
+		STR(ERROR_UNKNOWN);
+		STR(ERROR_OUT_OF_POOL_MEMORY);
+		STR(ERROR_INVALID_EXTERNAL_HANDLE);
+		STR(ERROR_FRAGMENTATION);
+		STR(ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS);
+		STR(PIPELINE_COMPILE_REQUIRED);
 		STR(ERROR_SURFACE_LOST_KHR);
 		STR(ERROR_NATIVE_WINDOW_IN_USE_KHR);
 		STR(SUBOPTIMAL_KHR);

framework/core/hpp_instance.cpp

@@ -186,6 +186,7 @@ bool enable_all_extensions(const std::vector<const char *>             required_
 HPPInstance::HPPInstance(const std::string                            &application_name,
                          const std::unordered_map<const char *, bool> &required_extensions,
                          const std::vector<const char *>              &required_validation_layers,
+                         const std::vector<vk::LayerSettingEXT>       &required_layer_settings,
                          bool                                          headless,
                          uint32_t                                      api_version)
 {
@@ -211,7 +212,7 @@ HPPInstance::HPPInstance(const std::string                            &applicati
 
 #if (defined(VKB_ENABLE_PORTABILITY))
 	enable_extension(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME, available_instance_extensions, enabled_extensions);
-	enable_extension(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME, available_instance_extensions, enabled_extensions);
+	bool portability_enumeration_available = enable_extension(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME, available_instance_extensions, enabled_extensions);
 #endif
 
 #ifdef USE_VALIDATION_LAYER_FEATURES
@@ -326,7 +327,10 @@ HPPInstance::HPPInstance(const std::string                            &applicati
 #endif
 
 #if (defined(VKB_ENABLE_PORTABILITY))
-	instance_info.flags |= vk::InstanceCreateFlagBits::eEnumeratePortabilityKHR;
+	if (portability_enumeration_available)
+	{
+		instance_info.flags |= vk::InstanceCreateFlagBits::eEnumeratePortabilityKHR;
+	}
 #endif
 
 #ifdef USE_VALIDATION_LAYER_FEATURES
@@ -347,6 +351,17 @@ HPPInstance::HPPInstance(const std::string                            &applicati
 	}
 #endif
 
+	vk::LayerSettingsCreateInfoEXT layerSettingsCreateInfo;
+
+	// If layer settings extension enabled by sample, then activate layer settings during instance creation
+	if (std::find(enabled_extensions.begin(), enabled_extensions.end(), VK_EXT_LAYER_SETTINGS_EXTENSION_NAME) != enabled_extensions.end())
+	{
+		layerSettingsCreateInfo.settingCount = static_cast<uint32_t>(required_layer_settings.size());
+		layerSettingsCreateInfo.pSettings    = required_layer_settings.data();
+		layerSettingsCreateInfo.pNext        = instance_info.pNext;
+		instance_info.pNext                  = &layerSettingsCreateInfo;
+	}
+
 	// Create the Vulkan instance
 	handle = vk::createInstance(instance_info);