Replace the wgpu_trace feature with a field in `bevy_render::settin…

…gs::WgpuSettings` (#14842)

# Objective
- Remove the `wgpu_trace` feature while still making it easy/possible to
record wgpu traces for debugging.
- Close #14725.
- Get a taste of the bevy codebase. :P

## Solution
This PR performs the above objective by removing the `wgpu_trace`
feature from all `Cargo.toml` files.

However, wgpu traces are still useful for debugging - but to record
them, you need to pass in a directory path to store the traces in. To
avoid forcing users into manually creating the renderer,
`bevy_render::settings::WgpuSettings` now has a `trace_path` field, so
that all of Bevy's automatic initialization can happen while still
allowing for tracing.

## Testing
- Did you test these changes? If so, how?
- I have tested these changes, but only via running `cargo run -p ci`. I
am hoping the Github Actions workflows will catch anything I missed.
- Are there any parts that need more testing?
  - I do not believe so.
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
- If you want to test these changes, I have updated the debugging guide
(`docs/debugging.md`) section on WGPU Tracing.
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
- I ran the above command on a Windows 10 64-bit (x64) machine, using
the `stable-x86_64-pc-windows-msvc` toolchain. I do not have anything
set up for other platforms or targets (though I can't imagine this needs
testing on other platforms).

---

## Migration Guide

1. The `bevy/wgpu_trace`, `bevy_render/wgpu_trace`, and
`bevy_internal/wgpu_trace` features no longer exist. Remove them from
your `Cargo.toml`, CI, tooling, and what-not.
2. Follow the instructions in the updated `docs/debugging.md` file in
the repository, under the WGPU Tracing section.

Because of the changes made, you can now generate traces to any path,
rather than the hardcoded `%WorkspaceRoot%/wgpu_trace` (where
`%WorkspaceRoot%` is... the root of your crate's workspace) folder.

(If WGPU hasn't restored tracing functionality...) Do note that WGPU has
not yet restored tracing functionality. However, once it does, the above
should be sufficient to generate new traces.

---------

Co-authored-by: TrialDragon <[email protected]>

Cargo.toml

@@ -180,9 +180,6 @@ trace_tracy_memory = [
 # Tracing support
 trace = ["bevy_internal/trace"]
 
-# Save a trace of all wgpu calls
-wgpu_trace = ["bevy_internal/wgpu_trace"]
-
 # EXR image format support
 exr = ["bevy_internal/exr"]
 

crates/bevy_internal/Cargo.toml

@@ -24,7 +24,6 @@ trace = [
 trace_chrome = ["bevy_log/tracing-chrome"]
 trace_tracy = ["bevy_render?/tracing-tracy", "bevy_log/tracing-tracy"]
 trace_tracy_memory = ["bevy_log/trace_tracy_memory"]
-wgpu_trace = ["bevy_render/wgpu_trace"]
 detailed_trace = ["bevy_utils/detailed_trace"]
 
 sysinfo_plugin = ["bevy_diagnostic/sysinfo_plugin"]

crates/bevy_render/Cargo.toml

@@ -29,7 +29,6 @@ zstd = ["ruzstd"]
 
 trace = ["profiling"]
 tracing-tracy = []
-wgpu_trace = []
 ci_limits = []
 webgl = ["wgpu/webgl"]
 webgpu = ["wgpu/webgpu"]

crates/bevy_render/src/renderer/mod.rs

@@ -195,16 +195,6 @@ pub async fn initialize_renderer(
         );
     }
 
-    #[cfg(feature = "wgpu_trace")]
-    let trace_path = {
-        let path = std::path::Path::new("wgpu_trace");
-        // ignore potential error, wgpu will log it
-        let _ = std::fs::create_dir(path);
-        Some(path)
-    };
-    #[cfg(not(feature = "wgpu_trace"))]
-    let trace_path = None;
-
     // Maybe get features and limits based on what is supported by the adapter/backend
     let mut features = wgpu::Features::empty();
     let mut limits = options.limits.clone();
@@ -357,7 +347,7 @@ pub async fn initialize_renderer(
                 required_limits: limits,
                 memory_hints: options.memory_hints.clone(),
             },
-            trace_path,
+            options.trace_path.as_deref(),
         )
         .await
         .unwrap();

crates/bevy_render/src/settings.rs

@@ -1,7 +1,7 @@
 use crate::renderer::{
     RenderAdapter, RenderAdapterInfo, RenderDevice, RenderInstance, RenderQueue,
 };
-use std::borrow::Cow;
+use std::{borrow::Cow, path::PathBuf};
 
 pub use wgpu::{
     Backends, Dx12Compiler, Features as WgpuFeatures, Gles3MinorVersion, InstanceFlags,
@@ -52,6 +52,8 @@ pub struct WgpuSettings {
     pub instance_flags: InstanceFlags,
     /// This hints to the WGPU device about the preferred memory allocation strategy.
     pub memory_hints: MemoryHints,
+    /// The path to pass to wgpu for API call tracing. This only has an effect if wgpu's tracing functionality is enabled.
+    pub trace_path: Option<PathBuf>,
 }
 
 impl Default for WgpuSettings {
@@ -116,6 +118,7 @@ impl Default for WgpuSettings {
             gles3_minor_version,
             instance_flags,
             memory_hints: MemoryHints::default(),
+            trace_path: None,
         }
     }
 }

docs/cargo_features.md

@@ -94,5 +94,4 @@ The default feature set enables most of the expected features of a game engine,
 |wayland|Wayland display server support|
 |webgpu|Enable support for WebGPU in Wasm. When enabled, this feature will override the `webgl2` feature and you won't be able to run Wasm builds with WebGL2, only with WebGPU.|
 |webp|WebP image format support|
-|wgpu_trace|Save a trace of all wgpu calls|
 |zlib|For KTX2 supercompression|

docs/debugging.md

@@ -13,6 +13,12 @@ When a suspected wgpu error occurs, you should capture a wgpu trace so that Bevy
 
 To capture a wgpu trace:
 
-1. Create a new `wgpu_trace` folder in the root of your cargo workspace
-2. Add the "wgpu_trace" feature to the bevy crate. (ex: `cargo run --example features wgpu_trace`)
-3. Zip up the wgpu_trace folder and attach it to the relevant issue. New wgpu issues should generally be created [in the wgpu repository](https://github.com/gfx-rs/wgpu). Please include the wgpu revision in your bug reports. You can find the revision in the `Cargo.lock` file in your workspace.
+1. Create a new folder in which to store your wgpu trace.
+2. Pass the path to the folder you created for your wgpu trace to `bevy_render::RenderPlugin`, using the `render_creation` field.
+   * If you're manually creating the renderer resources, pass the path to wgpu when creating the `RenderDevice` and `RenderQueue`.
+   * Otherwise, pass the path to Bevy via the `trace_path` field in `bevy_render::settings::WgpuSettings`.
+3. Add `wgpu = { version = "*", features = ["trace"]}` to your Cargo.toml.
+   * `version = "*"` tells Rust that this can be *any* version of the wgpu crate, so it will not try to pull in a different version of wgpu than what is already pulled in by Bevy.
+4. Compile and run your application, performing any in-app actions necessary to replicate the wgpu error.
+
+Once you've captured a wgpu trace, zip up the folder and attach it to the relevant issue. New wgpu issues should generally be created [in the wgpu repository](https://github.com/gfx-rs/wgpu). Please include the wgpu revision in your bug reports. You can find the revision in the `Cargo.lock` file in your workspace.