1// Copyright 2023-2024 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_EXT_layer_settings.adoc[]
6
7=== Other Extension Metadata
8
9*Last Modified Date*::
10    2023-09-23
11*IP Status*::
12    No known IP claims.
13*Contributors*::
14  - Christophe Riccio, LunarG
15  - Mark Lobodzinski, LunarG
16  - Charles Giessen, LunarG
17  - Spencer Fricke, LunarG
18  - Juan Ramos, LunarG
19  - Daniel Rakos, RasterGrid
20  - Shahbaz Youssefi, Google
21  - Lina Versace, Google
22  - Bill Hollings, The Brenwill Workshop
23  - Jon Leech, Khronos
24  - Tom Olson, Arm
25
26=== Description
27
28This extension provides a mechanism for configuring programmatically through
29the Vulkan API the behavior of layers.
30
31This extension provides the slink:VkLayerSettingsCreateInfoEXT struct that
32can be included in the pname:pNext chain of the slink:VkInstanceCreateInfo
33structure passed as the pname:pCreateInfo parameter of
34flink:vkCreateInstance.
35
36The structure contains an array of slink:VkLayerSettingEXT structure values
37that configure specific features of layers.
38
39=== Example
40
41`VK_EXT_layer_settings` is implemented by the Vulkan Profiles layer.
42
43It allows the profiles layer tests used by the profiles layer C.I.
44to programmatically configure the layer for each test without affecting the
45C.I.
46environment, allowing to run multiple tests concurrently.
47
48[source,c++]
49----
50const char* profile_file_data = JSON_TEST_FILES_PATH "VP_KHR_roadmap_2022.json";
51const char* profile_name_data = "VP_KHR_roadmap_2022";
52VkBool32 emulate_portability_data = VK_TRUE;
53const char* simulate_capabilities[] = {
54    "SIMULATE_API_VERSION_BIT",
55    "SIMULATE_FEATURES_BIT",
56    "SIMULATE_PROPERTIES_BIT",
57    "SIMULATE_EXTENSIONS_BIT",
58    "SIMULATE_FORMATS_BIT",
59    "SIMULATE_QUEUE_FAMILY_PROPERTIES_BIT"
60};
61const char* debug_reports[] = {
62    "DEBUG_REPORT_ERROR_BIT",
63    "DEBUG_REPORT_WARNING_BIT",
64    "DEBUG_REPORT_NOTIFICATION_BIT",
65    "DEBUG_REPORT_DEBUG_BIT"
66};
67
68const VkLayerSettingEXT settings[] = {
69     {kLayerName, kLayerSettingsProfileFile, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_file_data},
70     {kLayerName, kLayerSettingsProfileName, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_name_data},
71     {kLayerName, kLayerSettingsEmulatePortability, VK_LAYER_SETTING_TYPE_BOOL32_EXT, 1, &emulate_portability_data},
72     {kLayerName, kLayerSettingsSimulateCapabilities, VK_LAYER_SETTING_TYPE_STRING_EXT, 
73        static_cast<uint32_t>(std::size(simulate_capabilities)), simulate_capabilities},
74     {kLayerName, kLayerSettingsDebugReports, VK_LAYER_SETTING_TYPE_STRING_EXT,
75        static_cast<uint32_t>(std::size(debug_reports)), debug_reports}
76};
77
78const VkLayerSettingsCreateInfoEXT layer_settings_create_info{
79    VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT, nullptr,
80    static_cast<uint32_t>(std::size(settings)), settings};
81
82VkInstanceCreateInfo inst_create_info = {};
83... 
84inst_create_info.pNext = &layer_settings_create_info;
85vkCreateInstance(&inst_create_info, nullptr, &_instances);
86----
87
88[NOTE]
89.Note
90====
91The `apiext:VK_EXT_layer_settings` extension subsumes all the functionality
92provided in the `apiext:VK_EXT_validation_flags` extension and the
93`apiext:VK_EXT_validation_features` extension.
94====
95
96include::{generated}/interfaces/VK_EXT_layer_settings.adoc[]
97
98=== Issues
99
100  * How should application developers figure out the list of available
101    settings?
102
103This extension does not provide a reflection API for layer settings.
104Layer settings are described in each layer JSON manifest and the
105documentation of each layer which implements this extension.
106
107=== Version History
108
109  * Revision 1, 2020-06-17 (Mark Lobodzinski)
110  ** Initial revision for Validation layer internal usages
111  * Revision 2, 2023-09-26 (Christophe Riccio)
112  ** Refactor APIs for any layer usages and public release
113