Skip to content

Commit 5712583

Browse files
committed
Add some docs about lowspec rendering (#5091)
# Objective - When experimenting with rendering on lowspec machines I've run into some non-obvious things (huge thanks [superdump](https://github.com/superdump), [alice-i-cecile](https://github.com/alice-i-cecile), [mockersf](https://github.com/mockersf) and others for help) and so volunteered to document them. - Is a follow-up of https://discordapp.com/channels/691052431525675048/989137552919375902 ## Solution - I added docs about necessity of `ANGLE` to use `Backends::GL` on Windows. - Also documented why `prepare_windows` can be long to execute and some causes.
1 parent 5a3e777 commit 5712583

File tree

2 files changed

+27
-0
lines changed

2 files changed

+27
-0
lines changed

crates/bevy_render/src/settings.rs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ pub enum WgpuSettingsPriority {
1616
/// Provides configuration for renderer initialization. Use [`RenderDevice::features`](crate::renderer::RenderDevice::features),
1717
/// [`RenderDevice::limits`](crate::renderer::RenderDevice::limits), and the [`WgpuAdapterInfo`](crate::render_resource::WgpuAdapterInfo)
1818
/// resource to get runtime information about the actual adapter, backend, features, and limits.
19+
/// NOTE: [`Backends::DX12`](Backends::DX12), [`Backends::METAL`](Backends::METAL), and
20+
/// [`Backends::VULKAN`](Backends::VULKAN) are enabled by default for non-web and the best choice
21+
/// is automatically selected. Web using the `webgl` feature uses [`Backends::GL`](Backends::GL).
22+
/// NOTE: If you want to use [`Backends::GL`](Backends::GL) in a native app on Windows, you must
23+
/// use [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). This is because wgpu requires EGL to
24+
/// create a GL context without a window and only ANGLE supports that.
1925
#[derive(Clone)]
2026
pub struct WgpuSettings {
2127
pub device_label: Option<Cow<'static, str>>,

crates/bevy_render/src/view/window.rs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,27 @@ pub struct WindowSurfaces {
121121
configured_windows: HashSet<WindowId>,
122122
}
123123

124+
/// Creates and (re)configures window surfaces, and obtains a swapchain texture for rendering.
125+
///
126+
/// NOTE: `get_current_texture` in `prepare_windows` can take a long time if the GPU workload is
127+
/// the performance bottleneck. This can be seen in profiles as multiple prepare-stage systems all
128+
/// taking an unusually long time to complete, and all finishing at about the same time as the
129+
/// `prepare_windows` system. Improvements in bevy are planned to avoid this happening when it
130+
/// should not but it will still happen as it is easy for a user to create a large GPU workload
131+
/// relative to the GPU performance and/or CPU workload.
132+
/// This can be caused by many reasons, but several of them are:
133+
/// - GPU workload is more than your current GPU can manage
134+
/// - Error / performance bug in your custom shaders
135+
/// - wgpu was unable to detect a proper GPU hardware-accelerated device given the chosen
136+
/// [`Backends`](crate::settings::Backends), [`WgpuLimits`](crate::settings::WgpuLimits),
137+
/// and/or [`WgpuFeatures`](crate::settings::WgpuFeatures). For example, on Windows currently
138+
/// `DirectX 11` is not supported by wgpu 0.12 and so if your GPU/drivers do not support Vulkan,
139+
/// it may be that a software renderer called "Microsoft Basic Render Driver" using `DirectX 12`
140+
/// will be chosen and performance will be very poor. This is visible in a log message that is
141+
/// output during renderer initialization. Future versions of wgpu will support `DirectX 11`, but
142+
/// another alternative is to try to use [`ANGLE`](https://github.com/gfx-rs/wgpu#angle) and
143+
/// [`Backends::GL`](crate::settings::Backends::GL) if your GPU/drivers support `OpenGL 4.3` / `OpenGL ES 3.0` or
144+
/// later.
124145
pub fn prepare_windows(
125146
// By accessing a NonSend resource, we tell the scheduler to put this system on the main thread,
126147
// which is necessary for some OS s

0 commit comments

Comments
 (0)