use std::future::Future; use std::sync::Arc; use wgpu::{Instance, Surface}; use winit::{ application::ApplicationHandler, dpi::PhysicalSize, event::{KeyEvent, WindowEvent}, event_loop::{ActiveEventLoop, EventLoop, EventLoopProxy}, keyboard::{Key, NamedKey}, window::Window, }; pub trait Example: 'static + Sized { const SRGB: bool = true; fn optional_features() -> wgpu::Features { wgpu::Features::empty() } fn required_features() -> wgpu::Features { wgpu::Features::empty() } fn required_downlevel_capabilities() -> wgpu::DownlevelCapabilities { wgpu::DownlevelCapabilities { flags: wgpu::DownlevelFlags::empty(), shader_model: wgpu::ShaderModel::Sm5, ..wgpu::DownlevelCapabilities::default() } } fn required_limits() -> wgpu::Limits { wgpu::Limits::downlevel_webgl2_defaults() // These downlevel limits will allow the code to run on all possible hardware } fn init( config: &wgpu::SurfaceConfiguration, adapter: &wgpu::Adapter, device: &wgpu::Device, queue: &wgpu::Queue, ) -> Self; fn resize( &mut self, config: &wgpu::SurfaceConfiguration, device: &wgpu::Device, queue: &wgpu::Queue, ); fn update(&mut self, event: WindowEvent); fn render(&mut self, view: &wgpu::TextureView, device: &wgpu::Device, queue: &wgpu::Queue); } // Initialize logging in platform dependent ways. fn init_logger() { cfg_if::cfg_if! { if #[cfg(target_arch = "wasm32")] { // As we don't have an environment to pull logging level from, we use the query string. let query_string = web_sys::window().unwrap().location().search().unwrap(); let query_level: Option = parse_url_query_string(&query_string, "RUST_LOG") .and_then(|x| x.parse().ok()); let base_level = query_level.unwrap_or(log::LevelFilter::Info); // On web, we use fern, as console_log doesn't have filtering on a per-module level. fern::Dispatch::new() .level(base_level) .chain(fern::Output::call(console_log::log)) .apply() .unwrap(); std::panic::set_hook(Box::new(console_error_panic_hook::hook)); } else { // parse_default_env will read the RUST_LOG environment variable and apply it on top // of these default filters. env_logger::builder() .filter_level(log::LevelFilter::Info) // Millisecond timestamps; see // . .format_timestamp_millis() .parse_default_env() .init(); } } } /// Runs a future to completion. On native this blocks via pollster, on wasm this spawns /// a local task. This allows the same async wgpu initialization code to work on both platforms. #[cfg(not(target_arch = "wasm32"))] fn spawn(f: impl Future + 'static) { pollster::block_on(f); } /// Runs a future to completion. On native this blocks via pollster, on wasm this spawns /// a local task. This allows the same async wgpu initialization code to work on both platforms. #[cfg(target_arch = "wasm32")] fn spawn(f: impl Future + 'static) { wasm_bindgen_futures::spawn_local(f); } /// Wrapper type which manages the surface and surface configuration. /// /// As surface usage varies per platform, wrapping this up cleans up the event loop code. struct SurfaceWrapper { surface: Option>, config: Option, } impl SurfaceWrapper { /// Create a new surface wrapper with no surface or configuration. fn new() -> Self { Self { surface: None, config: None, } } /// Called after the instance is created, but before we request an adapter. /// /// On wasm, we need to create the surface here, as the WebGL backend needs /// a surface (and hence a canvas) to be present to create the adapter. /// /// We cannot unconditionally create a surface here, as Android requires /// us to wait until we receive the `Resumed` event to do so. fn pre_adapter(&mut self, instance: &Instance, window: Arc) { if cfg!(target_arch = "wasm32") { self.surface = Some(instance.create_surface(window).unwrap()); } } /// Called on resume to create (on native) and configure the surface. /// /// On all native platforms, this is where we create the surface. /// On wasm, the surface was already created in [`Self::pre_adapter`]. /// /// Additionally, we configure the surface based on the (now valid) window size. fn resume(&mut self, context: &ExampleContext, window: Arc, srgb: bool) { // Window size is only actually valid after we enter the event loop. let window_size = window.inner_size(); let width = window_size.width.max(1); let height = window_size.height.max(1); log::info!("Surface resume {window_size:?}"); // We didn't create the surface in pre_adapter, so we need to do so now. if !cfg!(target_arch = "wasm32") { self.surface = Some(context.instance.create_surface(window).unwrap()); } // From here on, self.surface should be Some. let surface = self.surface.as_ref().unwrap(); // Get the default configuration, let mut config = surface .get_default_config(&context.adapter, width, height) .expect("Surface isn't supported by the adapter."); if srgb { // Not all platforms (WebGPU) support sRGB swapchains, so we need to use view formats let view_format = config.format.add_srgb_suffix(); config.view_formats.push(view_format); } else { // All platforms support non-sRGB swapchains, so we can just use the format directly. let format = config.format.remove_srgb_suffix(); config.format = format; config.view_formats.push(format); }; config.desired_maximum_frame_latency = 3; surface.configure(&context.device, &config); self.config = Some(config); } /// Resize the surface, making sure to not resize to zero. fn resize(&mut self, context: &ExampleContext, size: PhysicalSize) { log::info!("Surface resize {size:?}"); let config = self.config.as_mut().unwrap(); config.width = size.width.max(1); config.height = size.height.max(1); let surface = self.surface.as_ref().unwrap(); surface.configure(&context.device, config); } /// Acquire the next surface texture. /// /// Returns `None` on failure. fn acquire( &mut self, context: &ExampleContext, window: Arc, ) -> Option { use wgpu::CurrentSurfaceTexture; let surface = self.surface.as_ref().unwrap(); match surface.get_current_texture() { CurrentSurfaceTexture::Success(frame) => Some(frame), // If we timed out or the window is occluded, skip this frame: CurrentSurfaceTexture::Timeout | CurrentSurfaceTexture::Occluded => None, // If the surface is outdated or suboptimal, reconfigure and retry. CurrentSurfaceTexture::Suboptimal(texture) => { drop(texture); surface.configure(&context.device, self.config()); match surface.get_current_texture() { CurrentSurfaceTexture::Success(frame) | CurrentSurfaceTexture::Suboptimal(frame) => Some(frame), other => panic!("Failed to acquire next surface texture: {other:?}"), } } CurrentSurfaceTexture::Outdated => { surface.configure(&context.device, self.config()); match surface.get_current_texture() { CurrentSurfaceTexture::Success(frame) | CurrentSurfaceTexture::Suboptimal(frame) => Some(frame), other => panic!("Failed to acquire next surface texture: {other:?}"), } } CurrentSurfaceTexture::Validation => { unreachable!("No error scope registered, so validation errors will panic") } // If the surface is lost, recreate and reconfigure it. CurrentSurfaceTexture::Lost => { self.surface = Some(context.instance.create_surface(window).unwrap()); self.surface .as_ref() .unwrap() .configure(&context.device, self.config()); match self.surface.as_ref().unwrap().get_current_texture() { CurrentSurfaceTexture::Success(frame) | CurrentSurfaceTexture::Suboptimal(frame) => Some(frame), other => panic!("Failed to acquire next surface texture: {other:?}"), } } } } /// On suspend on android, we drop the surface, as it's no longer valid. /// /// A suspend event is always followed by at least one resume event. fn suspend(&mut self) { if cfg!(target_os = "android") { self.surface = None; } } fn get(&self) -> Option<&'_ Surface<'static>> { self.surface.as_ref() } fn config(&self) -> &wgpu::SurfaceConfiguration { self.config.as_ref().unwrap() } } /// Context containing global wgpu resources. struct ExampleContext { instance: wgpu::Instance, adapter: wgpu::Adapter, device: wgpu::Device, queue: wgpu::Queue, } impl ExampleContext { /// Initializes the example context. async fn init_async( surface: &mut SurfaceWrapper, window: Arc, display_handle: winit::event_loop::OwnedDisplayHandle, ) -> Self { log::info!("Initializing wgpu..."); let instance_descriptor = wgpu::InstanceDescriptor::new_with_display_handle_from_env(Box::new(display_handle)); let instance = wgpu::Instance::new(instance_descriptor); surface.pre_adapter(&instance, window); let adapter = get_adapter_with_capabilities_or_from_env( &instance, &E::required_features(), &E::required_downlevel_capabilities(), &surface.get(), ) .await; // Make sure we use the texture resolution limits from the adapter, so we can support images the size of the surface. let needed_limits = E::required_limits().using_resolution(adapter.limits()); let info = adapter.get_info(); log::info!("Selected adapter: {} ({:?})", info.name, info.backend); let (device, queue) = adapter .request_device(&wgpu::DeviceDescriptor { label: None, required_features: (E::optional_features() & adapter.features()) | E::required_features(), required_limits: needed_limits, default_queue: wgpu::QueueDescriptor { label: None }, experimental_features: unsafe { wgpu::ExperimentalFeatures::enabled() }, memory_hints: wgpu::MemoryHints::MemoryUsage, trace: match std::env::var_os("WGPU_TRACE") { Some(path) => wgpu::Trace::Directory(path.into()), None => wgpu::Trace::Off, }, }) .await .expect("Unable to find a suitable GPU adapter!"); Self { instance, adapter, device, queue, } } } struct FrameCounter { // Instant of the last time we printed the frame time. last_printed_instant: web_time::Instant, // Number of frames since the last time we printed the frame time. frame_count: u32, } impl FrameCounter { fn new() -> Self { Self { last_printed_instant: web_time::Instant::now(), frame_count: 0, } } fn update(&mut self) { self.frame_count += 1; let new_instant = web_time::Instant::now(); let elapsed_secs = (new_instant - self.last_printed_instant).as_secs_f32(); if elapsed_secs > 1.0 { let elapsed_ms = elapsed_secs * 1000.0; let frame_time = elapsed_ms / self.frame_count as f32; let fps = self.frame_count as f32 / elapsed_secs; log::info!("Frame time {frame_time:.2}ms ({fps:.1} FPS)"); self.last_printed_instant = new_instant; self.frame_count = 0; } } } /// User event sent via [`EventLoopProxy`] to deliver async initialization results /// back to the main event loop. enum AppAction { /// The async wgpu initialization has completed. WgpuInitialized { context: ExampleContext, surface: SurfaceWrapper, }, } #[expect(clippy::large_enum_variant)] enum AppState { /// Waiting for the first `resumed()` call. Uninitialized, /// Window created, async wgpu initialization in progress. Loading, /// Fully initialized and rendering. Running { context: ExampleContext, surface: SurfaceWrapper, example: E, }, } /// The main application struct, implementing winit's [`ApplicationHandler`]. /// /// Winit 0.30 requires that windows are not created until the `resumed()` callback, /// and that all wgpu resources (instance, adapter, device) are initialized after the /// window exists. On native, this init happens synchronously via `pollster::block_on`. /// On wasm, it happens asynchronously via `wasm_bindgen_futures::spawn_local`, with /// the results delivered back through an [`EventLoopProxy`] user event. struct App { title: &'static str, proxy: EventLoopProxy, window: Option>, frame_counter: FrameCounter, occluded: bool, state: AppState, } impl App { fn new(title: &'static str, event_loop: &EventLoop) -> Self { Self { title, proxy: event_loop.create_proxy(), window: None, frame_counter: FrameCounter::new(), occluded: false, state: AppState::Uninitialized, } } } impl ApplicationHandler for App { /// Called when the application is (re)started. On the first call, the window and wgpu /// resources are created. On Android, this may be called again after each suspend — /// in that case we only need to re-create the surface. fn resumed(&mut self, event_loop: &ActiveEventLoop) { // On Android, re-create the surface after a suspend/resume cycle. if let AppState::Running { ref context, ref mut surface, .. } = self.state { if let Some(window) = &self.window { surface.resume(context, window.clone(), E::SRGB); window.request_redraw(); } return; } if !matches!(self.state, AppState::Uninitialized) { return; } self.state = AppState::Loading; #[cfg_attr( not(target_arch = "wasm32"), expect(unused_mut, reason = "wasm32 re-assigns to specify canvas") )] let mut attributes = Window::default_attributes().with_title(self.title); #[cfg(target_arch = "wasm32")] { use wasm_bindgen::JsCast; use winit::platform::web::WindowAttributesExtWebSys; let canvas = web_sys::window() .unwrap() .document() .unwrap() .get_element_by_id("canvas") .unwrap() .dyn_into::() .unwrap(); attributes = attributes.with_canvas(Some(canvas)); } let window = Arc::new( event_loop .create_window(attributes) .expect("Failed to create window"), ); self.window = Some(window.clone()); let display_handle = event_loop.owned_display_handle(); let proxy = self.proxy.clone(); // Spawn the async wgpu initialization. On native, `spawn` uses `pollster::block_on` // so this completes synchronously before `resumed()` returns. On wasm, `spawn` uses // `wasm_bindgen_futures::spawn_local` so the result arrives later via `user_event()`. spawn(async move { let mut surface = SurfaceWrapper::new(); let context = ExampleContext::init_async::(&mut surface, window.clone(), display_handle).await; surface.resume(&context, window, E::SRGB); let _ = proxy.send_event(AppAction::WgpuInitialized { context, surface }); }); } /// Receives the result of the async wgpu initialization. Creates the [`Example`] and /// transitions to the running state. fn user_event(&mut self, _event_loop: &ActiveEventLoop, event: AppAction) { match event { AppAction::WgpuInitialized { context, surface } => { let example = E::init( surface.config(), &context.adapter, &context.device, &context.queue, ); self.state = AppState::Running { context, surface, example, }; if let Some(window) = &self.window { window.request_redraw(); } } } } fn suspended(&mut self, _event_loop: &ActiveEventLoop) { if let AppState::Running { surface, .. } = &mut self.state { surface.suspend(); } } fn window_event( &mut self, event_loop: &ActiveEventLoop, _window_id: winit::window::WindowId, event: WindowEvent, ) { let AppState::Running { ref mut context, ref mut surface, ref mut example, } = self.state else { return; }; match event { WindowEvent::Resized(size) => { surface.resize(context, size); example.resize(surface.config(), &context.device, &context.queue); if let Some(window) = &self.window { window.request_redraw(); } } WindowEvent::KeyboardInput { event: KeyEvent { logical_key: Key::Named(NamedKey::Escape), .. }, .. } | WindowEvent::CloseRequested => { event_loop.exit(); } WindowEvent::RedrawRequested => { // Don't render while occluded, this may leak on apple platforms. if self.occluded { return; } self.frame_counter.update(); let window_arc = self.window.clone().unwrap(); if let Some(frame) = surface.acquire(context, window_arc) { let view = frame.texture.create_view(&wgpu::TextureViewDescriptor { format: Some(surface.config().view_formats[0]), ..wgpu::TextureViewDescriptor::default() }); example.render(&view, &context.device, &context.queue); if let Some(window) = &self.window { window.pre_present_notify(); } context.queue.present(frame); } // Request another redraw to keep the animation loop running. // Examples that only render once (like hello_triangle) omit // this call so the event loop can rest between frames. if let Some(window) = &self.window { window.request_redraw(); } } WindowEvent::Occluded(is_occluded) => { self.occluded = is_occluded; // Resume rendering when un-occluded. if !is_occluded { if let Some(window) = &self.window { window.request_redraw(); } } } _ => example.update(event), } } } fn start(title: &'static str) { init_logger(); log::debug!( "Enabled backends: {:?}", wgpu::Instance::enabled_backend_features() ); let event_loop = EventLoop::with_user_event().build().unwrap(); #[cfg_attr(target_arch = "wasm32", expect(unused_mut))] let mut app = App::::new(title, &event_loop); log::info!("Entering event loop..."); cfg_if::cfg_if! { if #[cfg(target_arch = "wasm32")] { use winit::platform::web::EventLoopExtWebSys; event_loop.spawn_app(app); } else { event_loop.run_app(&mut app).unwrap(); } } } pub fn run(title: &'static str) { start::(title); } #[cfg(target_arch = "wasm32")] /// Parse the query string as returned by `web_sys::window()?.location().search()?` and get a /// specific key out of it. pub fn parse_url_query_string<'a>(query: &'a str, search_key: &str) -> Option<&'a str> { let query_string = query.strip_prefix('?')?; for pair in query_string.split('&') { let mut pair = pair.split('='); let key = pair.next()?; let value = pair.next()?; if key == search_key { return Some(value); } } None } #[cfg(test)] pub use wgpu_test::image::ComparisonType; use crate::utils::get_adapter_with_capabilities_or_from_env; #[cfg(test)] #[derive(Clone)] pub struct ExampleTestParams { pub name: &'static str, // Path to the reference image, relative to the root of the repo. pub image_path: &'static str, pub width: u32, pub height: u32, pub optional_features: wgpu::Features, pub base_test_parameters: wgpu_test::TestParameters, /// Comparisons against FLIP statistics that determine if the test passes or fails. pub comparisons: &'static [ComparisonType], pub _phantom: std::marker::PhantomData, } #[cfg(test)] impl From> for wgpu_test::GpuTestConfiguration { fn from(params: ExampleTestParams) -> Self { wgpu_test::GpuTestConfiguration::new() .name(params.name) .parameters({ assert_eq!(params.width % 64, 0, "width needs to be aligned 64"); let features = E::required_features() | params.optional_features; params .base_test_parameters .clone() .features(features) .limits(E::required_limits()) }) .run_async(move |ctx| async move { let format = if E::SRGB { wgpu::TextureFormat::Rgba8UnormSrgb } else { wgpu::TextureFormat::Rgba8Unorm }; let dst_texture = ctx.device.create_texture(&wgpu::TextureDescriptor { label: Some("destination"), size: wgpu::Extent3d { width: params.width, height: params.height, depth_or_array_layers: 1, }, mip_level_count: 1, sample_count: 1, dimension: wgpu::TextureDimension::D2, format, usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC, view_formats: &[], }); let dst_view = dst_texture.create_view(&wgpu::TextureViewDescriptor::default()); let dst_buffer = ctx.device.create_buffer(&wgpu::BufferDescriptor { label: Some("image map buffer"), size: params.width as u64 * params.height as u64 * 4, usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, mapped_at_creation: false, }); let mut example = E::init( &wgpu::SurfaceConfiguration { usage: wgpu::TextureUsages::RENDER_ATTACHMENT, format, color_space: wgpu::SurfaceColorSpace::Auto, width: params.width, height: params.height, desired_maximum_frame_latency: 2, // Fifo corresponds to traditional VSync. It's supported everywhere. present_mode: wgpu::PresentMode::Fifo, alpha_mode: wgpu::CompositeAlphaMode::Auto, view_formats: vec![format], }, &ctx.adapter, &ctx.device, &ctx.queue, ); example.render(&dst_view, &ctx.device, &ctx.queue); let mut cmd_buf = ctx .device .create_command_encoder(&wgpu::CommandEncoderDescriptor::default()); cmd_buf.copy_texture_to_buffer( wgpu::TexelCopyTextureInfo { texture: &dst_texture, mip_level: 0, origin: wgpu::Origin3d::ZERO, aspect: wgpu::TextureAspect::All, }, wgpu::TexelCopyBufferInfo { buffer: &dst_buffer, layout: wgpu::TexelCopyBufferLayout { offset: 0, bytes_per_row: Some(params.width * 4), rows_per_image: None, }, }, wgpu::Extent3d { width: params.width, height: params.height, depth_or_array_layers: 1, }, ); ctx.queue.submit(Some(cmd_buf.finish())); let dst_buffer_slice = dst_buffer.slice(..); dst_buffer_slice.map_async(wgpu::MapMode::Read, |_| ()); ctx.async_poll(wgpu::PollType::wait_indefinitely()) .await .unwrap(); let bytes = dst_buffer_slice.get_mapped_range().unwrap().to_vec(); wgpu_test::image::compare_image_output( dbg!(env!("CARGO_MANIFEST_DIR").to_string() + "/../../" + params.image_path), &ctx.adapter_info, params.width, params.height, &bytes, params.comparisons, ) .await; }) } }