From 94d40d206eb6aece9f4f775e1394da335219a5df Mon Sep 17 00:00:00 2001 From: MichiRecRoom <1008889+LikeLakers2@users.noreply.github.com> Date: Sun, 25 Aug 2024 10:16:11 -0400 Subject: [PATCH] Replace the `wgpu_trace` feature with a field in `bevy_render::settings::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 <31419708+TrialDragon@users.noreply.github.com> --- Cargo.toml | 3 --- crates/bevy_internal/Cargo.toml | 1 - crates/bevy_render/Cargo.toml | 1 - crates/bevy_render/src/renderer/mod.rs | 12 +----------- crates/bevy_render/src/settings.rs | 5 ++++- docs/cargo_features.md | 1 - docs/debugging.md | 12 +++++++++--- 7 files changed, 14 insertions(+), 21 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 474058b45f..16a933183d 100644 --- a/Cargo.toml +++ b/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"] diff --git a/crates/bevy_internal/Cargo.toml b/crates/bevy_internal/Cargo.toml index 7505c8f0be..424a1416be 100644 --- a/crates/bevy_internal/Cargo.toml +++ b/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"] diff --git a/crates/bevy_render/Cargo.toml b/crates/bevy_render/Cargo.toml index 9ebd06678b..834fca03f1 100644 --- a/crates/bevy_render/Cargo.toml +++ b/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"] diff --git a/crates/bevy_render/src/renderer/mod.rs b/crates/bevy_render/src/renderer/mod.rs index 478128f219..582ad2d181 100644 --- a/crates/bevy_render/src/renderer/mod.rs +++ b/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(); diff --git a/crates/bevy_render/src/settings.rs b/crates/bevy_render/src/settings.rs index 1f9df24a78..7dbf016a8e 100644 --- a/crates/bevy_render/src/settings.rs +++ b/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, } impl Default for WgpuSettings { @@ -116,6 +118,7 @@ impl Default for WgpuSettings { gles3_minor_version, instance_flags, memory_hints: MemoryHints::default(), + trace_path: None, } } } diff --git a/docs/cargo_features.md b/docs/cargo_features.md index d2cbf06a23..c360c2eb8c 100644 --- a/docs/cargo_features.md +++ b/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| diff --git a/docs/debugging.md b/docs/debugging.md index f791e7d21b..60ce21b918 100644 --- a/docs/debugging.md +++ b/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.