[Merged by Bors] - Wgpu 0.15

[Elabajaba]

Objective

Update Bevy to wgpu 0.15.

Changelog

• Update to wgpu 0.15, wgpu-hal 0.15.1, and naga 0.11
• Users can now use the DirectX Shader Compiler (DXC) on Windows with DX12 for faster shader compilation and ShaderModel 6.0+ support (requires dxcompiler.dll and dxil.dll, which are included in DXC downloads from here)

Migration Guide

WGSL Top-Level let is now const

All top level constants are now declared with const, catching up with the wgsl spec.

let is no longer allowed at the global scope, only within functions.

-let SOME_CONSTANT = 12.0;
+const SOME_CONSTANT = 12.0;

TextureDescriptor and SurfaceConfiguration now requires a view_formats field

The new view_formats field in the TextureDescriptor is used to specify a list of formats the texture can be re-interpreted to in a texture view. Currently only changing srgb-ness is allowed (ex. Rgba8Unorm <=> Rgba8UnormSrgb). You should set view_formats to &[] (empty) unless you have a specific reason not to.

The DirectX Shader Compiler (DXC) is now supported on DX12

DXC is now the default shader compiler when using the DX12 backend. DXC is Microsoft's replacement for their legacy FXC compiler, and is faster, less buggy, and allows for modern shader features to be used (ShaderModel 6.0+). DXC requires dxcompiler.dll and dxil.dll to be available, otherwise it will log a warning and fall back to FXC.

You can get dxcompiler.dll and dxil.dll by downloading the latest release from Microsoft's DirectXShaderCompiler github repo and copying them into your project's root directory. These must be included when you distribute your Bevy game/app/etc if you plan on supporting the DX12 backend and are using DXC.

WgpuSettings now has a dx12_shader_compiler field which can be used to choose between either FXC or DXC (if you pass None for the paths for DXC, it will check for the .dlls in the working directory).

[Elabajaba]

