wgpu/documentation/extensions/
debug_printf.rs

1/*!
2# Shader `debugPrintf`
3
4`wgpu` supports shader debug printing on native backends when [`Features::DEBUG_PRINTF`] is enabled.
5This is a debugging extension and is not part of core WebGPU.
6
7## Requirements
8
9- Request [`Features::DEBUG_PRINTF`] when creating the device.
10- Add `enable wgpu_debug_printf;` to each WGSL module that calls `debugPrintf`.
11- Use a backend that advertises the feature:
12  - Metal with shader logging support, available in Metal 3.2 and later.
13  - Vulkan 1.3, or Vulkan with `VK_KHR_shader_non_semantic_info` support.
14
15On Metal, `wgpu` attaches an `MTLLogState` to the device's command queue and forwards the shader log messages to `log::info`.
16
17On Vulkan, `debugPrintf` output is produced through the validation layer debug-printf path.
18To receive Vulkan `debugPrintf` output:
19
20- Install the Vulkan SDK.
21- Request [`InstanceFlags::VALIDATION`] and [`InstanceFlags::DEBUG_PRINTF`].
22- Listen for log messages at the `Info` level.
23
24## WGSL Syntax
25
26`debugPrintf` is a statement-like built-in:
27
28```wgsl
29enable wgpu_debug_printf;
30
31@compute @workgroup_size(1)
32fn main(@builtin(global_invocation_id) id: vec3<u32>) {
33    debugPrintf("invocation: %u %u %u", id.x, id.y, id.z);
34}
35```
36
37The first argument must be a string literal. String literals are currently only accepted as the format argument to `debugPrintf`.
38
39Remaining arguments must currently be scalar values. Vector and matrix arguments may be supported in the future, but for now vector components should be passed individually.
40
41Format string interpretation follows the active backend's shader logging implementation. The supported format syntax is therefore intentionally limited to the common C-style debug printf forms accepted by Metal shader logging and Vulkan shader debug printf.
42
43## Backend Notes
44
45- Metal lowers `debugPrintf` to `metal::os_log_default.log_info`.
46- Vulkan lowers `debugPrintf` through SPIR-V `NonSemantic.DebugPrintf`.
47
48## References
49
50- [Apple Metal shader logging](https://developer.apple.com/documentation/metal/logging-shader-debug-messages)
51- [Vulkan shader debug printf sample](https://docs.vulkan.org/samples/latest/samples/extensions/shader_debugprintf/README.html)
52*/
53
54use crate::{Features, InstanceFlags};
wgpu/documentation/extensions/debug_printf.rs

wgpu/documentation/extensions/
debug_printf.rs
