Skip to main content

wgame_egui/
lib.rs

1//! Optional egui host for one wgame drawing area.
2//!
3//! Wrap a window, build controls in the layout callback, and hand the result to
4//! code generic over [`WindowHost`]. The callback returns the response from
5//! [`Canvas::show`]; its widget ID stays stable across frames. Input and camera
6//! coordinates are local logical pixels, including egui zoom. Clicking the canvas
7//! gives it keyboard focus. UI controls own their events; a captured canvas drag
8//! retains its release outside the canvas. Geometry/focus loss cancels gestures.
9//! Lifting a touch preserves its completed release and clears pointer hover;
10//! a cancelled touch aborts the gesture instead.
11//!
12//! ```no_run
13//! use wgame::{ContentFrame, WindowHost, gfx::{Target, types::color}};
14//! use wgame_egui::{egui, EguiWindow};
15//! async fn run(window: wgame::Window<'_>) -> wgame::Result<()> {
16//!     let mut host = EguiWindow::new(window, |ui, canvas| {
17//!         egui::Panel::top("toolbar").show(ui, |ui| { ui.label("My playground"); });
18//!         egui::CentralPanel::default().show(ui, |ui| canvas.show(ui)).inner
19//!     });
20//!     while let Some(mut frame) = host.next_frame().await? {
21//!         frame.clear(color::BLACK);
22//!         // Update once here, then render with frame.logical_camera().
23//!     }
24//!     Ok(())
25//! }
26//! ```
27//!
28//! Create renderers from the wrapper's [`WindowHost::graphics`]: its RGBA canvas
29//! target can have a different format from the OS surface. Composition uses one
30//! offscreen texture and an additional pass. Layout callbacks may run repeatedly;
31//! keep simulation updates outside them. Normal frame drop presents once;
32//! discard/panic drops all encoded commands (texture uploads may already occur).
33//! A hidden/empty canvas yields a minimal target with `visible() == false`, so
34//! application updates and UI actions can still run.
35//! For static content, call `host.wait_for_update(None).await` between frames.
36//! This wakes on input, OS redraws, and egui repaint deadlines (including animation
37//! and tooltip delays). Pass a timeout for application timers or zero for animation.
38//! After changing application state outside layout, request one more repaint with
39//! `host.context().request_repaint()` so the controls display the new state.
40//!
41//! This integration owns one OS window. Native secondary viewports and viewport
42//! screenshot/clipboard-image requests are not supported. Use embedded egui
43//! windows instead. The `desktop` feature enables native clipboard and links;
44//! `web` uses WebGL2 and a winit event adapter for pointer, touch, keyboard and
45//! wheel input. Browser text entry requires a hardware keyboard: mobile virtual
46//! keyboards, IME, system clipboard and file drops are not integrated. The web
47//! adapter provides an in-app text clipboard.
48
49#![forbid(unsafe_code)]
50
51mod input;
52mod repaint;
53#[cfg(not(target_arch = "wasm32"))]
54use egui_winit as platform;
55use std::sync::Arc;
56#[cfg(any(target_arch = "wasm32", test))]
57#[cfg_attr(not(target_arch = "wasm32"), allow(dead_code))]
58mod web;
59pub use egui;
60use input::CanvasState;
61#[cfg(target_arch = "wasm32")]
62use web as platform;
63use wgame::{
64    ContentFrame, WindowHost,
65    canvas::CanvasInput,
66    gfx::{self, Target},
67};
68
69/// The content texture, allocated to the available UI rectangle.
70pub struct Canvas {
71    texture: egui::TextureId,
72}
73impl Canvas {
74    /// Place exactly once per layout pass. The canvas uses a stable widget ID.
75    pub fn show(&self, ui: &mut egui::Ui) -> egui::Response {
76        let (_, rect) = ui.allocate_space(ui.available_size().max(egui::Vec2::ZERO));
77        let response = ui.interact(
78            rect,
79            egui::Id::new("wgame-canvas"),
80            egui::Sense::click_and_drag(),
81        );
82        ui.painter().image(
83            self.texture,
84            rect,
85            egui::Rect::from_min_max(egui::Pos2::ZERO, egui::pos2(1.0, 1.0)),
86            egui::Color32::WHITE,
87        );
88        if response.clicked() || response.drag_started() {
89            response.request_focus();
90        }
91        response
92    }
93}
94
95struct Painter {
96    target: gfx::Offscreen,
97    renderer: egui_wgpu::Renderer,
98    canvas: Canvas,
99}
100impl Painter {
101    fn new(graphics: &gfx::Graphics) -> Self {
102        let canvas_graphics = gfx::Graphics::new(
103            graphics.adapter().clone(),
104            graphics.device().clone(),
105            graphics.queue().clone(),
106            wgpu::TextureFormat::Rgba8Unorm,
107        );
108        let target = gfx::Offscreen::new(&canvas_graphics, (1, 1));
109        let mut renderer =
110            egui_wgpu::Renderer::new(graphics.device(), graphics.format(), Default::default());
111        let texture = renderer.register_native_texture(
112            graphics.device(),
113            target.view(),
114            wgpu::FilterMode::Linear,
115        );
116        Self {
117            target,
118            renderer,
119            canvas: Canvas { texture },
120        }
121    }
122    fn resize(&mut self, size: (u32, u32)) {
123        if self.target.size() != size {
124            self.target = gfx::Offscreen::new(self.target.state(), size);
125            self.renderer.update_egui_texture_from_wgpu_texture(
126                self.target.state().device(),
127                self.target.view(),
128                wgpu::FilterMode::Linear,
129                self.canvas.texture,
130            );
131        }
132    }
133    fn paint(
134        &mut self,
135        root: &mut impl Target,
136        jobs: &[egui::ClippedPrimitive],
137        screen: &egui_wgpu::ScreenDescriptor,
138    ) -> Vec<wgpu::CommandBuffer> {
139        let mut before = vec![self.target.finish()];
140        let graphics = root.state().clone();
141        let extra = self.renderer.update_buffers(
142            graphics.device(),
143            graphics.queue(),
144            root.encoder(),
145            jobs,
146            screen,
147        );
148        before.extend(extra);
149        let view = root.view().clone();
150        {
151            let mut pass = root
152                .encoder()
153                .begin_render_pass(&wgpu::RenderPassDescriptor {
154                    label: Some("egui composition"),
155                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
156                        view: &view,
157                        resolve_target: None,
158                        depth_slice: None,
159                        ops: wgpu::Operations {
160                            load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
161                            store: wgpu::StoreOp::Store,
162                        },
163                    })],
164                    ..Default::default()
165                })
166                .forget_lifetime();
167            self.renderer.render(&mut pass, jobs, screen);
168        }
169        before
170    }
171}
172
173/// A window decorated with an egui layout containing one [`Canvas`].
174pub struct EguiWindow<'w, L> {
175    window: wgame::Window<'w>,
176    events: wgame::app::Input,
177    context: egui::Context,
178    platform: platform::State,
179    layout: L,
180    painter: Painter,
181    input: CanvasState,
182    size: Option<(u32, u32)>,
183    closed: bool,
184    repaint: Arc<repaint::Repaint>,
185}
186impl<'w, L: FnMut(&mut egui::Ui, &Canvas) -> egui::Response> EguiWindow<'w, L> {
187    pub fn new(window: wgame::Window<'w>, layout: L) -> Self {
188        let context = egui::Context::default();
189        context.set_embed_viewports(true);
190        let repaint = Arc::new(repaint::Repaint::default());
191        context.set_request_repaint_callback({
192            let repaint = repaint.clone();
193            move |info| {
194                if info.viewport_id == egui::ViewportId::ROOT {
195                    repaint.request(info.delay);
196                }
197            }
198        });
199        let mut platform = platform::State::new(
200            context.clone(),
201            egui::ViewportId::ROOT,
202            window.raw(),
203            Some(window.scale_factor() as f32),
204            window.raw().theme(),
205            Some(window.graphics().device().limits().max_texture_dimension_2d as usize),
206        );
207        platform.egui_input_mut().focused = window.raw().has_focus();
208        Self {
209            events: window.input(),
210            painter: Painter::new(window.graphics()),
211            window,
212            context,
213            platform,
214            layout,
215            input: CanvasState::default(),
216            size: None,
217            closed: false,
218            repaint,
219        }
220    }
221    pub fn context(&self) -> &egui::Context {
222        &self.context
223    }
224}
225impl<'w, L: FnMut(&mut egui::Ui, &Canvas) -> egui::Response> WindowHost for EguiWindow<'w, L> {
226    type Frame<'a>
227        = Frame<'w, 'a>
228    where
229        Self: 'a;
230    fn graphics(&self) -> &gfx::Graphics {
231        self.painter.target.state()
232    }
233    async fn wait_for_update(&mut self, timeout: Option<std::time::Duration>) {
234        if !self.closed && timeout != Some(std::time::Duration::ZERO) {
235            futures::future::select(
236                Box::pin(self.window.wait_for_update(timeout)),
237                Box::pin(self.repaint.wait()),
238            )
239            .await;
240        }
241    }
242    async fn next_frame(&mut self) -> wgame::Result<Option<Self::Frame<'_>>> {
243        {
244            if self.closed {
245                return Ok(None);
246            }
247            let raw_window = self.window.raw();
248            let Some(root) = self.window.next_frame().await? else {
249                return Ok(None);
250            };
251            while let Some(event) = self.events.try_next() {
252                #[cfg(not(target_arch = "wasm32"))]
253                let _ = self.platform.on_window_event(raw_window, &event);
254                #[cfg(target_arch = "wasm32")]
255                self.platform.on_window_event(raw_window, &event);
256            }
257            platform::update_viewport_info(
258                self.platform
259                    .egui_input_mut()
260                    .viewports
261                    .entry(egui::ViewportId::ROOT)
262                    .or_default(),
263                &self.context,
264                raw_window,
265                false,
266            );
267            let raw = self.platform.take_egui_input(raw_window);
268            let events = raw.events.clone();
269            let focused = raw.focused;
270            let mut response = None;
271            self.repaint.clear();
272            let mut output = self.context.run_ui(raw, |ui| {
273                response = Some((self.layout)(ui, &self.painter.canvas));
274            });
275            // Drain first: TexturesDelta requires explicit handling even on discard.
276            let updates = std::mem::take(&mut output.textures_delta.set);
277            let free = std::mem::take(&mut output.textures_delta.free)
278                .into_iter()
279                .collect();
280            for (id, deltas) in updates {
281                for delta in deltas {
282                    self.painter.renderer.update_texture(
283                        root.state().device(),
284                        root.state().queue(),
285                        id,
286                        &delta,
287                    );
288                }
289            }
290            self.platform
291                .handle_platform_output(raw_window, output.platform_output);
292            if let Some(viewport) = output.viewport_output.remove(&egui::ViewportId::ROOT) {
293                self.repaint.request(viewport.repaint_delay);
294                self.closed |= viewport
295                    .commands
296                    .iter()
297                    .any(|cmd| matches!(cmd, egui::ViewportCommand::Close));
298                platform::process_viewport_commands(
299                    &self.context,
300                    self.platform
301                        .egui_input_mut()
302                        .viewports
303                        .entry(egui::ViewportId::ROOT)
304                        .or_default(),
305                    viewport.commands,
306                    raw_window,
307                    &mut Vec::new(),
308                );
309            }
310            let response = response.expect("egui executes a layout pass");
311            let modifiers = self.context.input(|i| i.modifiers);
312            let scale = output.pixels_per_point;
313            let mut input = self
314                .input
315                .collect(&response, &events, focused, modifiers, scale);
316            if input.focused
317                && !input
318                    .events
319                    .iter()
320                    .any(|event| matches!(event, wgame::canvas::Event::Cancelled))
321            {
322                input.relative_motion = root.input().relative_motion;
323            }
324            let visible = response.rect.is_positive() && response.interact_rect.is_positive();
325            let limit = root.state().device().limits().max_texture_dimension_2d;
326            let size = (
327                (response.rect.width() * scale)
328                    .round()
329                    .clamp(1.0, limit as f32) as u32,
330                (response.rect.height() * scale)
331                    .round()
332                    .clamp(1.0, limit as f32) as u32,
333            );
334            let resized = (self.size != Some(size)).then_some(size);
335            self.size = Some(size);
336            self.painter.resize(size);
337            let jobs = self.context.tessellate(output.shapes, scale);
338            let (width, height) = root.size();
339            let screen = egui_wgpu::ScreenDescriptor {
340                size_in_pixels: [width, height],
341                pixels_per_point: scale,
342            };
343            let frame = Frame {
344                root: Some(root),
345                painter: &mut self.painter,
346                jobs,
347                screen,
348                free,
349                input,
350                resized,
351                logical_size: (
352                    response.rect.width().max(1.0 / scale) as f64,
353                    response.rect.height().max(1.0 / scale) as f64,
354                ),
355                visible,
356            };
357            Ok(Some(frame))
358        }
359    }
360}
361
362/// Borrowed canvas target; presentation composites it with the UI.
363pub struct Frame<'w, 'a> {
364    root: Option<wgame::Frame<'w, 'a>>,
365    painter: &'a mut Painter,
366    jobs: Vec<egui::ClippedPrimitive>,
367    screen: egui_wgpu::ScreenDescriptor,
368    free: Vec<egui::TextureId>,
369    input: CanvasInput,
370    resized: Option<(u32, u32)>,
371    logical_size: (f64, f64),
372    visible: bool,
373}
374impl Target for Frame<'_, '_> {
375    fn state(&self) -> &gfx::Graphics {
376        self.painter.target.state()
377    }
378    fn view(&self) -> &wgpu::TextureView {
379        self.painter.target.view()
380    }
381    fn depth_view(&self) -> &wgpu::TextureView {
382        self.painter.target.depth_view()
383    }
384    fn encoder(&mut self) -> &mut wgpu::CommandEncoder {
385        self.painter.target.encoder()
386    }
387}
388impl ContentFrame for Frame<'_, '_> {
389    fn visible(&self) -> bool {
390        self.visible
391    }
392    fn input(&self) -> &CanvasInput {
393        &self.input
394    }
395    fn scale_factor(&self) -> f64 {
396        self.screen.pixels_per_point as f64
397    }
398    fn logical_size(&self) -> (f64, f64) {
399        self.logical_size
400    }
401    fn resized(&self) -> Option<(u32, u32)> {
402        self.resized
403    }
404    fn present(mut self) {
405        self.finish(true);
406    }
407    fn discard(mut self) {
408        self.finish(false);
409    }
410}
411impl Frame<'_, '_> {
412    fn finish(&mut self, present: bool) {
413        let Some(mut root) = self.root.take() else {
414            return;
415        };
416        if present {
417            let before = self.painter.paint(&mut root, &self.jobs, &self.screen);
418            root.submit_before(before);
419            root.present();
420        } else {
421            self.painter.target.discard();
422            root.discard();
423        }
424        for id in self.free.drain(..) {
425            self.painter.renderer.free_texture(&id);
426        }
427    }
428}
429impl Drop for Frame<'_, '_> {
430    fn drop(&mut self) {
431        self.finish(!std::thread::panicking());
432    }
433}
434
435#[cfg(test)]
436mod rendering_tests;