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_non_sampler_bindings: 2048,
163            ..limits
164        });
165
166        // Request SHADER_F16 only if the adapter supports it (e.g., not available in WebGL2)
167        let required_features = if adapter.features().contains(wgpu::Features::SHADER_F16) {
168            wgpu::Features::SHADER_F16
169        } else {
170            wgpu::Features::empty()
171        };
172
173        let mut errors = Vec::new();
174
175        for required_limits in limits {
176            let result = adapter
177                .request_device(&wgpu::DeviceDescriptor {
178                    label: Some("iced_wgpu::window::compositor device descriptor"),
179                    required_features,
180                    required_limits: required_limits.clone(),
181                    memory_hints: wgpu::MemoryHints::MemoryUsage,
182                    trace: wgpu::Trace::Off,
183                    experimental_features: wgpu::ExperimentalFeatures::disabled(),
184                })
185                .await;
186
187            match result {
188                Ok((device, queue)) => {
189                    let engine = Engine::new(
190                        &adapter,
191                        device,
192                        queue,
193                        format,
194                        settings.antialiasing,
195                        shell,
196                    );
197
198                    return Ok(Compositor {
199                        instance,
200                        adapter,
201                        format,
202                        alpha_mode,
203                        engine,
204                        settings,
205                    });
206                }
207                Err(error) => {
208                    errors.push((required_limits, error));
209                }
210            }
211        }
212
213        Err(Error::RequestDeviceFailed(errors))
214    }
215}
216
217/// Creates a [`Compositor`] with the given [`Settings`] and window.
218pub async fn new(
219    settings: Settings,
220    display: impl compositor::Display,
221    compatible_window: impl compositor::Window,
222    shell: Shell,
223) -> Result<Compositor, Error> {
224    Compositor::request(settings, display, compatible_window, shell).await
225}
226
227/// Presents the given primitives with the given [`Compositor`].
228pub fn present(
229    renderer: &mut Renderer,
230    surface: &mut wgpu::Surface<'static>,
231    viewport: &Viewport,
232    background_color: Color,
233    on_pre_present: impl FnOnce(),
234) -> Result<(), compositor::SurfaceError> {
235    match surface.get_current_texture() {
236        wgpu::CurrentSurfaceTexture::Success(frame) => {
237            let view = &frame
238                .texture
239                .create_view(&wgpu::TextureViewDescriptor::default());
240
241            let _submission = renderer.present(
242                Some(background_color),
243                frame.texture.format(),
244                view,
245                viewport,
246            );
247
248            // Present the frame
249            on_pre_present();
250            frame.present();
251
252            Ok(())
253        }
254        wgpu::CurrentSurfaceTexture::Suboptimal(_) | wgpu::CurrentSurfaceTexture::Outdated => {
255            Err(compositor::SurfaceError::Outdated)
256        }
257        wgpu::CurrentSurfaceTexture::Timeout => Err(compositor::SurfaceError::Timeout),
258        wgpu::CurrentSurfaceTexture::Occluded => Err(compositor::SurfaceError::Occluded),
259        wgpu::CurrentSurfaceTexture::Lost => Err(compositor::SurfaceError::Lost),
260        wgpu::CurrentSurfaceTexture::Validation => Err(compositor::SurfaceError::Other),
261    }
262}
263
264impl graphics::Compositor for Compositor {
265    type Renderer = Renderer;
266    type Surface = wgpu::Surface<'static>;
267
268    async fn new(
269        settings: backend::Settings,
270        display: impl compositor::Display,
271        compatible_window: impl compositor::Window,
272        shell: Shell,
273    ) -> Result<Self, backend::Error> {
274        if settings.backend.hardware().is_none() && !settings.backend.matches("wgpu") {
275            return Err(backend::Error::GraphicsAdapterNotFound {
276                backend: "wgpu",
277                reason: backend::Reason::DidNotMatch {
278                    preferred_backend: settings.backend,
279                },
280            });
281        }
282
283        let mut settings = Settings::from(settings);
284
285        if let Some(backends) = wgpu::Backends::from_env() {
286            settings.backends = backends;
287        }
288
289        if let Some(present_mode) = present_mode_from_env() {
290            settings.present_mode = present_mode;
291        }
292
293        Ok(new(settings, display, compatible_window, shell).await?)
294    }
295
296    fn create_renderer(&self, settings: renderer::Settings) -> Self::Renderer {
297        Renderer::new(self.engine.clone(), settings)
298    }
299
300    fn create_surface(
301        &mut self,
302        window: impl compositor::Window,
303        width: u32,
304        height: u32,
305    ) -> Self::Surface {
306        let mut surface = self
307            .instance
308            .create_surface(wgpu::SurfaceTarget::Window(Box::new(window)))
309            .expect("Create surface");
310
311        if width > 0 && height > 0 {
312            self.configure_surface(&mut surface, width, height);
313        }
314
315        surface
316    }
317
318    fn configure_surface(&mut self, surface: &mut Self::Surface, width: u32, height: u32) {
319        surface.configure(
320            &self.engine.device,
321            &wgpu::SurfaceConfiguration {
322                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
323                format: self.format,
324                present_mode: self.settings.present_mode,
325                width,
326                height,
327                alpha_mode: self.alpha_mode,
328                view_formats: vec![],
329                desired_maximum_frame_latency: 1,
330            },
331        );
332    }
333
334    fn information(&self) -> compositor::Information {
335        let information = self.adapter.get_info();
336
337        compositor::Information {
338            adapter: information.name,
339            backend: format!("{:?}", information.backend),
340        }
341    }
342
343    fn present(
344        &mut self,
345        renderer: &mut Self::Renderer,
346        surface: &mut Self::Surface,
347        viewport: &Viewport,
348        background_color: Color,
349        on_pre_present: impl FnOnce(),
350    ) -> Result<(), compositor::SurfaceError> {
351        present(
352            renderer,
353            surface,
354            viewport,
355            background_color,
356            on_pre_present,
357        )
358    }
359
360    fn screenshot(
361        &mut self,
362        renderer: &mut Self::Renderer,
363        viewport: &Viewport,
364        background_color: Color,
365    ) -> Vec<u8> {
366        renderer.screenshot(viewport, background_color)
367    }
368}
369
370/// The settings of a [`Compositor`].
371#[derive(Debug, Clone, Copy, PartialEq)]
372pub struct Settings {
373    /// The present mode of the [`Renderer`].
374    ///
375    /// [`Renderer`]: crate::Renderer
376    pub present_mode: wgpu::PresentMode,
377
378    /// The graphics backends to use.
379    pub backends: wgpu::Backends,
380
381    /// The power-usage preference for graphics adapters.
382    ///
383    /// By default, it is [`backend::PowerPreference::None`].
384    pub power_preference: backend::PowerPreference,
385
386    /// The antialiasing strategy that will be used for triangle primitives.
387    ///
388    /// By default, it is `None`.
389    pub antialiasing: Option<Antialiasing>,
390}
391
392impl Default for Settings {
393    fn default() -> Settings {
394        Settings {
395            present_mode: wgpu::PresentMode::AutoVsync,
396            backends: wgpu::Backends::all(),
397            power_preference: backend::PowerPreference::None,
398            antialiasing: None,
399        }
400    }
401}
402
403impl From<backend::Settings> for Settings {
404    fn from(settings: backend::Settings) -> Self {
405        let backends = settings
406            .backend
407            .hardware()
408            .map(|api| match api {
409                backend::Api::Best => wgpu::Backends::all(),
410                backend::Api::Vulkan => wgpu::Backends::VULKAN,
411                backend::Api::Metal => wgpu::Backends::METAL,
412                backend::Api::DirectX12 => wgpu::Backends::DX12,
413                backend::Api::OpenGL => wgpu::Backends::GL,
414                backend::Api::WebGPU => wgpu::Backends::BROWSER_WEBGPU,
415            })
416            .unwrap_or_else(wgpu::Backends::all);
417
418        Self {
419            present_mode: if settings.vsync {
420                wgpu::PresentMode::AutoVsync
421            } else {
422                wgpu::PresentMode::AutoNoVsync
423            },
424            antialiasing: settings.antialiasing.then_some(Antialiasing::MSAAx4),
425            backends,
426            power_preference: settings.power_preference,
427        }
428    }
429}
430
431/// Obtains a [`wgpu::PresentMode`] from the current environment
432/// configuration, if set.
433///
434/// The value returned by this function can be changed by setting
435/// the `ICED_PRESENT_MODE` env variable. The possible values are:
436///
437/// - `vsync` → [`wgpu::PresentMode::AutoVsync`]
438/// - `no_vsync` → [`wgpu::PresentMode::AutoNoVsync`]
439/// - `immediate` → [`wgpu::PresentMode::Immediate`]
440/// - `fifo` → [`wgpu::PresentMode::Fifo`]
441/// - `fifo_relaxed` → [`wgpu::PresentMode::FifoRelaxed`]
442/// - `mailbox` → [`wgpu::PresentMode::Mailbox`]
443pub fn present_mode_from_env() -> Option<wgpu::PresentMode> {
444    let present_mode = std::env::var("ICED_PRESENT_MODE").ok()?;
445
446    match present_mode.to_lowercase().as_str() {
447        "vsync" => Some(wgpu::PresentMode::AutoVsync),
448        "no_vsync" => Some(wgpu::PresentMode::AutoNoVsync),
449        "immediate" => Some(wgpu::PresentMode::Immediate),
450        "fifo" => Some(wgpu::PresentMode::Fifo),
451        "fifo_relaxed" => Some(wgpu::PresentMode::FifoRelaxed),
452        "mailbox" => Some(wgpu::PresentMode::Mailbox),
453        _ => None,
454    }
455}
iced_wgpu/window/compositor.rs

iced_wgpu/window/
compositor.rs
