// Copyright 2023-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_layer_settings.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2023-09-23
*IP Status*::
    No known IP claims.
*Contributors*::
  - Christophe Riccio, LunarG
  - Mark Lobodzinski, LunarG
  - Charles Giessen, LunarG
  - Spencer Fricke, LunarG
  - Juan Ramos, LunarG
  - Daniel Rakos, RasterGrid
  - Shahbaz Youssefi, Google
  - Lina Versace, Google
  - Bill Hollings, The Brenwill Workshop
  - Jon Leech, Khronos
  - Tom Olson, Arm

=== Description

This extension provides a mechanism for configuring programmatically through
the Vulkan API the behavior of layers.

This extension provides the slink:VkLayerSettingsCreateInfoEXT struct that
can be included in the pname:pNext chain of the slink:VkInstanceCreateInfo
structure passed as the pname:pCreateInfo parameter of
flink:vkCreateInstance.

The structure contains an array of slink:VkLayerSettingEXT structure values
that configure specific features of layers.

=== Example

`VK_EXT_layer_settings` is implemented by the Vulkan Profiles layer.

It allows the profiles layer tests used by the profiles layer C.I.
to programmatically configure the layer for each test without affecting the
C.I.
environment, allowing to run multiple tests concurrently.

[source,c++]
----
const char* profile_file_data = JSON_TEST_FILES_PATH "VP_KHR_roadmap_2022.json";
const char* profile_name_data = "VP_KHR_roadmap_2022";
VkBool32 emulate_portability_data = VK_TRUE;
const char* simulate_capabilities[] = {
    "SIMULATE_API_VERSION_BIT",
    "SIMULATE_FEATURES_BIT",
    "SIMULATE_PROPERTIES_BIT",
    "SIMULATE_EXTENSIONS_BIT",
    "SIMULATE_FORMATS_BIT",
    "SIMULATE_QUEUE_FAMILY_PROPERTIES_BIT"
};
const char* debug_reports[] = {
    "DEBUG_REPORT_ERROR_BIT",
    "DEBUG_REPORT_WARNING_BIT",
    "DEBUG_REPORT_NOTIFICATION_BIT",
    "DEBUG_REPORT_DEBUG_BIT"
};

const VkLayerSettingEXT settings[] = {
     {kLayerName, kLayerSettingsProfileFile, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_file_data},
     {kLayerName, kLayerSettingsProfileName, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_name_data},
     {kLayerName, kLayerSettingsEmulatePortability, VK_LAYER_SETTING_TYPE_BOOL32_EXT, 1, &emulate_portability_data},
     {kLayerName, kLayerSettingsSimulateCapabilities, VK_LAYER_SETTING_TYPE_STRING_EXT, 
        static_cast<uint32_t>(std::size(simulate_capabilities)), simulate_capabilities},
     {kLayerName, kLayerSettingsDebugReports, VK_LAYER_SETTING_TYPE_STRING_EXT,
        static_cast<uint32_t>(std::size(debug_reports)), debug_reports}
};

const VkLayerSettingsCreateInfoEXT layer_settings_create_info{
    VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT, nullptr,
    static_cast<uint32_t>(std::size(settings)), settings};

VkInstanceCreateInfo inst_create_info = {};
... 
inst_create_info.pNext = &layer_settings_create_info;
vkCreateInstance(&inst_create_info, nullptr, &_instances);
----

[NOTE]
.Note
====
The `apiext:VK_EXT_layer_settings` extension subsumes all the functionality
provided in the `apiext:VK_EXT_validation_flags` extension and the
`apiext:VK_EXT_validation_features` extension.
====

include::{generated}/interfaces/VK_EXT_layer_settings.adoc[]

=== Issues

  * How should application developers figure out the list of available
    settings?

This extension does not provide a reflection API for layer settings.
Layer settings are described in each layer JSON manifest and the
documentation of each layer which implements this extension.

=== Version History

  * Revision 1, 2020-06-17 (Mark Lobodzinski)
  ** Initial revision for Validation layer internal usages
  * Revision 2, 2023-09-26 (Christophe Riccio)
  ** Refactor APIs for any layer usages and public release