|
| 1 | +//// |
| 2 | +- Copyright (c) 2025, Holochip Inc. |
| 3 | +- |
| 4 | +- SPDX-License-Identifier: Apache-2.0 |
| 5 | +- |
| 6 | +- Licensed under the Apache License, Version 2.0 the "License"; |
| 7 | +- you may not use this file except in compliance with the License. |
| 8 | +- You may obtain a copy of the License at |
| 9 | +- |
| 10 | +- http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | +- |
| 12 | +- Unless required by applicable law or agreed to in writing, software |
| 13 | +- distributed under the License is distributed on an "AS IS" BASIS, |
| 14 | +- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 | +- See the License for the specific language governing permissions and |
| 16 | +- limitations under the License. |
| 17 | +- |
| 18 | +//// |
| 19 | += VK_KHR_shader_relaxed_extended_instruction — Enable SPIR-V relaxed extended instruction for non-semantic sets |
| 20 | +
|
| 21 | +This sample demonstrates the device feature VK_KHR_shader_relaxed_extended_instruction and how it relates to SPV_KHR_relaxed_extended_instruction in SPIR-V. The SPIR-V extension introduces a new instruction that allows certain forward references in extended instruction sets used by non-semantic information (for example, the NonSemantic.DebugPrintf instruction set used by GL_EXT_debug_printf). In Vulkan, those non-semantic instruction sets are allowed via VK_KHR_shader_non_semantic_info. |
| 22 | + |
| 23 | +== What is it? |
| 24 | +- SPV_KHR_relaxed_extended_instruction adds a SPIR-V mechanism to relax forward‑reference rules for extended instruction sets, specifically for non‑semantic information. |
| 25 | +- VK_KHR_shader_relaxed_extended_instruction is the Vulkan device extension/feature that allows modules using that SPIR‑V extension to be consumed by the driver. |
| 26 | +- This interacts with SPV_KHR_non_semantic_info and VK_KHR_shader_non_semantic_info: the relaxed forward‑reference rule applies to non‑semantic extended instruction sets like `NonSemantic.DebugPrintf`. |
| 27 | + |
| 28 | +The feature is exposed via `VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR` with a single boolean field `shaderRelaxedExtendedInstruction`. |
| 29 | + |
| 30 | +== Why/when to use it |
| 31 | +- When compiling shaders that embed non‑semantic extended instruction sets (e.g., debug info or debugPrintf) that may use forward references that were previously disallowed. |
| 32 | +- When you want tool and debugging SPIR‑V to be accepted by implementations that support this relaxation, without affecting the program’s semantics (non‑semantic content does not change the observable results). |
| 33 | +- Shaders should continue to function when the feature is off; the relaxation only affects acceptance of certain SPIR‑V forms, not execution semantics. |
| 34 | + |
| 35 | +== What this sample does |
| 36 | +- Enables device extensions: `VK_KHR_shader_relaxed_extended_instruction` and `VK_KHR_shader_non_semantic_info`. |
| 37 | +- Requests the feature via the framework’s feature‑chaining helper. |
| 38 | +- Builds a tiny compute pipeline whose shader calls `debugPrintfEXT` (a non‑semantic extended instruction). |
| 39 | +- Records a per‑frame command buffer that dispatches the compute shader once, then transitions the swapchain image to `PRESENT` and presents. This keeps WSI synchronization correct and demonstrates consumption of a shader module that contains non‑semantic extended instructions. |
| 40 | + |
| 41 | +== Required Vulkan extensions and features |
| 42 | +- Device extensions (required by this sample): |
| 43 | + * `VK_KHR_shader_relaxed_extended_instruction` |
| 44 | + * `VK_KHR_shader_non_semantic_info` |
| 45 | +- Instance extension for feature chaining: `VK_KHR_get_physical_device_properties2` (the framework enables this; the sample requests it explicitly). |
| 46 | +- Device feature (required): `VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR::shaderRelaxedExtendedInstruction = VK_TRUE` |
| 47 | + |
| 48 | +Code excerpt: |
| 49 | +[source,cpp] |
| 50 | +---- |
| 51 | +ShaderRelaxedExtendedInstruction::ShaderRelaxedExtendedInstruction() |
| 52 | +{ |
| 53 | + title = "Shader relaxed extended instruction (VK_KHR_shader_relaxed_extended_instruction)"; |
| 54 | + add_instance_extension(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME); |
| 55 | + add_device_extension(VK_KHR_SHADER_RELAXED_EXTENDED_INSTRUCTION_EXTENSION_NAME); |
| 56 | + add_device_extension(VK_KHR_SHADER_NON_SEMANTIC_INFO_EXTENSION_NAME); |
| 57 | +} |
| 58 | +
|
| 59 | +void ShaderRelaxedExtendedInstruction::request_gpu_features(vkb::core::PhysicalDeviceC &gpu) |
| 60 | +{ |
| 61 | + REQUEST_REQUIRED_FEATURE(gpu, |
| 62 | + VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR, |
| 63 | + shaderRelaxedExtendedInstruction); |
| 64 | +} |
| 65 | +---- |
| 66 | + |
| 67 | +Shader (GLSL) used by this sample: |
| 68 | +[source,glsl] |
| 69 | +---- |
| 70 | +#version 450 |
| 71 | +#extension GL_EXT_debug_printf : enable |
| 72 | +layout(local_size_x = 1, local_size_y = 1, local_size_z = 1) in; |
| 73 | +void main() { |
| 74 | + debugPrintfEXT("relaxed-ext-inst demo: gid = %u", gl_GlobalInvocationID.x); |
| 75 | +} |
| 76 | +---- |
| 77 | + |
| 78 | +TIP: To actually see the `debugPrintfEXT` output, run with validation configured to capture debug printf (see the `shader_debugprintf` sample or use VK_EXT_layer_settings to enable `VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT`). This sample registers an INFO‑severity `VkDebugUtilsMessengerEXT` so messages are visible when validation is active. |
| 79 | + |
| 80 | +NOTE: If `VK_EXT_layer_settings` is not available from the validation layer at runtime, the sample automatically falls back to `VK_EXT_validation_features` and enables `VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT` during instance creation. In that case you do not need any environment configuration to see output. |
| 81 | + |
0 commit comments