From 02daf2875102a6ff7bd12f352e7a36b48734d609 Mon Sep 17 00:00:00 2001 From: Erich Gubler Date: Tue, 5 Nov 2024 10:33:05 -0500 Subject: [PATCH] =?UTF-8?q?docs(CHANGELOG):=20add=20entry=20for=20`diagnos?= =?UTF-8?q?tic(=E2=80=A6)`=20directives?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2087875ee1..7a0066cbe2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,11 +40,62 @@ Bottom level categories: ## Unreleased +## Major changes + +### The `diagnostic(…);` directive is now supported in WGSL + +Naga now parses `diagnostic(…);` directives according to the WGSL spec. This allows users to control certain lints, similar to Rust's `allow`, `warn`, and `deny` attributes. For example, in standard WGSL (but, notably, not Naga yet—see ) this snippet would emit a uniformity error: + +```wgsl +@group(0) @binding(0) var s : sampler; +@group(0) @binding(2) var tex : texture_2d; +@group(1) @binding(0) var ro_buffer : array; + +@fragment +fn main(@builtin(position) p : vec4f) -> @location(0) vec4f { + if ro_buffer[0] == 0 { + // Emits a derivative uniformity error during validation. + return textureSample(tex, s, vec2(0.,0.)); + } + + return vec4f(0.); +} +``` + +…but we can now silence it with the `off` severity level, like so: + +```wgsl +// Disable the diagnosic with this… +diagnostic(off, derivative_uniformity); + +@group(0) @binding(0) var s : sampler; +@group(0) @binding(2) var tex : texture_2d; +@group(1) @binding(0) var ro_buffer : array; + +@fragment +fn main(@builtin(position) p : vec4f) -> @location(0) vec4f { + if ro_buffer[0] == 0 { + // Look ma, no error! + return textureSample(tex, s, vec2(0.,0.)); + } + + return vec4f(0.); +} +``` + +There are some limitations to keep in mind with this new functionality: + +- We do not yet support `diagnostic(…)` rules in attribute position (i.e., `@diagnostic(…) fn my_func { … }`). This is being tracked in . We expect that rules in `fn` attribute position will be relaxed shortly (see ), but the prioritization for statement positions is unclear. If you are blocked by not being able to parse `diagnostic(…)` rules in statement positions, please let us know in that issue, so we can determine how to prioritize it! +- Standard WGSL specifies `error`, `warning`, `info`, and `off` severity levels. These are all technically usable now! A caveat, though: warning- and info-level are only emitted to `stderr` via the `log` façade, rather than being reported through a `Result::Err` in Naga or the `CompilationInfo` interface in `wgpu{,-core}`. This will require breaking changes in Naga to fix, and is being tracked by . +- Not all lints can be controlled with `diagnostic(…)` rules. In fact, only the `derivative_uniformity` triggering rule exists in the WGSL standard. That said, Naga contributors are excited to see how this level of control unlocks a new ecosystem of configurable diagnostics. +- Finally, `diagnostic(…)` rules are not yet emitted in WGSL output. This means that `wgsl-in` → `wgsl-out` is currently a lossy process. We felt that it was important to unblock users who needed `diagnostic(…)` rules (i.e., ) before we took significant effort to fix this (tracked in ). + +By @ErichDonGubler in [#6456](https://github.com/gfx-rs/wgpu/pull/6456), [#6148](https://github.com/gfx-rs/wgpu/pull/6148). + ### New Features #### Naga -- Parse `diagnostic(…)` directives, but don't implement any triggering rules yet. By @ErichDonGubler in [#6456](https://github.com/gfx-rs/wgpu/pull/6456). - Fix an issue where `naga` CLI would incorrectly skip the first positional argument when `--stdin-file-path` was specified. By @ErichDonGubler in [#6480](https://github.com/gfx-rs/wgpu/pull/6480). - Fix textureNumLevels in the GLSL backend. By @magcius in [#6483](https://github.com/gfx-rs/wgpu/pull/6483).