Update the layer chapter (#357)

Author: christophe-lunarg

chapters/layers.adoc

@@ -1,4 +1,4 @@
-// Copyright 2019-2022 The Khronos Group, Inc.
+// Copyright 2019-2025 The Khronos Group, Inc.
 // SPDX-License-Identifier: CC-BY-4.0
 
 ifndef::chapters[:chapters:]
@@ -7,18 +7,34 @@ ifndef::images[:images: images/]
 [[layers]]
 = Layers
 
-Layers are optional components that augment the Vulkan system. They can intercept, evaluate, and modify existing Vulkan functions on their way from the application down to the hardware. Layer properties can be queried from an application with link:https://docs.vulkan.org/spec/latest/chapters/extensions.html#vkEnumerateInstanceLayerProperties[vkEnumerateInstanceLayerProperties].
+Layers are optional components that augment the Vulkan system, packaged as shared libraries that get dynamically loaded in by the loader. They can intercept, evaluate, and modify existing Vulkan functions on their way from the application down to the hardware.
 
-== Using Layers
+For example, by design, minimal error checking is done inside a Vulkan driver, link:https://vulkan.lunarg.com/doc/sdk/latest/windows/khronos_validation_layer.html[_Vulkan Validation_ layer] can be used to to assist developers in isolating incorrect usage, and in verifying that applications correctly use the API.
 
-Layers are packaged as shared libraries that get dynamically loaded in by the loader and inserted between it and the application. The two things needed to use layers are the location of the binary files and which layers to enable. The layers to use can be either explicitly enabled by the application or implicitly enabled by telling the loader to use them. More details about implicit and explicit layers can be found in the link:https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderApplicationInterface.md#implicit-vs-explicit-layers[Loader and Layer Interface].
+Layers are packaged as shared libraries that get dynamically loaded in by the loader and inserted between it and the application. 
 
-The link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK] contains a link:https://vulkan.lunarg.com/doc/sdk/latest/windows/layer_configuration.html[layer configuration document] that is very specific to how to discover and configure layers on each of the platforms.
+The layers can be either explicitly enabled or implicitly enabled. More details about implicit and explicit layers can be found in the link:https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderApplicationInterface.md#implicit-vs-explicit-layers[Loader and Layer Interface].
 
-== Vulkan Configurator Tool
+== Configuring Layers
 
-Developers on Windows, Linux, and macOS can use the Vulkan Configurator, vkconfig, to enable explicit layers and disable implicit layers as well as change layer settings from a graphical user interface.
-Please see the link:https://vulkan.lunarg.com/doc/sdk/latest/windows/vkconfig.html[Vulkan Configurator documentation] in the Vulkan SDK for more information on using the Vulkan Configurator.
+A _layers configuration_ consists in two operations:
+- Selecting and ordering layers
+- Configuring each layer themselves using settings
+
+Layers can be configured using three different methods to match specific Vulkan developers' workflows:
+- Using environment variables: link:https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderInterfaceArchitecture.md[Loader environment variables] and link:https://github.com/KhronosGroup/Vulkan-Utility-Libraries/blob/main/docs/layer_configuration.md#layer-settings-environment-variables[per-layer settings environment variables]
+- Using dedicated Vulkan system files: link:https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderSettingsFile.md[`vk_loader_settings.json`] and link:https://github.com/KhronosGroup/Vulkan-Utility-Libraries/blob/main/docs/layer_configuration.md#configuring-the-layers-using-the-settings-file-vk_layer_settingstxt[`vk_layer_settings.txt`]
+- Using the Vulkan API, programmably in the Vulkan application: link:https://docs.vulkan.org/refpages/latest/refpages/source/vkCreateInstance.html[`vkCreateInstance`] and link:https://github.com/KhronosGroup/Vulkan-Utility-Libraries/blob/main/docs/layer_configuration.md#configuring-the-layer-settings-using-vk_ext_layer_settings[`VK_EXT_layer_settings`]
+
+link:https://vulkan.lunarg.com/doc/sdk/latest/windows/vkconfig.html[_Vulkan Configurator_] simplifies the usage of these three methods. Using the graphical user interface, we can create _layers configuration_. The tool automatically create and locate the `vk_loader_settings.json` and `vk_layer_settings.txt` files. It can also be used to generate environment variables scripts and a C++ header library that can be directly included within the Vulkan application code.
+
+The link:https://github.com/KhronosGroup/Vulkan-Utility-Libraries/blob/main/docs/layer_configuration.md[Layer Configuration] document is providing details on layer configuration.
+
+== Layers settings backward compatbility policy
+
+Settings which are unknown by the layer will be ignored independently of the method. It's the responsibility of the layer developer to ensure backward compatibility with previous versions of the layer.
+
+This is to ensure the list of layer settings remain relatively stable across versions and that the responsibility of handling layer backward compatibility doesn't fall on Vulkan application developers as this could quickly become untrackable.
 
 == Device Layers Deprecation
 
@@ -28,26 +44,12 @@ There used to be both instance layers and device layers, but device layers were
 
 Anyone can create a layer as long as it follows the link:https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderApplicationInterface.md#loader-and-layer-interface[loader to layer interface] which is how the loader and layers agree to communicate with each other.
 
-== Platform Variations
-
-The way to load a layer in implicitly varies between loader and platform.
+To ensure consistency and a smooth integration with Vulkan Configurator and other SDK tools, the link:https://github.com/KhronosGroup/Vulkan-Utility-Libraries[Vulkan::LayerSettings] should be used by the layer implementation.
 
-=== Android
+== Android
 
 As of Android P (Android 9 / API level 28), if a device is in a debuggable state such that `getprop ro.debuggable` link:https://cs.android.com/android/platform/superproject/+/android-9.0.0_r1:frameworks/native/vulkan/libvulkan/layers_extensions.cpp;l=454[returns 1], then the loader will look in link:https://cs.android.com/android/platform/superproject/+/android-9.0.0_r1:frameworks/native/vulkan/libvulkan/layers_extensions.cpp;l=67[/data/local/debug/vulkan].
 
 Starting in Android P (Android 9 / API level 28) implicit layers can be link:https://developer.android.com/ndk/guides/graphics/validation-layer#vl-adb[pushed using ADB] if the application was built in debug mode.
 
 There is no way other than the options above to use implicit layers.
-
-=== Linux
-
-The link:https://vulkan.lunarg.com/doc/sdk/latest/linux/layer_configuration.html[Vulkan SDK] explains how to use implicit layers on Linux.
-
-=== MacOS
-
-The link:https://vulkan.lunarg.com/doc/sdk/latest/mac/layer_configuration.html[Vulkan SDK] explains how to use implicit layers on MacOS.
-
-=== Windows
-
-The link:https://vulkan.lunarg.com/doc/sdk/latest/windows/layer_configuration.html[Vulkan SDK] explains how to use implicit layers on Windows.