From 0ae7afbcad07c4c01a14a99f4ad653eb2c07e90a Mon Sep 17 00:00:00 2001
From: Martin Svanberg <martin@martinsvanberg.com>
Date: Wed, 26 Jun 2024 14:44:48 +0200
Subject: [PATCH] Print warning when using llvmpipe (#13780)

# Objective

Numerous people have been confused that Bevy runs slowly, when the
reason is that the `llvmpipe` software rendered is being used.

## Solution

Printing a warning could reduce the confusion.
---
 crates/bevy_render/src/renderer/mod.rs | 12 +++++++++--
 errors/B0006.md                        | 30 ++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 errors/B0006.md

diff --git a/crates/bevy_render/src/renderer/mod.rs b/crates/bevy_render/src/renderer/mod.rs
index 3fa3d51b7f..6893e745e2 100644
--- a/crates/bevy_render/src/renderer/mod.rs
+++ b/crates/bevy_render/src/renderer/mod.rs
@@ -3,7 +3,7 @@ mod render_device;
 
 use bevy_derive::{Deref, DerefMut};
 use bevy_tasks::ComputeTaskPool;
-use bevy_utils::tracing::{error, info, info_span};
+use bevy_utils::tracing::{error, info, info_span, warn};
 pub use graph_runner::*;
 pub use render_device::*;
 
@@ -20,7 +20,8 @@ use bevy_time::TimeSender;
 use bevy_utils::Instant;
 use std::sync::Arc;
 use wgpu::{
-    Adapter, AdapterInfo, CommandBuffer, CommandEncoder, Instance, Queue, RequestAdapterOptions,
+    Adapter, AdapterInfo, CommandBuffer, CommandEncoder, DeviceType, Instance, Queue,
+    RequestAdapterOptions,
 };
 
 /// Updates the [`RenderGraph`] with all of its nodes and then runs it to render the entire frame.
@@ -187,6 +188,13 @@ pub async fn initialize_renderer(
     let adapter_info = adapter.get_info();
     info!("{:?}", adapter_info);
 
+    if adapter_info.device_type == DeviceType::Cpu {
+        warn!(
+            "The selected adapter is using the a driver that only supports software rendering. \
+             This is likely to be very slow. See https://bevyengine.org/learn/errors/b0006/"
+        );
+    }
+
     #[cfg(feature = "wgpu_trace")]
     let trace_path = {
         let path = std::path::Path::new("wgpu_trace");
diff --git a/errors/B0006.md b/errors/B0006.md
new file mode 100644
index 0000000000..27d13b1e6b
--- /dev/null
+++ b/errors/B0006.md
@@ -0,0 +1,30 @@
+# B0006
+
+A runtime warning.
+
+Bevy's renderer is designed to be used with hardware acceleration. When initializing the renderer, Bevy will print an `AdapterInfo` line. If the driver in the `AdapterInfo` is indicated to be a software renderer, then the driver does not support hardware acceleration and Bevy will most likely be slow.
+
+## Possible solutions
+
+- Update your graphics driver. Your driver could simply be outdated.
+- It is possible that the hardware itself is too old.
+- You could try using a different backend for the `RenderPlugin`, for example the OpenGL backend. However, please be aware that this could reduce the renderer's performance on other systems that don't have this problem. Here's an example of how to do this:
+
+```rust
+fn main() {
+    App::new()
+        .add_plugins(
+            DefaultPlugins.set(RenderPlugin {
+                render_creation: WgpuSettings {
+                    backends: Some(Backends::GL),
+                    ..default()
+                }
+                .into(),
+                ..default()
+            }),
+        )
+        .run();
+}
+```
+
+The backend can also be configured using environment variables, by setting `WGPU_BACKEND=[backend]` on Linux/Mac or `set WGPU_BACKEND=[backend]` on Windows, where `[backend]` is one of `vulkan`, `metal`, `dx12`, or `gl`.