Add sample demonstrating VK_EXT_layer_settings usage #1419
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Copyright (c) 2025-2026, Holochip Inc. | ||
| # | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 the "License"; | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
| # | ||
|
|
||
| get_filename_component(FOLDER_NAME ${CMAKE_CURRENT_LIST_DIR} NAME) | ||
| get_filename_component(PARENT_DIR ${CMAKE_CURRENT_LIST_DIR} PATH) | ||
| get_filename_component(CATEGORY_NAME ${PARENT_DIR} NAME) | ||
|
|
||
| add_sample_with_tags( | ||
| ID ${FOLDER_NAME} | ||
| CATEGORY ${CATEGORY_NAME} | ||
| AUTHOR "Holochip" | ||
| NAME "Layer settings" | ||
| DESCRIPTION "Demonstrates using VK_EXT_layer_settings to configure validation at runtime" | ||
| ) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,191 @@ | ||
| //// | ||
| - Copyright (c) 2026, Holochip Inc | ||
| - | ||
| - SPDX-License-Identifier: Apache-2.0 | ||
| - | ||
| - Licensed under the Apache License, Version 2.0 the "License"; | ||
| - you may not use this file except in compliance with the License. | ||
| - You may obtain a copy of the License at | ||
| - | ||
| - http://www.apache.org/licenses/LICENSE-2.0 | ||
| - | ||
| - Unless required by applicable law or agreed to in writing, software | ||
| - distributed under the License is distributed on an "AS IS" BASIS, | ||
| - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| - See the License for the specific language governing permissions and | ||
| - limitations under the License. | ||
| - | ||
| //// | ||
| ifdef::site-gen-antora[] | ||
| TIP: The source for this sample can be found in the https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/extensions/layer_settings[Khronos Vulkan samples github repository]. | ||
| endif::[] | ||
|
|
||
| = VK_EXT_layer_settings — Configure validation layers programmatically | ||
|
gpx1000 marked this conversation as resolved.
|
||
|
|
||
| This sample demonstrates how to use VK_EXT_layer_settings to configure Vulkan layers (in particular `VK_LAYER_KHRONOS_validation`) directly from your application. Instead of relying on environment variables or JSON files, you can enable features like Best Practices and `debugPrintfEXT`, tune message filtering, or change output settings via code. | ||
|
|
||
| Note: This sample works properly in debug mode and should be viewed in that build configuration. | ||
|
|
||
| == Why use layer settings? | ||
|
|
||
| - Portability and reproducibility: ship settings with the app, not the environment. | ||
| - Fine-grained control: enable/disable individual validation features and categories. | ||
| - Better UX for samples and tools: turn on useful validation features without asking users to edit configs. | ||
|
|
||
| VK_EXT_layer_settings supersedes the older `VK_EXT_validation_features` and `VK_EXT_validation_flags` by offering a general, extensible way to pass settings to any Vulkan layer (not just validation). | ||
|
|
||
| == What this sample does | ||
|
|
||
| - Enables the instance extension `VK_EXT_layer_settings` (optionally). | ||
| - Adds settings for the Khronos validation layer before the Vulkan instance is created: | ||
| ** Enables Best Practices checks. | ||
| ** Enables `debugPrintfEXT` support (so shader `debugPrintf` messages are emitted via validation). | ||
| - Provides an interactive UI with toggleable validation scenarios that demonstrate common mistakes: | ||
| ** *Wrong Buffer Flags*: Creates a buffer with `TRANSFER_DST` usage but binds it as a vertex buffer (missing `VERTEX_BUFFER_BIT`). | ||
| ** *Suboptimal Transitions*: Performs image layout transitions to `GENERAL` instead of more optimal layouts like `COLOR_ATTACHMENT_OPTIMAL`. | ||
| ** *Many Small Allocations*: Creates numerous small memory allocations (512 bytes each) instead of suballocating from larger blocks. | ||
| - Displays validation messages in real-time within the application UI, showing warning counts per scenario and total statistics. | ||
| - Works on all platforms without requiring terminal access to see validation output. | ||
|
|
||
| == How to use this sample | ||
|
|
||
| When you run the sample, you'll see an interactive UI with checkboxes for each validation scenario: | ||
|
|
||
| 1. *Enable scenarios individually*: Check the boxes to activate specific Best Practices violations. | ||
| 2. *Observe validation messages*: Watch the "Recent Validation Messages" section populate with warnings as scenarios trigger. | ||
| 3. *Review statistics*: See warning counts per scenario and total counts at the bottom. | ||
| 4. *Learn from mistakes*: Each scenario demonstrates a real-world mistake that Best Practices validation catches. | ||
|
|
||
| === What each scenario teaches | ||
|
|
||
| *Wrong Buffer Flags*:: | ||
| Demonstrates the importance of declaring correct usage flags at buffer creation time. Using a buffer without the appropriate usage bit (e.g., `VERTEX_BUFFER_BIT`) can lead to undefined behavior or performance issues on some implementations. | ||
|
|
||
| *Suboptimal Transitions*:: | ||
| Shows why choosing the right image layout matters. Transitioning to `GENERAL` layout is legal but often suboptimal—specific layouts like `COLOR_ATTACHMENT_OPTIMAL` or `SHADER_READ_ONLY_OPTIMAL` enable better performance. | ||
|
|
||
| *Many Small Allocations*:: | ||
| Demonstrates why suballocation is important. Creating hundreds of tiny memory allocations wastes resources and can hit driver limits. Use a memory allocator library (like VMA) or implement suballocation. | ||
|
|
||
| == When to use it vs. alternatives | ||
| - Prefer VK_EXT_layer_settings whenever you need to configure validation from within your app (development builds, samples, tools). | ||
| - `VK_EXT_validation_features` and `VK_EXT_validation_flags` are deprecated by layer settings; use those only for legacy purposes. | ||
|
|
||
| == Using VK_EXT_layer_settings | ||
| If you are integrating layer settings directly into your own Vulkan app, the flow is simple: | ||
|
|
||
| 1. Enable validation layers (e.g., "VK_LAYER_KHRONOS_validation"). | ||
| 2. Check that the validation layer advertises the instance extension VK_EXT_layer_settings. | ||
| 3. If available, add VK_EXT_layer_settings to your instance extension list. | ||
| 4. Create one or more VkLayerSettingEXT entries (for example, to enable Best Practices and debugPrintfEXT). | ||
| 5. Chain a VkLayerSettingsCreateInfoEXT with those settings into VkInstanceCreateInfo::pNext. | ||
| 6. Call vkCreateInstance as usual. The layer consumes the settings at instance creation time. | ||
| 7. Optional: Create a VkDebugUtilsMessengerEXT so you can see validation output. | ||
|
|
||
| === Minimal C/C++ example (C API shown) | ||
| [source,cpp] | ||
| ---- | ||
| #include <vulkan/vulkan.h> | ||
| #include <vector> | ||
| #include <cstring> | ||
| #include <ranges> | ||
|
|
||
| static const char *kValidationLayer = "VK_LAYER_KHRONOS_validation"; | ||
|
|
||
| // Helper to check if VK_EXT_layer_settings is advertised by the validation layer | ||
| bool layer_settings_supported() | ||
| { | ||
| uint32_t count = 0; | ||
| vkEnumerateInstanceExtensionProperties(kValidationLayer, &count, nullptr); | ||
| std::vector<VkExtensionProperties> exts(count); | ||
| vkEnumerateInstanceExtensionProperties(kValidationLayer, &count, exts.data()); | ||
| return std::ranges::find_if(exts, [](auto const &e) { | ||
| return std::strcmp(e.extensionName, VK_EXT_LAYER_SETTINGS_EXTENSION_NAME) == 0; | ||
| }) != exts.end(); | ||
| } | ||
|
|
||
| // Helper to check if VK_EXT_validation_features is advertised by the validation layer | ||
| bool validation_features_supported() | ||
| { | ||
| uint32_t count = 0; | ||
| vkEnumerateInstanceExtensionProperties(kValidationLayer, &count, nullptr); | ||
| std::vector<VkExtensionProperties> exts(count); | ||
| vkEnumerateInstanceExtensionProperties(kValidationLayer, &count, exts.data()); | ||
| return std::ranges::find_if(exts, [](auto const &e) { | ||
| return std::strcmp(e.extensionName, VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME) == 0; | ||
| }) != exts.end(); | ||
| } | ||
|
|
||
| VkInstance create_instance_with_layer_settings() | ||
| { | ||
| std::vector<const char *> instance_exts; | ||
| instance_exts.push_back(VK_KHR_SURFACE_EXTENSION_NAME); | ||
| // Add your platform surface extension(s), e.g. VK_KHR_xcb_surface, VK_KHR_win32_surface, etc. | ||
|
|
||
| const char *layers[] = {kValidationLayer}; | ||
|
|
||
| // Prepare layer settings (strings) we want to enable | ||
| static const char *enables[] = { | ||
| "VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT", | ||
| "VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT", | ||
| }; | ||
|
|
||
| // One setting object that enables both features above | ||
| VkLayerSettingEXT setting{}; | ||
| setting.pLayerName = kValidationLayer; | ||
| setting.pSettingName = "enables"; // well-known name used by VVL | ||
| setting.type = VK_LAYER_SETTING_TYPE_STRING_EXT; // string list | ||
| setting.valueCount = static_cast<uint32_t>(std::size(enables)); | ||
| setting.pValues = enables; // const char* array | ||
|
|
||
| VkLayerSettingsCreateInfoEXT layer_settings_ci{VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT}; | ||
| layer_settings_ci.settingCount = 1; | ||
| layer_settings_ci.pSettings = &setting; | ||
|
|
||
| // Build instance create info and chain layer settings if supported | ||
| VkInstanceCreateInfo ici{VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO}; | ||
| ici.ppEnabledLayerNames = layers; | ||
| ici.enabledLayerCount = 1; | ||
| ici.ppEnabledExtensionNames = instance_exts.data(); | ||
| ici.enabledExtensionCount = static_cast<uint32_t>(instance_exts.size()); | ||
|
|
||
| const bool has_layer_settings = layer_settings_supported(); | ||
| const bool has_validation_features = validation_features_supported(); | ||
| if (has_layer_settings) | ||
| { | ||
| // You also need to add VK_EXT_layer_settings to the enabled instance extensions | ||
| instance_exts.push_back(VK_EXT_LAYER_SETTINGS_EXTENSION_NAME); | ||
| ici.ppEnabledExtensionNames = instance_exts.data(); | ||
| ici.enabledExtensionCount = static_cast<uint32_t>(instance_exts.size()); | ||
| ici.pNext = &layer_settings_ci; | ||
| } | ||
| else if (has_validation_features) | ||
| { | ||
| // Fallback for older SDKs: use VK_EXT_validation_features | ||
|
gpx1000 marked this conversation as resolved.
|
||
| static const VkValidationFeatureEnableEXT vfe[] = { | ||
| VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT, | ||
| VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT, | ||
| }; | ||
| static VkValidationFeaturesEXT validation_features{VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT}; | ||
| validation_features.enabledValidationFeatureCount = static_cast<uint32_t>(std::size(vfe)); | ||
| validation_features.pEnabledValidationFeatures = vfe; | ||
| ici.pNext = &validation_features; // no VK_EXT_layer_settings needed for this path | ||
| } | ||
|
|
||
| VkInstance instance = VK_NULL_HANDLE; | ||
| VkResult result = vkCreateInstance(&ici, nullptr, &instance); | ||
| if (result != VK_SUCCESS) | ||
| { | ||
| // Handle error (missing extensions/layers, etc.) | ||
| return VK_NULL_HANDLE; | ||
| } | ||
|
|
||
| return instance; | ||
| } | ||
| ---- | ||
|
|
||
| TIP: debugPrintfEXT only produces messages when your shaders call debugPrintf. See the shader_debugprintf sample for a complete pipeline + shader example that emits messages through validation. | ||
|
|
||
| NOTE: VK_EXT_layer_settings is an instance extension provided by the layer. On some systems it may not be present; the fallback above using VK_EXT_validation_features enables the same categories in a more limited, legacy way. | ||
|
|
||
| CAUTION: Layer settings only affect layers that recognize them. Enabling layer settings without enabling the corresponding layer (e.g., VK_LAYER_KHRONOS_validation) has no effect. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.