1// Copyright 2023-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= VK_EXT_layer_settings 6 7:toc: left 8:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ 9:sectnums: 10 11Adds an extension that allows applications to provide layer settings to any layers implementing the 12extension during instance creation. 13 14== Problem Statement 15 16Typically, Vulkan layers can be configured using either environment variables or the vk_layer_settings.txt file. 17Alternatively, the Vulkan validation layer can be configure programmatically using the `VK_EXT_validation_features`. 18 19`VK_EXT_validation_features` enables configuring the validation layer at instance creation time which allows running 20multiple Vulkan instances in parallel with different layer setting values for each Vulkan instance. A use case is 21C.I., providing shorter runs. 22 23However, the `VK_EXT_validation_features` extension has multiple issues: 24 * The `VK_EXT_validation_features` extension is dedicated to the validation layer exposing explicitly each validation 25layer feature. 26 * Each time a new validation layer feature is implemented (which is quite often), the validation layer developer 27should theoretically create a new extension to expose the new feature. 28 * Each layer that would want to expose layer settings programmatically would need to create Vulkan extensions. 29 * Not all layer developers are Khronos members, preventing them or at least making it difficult to submit extensions. 30 31== Proposal 32 33The goal of `VK_EXT_layer_settings` is to provide a generic mechanism to configure layer settings programmatically, 34a single extension that could be implemented by any layer. It is currently implemented by the validation layer, the 35profiles layer, the API dump layer, the screenshot layer, the memory decompression layer, the synchronization 2 layer 36and the shader object layer. 37 38The intent of the extension is to be implemented in any layer that has settings to provide a consistent method across 39layers. 40 41`VK_EXT_layer_settings` extends the `pNext` chain of link:{refpage}VkInstanceCreateInfo.html[VkInstanceCreateInfo] to 42provide a list of structures which contain the information needed by the layers to configure their settings. 43 44Each setting is built around a basic type (bool32, int32, int64, uint32, uint64, float32, float64 and strings) which 45can be an array. This restricts how settings are expressed, if the intent of the layer developer for a setting is a 46structure, then the structure will be split into multiple settings, one for each member. 47 48This approach is designed to be compatible with existing alternative methods to configure layer settings: 49 * Environment variables 50 * vk_layer_settings.txt (hand-written or generated by Vulkan Configurator) 51 52All three methods are implemented by the *Vulkan Layer Settings library* which can be easily integrated in any layer code 53base to provide a consistent design across layers. 54 55[source,c] 56---- 57typedef enum VkLayerSettingTypeEXT { 58 VK_LAYER_SETTING_TYPE_BOOL32_EXT = 0, 59 VK_LAYER_SETTING_TYPE_INT32_EXT, 60 VK_LAYER_SETTING_TYPE_INT64_EXT, 61 VK_LAYER_SETTING_TYPE_UINT32_EXT, 62 VK_LAYER_SETTING_TYPE_UINT64_EXT, 63 VK_LAYER_SETTING_TYPE_FLOAT32_EXT, 64 VK_LAYER_SETTING_TYPE_FLOAT64_EXT, 65 VK_LAYER_SETTING_TYPE_STRING_EXT 66} VkLayerSettingTypeEXT; 67 68typedef struct VkLayerSettingEXT { 69 const char *pLayerName; 70 const char *pSettingName; 71 VkLayerSettingTypeEXT type; 72 uint32_t count; 73 const void *pValues; 74} VkLayerSettingEXT; 75 76typedef struct VkLayerSettingsCreateInfoEXT { 77 VkStructureType sType; 78 const void *pNext; 79 uint32_t settingCount; 80 const VkLayerSettingEXT *pSettings; 81} VkLayerSettingsCreateInfoEXT; 82---- 83 84== Example Usage 85 86This example shows a typical usage to configure the Profiles layer programmatically, 87here clamping the system capabilities to the Vulkan Roadmap 2022 profile set of capabilities. 88 89[source,c] 90---- 91const char* profile_file_data = JSON_TEST_FILES_PATH "VP_KHR_roadmap_2022.json"; 92const char* profile_name_data = "VP_KHR_roadmap_2022"; 93VkBool32 emulate_portability_data = VK_TRUE; 94const char* simulate_capabilities[] = { 95 "SIMULATE_API_VERSION_BIT", 96 "SIMULATE_FEATURES_BIT", 97 "SIMULATE_PROPERTIES_BIT", 98 "SIMULATE_EXTENSIONS_BIT", 99 "SIMULATE_FORMATS_BIT", 100 "SIMULATE_QUEUE_FAMILY_PROPERTIES_BIT" 101}; 102const char* debug_reports[] = { 103 "DEBUG_REPORT_ERROR_BIT", 104 "DEBUG_REPORT_WARNING_BIT", 105 "DEBUG_REPORT_NOTIFICATION_BIT", 106 "DEBUG_REPORT_DEBUG_BIT" 107}; 108 109const VkLayerSettingEXT settings[] = { 110 {kLayerName, kLayerSettingsProfileFile, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_file_data}, 111 {kLayerName, kLayerSettingsProfileName, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_name_data}, 112 {kLayerName, kLayerSettingsEmulatePortability, VK_LAYER_SETTING_TYPE_BOOL32_EXT, 1, &emulate_portability_data}, 113 {kLayerName, kLayerSettingsSimulateCapabilities, VK_LAYER_SETTING_TYPE_STRING_EXT, 114 static_cast<uint32_t>(std::size(simulate_capabilities)), simulate_capabilities}, 115 {kLayerName, kLayerSettingsDebugReports, VK_LAYER_SETTING_TYPE_STRING_EXT, 116 static_cast<uint32_t>(std::size(debug_reports)), debug_reports} 117}; 118 119const VkLayerSettingsCreateInfoEXT layer_settings_create_info{ 120 VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT, nullptr, 121 static_cast<uint32_t>(std::size(settings)), settings}; 122 123VkInstanceCreateInfo inst_create_info = {}; 124... 125inst_create_info.pNext = &layer_settings_create_info; 126vkCreateInstance(&inst_create_info, nullptr, &_instances); 127---- 128 129== Issues 130 131=== RESOLVED: Should the extension provide a query to list the layers settings? 132 133No, deferred to a separated extension is necessary. 134 135Typically, just like any Vulkan extension, to use a setting, this setting must be understood by the 136Vulkan application developer because they affect the behavior of the application. So simply querying 137the settings list is not a relevant use case for an application developer. Basically, just like 138enabling the raytracing extensions also requires implementation of raytracing by the application. 139 140Most importantly, we want the layer developers to be responsible of maintening layer settings 141compatibility between layer versions instead of the application developers. This approach would ensure 142for Vulkan application developer that layers remain easy to use, to upgrade and to support across 143versions. 144 145Finally, there is the problem that the query would be an instance level extension that would require 146a Vulkan Loader change to be exposed. Hence, up to date loader version on the system running the layer 147to be able to expose the extension... This may or may not be an issue depending on the use cases and 148platforms. Consequently, if some relevant use cases for a query API are identified, we should create 149a dedicated extension so that VK_EXT_layer_settings would be expose and the dedicated extension would 150be expose only when the Vulkan loader is up to date. 151 152=== RESOLVED: Should this extension deprecate `VK_EXT_validation_features`? 153 154The validation layer implements both `VK_EXT_layer_settings` and `VK_EXT_validation_features` for 155backward compatibility and there is no plan to remove `VK_EXT_validation_features` yet. 156 157