Merge branch 'main' into Availability-dashboard

Author: gpx1000

.github/workflows/CI.yml

@@ -44,4 +44,4 @@ jobs:
       - name: awesome_bot
         run: |
           gem install awesome_bot
-          awesome_bot --request-delay 2 -t 20 --allow-redirect --allow-dupe chapters/*.adoc chapters/extensions/*.adoc --white-list https://apps.apple.com/,https://www.youtube.com/,https://khr.io/slack,https://www.khronos.org/opengl/
+          awesome_bot --request-delay 2 -t 20 --allow-redirect --allow-dupe chapters/*.adoc chapters/extensions/*.adoc --white-list http://schemas.android.com/apk/res/android.xsd,https://apps.apple.com/,https://www.youtube.com/,https://khr.io/slack,https://www.khronos.org/opengl/

README.adoc

@@ -66,6 +66,10 @@ The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc`
 
 == xref:{chapters}deprecated.adoc[Deprecated]
 
+== xref:{chapters}windowing_audio_input.adoc[Windowing, Audio, and Input]
+
+== xref:{chapters}ide.adoc[Development Environments & IDEs]
+
 == xref:{chapters}vulkan_profiles.adoc[Vulkan Profiles]
 
 == xref:{chapters}loader.adoc[Loader]

antora/modules/ROOT/nav.adoc

@@ -17,6 +17,7 @@
 ** xref:{chapters}portability_initiative.adoc[]
 ** xref:{chapters}vulkan_cts.adoc[]
 ** xref:{chapters}development_tools.adoc[]
+** xref:{chapters}ide.adoc[]
 ** xref:{chapters}validation_overview.adoc[]
 ** xref:{chapters}decoder_ring.adoc[]
 * Using Vulkan
@@ -30,6 +31,7 @@
 *** xref:{chapters}formats.adoc[]
 ** xref:{chapters}queues.adoc[]
 ** xref:{chapters}wsi.adoc[]
+** xref:{chapters}windowing_audio_input.adoc[]
 ** xref:{chapters}pnext_and_stype.adoc[]
 ** xref:{chapters}synchronization.adoc[]
 *** xref:{chapters}extensions/VK_KHR_synchronization2.adoc[]

chapters/buffer_device_address.adoc

@@ -81,7 +81,88 @@ OpStore %ptr %obj Aligned 16
 
 Shading languages will have a default, but can allow you to align it explicitly (ex `buffer_reference_alignment`).
 
-The goal of this alignment is this is a promise for how aligned this specific pointer is. The user is responsible to confirm the address they use is aligned to it.
+The goal of this alignment is this is a promise for how aligned this specific pointer is.
+The compiler has no idea what the address will be when the shader is compiled.
+By providing an alignment it can generate valid code to match the requirement.
+The user is responsible to confirm the address they use is aligned to it.
+
+[source,glsl]
+----
+layout(buffer_reference, buffer_reference_align = 64) buffer MyBDA {
+    uint data;
+};
+
+MyBDA ptr_a; // at 0x1000
+MyBDA ptr_b; // at 0x1010
+MyBDA ptr_c; // at 0x1040
+
+ptr_a.data = 0; // (Aligned 64) valid!
+ptr_b.data = 0; // (Aligned 64) invalid!
+ptr_c.data = 0; // (Aligned 64) valid!
+----
+
+When deciding on an alignment, the minimum value will always be the size greater than or equal to the largest scalar/component type in the block.
+
+[source,glsl]
+----
+// alignment must be at least 4
+layout(buffer_reference) buffer MyBDA {
+    vec4 a; // scalar is float
+};
+
+// alignment must be at least 1
+layout(buffer_reference) buffer MyBDA {
+    uint8_t a; // scalar is 8-bit int
+};
+
+// alignment must be at least 8
+layout(buffer_reference) buffer MyBDA {
+    uint a; // 32-bit
+    double b; // 64-bit
+};
+----
+
+=== Alignment Example
+
+To help explain alignment, lets take an example of loading an array of vectors
+
+[source,glsl]
+----
+layout(buffer_reference, buffer_reference_align = ???) buffer MyBDA {
+    uvec4 data[];
+};
+
+MyBDA ptr; // at 0x1000
+ptr.data[i] = uvec4(0);
+----
+
+Here we have 2 options, we could set the `Aligned` to be `4` or `16`.
+
+If we set alignment to `16` we are letting the compiler know it can load 16 bytes at a time, so it will hopefully do a vector load/store on the memory.
+
+If we set alignment to `4` the compiler will likely have no way to infer the real alignment and will now do 4 scalar int load/store on the memory.
+
+[NOTE]
+====
+Some GPUs can do vector load/store even on unaligned addresses.
+====
+
+For the next case, if we had `uvec3` instead of `uvec4` such as
+
+[source,glsl]
+----
+layout(buffer_reference, buffer_reference_align = 4, scalar) buffer MyBDA {
+    uvec3 data[];
+};
+
+data[0]; // 0x1000
+data[1]; // 0x100C
+data[2]; // 0x1018
+data[3]; // 0x1024
+----
+
+We know that setting the alignment to `16` would be violated at `data[1]` and therefore we need to use an alignment of `4` in this case.
+Luckily shading languages will help do this for you as seen in both link:https://godbolt.org/z/jWGKax1ed[glslang] and link:https://godbolt.org/z/Y7xW3Mfd4[slang] .
 
 === Nullptr
 

chapters/development_tools.adoc

@@ -24,7 +24,7 @@ Layers are optional components that augment the Vulkan system. They can intercep
     The validation layer included multiple features:
   ** link:https://vulkan.lunarg.com/doc/sdk/latest/windows/synchronization_usage.html[Synchronization Validation]: Identify resource access conflicts due to missing or incorrect synchronization operations between actions (Draw, Copy, Dispatch, Blit) reading or writing the same regions of memory.
   ** link:https://vulkan.lunarg.com/doc/sdk/latest/windows/gpu_validation.html[GPU-Assisted Validation]: Instrument shader code to perform run-time checks for error conditions produced during shader execution.
-  ** link:https://vulkan.lunarg.com/doc/sdk/latest/windows/debug_printf.html[Shader printf]: Debug shader code by "`printing`" any values of interest to the debug callback or stdout.
+  ** link:https://vulkan.lunarg.com/doc/sdk/latest/windows/debug_printf.html[Shader printf]: Debug shader code by "`printing`" any values of interest to the debug callback or stdout. Environment variables provide a fast path for enabling this feature without code changes.
   ** link:https://vulkan.lunarg.com/doc/sdk/latest/windows/best_practices.html[Best Practices Warnings]: Highlights potential performance issues, questionable usage patterns, common mistakes.
 
 === Vulkan SDK layers
@@ -60,7 +60,7 @@ There are also other publicly available layers that can be used to help in devel
   * link:https://developer.qualcomm.com/software/adreno-gpu-sdk/tools[`VK_LAYER_adreno`], the Vulkan Adreno Layer.
     Checks Vulkan applications for best practices on Qualcomm Adreno devices.
 
-== Debugging 
+== Debugging
 
 Debugging something running on a GPU can be incredibly hard, luckily there are tools out there to help.
 
@@ -78,16 +78,107 @@ The following tools help debug crashes.
   * link:https://gpuopen.com/radeon-gpu-detective[AMD GPU detective]
   * link:https://developer.nvidia.com/nsight-aftermath[NVIDIA Nsight Aftermath SDK]
 
+=== Shader Debugging
+
+Debugging shaders requires specialized tools and techniques. For comprehensive guidance on shader debugging in Vulkan applications, including:
+
+  * Shader debugging tools and their IDE integration
+  * GPU-Assisted Validation for shader debugging
+  * Shader printf techniques for both GLSL and HLSL
+  * IDE-specific shader debugging configurations
+  * Best practices for shader debugging workflows
+
+See the xref:{chapters}ide.adoc#shader-debugging[Shader Debugging Integration] section in the Development Environments & IDEs chapter.
+
+[[profiling]]
 == Profiling
 
-With anything related to a GPU it is best to not assume and profile when possible. Here is a list of known profilers to aid in your development.
+With anything related to a GPU it is best to not assume and profile when possible. Profiling tools can help identify performance bottlenecks, analyze GPU workloads, and optimize your Vulkan applications. For IDE-specific profiling integration, see the xref:{chapters}ide.adoc[Development Environments & IDEs] chapter.
 
-  * link:https://gpuopen.com/rgp/[AMD Radeon GPU Profiler] - Low-level performance analysis tool for AMD Radeon GPUs.
-  * link:https://developer.android.com/agi[Android GPU Inspector (AGI)] - Google's profiler for the Android platform with support for Vulkan  
-  * link:https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer[Arm Streamline Performance Analyzer] - Visualize the performance of mobile games and applications for a broad range of devices, using Arm Mobile Studio.
-  * link:https://www.intel.com/content/www/us/en/developer/tools/graphics-performance-analyzers/overview.html[Intel(R) GPA] - Intel's Graphics Performance Analyzers that supports capturing and analyzing multi-frame streams of Vulkan apps.
-  * link:https://developer.nvidia.com/nsight-graphics[NVIDIA Nsight]
-  * link:https://github.com/GPUOpen-Tools/OCAT[OCAT] - The Open Capture and Analytics Tool (OCAT) provides an FPS overlay and performance measurement for D3D11, D3D12, and Vulkan.
-  * link:https://developer.imaginationtech.com[PVRTune]
-  * link:https://developer.qualcomm.com/software/snapdragon-profiler[Qualcomm Snapdragon Profiler] - Profiling tool targeting Adreno GPU.
-  * link:https://www.vktracer.com[VKtracer] - Cross-vendor and cross-platform profiler.
+=== Vendor-Specific Profiling Tools
+
+==== AMD
+
+  * link:https://gpuopen.com/rgp/[AMD Radeon GPU Profiler (RGP)] - Low-level performance analysis tool for AMD Radeon GPUs.
+    ** Provides detailed timing information for Vulkan API calls and GPU workloads
+    ** Visualizes the rendering pipeline and identifies bottlenecks
+    ** Supports hardware-based ray tracing analysis
+    ** Integrates with xref:{chapters}ide.adoc#visual-studio[Visual Studio] through the Radeon Developer Panel
+
+==== NVIDIA
+
+  * link:https://developer.nvidia.com/nsight-graphics[NVIDIA Nsight Graphics] - Comprehensive graphics debugger and profiler for NVIDIA GPUs.
+    ** Provides frame debugging, GPU trace capture, and performance analysis
+    ** Supports Vulkan API debugging and optimization
+    ** Includes shader profiling and memory analysis
+    ** Integrates with xref:{chapters}ide.adoc#visual-studio[Visual Studio] and can be used standalone
+
+==== ARM
+
+  * link:https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer[Arm Streamline Performance Analyzer] - Performance analysis tool for Arm-based devices.
+    ** Visualizes the performance of mobile games and applications
+    ** Provides CPU, GPU, and system-level performance metrics
+    ** Supports Vulkan workload analysis
+    ** Part of Arm Mobile Studio, which integrates with various IDEs
+
+==== Imagination Technologies
+
+  * link:https://developer.imaginationtech.com[PVRTune] - Performance analysis tool for PowerVR GPUs.
+    ** Provides real-time hardware performance metrics
+    ** Supports Vulkan API tracing and analysis
+    ** Helps identify bottlenecks in PowerVR-based devices
+    ** Works with xref:{chapters}ide.adoc#android-studio[Android Studio] for mobile development
+
+==== Qualcomm
+
+  * link:https://developer.qualcomm.com/software/snapdragon-profiler[Qualcomm Snapdragon Profiler] - Profiling tool targeting Adreno GPUs.
+    ** Provides detailed GPU metrics for Qualcomm Snapdragon devices
+    ** Supports Vulkan API trace capture and analysis
+    ** Includes shader profiling and optimization suggestions
+    ** Integrates with xref:{chapters}ide.adoc#android-studio[Android Studio] for Android development
+
+=== Platform-Specific Profiling Tools
+
+==== Android
+
+  * link:https://developer.android.com/agi[Android GPU Inspector (AGI)] - Google's profiler for the Android platform.
+    ** Provides Vulkan API tracing and GPU performance analysis
+    ** Supports system trace correlation with GPU workloads
+    ** Helps identify rendering bottlenecks on Android devices
+    ** Integrates with xref:{chapters}ide.adoc#android-studio[Android Studio]
+
+=== Cross-Platform Profiling Tools
+
+  * link:https://github.com/GPUOpen-Tools/OCAT[OCAT] (Open Capture and Analytics Tool) - FPS overlay and performance measurement tool.
+    ** Provides real-time FPS monitoring and performance metrics
+    ** Supports D3D11, D3D12, and Vulkan
+    ** Generates detailed performance reports
+    ** Works alongside any development environment
+
+  * link:https://www.vktracer.com[VKtracer] - Cross-vendor and cross-platform Vulkan profiler.
+    ** Captures and analyzes Vulkan API calls
+    ** Works with all Vulkan-compatible GPUs
+    ** Provides timing information and bottleneck identification
+    ** Compatible with various development environments
+
+  * link:https://vulkan.lunarg.com/doc/sdk/latest/windows/capture_tools.html[GFXReconstruct] - Frame capture and replay tool for Vulkan.
+    ** Captures Vulkan API calls for later analysis
+    ** Supports cross-platform capture and replay
+    ** Helps identify performance issues and bugs
+    ** Included in the Vulkan SDK and works with all major IDEs
+
+=== Profiling Best Practices
+
+When profiling Vulkan applications, consider the following best practices:
+
+1. **Start with validation layers**: Before profiling, ensure your application passes validation to avoid measuring performance of incorrect code.
+
+2. **Profile on target hardware**: Performance characteristics can vary significantly between different GPUs and platforms.
+
+3. **Use vendor-specific tools** for the most detailed insights on specific hardware.
+
+4. **Combine CPU and GPU profiling** to identify bottlenecks across the entire rendering pipeline.
+
+5. **Profile regularly** throughout development to catch performance regressions early.
+
+For IDE-specific profiling workflows, refer to the relevant sections in the xref:{chapters}ide.adoc[Development Environments & IDEs] chapter.