Fix WSL support, update troubleshooting guide (#8610)

Author: Wumpf

Cargo.lock

@@ -1948,7 +1948,7 @@ checksum = "0d6ef0072f8a535281e4876be788938b528e9a1d43900b82c2569af7da799125"
 [[package]]
 name = "ecolor"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "bytemuck",
  "color-hex",
@@ -1965,7 +1965,7 @@ checksum = "18aade80d5e09429040243ce1143ddc08a92d7a22820ac512610410a4dd5214f"
 [[package]]
 name = "eframe"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "ahash",
  "bytemuck",
@@ -2004,11 +2004,12 @@ dependencies = [
 [[package]]
 name = "egui"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "accesskit",
  "ahash",
  "backtrace",
+ "bitflags 2.6.0",
  "emath",
  "epaint",
  "log",
@@ -2021,7 +2022,7 @@ dependencies = [
 [[package]]
 name = "egui-wgpu"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "ahash",
  "bytemuck",
@@ -2040,7 +2041,7 @@ dependencies = [
 [[package]]
 name = "egui-winit"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "accesskit_winit",
  "ahash",
@@ -2081,7 +2082,7 @@ dependencies = [
 [[package]]
 name = "egui_extras"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "ahash",
  "egui",
@@ -2098,7 +2099,7 @@ dependencies = [
 [[package]]
 name = "egui_glow"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "ahash",
  "bytemuck",
@@ -2115,7 +2116,7 @@ dependencies = [
 [[package]]
 name = "egui_kittest"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "dify",
  "eframe",
@@ -2124,12 +2125,13 @@ dependencies = [
  "image",
  "kittest",
  "pollster 0.4.0",
+ "wgpu",
 ]
 
 [[package]]
 name = "egui_plot"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui_plot.git?rev=4a16b8842aa39e6ea6b6c9c98afe20e060e767b6#4a16b8842aa39e6ea6b6c9c98afe20e060e767b6"
+source = "git+https://github.com/emilk/egui_plot.git?rev=80e2199a2e121db288fe6b0099d91c35acc75a7c#80e2199a2e121db288fe6b0099d91c35acc75a7c"
 dependencies = [
  "ahash",
  "egui",
@@ -2185,7 +2187,7 @@ checksum = "60b1af1c220855b6ceac025d3f6ecdd2b7c4894bfe9cd9bda4fbb4bc7c0d4cf0"
 [[package]]
 name = "emath"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "bytemuck",
  "serde",
@@ -2301,7 +2303,7 @@ dependencies = [
 [[package]]
 name = "epaint"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 dependencies = [
  "ab_glyph",
  "ahash",
@@ -2320,7 +2322,7 @@ dependencies = [
 [[package]]
 name = "epaint_default_fonts"
 version = "0.30.0"
-source = "git+https://github.com/emilk/egui.git?rev=938d8b0d2e2a551ac354d76d6208188e5942b21e#938d8b0d2e2a551ac354d76d6208188e5942b21e"
+source = "git+https://github.com/emilk/egui.git?rev=f0d7c74e838b8e8920a22e7515990fbe057ec218#f0d7c74e838b8e8920a22e7515990fbe057ec218"
 
 [[package]]
 name = "equivalent"
@@ -2908,6 +2910,18 @@ dependencies = [
  "bitflags 2.6.0",
 ]
 
+[[package]]
+name = "gpu-allocator"
+version = "0.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c151a2a5ef800297b4e79efa4f4bec035c5f51d5ae587287c9b952bdf734cacd"
+dependencies = [
+ "log",
+ "presser",
+ "thiserror 1.0.65",
+ "windows 0.58.0",
+]
+
 [[package]]
 name = "gpu-descriptor"
 version = "0.3.0"
@@ -5118,6 +5132,12 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "presser"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8cf8e6a8aa66ce33f63993ffc4ea4271eb5b0530a9002db8455ea6050c77bfa"
+
 [[package]]
 name = "prettyplease"
 version = "0.2.25"
@@ -5462,6 +5482,12 @@ dependencies = [
  "rand",
 ]
 
+[[package]]
+name = "range-alloc"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c8a99fddc9f0ba0a85884b8d14e3592853e787d581ca1816c91349b10e4eeab"
+
 [[package]]
 name = "raw-cpuid"
 version = "11.2.0"
@@ -9723,6 +9749,7 @@ dependencies = [
  "android_system_properties",
  "arrayvec",
  "ash",
+ "bit-set",
  "bitflags 2.6.0",
  "block",
  "bytemuck",
@@ -9731,6 +9758,7 @@ dependencies = [
  "glow 0.14.2",
  "glutin_wgl_sys",
  "gpu-alloc",
+ "gpu-allocator",
  "gpu-descriptor",
  "js-sys",
  "khronos-egl",
@@ -9744,6 +9772,7 @@ dependencies = [
  "once_cell",
  "parking_lot",
  "profiling",
+ "range-alloc",
  "raw-window-handle",
  "renderdoc-sys",
  "rustc-hash 1.1.0",
@@ -9753,6 +9782,7 @@ dependencies = [
  "web-sys",
  "wgpu-types",
  "windows 0.58.0",
+ "windows-core 0.58.0",
 ]
 
 [[package]]

Cargo.toml

@@ -558,13 +558,13 @@ significant_drop_tightening = "allow" # An update of parking_lot made this trigg
 # As a last resport, patch with a commit to our own repository.
 # ALWAYS document what PR the commit hash is part of, or when it was merged into the upstream trunk.
 
-ecolor = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }       # egui master 2025-01-03
-eframe = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }       # egui master 2025-01-03
-egui = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }         # egui master 2025-01-03
-egui_extras = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }  # egui master 2025-01-03
-egui_kittest = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" } # egui master 2025-01-03
-egui-wgpu = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }    # egui master 2025-01-03
-emath = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354d76d6208188e5942b21e" }        # egui master 2025-01-03
+ecolor = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }       # egui master 2025-01-08
+eframe = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }       # egui master 2025-01-08
+egui = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }         # egui master 2025-01-08
+egui_extras = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }  # egui master 2025-01-08
+egui_kittest = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" } # egui master 2025-01-08
+egui-wgpu = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }    # egui master 2025-01-08
+emath = { git = "https://github.com/emilk/egui.git", rev = "f0d7c74e838b8e8920a22e7515990fbe057ec218" }        # egui master 2025-01-08
 
 # Useful while developing:
 # ecolor = { path = "../../egui/crates/ecolor" }
@@ -575,7 +575,7 @@ emath = { git = "https://github.com/emilk/egui.git", rev = "938d8b0d2e2a551ac354
 # egui-wgpu = { path = "../../egui/crates/egui-wgpu" }
 # emath = { path = "../../egui/crates/emath" }
 
-egui_plot = { git = "https://github.com/emilk/egui_plot.git", rev = "4a16b8842aa39e6ea6b6c9c98afe20e060e767b6" }
+egui_plot = { git = "https://github.com/emilk/egui_plot.git", rev = "80e2199a2e121db288fe6b0099d91c35acc75a7c" }
 # egui_plot = { path = "../../egui_plot/egui_plot" }
 
 # egui_tiles = { git = "https://github.com/rerun-io/egui_tiles", rev = "48e0ef566479000a23d8dabf84badced98f1b9a6" } # https://github.com/rerun-io/egui_tiles/pull/89 2024-11-19

crates/top/rerun/src/commands/entrypoint.rs

@@ -857,7 +857,7 @@ fn run_impl(
                 }
                 Box::new(app)
             }),
-            args.renderer,
+            args.renderer.as_deref(),
         )
         .map_err(|err| err.into());
 

crates/viewer/re_component_ui/src/marker_shape.rs

@@ -39,7 +39,7 @@ pub(crate) fn edit_marker_shape_ui(
 
                             if response.clicked() {
                                 *edit_marker = marker;
-                                response.changed = true;
+                                response.mark_changed();
                             }
 
                             combined_response = Some(match combined_response {

crates/viewer/re_renderer/src/config.rs

@@ -61,7 +61,25 @@ impl DeviceTier {
             flags: match self {
                 Self::Gles => wgpu::DownlevelFlags::empty(),
                 // Require fully WebGPU compliance for the native tier.
-                Self::FullWebGpuSupport => wgpu::DownlevelFlags::all(),
+                Self::FullWebGpuSupport => {
+                    // Turn a blind eye on a few features that are missing as of writing in WSL even with latest Vulkan drivers.
+                    // Pretend we still have full WebGPU support anyways.
+                    wgpu::DownlevelFlags::compliant()
+                        // Lacking `SURFACE_VIEW_FORMATS` means we can't set the format of views on surface textures
+                        // (the result of `get_current_texture`).
+                        // And the surface won't tell us which formats are supported.
+                        // We avoid doing anything wonky with surfaces anyways, so we won't hit this.
+                        .intersection(wgpu::DownlevelFlags::SURFACE_VIEW_FORMATS.complement())
+                        // Lacking `FULL_DRAW_INDEX_UINT32` means that vertex indices above 2^24-1 are invalid.
+                        // I.e. we can only draw with about 16.8mio vertices per mesh.
+                        // Typically we don't reach this limit.
+                        //
+                        // This can happen if…
+                        // * OpenGL: `GL_MAX_ELEMENT_INDEX` reports a value lower than `std::u32::MAX`
+                        // * Vulkan: `VkPhysicalDeviceLimits::fullDrawIndexUint32` is false.
+                        // The consequence of exceeding this limit seems to be undefined.
+                        .intersection(wgpu::DownlevelFlags::FULL_DRAW_INDEX_UINT32.complement())
+                }
             },
             limits: Default::default(), // unused so far both here and in wgpu as of writing.
 
@@ -84,6 +102,7 @@ impl DeviceTier {
         downlevel_caps: &wgpu::DownlevelCapabilities,
     ) -> Result<(), InsufficientDeviceCapabilities> {
         let required_downlevel_caps_webgpu = self.required_downlevel_capabilities();
+
         if downlevel_caps.shader_model < required_downlevel_caps_webgpu.shader_model {
             Err(InsufficientDeviceCapabilities::TooLowShaderModel {
                 required: required_downlevel_caps_webgpu.shader_model,
@@ -296,6 +315,47 @@ impl DeviceCaps {
     }
 }
 
+pub fn instance_descriptor(force_backend: Option<&str>) -> wgpu::InstanceDescriptor {
+    let backends = if let Some(force_backend) = force_backend {
+        if let Some(backend) = parse_graphics_backend(force_backend) {
+            if let Err(err) = validate_graphics_backend_applicability(backend) {
+                re_log::error!("Failed to force rendering backend parsed from {force_backend:?}: {err}\nUsing default backend instead.");
+                supported_backends()
+            } else {
+                re_log::info!("Forcing graphics backend to {backend:?}.");
+                backend.into()
+            }
+        } else {
+            re_log::error!("Failed to parse rendering backend string {force_backend:?}. Using default backend instead.");
+            supported_backends()
+        }
+    } else {
+        supported_backends()
+    };
+
+    wgpu::InstanceDescriptor {
+        backends,
+
+        flags: wgpu::InstanceFlags::default()
+            // Allow adapters that aren't compliant with the backend they're implementing.
+            // A concrete example of this is the latest Vulkan drivers on WSL which (as of writing)
+            // advertise themselves as not being Vulkan compliant but work fine for the most part.
+            //
+            // In the future we might consider enabling this _only_ for WSL as this might otherwise
+            // cause us to run with arbitrary development versions of drivers.
+            // (then again, if a user has such a driver they likely *want* us to run with it anyways!)
+            .union(wgpu::InstanceFlags::ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER)
+            // Allow manipulation via environment variables.
+            .with_env(),
+
+        // FXC isn't great (slow & outdated), but DXC is painful to ship as it has to be provided separately.
+        // (Note though that we generally prefer running with Vulkan)
+        dx12_shader_compiler: wgpu::Dx12Compiler::Fxc,
+
+        gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
+    }
+}
+
 /// Backends that are officially supported by `re_renderer`.
 ///
 /// Other backend might work as well, but lack of support isn't regarded as a bug.

crates/viewer/re_renderer/src/context.rs

@@ -23,7 +23,8 @@ const STARTUP_FRAME_IDX: u64 = u64::MAX;
 #[derive(thiserror::Error, Debug)]
 pub enum RenderContextError {
     #[error(
-        "The GPU/graphics driver is lacking some abilities: {0}.\nConsider updating the driver."
+        "The GPU/graphics driver is lacking some abilities: {0}. \
+        Check the troubleshooting guide at https://rerun.io/docs/getting-started/troubleshooting and consider updating your graphics driver."
     )]
     InsufficientDeviceCapabilities(#[from] crate::config::InsufficientDeviceCapabilities),
 }

crates/viewer/re_renderer_examples/framework.rs

@@ -7,11 +7,7 @@ use std::sync::Arc;
 use anyhow::Context as _;
 use web_time::Instant;
 
-use re_renderer::{
-    config::{supported_backends, DeviceCaps},
-    view_builder::ViewBuilder,
-    RenderContext,
-};
+use re_renderer::{config::DeviceCaps, view_builder::ViewBuilder, RenderContext};
 
 use winit::{
     application::ApplicationHandler,
@@ -112,14 +108,12 @@ fn preferred_framebuffer_format(formats: &[wgpu::TextureFormat]) -> wgpu::Textur
 impl<E: Example + 'static> Application<E> {
     async fn new(window: Window) -> anyhow::Result<Self> {
         let window = Arc::new(window);
-        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
-            backends: supported_backends(),
-            flags: wgpu::InstanceFlags::default()
-                // Run without validation layers, they can be annoying on shader reload depending on the backend.
-                .intersection(wgpu::InstanceFlags::VALIDATION.complement()),
-            dx12_shader_compiler: wgpu::Dx12Compiler::Fxc,
-            gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
-        });
+
+        let mut instance_desc = re_renderer::config::instance_descriptor(None);
+        // Run without validation layers, they can be annoying on shader reload depending on the backend.
+        instance_desc.flags.remove(wgpu::InstanceFlags::VALIDATION);
+
+        let instance = wgpu::Instance::new(instance_desc);
         let surface = instance.create_surface(window.clone()).unwrap();
         let adapter = instance
             .request_adapter(&wgpu::RequestAdapterOptions {

crates/viewer/re_ui/examples/re_ui_example/main.rs

@@ -441,7 +441,7 @@ impl egui_tiles::Behavior<Tab> for MyTileTreeBehavior {
         _tile_id: egui_tiles::TileId,
         _pane: &mut Tab,
     ) -> egui_tiles::UiResponse {
-        egui::Frame::none().inner_margin(4.0).show(ui, |ui| {
+        egui::Frame::new().inner_margin(4.0).show(ui, |ui| {
             egui::warn_if_debug_build(ui);
             ui.label("Hover me for a tooltip")
                 .on_hover_text("This is a tooltip");

crates/viewer/re_ui/src/list_item/list_item.rs

@@ -332,8 +332,8 @@ impl ListItem {
         // override_hover should not affect the returned response
         let mut style_response = response.clone();
         if force_hovered {
-            style_response.contains_pointer = true;
-            style_response.hovered = true;
+            style_response.flags |= egui::response::Flags::CONTAINS_POINTER;
+            style_response.flags |= egui::response::Flags::HOVERED;
         }
 
         let mut collapse_response = None;

crates/viewer/re_ui/src/ui_ext.rs

@@ -25,7 +25,7 @@ fn notification_label(
     visible_text: &str,
     full_text: &str,
 ) -> egui::Response {
-    egui::Frame::none()
+    egui::Frame::new()
         .stroke((1.0, fg_color))
         .fill(error_label_bg_color(fg_color))
         .rounding(4.0)