From 84981ead737fee3cc2e8a17193f2867e183e2af1 Mon Sep 17 00:00:00 2001
From: unknown <icculus@icculus.org>
Date: Thu, 9 Oct 2025 13:41:49 -0400
Subject: [PATCH] docs: Note that Windows might block SDL_PollEvent() on window
 drag.

Reference Issue #13435.
---
 include/SDL3/SDL_events.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 54e8292343..32dc1b53bf 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -1260,6 +1260,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
  * }
  * ```
  *
+ * Note that Windows (and possibly other platforms) has a quirk about how it
+ * handles events while dragging/resizing a window, which can cause this
+ * function to block for significant amounts of time. Technical explanations
+ * and solutions are discussed on the wiki:
+ *
+ * https://wiki.libsdl.org/SDL3/AppFreezeDuringDrag
+ *
  * \param event the SDL_Event structure to be filled with the next event from
  *              the queue, or NULL.
  * \returns true if this got an event or false if there are none available.