iced_wgpu/window/
compositor.rs

1//! Connect a window with a renderer.
2use crate::core::Color;
3use crate::core::backend;
4use crate::core::renderer;
5use crate::graphics::color;
6use crate::graphics::compositor;
7use crate::graphics::{self, Antialiasing, Shell, Viewport};
8use crate::{Engine, Renderer};
9
10/// A window graphics backend for iced powered by `wgpu`.
11pub struct Compositor {
12    instance: wgpu::Instance,
13    adapter: wgpu::Adapter,
14    format: wgpu::TextureFormat,
15    alpha_mode: wgpu::CompositeAlphaMode,
16    engine: Engine,
17    settings: Settings,
18}
19
20/// A compositor error.
21#[derive(Debug, Clone, thiserror::Error)]
22pub enum Error {
23    /// The surface creation failed.
24    #[error("the surface creation failed: {0}")]
25    SurfaceCreationFailed(#[from] wgpu::CreateSurfaceError),
26    /// The surface is not compatible.
27    #[error("the surface is not compatible")]
28    IncompatibleSurface,
29    /// No adapter was found for the options requested.
30    #[error("no adapter was found for the options requested: {0:?}")]
31    NoAdapterFound(String),
32    /// No device request succeeded.
33    #[error("no device request succeeded: {0:?}")]
34    RequestDeviceFailed(Vec<(wgpu::Limits, wgpu::RequestDeviceError)>),
35}
36
37impl From<Error> for backend::Error {
38    fn from(error: Error) -> Self {
39        Self::GraphicsAdapterNotFound {
40            backend: "wgpu",
41            reason: backend::Reason::RequestFailed(error.to_string()),
42        }
43    }
44}
45
46impl Compositor {
47    /// Requests a new [`Compositor`] with the given [`Settings`].
48    ///
49    /// Returns `None` if no compatible graphics adapter could be found.
50    pub async fn request(
51        settings: Settings,
52        display: impl compositor::Display,
53        compatible_window: impl compositor::Window,
54        shell: Shell,
55    ) -> Result<Self, Error> {
56        let instance = wgpu::util::new_instance_with_webgpu_detection(wgpu::InstanceDescriptor {
57            backends: settings.backends,
58            flags: if cfg!(feature = "strict-assertions") {
59                wgpu::InstanceFlags::debugging()
60            } else {
61                wgpu::InstanceFlags::empty()
62            },
63            ..wgpu::InstanceDescriptor::new_with_display_handle(Box::new(display))
64        })
65        .await;
66
67        log::info!("{settings:#?}");
68
69        #[cfg(not(target_arch = "wasm32"))]
70        if log::max_level() >= log::LevelFilter::Info {
71            let available_adapters: Vec<_> = instance
72                .enumerate_adapters(settings.backends)
73                .await
74                .iter()
75                .map(wgpu::Adapter::get_info)
76                .collect();
77            log::info!("Available adapters: {available_adapters:#?}");
78        }
79
80        #[allow(unsafe_code)]
81        let compatible_surface = instance
82            .create_surface(wgpu::SurfaceTarget::Window(Box::new(compatible_window)))
83            .ok();
84
85        let power_preference = match settings.power_preference {
86            backend::PowerPreference::None => wgpu::PowerPreference::None,
87            backend::PowerPreference::LowPower => wgpu::PowerPreference::LowPower,
88            backend::PowerPreference::HighPerformance => wgpu::PowerPreference::HighPerformance,
89        };
90
91        let adapter_options = wgpu::RequestAdapterOptions {
92            power_preference: wgpu::PowerPreference::from_env().unwrap_or(power_preference),
93            compatible_surface: compatible_surface.as_ref(),
94            force_fallback_adapter: false,
95        };
96
97        let adapter = instance
98            .request_adapter(&adapter_options)
99            .await
100            .map_err(|_error| Error::NoAdapterFound(format!("{adapter_options:?}")))?;
101
102        log::info!("Selected: {:#?}", adapter.get_info());
103
104        let (format, alpha_mode) = compatible_surface
105            .as_ref()
106            .and_then(|surface| {
107                let capabilities = surface.get_capabilities(&adapter);
108
109                let formats = capabilities.formats.iter().copied();
110
111                log::info!("Available formats: {formats:#?}");
112
113                const BLACKLIST: &[wgpu::TextureFormat] = &[
114                    wgpu::TextureFormat::Rgb10a2Unorm,
115                    wgpu::TextureFormat::Rgb10a2Uint,
116                ];
117
118                let mut formats = formats.filter(|format| {
119                    format.required_features() == wgpu::Features::empty()
120                        && !BLACKLIST.contains(format)
121                });
122
123                let format = if color::GAMMA_CORRECTION {
124                    formats.find(wgpu::TextureFormat::is_srgb)
125                } else {
126                    formats.find(|format| !wgpu::TextureFormat::is_srgb(format))
127                };
128
129                let format = format.or_else(|| {
130                    log::warn!("No format found!");
131
132                    capabilities.formats.first().copied()
133                });
134
135                let alpha_modes = capabilities.alpha_modes;
136
137                log::info!("Available alpha modes: {alpha_modes:#?}");
138
139                let preferred_alpha =
140                    if alpha_modes.contains(&wgpu::CompositeAlphaMode::PreMultiplied) {
141                        wgpu::CompositeAlphaMode::PreMultiplied
142                    } else {
143                        wgpu::CompositeAlphaMode::Auto
144                    };
145
146                format.zip(Some(preferred_alpha))
147            })
148            .ok_or(Error::IncompatibleSurface)?;
149
150        log::info!("Selected format: {format:?} with alpha mode: {alpha_mode:?}");
151
152        #[cfg(target_arch = "wasm32")]
153        let limits = [wgpu::Limits::downlevel_webgl2_defaults().using_resolution(adapter.limits())];
154
155        #[cfg(not(target_arch = "wasm32"))]
156        let limits = [
157            wgpu::Limits::default().using_resolution(adapter.limits()),
158            wgpu::Limits::downlevel_defaults().using_resolution(adapter.limits()),
159        ];
160
161        let limits = limits.into_iter().map(|limits| wgpu::Limits {
162            max_bind_groups: 2,
163            max_non_sampler_bindings: 2048,
164            ..limits
165        });
166
167        // Request SHADER_F16 only if the adapter supports it (e.g., not available in WebGL2)
168        let required_features = if adapter.features().contains(wgpu::Features::SHADER_F16) {
169            wgpu::Features::SHADER_F16
170        } else {
171            wgpu::Features::empty()
172        };
173
174        let mut errors = Vec::new();
175
176        for required_limits in limits {
177            let result = adapter
178                .request_device(&wgpu::DeviceDescriptor {
179                    label: Some("iced_wgpu::window::compositor device descriptor"),
180                    required_features,
181                    required_limits: required_limits.clone(),
182                    memory_hints: wgpu::MemoryHints::MemoryUsage,
183                    trace: wgpu::Trace::Off,
184                    experimental_features: wgpu::ExperimentalFeatures::disabled(),
185                })
186                .await;
187
188            match result {
189                Ok((device, queue)) => {
190                    let engine = Engine::new(
191                        &adapter,
192                        device,
193                        queue,
194                        format,
195                        settings.antialiasing,
196                        shell,
197                    );
198
199                    return Ok(Compositor {
200                        instance,
201                        adapter,
202                        format,
203                        alpha_mode,
204                        engine,
205                        settings,
206                    });
207                }
208                Err(error) => {
209                    errors.push((required_limits, error));
210                }
211            }
212        }
213
214        Err(Error::RequestDeviceFailed(errors))
215    }
216}
217
218/// Creates a [`Compositor`] with the given [`Settings`] and window.
219pub async fn new(
220    settings: Settings,
221    display: impl compositor::Display,
222    compatible_window: impl compositor::Window,
223    shell: Shell,
224) -> Result<Compositor, Error> {
225    Compositor::request(settings, display, compatible_window, shell).await
226}
227
228/// Presents the given primitives with the given [`Compositor`].
229pub fn present(
230    renderer: &mut Renderer,
231    surface: &mut wgpu::Surface<'static>,
232    viewport: &Viewport,
233    background_color: Color,
234    on_pre_present: impl FnOnce(),
235) -> Result<(), compositor::SurfaceError> {
236    match surface.get_current_texture() {
237        wgpu::CurrentSurfaceTexture::Success(frame) => {
238            let view = &frame
239                .texture
240                .create_view(&wgpu::TextureViewDescriptor::default());
241
242            let _submission = renderer.present(
243                Some(background_color),
244                frame.texture.format(),
245                view,
246                viewport,
247            );
248
249            // Present the frame
250            on_pre_present();
251            frame.present();
252
253            Ok(())
254        }
255        wgpu::CurrentSurfaceTexture::Suboptimal(_) | wgpu::CurrentSurfaceTexture::Outdated => {
256            Err(compositor::SurfaceError::Outdated)
257        }
258        wgpu::CurrentSurfaceTexture::Timeout => Err(compositor::SurfaceError::Timeout),
259        wgpu::CurrentSurfaceTexture::Occluded => Err(compositor::SurfaceError::Occluded),
260        wgpu::CurrentSurfaceTexture::Lost => Err(compositor::SurfaceError::Lost),
261        wgpu::CurrentSurfaceTexture::Validation => Err(compositor::SurfaceError::Other),
262    }
263}
264
265impl graphics::Compositor for Compositor {
266    type Renderer = Renderer;
267    type Surface = wgpu::Surface<'static>;
268
269    async fn new(
270        settings: backend::Settings,
271        display: impl compositor::Display,
272        compatible_window: impl compositor::Window,
273        shell: Shell,
274    ) -> Result<Self, backend::Error> {
275        if settings.backend.hardware().is_none() && !settings.backend.matches("wgpu") {
276            return Err(backend::Error::GraphicsAdapterNotFound {
277                backend: "wgpu",
278                reason: backend::Reason::DidNotMatch {
279                    preferred_backend: settings.backend,
280                },
281            });
282        }
283
284        let mut settings = Settings::from(settings);
285
286        if let Some(backends) = wgpu::Backends::from_env() {
287            settings.backends = backends;
288        }
289
290        if let Some(present_mode) = present_mode_from_env() {
291            settings.present_mode = present_mode;
292        }
293
294        Ok(new(settings, display, compatible_window, shell).await?)
295    }
296
297    fn create_renderer(&self, settings: renderer::Settings) -> Self::Renderer {
298        Renderer::new(self.engine.clone(), settings)
299    }
300
301    fn create_surface(
302        &mut self,
303        window: impl compositor::Window,
304        width: u32,
305        height: u32,
306    ) -> Self::Surface {
307        let mut surface = self
308            .instance
309            .create_surface(wgpu::SurfaceTarget::Window(Box::new(window)))
310            .expect("Create surface");
311
312        if width > 0 && height > 0 {
313            self.configure_surface(&mut surface, width, height);
314        }
315
316        surface
317    }
318
319    fn configure_surface(&mut self, surface: &mut Self::Surface, width: u32, height: u32) {
320        surface.configure(
321            &self.engine.device,
322            &wgpu::SurfaceConfiguration {
323                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
324                format: self.format,
325                present_mode: self.settings.present_mode,
326                width,
327                height,
328                alpha_mode: self.alpha_mode,
329                view_formats: vec![],
330                desired_maximum_frame_latency: 1,
331            },
332        );
333    }
334
335    fn information(&self) -> compositor::Information {
336        let information = self.adapter.get_info();
337
338        compositor::Information {
339            adapter: information.name,
340            backend: format!("{:?}", information.backend),
341        }
342    }
343
344    fn present(
345        &mut self,
346        renderer: &mut Self::Renderer,
347        surface: &mut Self::Surface,
348        viewport: &Viewport,
349        background_color: Color,
350        on_pre_present: impl FnOnce(),
351    ) -> Result<(), compositor::SurfaceError> {
352        present(
353            renderer,
354            surface,
355            viewport,
356            background_color,
357            on_pre_present,
358        )
359    }
360
361    fn screenshot(
362        &mut self,
363        renderer: &mut Self::Renderer,
364        viewport: &Viewport,
365        background_color: Color,
366    ) -> Vec<u8> {
367        renderer.screenshot(viewport, background_color)
368    }
369}
370
371/// The settings of a [`Compositor`].
372#[derive(Debug, Clone, Copy, PartialEq)]
373pub struct Settings {
374    /// The present mode of the [`Renderer`].
375    ///
376    /// [`Renderer`]: crate::Renderer
377    pub present_mode: wgpu::PresentMode,
378
379    /// The graphics backends to use.
380    pub backends: wgpu::Backends,
381
382    /// The power-usage preference for graphics adapters.
383    ///
384    /// By default, it is [`backend::PowerPreference::None`].
385    pub power_preference: backend::PowerPreference,
386
387    /// The antialiasing strategy that will be used for triangle primitives.
388    ///
389    /// By default, it is `None`.
390    pub antialiasing: Option<Antialiasing>,
391}
392
393impl Default for Settings {
394    fn default() -> Settings {
395        Settings {
396            present_mode: wgpu::PresentMode::AutoVsync,
397            backends: wgpu::Backends::all(),
398            power_preference: backend::PowerPreference::None,
399            antialiasing: None,
400        }
401    }
402}
403
404impl From<backend::Settings> for Settings {
405    fn from(settings: backend::Settings) -> Self {
406        let backends = settings
407            .backend
408            .hardware()
409            .map(|api| match api {
410                backend::Api::Best => wgpu::Backends::all(),
411                backend::Api::Vulkan => wgpu::Backends::VULKAN,
412                backend::Api::Metal => wgpu::Backends::METAL,
413                backend::Api::DirectX12 => wgpu::Backends::DX12,
414                backend::Api::OpenGL => wgpu::Backends::GL,
415                backend::Api::WebGPU => wgpu::Backends::BROWSER_WEBGPU,
416            })
417            .unwrap_or_else(wgpu::Backends::all);
418
419        Self {
420            present_mode: if settings.vsync {
421                wgpu::PresentMode::AutoVsync
422            } else {
423                wgpu::PresentMode::AutoNoVsync
424            },
425            antialiasing: settings.antialiasing.then_some(Antialiasing::MSAAx4),
426            backends,
427            power_preference: settings.power_preference,
428        }
429    }
430}
431
432/// Obtains a [`wgpu::PresentMode`] from the current environment
433/// configuration, if set.
434///
435/// The value returned by this function can be changed by setting
436/// the `ICED_PRESENT_MODE` env variable. The possible values are:
437///
438/// - `vsync` → [`wgpu::PresentMode::AutoVsync`]
439/// - `no_vsync` → [`wgpu::PresentMode::AutoNoVsync`]
440/// - `immediate` → [`wgpu::PresentMode::Immediate`]
441/// - `fifo` → [`wgpu::PresentMode::Fifo`]
442/// - `fifo_relaxed` → [`wgpu::PresentMode::FifoRelaxed`]
443/// - `mailbox` → [`wgpu::PresentMode::Mailbox`]
444pub fn present_mode_from_env() -> Option<wgpu::PresentMode> {
445    let present_mode = std::env::var("ICED_PRESENT_MODE").ok()?;
446
447    match present_mode.to_lowercase().as_str() {
448        "vsync" => Some(wgpu::PresentMode::AutoVsync),
449        "no_vsync" => Some(wgpu::PresentMode::AutoNoVsync),
450        "immediate" => Some(wgpu::PresentMode::Immediate),
451        "fifo" => Some(wgpu::PresentMode::Fifo),
452        "fifo_relaxed" => Some(wgpu::PresentMode::FifoRelaxed),
453        "mailbox" => Some(wgpu::PresentMode::Mailbox),
454        _ => None,
455    }
456}
iced_wgpu/window/compositor.rs

iced_wgpu/window/
compositor.rs
