From 2d814718200a5585216f90766693bca1582b3c0e Mon Sep 17 00:00:00 2001
From: irrlicht <david@bernet.it>
Date: Sat, 23 May 2026 10:49:32 +0200
Subject: [PATCH] poll_event

---
 README.md           | 15 +++++++++------
 examples/starter.rs | 11 ++++++-----
 src/lib.rs          |  8 ++++++++
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index cffece8..a30c8d4 100644
--- a/README.md
+++ b/README.md
@@ -31,14 +31,11 @@ fn main() {
     while !p.should_close() {
         p.poll_events(None);
 
-        // drain_events() borrowt &mut self → close erst nach dem Loop setzen.
-        let mut close = false;
-        for ev in p.drain_events() {
+        while let Some(ev) = p.poll_event() {
             if let Event::Key { key: Key::Escape, pressed: true, .. } = ev {
-                close = true;
+                p.request_close();
             }
         }
-        if close { p.request_close(); }
 
         let (w, _h) = p.framebuffer_size();
         let fb = p.framebuffer_mut();
@@ -58,8 +55,14 @@ fn main() {
   Default = 800×600 Fenster, 320×240 Framebuffer, 4:3, `palette::RGB332`.
 - `Platform::new(cfg)` – Fenster + GPU-Pipeline aufsetzen.
 - `poll_events(timeout)` – winit-Events einlesen (`None` = blockierend).
+- `poll_event() -> Option<Event>` – ein Event aus der Queue holen. Gibt
+  `&mut self` nach jedem Call frei, sodass im Loop direkt auf die Platform
+  reagiert werden kann (`request_close`, `set_mouse_capture`, `palette_mut` …).
+  Empfohlen für die normale Event-Schleife.
 - `drain_events()` – Iterator über `Event` (`Key`, `Char`, `MouseMove`,
-  `MouseBtn`, `Resize`, `CloseRequested`).
+  `MouseBtn`, `Resize`, `CloseRequested`). Borrowt `&mut self` bis der
+  Iterator fertig ist — Reaktionen auf die Platform müssen dann nach dem
+  Loop angewandt werden. Nützlich für reines Loggen/Filtern.
 - `framebuffer_mut()` – `&mut [u8]` der Länge `w*h`, je Pixel ein Paletten-Index.
 - `palette_mut()` / `palette()` – `&mut [[u8; 3]; 256]` bzw. `&[...]`; Schreibzugriff
   markiert die Palette dirty, der nächste `present()` lädt sie hoch.
diff --git a/examples/starter.rs b/examples/starter.rs
index c847f59..a2ca8fa 100644
--- a/examples/starter.rs
+++ b/examples/starter.rs
@@ -28,17 +28,18 @@ fn main() {
         // Event schlafen — gut für statische UIs, schlecht für Animation.
         p.poll_events(Some(Duration::from_millis(0)));
 
-        // drain_events() borrowt &mut self → Aktionen auf p erst nach dem Loop.
-        let mut close = false;
-        for ev in p.drain_events() {
+        // poll_event() gibt &mut self nach jedem Call wieder frei → Aktionen
+        // auf p (request_close, set_mouse_capture, palette_mut …) sind direkt
+        // im Loop erlaubt. drain_events() existiert weiter für den Fall, dass
+        // nur gelesen wird.
+        while let Some(ev) = p.poll_event() {
             match ev {
-                Event::Key { key: Key::Escape, pressed: true, .. }      => close = true,
+                Event::Key { key: Key::Escape, pressed: true, .. }      => p.request_close(),
                 Event::MouseMove { x, y }                               => mouse = (x, y),
                 Event::MouseBtn  { button: MouseButton::Left, pressed } => paint = pressed,
                 _ => {}
             }
         }
-        if close { p.request_close(); }
 
         let (w, h) = p.framebuffer_size();
         let fb     = p.framebuffer_mut();
diff --git a/src/lib.rs b/src/lib.rs
index 08f3aef..48375a6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -311,6 +311,14 @@ impl Platform {
         self.event_queue.drain(..)
     }
 
+    /// Holt ein einzelnes Event aus der Queue. Gibt `&mut self` nach jedem Call
+    /// wieder frei, im Gegensatz zu `drain_events()` — sodass im Loop direkt
+    /// auf die Platform reagiert werden kann (`request_close`, `set_mouse_capture`,
+    /// `palette_mut` …).
+    pub fn poll_event(&mut self) -> Option<Event> {
+        self.event_queue.pop_front()
+    }
+
     pub fn framebuffer_mut(&mut self) -> &mut [u8] { &mut self.framebuffer }
     pub fn framebuffer_size(&self) -> (u32, u32)  { self.framebuffer_size }