From 734c134f2d0e01589736aa75373f59d9e1aae7be Mon Sep 17 00:00:00 2001 From: Nikita Krylov Date: Fri, 24 Jun 2022 17:20:55 +0300 Subject: [PATCH 1/4] Add some docs about lowspec rendering --- crates/bevy_render/src/settings.rs | 2 ++ crates/bevy_render/src/view/window.rs | 10 ++++++++++ 2 files changed, 12 insertions(+) diff --git a/crates/bevy_render/src/settings.rs b/crates/bevy_render/src/settings.rs index 229ce1a89defc..041ffdd5b5332 100644 --- a/crates/bevy_render/src/settings.rs +++ b/crates/bevy_render/src/settings.rs @@ -16,6 +16,8 @@ pub enum WgpuSettingsPriority { /// Provides configuration for renderer initialization. Use [`RenderDevice::features`](crate::renderer::RenderDevice::features), /// [`RenderDevice::limits`](crate::renderer::RenderDevice::limits), and the [`WgpuAdapterInfo`](crate::render_resource::WgpuAdapterInfo) /// resource to get runtime information about the actual adapter, backend, features, and limits. +/// NOTE: [`Backends::GL`](Backends::GL) is disabled by default. +/// You can use [`Backends::GL`](Backends::GL) on Windows only with the help of [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). #[derive(Clone)] pub struct WgpuSettings { pub device_label: Option>, diff --git a/crates/bevy_render/src/view/window.rs b/crates/bevy_render/src/view/window.rs index 305a56ddd115b..fdd27bbcc5f93 100644 --- a/crates/bevy_render/src/view/window.rs +++ b/crates/bevy_render/src/view/window.rs @@ -121,6 +121,16 @@ pub struct WindowSurfaces { configured_windows: HashSet, } +/// Creates or updates window surfaces for rendering. +/// +/// NOTE: `prepare_windows` can take a long time (and this can be seen using profiling) +/// if the GPU is a serious bottleneck and doesn't manage to keep up with CPU. +/// This can be caused by many reasons, but several of them are: +/// - Just too much load for current spec +/// - Unusual high workload (and maybe errouneusly written custom shaders causing it) +/// - Bad drivers or mismatch with chosen [`Backends`](crate::settings::Backends) / +/// [`WgpuLimits`](crate::settings::WgpuLimits) / [`WgpuFeatures`](crate::settings::WgpuFeatures) +/// causing `wgpu` to pick up software renderer adapter which is usually not what you want. pub fn prepare_windows( // By accessing a NonSend resource, we tell the scheduler to put this system on the main thread, // which is necessary for some OS s From fd37ed03264464c99a2bfe4b4107d75a3384981f Mon Sep 17 00:00:00 2001 From: Nikita Date: Sat, 25 Jun 2022 01:39:48 +0300 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Alice Cecile --- crates/bevy_render/src/settings.rs | 2 +- crates/bevy_render/src/view/window.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/bevy_render/src/settings.rs b/crates/bevy_render/src/settings.rs index 041ffdd5b5332..8831cb182fb3c 100644 --- a/crates/bevy_render/src/settings.rs +++ b/crates/bevy_render/src/settings.rs @@ -17,7 +17,7 @@ pub enum WgpuSettingsPriority { /// [`RenderDevice::limits`](crate::renderer::RenderDevice::limits), and the [`WgpuAdapterInfo`](crate::render_resource::WgpuAdapterInfo) /// resource to get runtime information about the actual adapter, backend, features, and limits. /// NOTE: [`Backends::GL`](Backends::GL) is disabled by default. -/// You can use [`Backends::GL`](Backends::GL) on Windows only with the help of [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). +/// On Windows, this requires [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). #[derive(Clone)] pub struct WgpuSettings { pub device_label: Option>, diff --git a/crates/bevy_render/src/view/window.rs b/crates/bevy_render/src/view/window.rs index fdd27bbcc5f93..c33f2a21686cd 100644 --- a/crates/bevy_render/src/view/window.rs +++ b/crates/bevy_render/src/view/window.rs @@ -127,10 +127,10 @@ pub struct WindowSurfaces { /// if the GPU is a serious bottleneck and doesn't manage to keep up with CPU. /// This can be caused by many reasons, but several of them are: /// - Just too much load for current spec -/// - Unusual high workload (and maybe errouneusly written custom shaders causing it) +/// - Unusual high workload (possibly an error in your custom shaders) /// - Bad drivers or mismatch with chosen [`Backends`](crate::settings::Backends) / /// [`WgpuLimits`](crate::settings::WgpuLimits) / [`WgpuFeatures`](crate::settings::WgpuFeatures) -/// causing `wgpu` to pick up software renderer adapter which is usually not what you want. +/// causing `wgpu` to choose a (very slow) software renderer adapter. pub fn prepare_windows( // By accessing a NonSend resource, we tell the scheduler to put this system on the main thread, // which is necessary for some OS s From 79ed137b0855a4a5dae9881b8175a0ad98953111 Mon Sep 17 00:00:00 2001 From: Nikita Date: Sat, 25 Jun 2022 17:24:34 +0300 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Robert Swain --- crates/bevy_render/src/settings.rs | 8 ++++++-- crates/bevy_render/src/view/window.rs | 27 +++++++++++++++++++-------- 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/crates/bevy_render/src/settings.rs b/crates/bevy_render/src/settings.rs index 8831cb182fb3c..b65c878cee8d6 100644 --- a/crates/bevy_render/src/settings.rs +++ b/crates/bevy_render/src/settings.rs @@ -16,8 +16,12 @@ pub enum WgpuSettingsPriority { /// Provides configuration for renderer initialization. Use [`RenderDevice::features`](crate::renderer::RenderDevice::features), /// [`RenderDevice::limits`](crate::renderer::RenderDevice::limits), and the [`WgpuAdapterInfo`](crate::render_resource::WgpuAdapterInfo) /// resource to get runtime information about the actual adapter, backend, features, and limits. -/// NOTE: [`Backends::GL`](Backends::GL) is disabled by default. -/// On Windows, this requires [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). +/// NOTE: [`Backends::DX12`](Backends::DX12), [`Backends::METAL`](Backends::METAL), and +/// [`Backends::VULKAN`](Backends::VULKAN) are enabled by default for non-web and the best choice +/// is automatically selected. Web using the `webgl` feature uses [`Backends::GL`](Backends::GL). +/// NOTE: If you want to use [`Backends::GL`](Backends::GL) in a native app on Windows, you must +/// use [`ANGLE`](https://github.com/gfx-rs/wgpu#angle). This is because wgpu requires EGL to +/// create a GL context without a window and only ANGLE supports that. #[derive(Clone)] pub struct WgpuSettings { pub device_label: Option>, diff --git a/crates/bevy_render/src/view/window.rs b/crates/bevy_render/src/view/window.rs index c33f2a21686cd..a7cfbe5b54162 100644 --- a/crates/bevy_render/src/view/window.rs +++ b/crates/bevy_render/src/view/window.rs @@ -121,16 +121,27 @@ pub struct WindowSurfaces { configured_windows: HashSet, } -/// Creates or updates window surfaces for rendering. +/// Creates and (re)configures window surfaces, and obtains a swapchain texture for rendering. /// -/// NOTE: `prepare_windows` can take a long time (and this can be seen using profiling) -/// if the GPU is a serious bottleneck and doesn't manage to keep up with CPU. +/// NOTE: `get_current_texture` in `prepare_windows` can take a long time if the GPU workload is +/// the performance bottleneck. This can be seen in profiles as multiple prepare-stage systems all +/// taking an unusually long time to complete, and all finishing at about the same time as the +/// `prepare_windows` system. Improvements in bevy are planned to avoid this happening when it +/// should not but it will still happen as it is easy for a user to create a large GPU workload +/// relative to the GPU performance and/or CPU workload. /// This can be caused by many reasons, but several of them are: -/// - Just too much load for current spec -/// - Unusual high workload (possibly an error in your custom shaders) -/// - Bad drivers or mismatch with chosen [`Backends`](crate::settings::Backends) / -/// [`WgpuLimits`](crate::settings::WgpuLimits) / [`WgpuFeatures`](crate::settings::WgpuFeatures) -/// causing `wgpu` to choose a (very slow) software renderer adapter. +/// - GPU workload is more than your current GPU can manage +/// - Error / performance bug in your custom shaders +/// - wgpu was unable to detect a proper GPU hardware-accelerated device given the chosen +/// [`Backends`](crate::settings::Backends), [`WgpuLimits`](crate::settings::WgpuLimits), +/// and/or [`WgpuFeatures`](crate::settings::WgpuFeatures). For example, on Windows currently +/// DirectX 11 is not supported by wgpu 0.12 and so if your GPU/drivers do not support Vulkan, +/// it may be that a software renderer called "Microsoft Basic Render Driver" using DirectX 12 +/// will be chosen and performance will be very poor. This is visible in a log message that is +/// output during renderer initialization. Future versions of wgpu will support DirectX 11, but +/// another alternative is to try to use [`ANGLE`](https://github.com/gfx-rs/wgpu#angle) and +/// [`Backends::GL`](Backends::GL) if your GPU/drivers support OpenGL 4.3 / OpenGL ES 3.0 or +/// later. pub fn prepare_windows( // By accessing a NonSend resource, we tell the scheduler to put this system on the main thread, // which is necessary for some OS s From def85aa756a16d5151b4eb9592d6db33b538068b Mon Sep 17 00:00:00 2001 From: Nikita Krylov Date: Sat, 25 Jun 2022 17:50:54 +0300 Subject: [PATCH 4/4] Backtick rendering API names and fix link --- crates/bevy_render/src/view/window.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/bevy_render/src/view/window.rs b/crates/bevy_render/src/view/window.rs index a7cfbe5b54162..85557b5ed80af 100644 --- a/crates/bevy_render/src/view/window.rs +++ b/crates/bevy_render/src/view/window.rs @@ -135,12 +135,12 @@ pub struct WindowSurfaces { /// - wgpu was unable to detect a proper GPU hardware-accelerated device given the chosen /// [`Backends`](crate::settings::Backends), [`WgpuLimits`](crate::settings::WgpuLimits), /// and/or [`WgpuFeatures`](crate::settings::WgpuFeatures). For example, on Windows currently -/// DirectX 11 is not supported by wgpu 0.12 and so if your GPU/drivers do not support Vulkan, -/// it may be that a software renderer called "Microsoft Basic Render Driver" using DirectX 12 +/// `DirectX 11` is not supported by wgpu 0.12 and so if your GPU/drivers do not support Vulkan, +/// it may be that a software renderer called "Microsoft Basic Render Driver" using `DirectX 12` /// will be chosen and performance will be very poor. This is visible in a log message that is -/// output during renderer initialization. Future versions of wgpu will support DirectX 11, but +/// output during renderer initialization. Future versions of wgpu will support `DirectX 11`, but /// another alternative is to try to use [`ANGLE`](https://github.com/gfx-rs/wgpu#angle) and -/// [`Backends::GL`](Backends::GL) if your GPU/drivers support OpenGL 4.3 / OpenGL ES 3.0 or +/// [`Backends::GL`](crate::settings::Backends::GL) if your GPU/drivers support `OpenGL 4.3` / `OpenGL ES 3.0` or /// later. pub fn prepare_windows( // By accessing a NonSend resource, we tell the scheduler to put this system on the main thread,