I'd prefer to default to the DXC shader compiler for DX12 for this PR, as it's faster/supports modern features (FXC doesn't support Shadermodel 6.0+, while DXC does. Note that the techpowerup shadermodel support is inaccurate, as new drivers have upped the support on older GPUs), is actually maintained (unlike FXC, the current default), and is necessary for eg. FSR2 support for users using DX12.

The problem is that it requires the user to get dxcompiler.dll and dxil.dll (from the releases tab on https://github.com/microsoft/DirectXShaderCompiler) and ship them with their game if they plan on supporting DX12. There is an environment variable users can set so they don't have to keep copying the .dlls into every new project. edit: forgot what I did in my own PR

Currently WGPU logs a warning (sidenote, why are we filtering out WGPUs warning logs?) and falls back to FXC if either of the .dlls are missing.

WGPU wants to switch to DX12 by default for Windows in the near future (probably within the next 2 releases?), so testing this feature (including what docs improvements are needed, error message tweaks, possible bugs, unsupported drivers, etc) is imo pretty important before that happens to try and limit any future papercuts once that happens. (and for now, 99% of Bevy Windows users use Vulkan anyways, since it's the default)

edit: Users can test the wgpu dx12 backend (on Windows) by creating/setting the WGPU_BACKEND environment variable to dx12. You can temporarily set it for a terminal's scope by writing $env:WGPU_BACKEND="dx12" (including the $)

[JMS55]

Thanks for this PR! Haven't downloaded and tested it, but the PR itself lgtm. Only thing I would change is mention in the migration guide that you should use an empty view_formats (&[]) unless you have a specific reason not to. I imagine most people won't know how to fill it out otherwise - we should tell them it's ok to leave blank.

Not approving this yet, as when I was using a git branch of wgpu, I was getting errors about multisampled texture creation when MSAA was enabled. @Elabajaba can you confirm if MSAA works? Once you do, I'll approve this PR.

[Elabajaba]

...mention in the migration guide that you should use an empty view_formats (&[]) unless you have a specific reason not to.

Done

Not approving this yet, as when I was using a git branch of wgpu, I was getting errors about multisampled texture creation when MSAA was enabled.

MSAA works fine on my machine on DX12 , Vulkan and webGL in Firefox, but I think most MSAA issues are Linux+Intel+Vulkan or GL which I don't have to test against.

[Elabajaba]

Ideally we'd try to use an sRGB texture_view on the surface if sRGB surface formats aren't supported (afaik only WebGPU doesn't support sRGB surface formats, so if someone somehow gets Bevy working with webgpu before next release, the colours will be wrong). However, I couldn't get it working on Vulkan without spewing thousands of validation errors per second, so I just made a TODO of it at SurfaceConfiguration creation.

Other than that, I think it's ready? Maybe the book should be updated to tell users to download DXC and drop the .dlls into their project if they want to use DX12?

edit: Oh yeah, wgsl-analyzer doesn't support top level const (wgsl-analyzer/wgsl-analyzer#66), so it's horribly broken for naga 0.11+/wgpu 0.15+

[robtfm]

bors try

[bors]

try

Build failed:

• check-compiles

[superdump]

Could we instead try to find the first sRGB format supported, else fall back to format[0]?

[Elabajaba]

Wouldn't that require iterating through all the formats available and checking if they're either Bgra8UnormSrgb or Rgba8UnormSrgb? IMO that's less clear than just explicitly requesting the formats.

let good_formats = [TextureFormat::Bgra8UnormSrgb, TextureFormat::Rgba8UnormSrgb];
let mut format = formats[0];
for available_format in formats {
    if good_formats.contains(&available_format) {
        format = available_format;
        break;
    }
}

[robtfm]

Could we instead try to find the first sRGB format supported, else fall back to format[0]?

i agree with the suggestion. looking for a supported srgb format starting at the beginning of the list seems like the robust choice that preserves wgpu "preferred" format (the wgpu docs say explicitly "The first format in the vector is preferred") while still giving an srgb result if possible. that's different to the current change here which will pick Rgba8UnormSrgb over Bgra8UnormSrgb even if Bgra8UnormSrgb is first.

there's also a bunch of BcN and Etc2 formats that return srgb: true in decsribe(). presumably surfaces can't return them? but perhaps its still better to search the list and call describe() on them for future compatibility/weird device compatibility.

as an aside, it looks like for me at least that the formats changed. in 0.15 win/nvidia/vulkan i get [Bgra8Unorm, Bgra8UnormSrgb, Rgba16Float] where in 0.14 i used to get [Bgra8UnormSrgb, Bgra8Unorm, Rgba16Float, Rgb10a2Unorm, Rgb10a2Unorm]. has the wgpu idea of "preferred" changed?

[superdump]

I think iterate the formats and check texture_format.describe().srgb.

[Elabajaba]

I disagree with doing the .describe().srgb, as like rob says there's multiple formats that we don't want for a surface that are srgb (and in the future afaik we don't want an srgb surface for hdr output). Those formats should be filtered out by wgpu, but I'd prefer to explicitly request formats here as imo it's clearer (and there's only 2 that we want).

[superdump]

I'm wondering if the preferred formats (i.e. those closer to the beginning of the list) are more likely to support more features like more MSAA modes or so. Also, my understanding is that some devices prefer Bgra over Rgba, but will support both. I don't know if there's a performance hit somewhere just for doing the swizzling. I think the hard-coded way overrides the preferences of the device, whereas the respecting-preferences way 'risks' choosing a 'poor' sRGB format that is less preferred and less suitable.

@cwfitzgerald - do you know if it is better to:

1. hard-code and request Rgba8UnormSrgb, else Bgra8UnormSrgb, else fall back to the first format in the list
2. or if it is better to look for the first sRGB format in the list, else fall back to the first format in the list
3. or just take the first format in the list and then manually apply sRGB in a shader if the format is not an sRGB format?

[superdump]

I had missed that the PR was updated to default to the first format, and then iterate the list to look for either Rgba8UnormSrgb or Bgra8UnormSrgb and select the first encountered of those two if available. So it's a bit like option 2 above but filtering on the pool of allowed sRGB formats. Seems ok for now but I'm still interested in cwfitzgerald's input.

[Elabajaba]

CI failures should be fixed since #7370 and #7368 landed in main. I don't think I need to rebase on main for it to work this time.

[rparrett]

I tested all the examples on MacOS/M1.

post_processing and shader_prepass are broken, but both seem unrelated to this PR.

[Elabajaba]

I tested all the examples on MacOS/M1.

post_processing and shader_prepass are broken, but both seem unrelated to this PR.

Looks like the cascaded shadow maps (CSM) PR probably broke both of them, as I'm now getting failures when running those examples after rebasing on main with CSM.

#6997 is a bit of a bodge and needs to be updated for CSM, but should fix them. #5703 is probably the better fix, but might not land in time for the next bevy release?

[robtfm]

bors try

[bors]

try

Build succeeded:

• build (windows-latest)
• build (ubuntu-latest)
• build (macos-latest)
• build-wasm
• build-android
• markdownlint
• ci
• run-examples
• run-examples-on-wasm
• check-doc
• check-missing-examples-in-docs
• check-compiles
• build-and-install-on-iOS
• run-examples-on-windows-dx12
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• msrv

[Elabajaba]

This currently panics when Msaa is used on an unsupported format instead of silently falling back to no Msaa (due to wgpu changes). Afaik this is mainly an issue on Linux+Vulkan+Intel Mesa setups.

Ideally we'd have the Msaa on Windows PR lined up (along with 2x and 8x support, since they all require the same querying for supported msaa formats on the Surface's format), but I can probably add a check on surface creation to log an error and fall back to disabling Msaa, and a TODO to remove it once someone does #7194.

[JMS55]

Small doc issue, otherwise looks good to me. Can't comment on the format texture stuff, I don't understand it well enough. I'll leave that to others to review.

The MSAA check is important - it causes a crash on intel + vulkan + linux for me otherwise. Previous versions of wgpu were giving me weird white artifacts around edges due to MSAA.

[robtfm]

this is indeed pretty ugly, but at least ResMut<Msaa> doesn't conflict with anything here so it shouldn't affect perf. good incentive to get #7194 done :)

[superdump]

Thanks for the changes to the surface format selection. :) Looking close to mergeable now I think.

[superdump]

What are the implications here? The comment doesn't elaborate enough for me to understand its purpose. It seems to imply that something assumes a default that will be an sRGB format?

[superdump]

The wgpu documentation suggests this is about potentially requesting a different kind of texture view than the texture format of the surface texture. So I suppose we would do something like:

if !main_texture_format.describe().srgb {
    main_texture_format.add_srgb_suffix()
}

Or, we could even do it unconditionally as the same format would be returned anyway: https://docs.rs/wgpu-types/0.15.0/src/wgpu_types/lib.rs.html#2608 ?

[superdump]

I commented this with a focus on understanding the wgpu-side and calling it. But for our side I feel like we should only need to bother about srgb for the final surface, but I know that the deband dithering needs to be applied where quantisation happens which is unfortunately at the output of the main lighting pass, and then if we’re converting to srgb at some later point like in the final blit to the surface texture, we’d probably need to apply it there too.

[Elabajaba]

Afaik this should only be an issue on WebGPU (and maybe Nvidia Wayland?) where sRGB surfaces aren't supported.

You need to use an sRGB texture view on the surfaces for the output colours to look right, but I was running into Vulkan validation errors which seemed to imply that the whole pipeline needs to have the same sRGB texture view as the surface it outputs to. (which isn't possible, as texture views are currently limited in wgpu to the same format as the texture, just with sRGB toggled)

[Elabajaba]

The validation issues might also be due to a wgpu bug. There's a fix for it (gfx-rs/wgpu#3432), but I haven't tested it yet.

[superdump]

One problem I see with this is that MSAA can be toggled at runtime. We have an msaa example that tests that IIRC. What happens in that case? If it was a problem before wgpu 0.15 and so is not a regression then we can just create an issue and not block this PR.

[Elabajaba]

Pre 0.15 it wouldn't cause a panic, it just wouldn't work and would render strangely (weird white outlines around stuff, that no longer happens with this according to Jasmine (@JMS55)).

In 0.15 it panics.

@JMS55 tested this and it works both when MSAA is enabled at the start, and when it's toggled at runtime.

[JMS55]

To be clear, in 0.15 it panics when MSAA is turned on.

This code to disable MSAA works well and prevents the crash, including when toggled at runtime.

[coreh]

Does this also allow us to use const expressions?

[Elabajaba]

Does this also allow us to use const expressions?

I don't know, and I didn't see anything about it in the wgpu or naga changelog when I skimmed it.

[superdump]

@Elabajaba could you rebase? I’m going to give this another look over but I think it’s probably ready to merge.

[superdump]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12