ailloli_ui_winit/
wgpu_bootstrap.rs

1//! Create a [`ailloli_ui_render_wgpu::Renderer`] from a winit window.
2
3use std::sync::Arc;
4
5use ailloli_ui_render_wgpu::{
6    PhysicalExtent, Renderer, RendererError, RendererOptions, SurfaceReattachOutcome,
7};
8use winit::window::Window;
9
10/// Builds the GPU renderer for the given window.
11///
12/// The window is wrapped in `Arc` so the wgpu `Surface` and the application
13/// co-own it. Without shared ownership, the surface could
14/// reference a moved/dropped window, causing flaky Wayland segfaults at startup.
15/// The current physical inner size, including a possible zero minimized size,
16/// seeds renderer configuration; renderer defaults choose the remaining policy.
17///
18/// # Errors
19///
20/// Propagates adapter, device, surface, and renderer initialization failures.
21///
22/// # Examples
23///
24/// ```no_run
25/// use std::sync::Arc;
26/// use ailloli_ui_winit::wgpu_bootstrap::renderer_from_window;
27/// fn initialize(window: Arc<winit::window::Window>) {
28///     let renderer: ailloli_ui_render_wgpu::Renderer = renderer_from_window(window).unwrap();
29///     let _ = renderer;
30/// }
31/// ```
32pub fn renderer_from_window(window: Arc<Window>) -> Result<Renderer, RendererError> {
33    renderer_from_window_with_options(window, RendererOptions::default())
34}
35
36/// Builds the GPU renderer with explicit host-neutral renderer options.
37///
38/// The window and wgpu surface share ownership. A pre-present callback invokes
39/// winit's [`Window::pre_present_notify`] before each platform presentation.
40///
41/// # Errors
42///
43/// Propagates adapter, device, surface, and renderer initialization failures.
44///
45/// # Examples
46///
47/// ```no_run
48/// use std::sync::Arc;
49/// use ailloli_ui_render_wgpu::RendererOptions;
50/// fn initialize(window: Arc<winit::window::Window>) {
51///     let renderer = ailloli_ui_winit::wgpu_bootstrap::renderer_from_window_with_options(
52///         window,
53///         RendererOptions::default(),
54///     ).unwrap();
55///     let _: ailloli_ui_render_wgpu::Renderer = renderer;
56/// }
57/// ```
58pub fn renderer_from_window_with_options(
59    window: Arc<Window>,
60    options: RendererOptions,
61) -> Result<Renderer, RendererError> {
62    let size = window.inner_size();
63    let notify_window = window.clone();
64    Renderer::new_with_surface_target(
65        window,
66        PhysicalExtent::new(size.width, size.height),
67        options,
68        Some(Arc::new(move || notify_window.pre_present_notify())),
69    )
70}
71
72/// Detaches native presentation while retaining the renderer's GPU context.
73///
74/// The caller must drop the winit window only after this function returns so
75/// the surface's raw handles remain valid through the attachment teardown.
76/// `true` means an attached surface was removed; `false` means the renderer was
77/// already detached. GPU devices, pipelines, caches, and offscreen state remain.
78///
79/// # Examples
80///
81/// ```no_run
82/// fn suspend(renderer: &mut ailloli_ui_render_wgpu::Renderer) {
83///     let detached: bool =
84///         ailloli_ui_winit::wgpu_bootstrap::detach_renderer_surface(renderer);
85///     let _ = detached;
86/// }
87/// ```
88pub fn detach_renderer_surface(renderer: &mut Renderer) -> bool {
89    renderer.detach_surface()
90}
91
92/// Reattaches a retained renderer to a newly-created winit window.
93///
94/// Compatible surfaces reuse the existing instance, adapter, device, queue,
95/// pipelines, and caches. The renderer performs a full GPU bootstrap fallback
96/// when the retained adapter cannot present to the new surface.
97/// The new window's current physical client size becomes the surface extent,
98/// and winit's pre-present callback is installed for subsequent frames.
99///
100/// # Errors
101///
102/// Propagates surface creation, compatibility, or fallback bootstrap failures.
103///
104/// # Examples
105///
106/// ```no_run
107/// use std::sync::Arc;
108/// use ailloli_ui_render_wgpu::{Renderer, SurfaceReattachOutcome};
109/// fn resume(renderer: &mut Renderer, window: Arc<winit::window::Window>) {
110///     let outcome: SurfaceReattachOutcome =
111///         ailloli_ui_winit::wgpu_bootstrap::reattach_renderer_to_window(renderer, window)
112///             .unwrap();
113///     let _ = outcome;
114/// }
115/// ```
116pub fn reattach_renderer_to_window(
117    renderer: &mut Renderer,
118    window: Arc<Window>,
119) -> Result<SurfaceReattachOutcome, RendererError> {
120    let size = window.inner_size();
121    let notify_window = window.clone();
122    renderer.reattach_surface_target(
123        window,
124        PhysicalExtent::new(size.width, size.height),
125        Some(Arc::new(move || notify_window.pre_present_notify())),
126    )
127}