From e79ce2a200620eec34951672e48fdae6e6122d8a Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 27 Aug 2024 21:57:27 -0400
Subject: [PATCH] asyncio: Added async i/o APIs.
---
Android.mk | 1 +
CMakeLists.txt | 3 +-
VisualC-GDK/SDL/SDL.vcxproj | 5 +
VisualC-GDK/SDL/SDL.vcxproj.filters | 15 +
VisualC/SDL/SDL.vcxproj | 5 +
VisualC/SDL/SDL.vcxproj.filters | 18 +
Xcode/SDL/SDL.xcodeproj/project.pbxproj | 29 +
examples/CMakeLists.txt | 1 +
examples/asyncio/01-load-bitmaps/README.txt | 6 +
.../asyncio/01-load-bitmaps/load-bitmaps.c | 125 +++++
include/SDL3/SDL.h | 1 +
include/SDL3/SDL_asyncio.h | 506 ++++++++++++++++++
src/SDL.c | 2 +
src/dynapi/SDL_dynapi.sym | 11 +
src/dynapi/SDL_dynapi_overrides.h | 11 +
src/dynapi/SDL_dynapi_procs.h | 11 +
src/file/SDL_asyncio.c | 335 ++++++++++++
src/file/SDL_asyncio_c.h | 30 ++
src/file/SDL_sysasyncio.h | 133 +++++
src/file/generic/SDL_asyncio_generic.c | 460 ++++++++++++++++
test/CMakeLists.txt | 1 +
test/testasyncio.c | 176 ++++++
22 files changed, 1883 insertions(+), 2 deletions(-)
create mode 100644 examples/asyncio/01-load-bitmaps/README.txt
create mode 100644 examples/asyncio/01-load-bitmaps/load-bitmaps.c
create mode 100644 include/SDL3/SDL_asyncio.h
create mode 100644 src/file/SDL_asyncio.c
create mode 100644 src/file/SDL_asyncio_c.h
create mode 100644 src/file/SDL_sysasyncio.h
create mode 100644 src/file/generic/SDL_asyncio_generic.c
create mode 100644 test/testasyncio.c
diff --git a/Android.mk b/Android.mk
index b352cb3186ee5..6735c877a98f9 100644
--- a/Android.mk
+++ b/Android.mk
@@ -35,6 +35,7 @@ LOCAL_SRC_FILES := \
$(wildcard $(LOCAL_PATH)/src/dynapi/*.c) \
$(wildcard $(LOCAL_PATH)/src/events/*.c) \
$(wildcard $(LOCAL_PATH)/src/file/*.c) \
+ $(wildcard $(LOCAL_PATH)/src/file/generic/*.c) \
$(wildcard $(LOCAL_PATH)/src/gpu/*.c) \
$(wildcard $(LOCAL_PATH)/src/gpu/vulkan/*.c) \
$(wildcard $(LOCAL_PATH)/src/haptic/*.c) \
diff --git a/CMakeLists.txt b/CMakeLists.txt
index d83a7e59509d0..70e7d51551f2e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1119,6 +1119,7 @@ sdl_glob_sources(
"${SDL3_SOURCE_DIR}/src/dynapi/*.c"
"${SDL3_SOURCE_DIR}/src/events/*.c"
"${SDL3_SOURCE_DIR}/src/file/*.c"
+ "${SDL3_SOURCE_DIR}/src/file/generic/*.c"
"${SDL3_SOURCE_DIR}/src/filesystem/*.c"
"${SDL3_SOURCE_DIR}/src/gpu/*.c"
"${SDL3_SOURCE_DIR}/src/joystick/*.c"
@@ -2111,8 +2112,6 @@ elseif(APPLE)
set(HAVE_SDL_MAIN_CALLBACKS TRUE)
endif()
- sdl_glob_sources("${SDL3_SOURCE_DIR}/src/file/cocoa/*.m")
-
if(SDL_CAMERA)
if(MACOS OR IOS)
set(SDL_CAMERA_DRIVER_COREMEDIA 1)
diff --git a/VisualC-GDK/SDL/SDL.vcxproj b/VisualC-GDK/SDL/SDL.vcxproj
index 7d41bbc5e76b4..e00f1705b7666 100644
--- a/VisualC-GDK/SDL/SDL.vcxproj
+++ b/VisualC-GDK/SDL/SDL.vcxproj
@@ -339,6 +339,7 @@
<ClInclude Include="..\..\include\SDL3\SDL_haptic.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hints.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hidapi.h" />
+ <ClInclude Include="..\..\include\SDL3\SDL_asyncio.h" />
<ClInclude Include="..\..\include\SDL3\SDL_joystick.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keyboard.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keycode.h" />
@@ -432,6 +433,8 @@
<ClInclude Include="..\..\src\events\SDL_windowevents_c.h" />
<ClInclude Include="..\..\src\filesystem\SDL_sysfilesystem.h" />
<ClInclude Include="..\..\src\gpu\SDL_sysgpu.h" />
+ <ClInclude Include="..\..\src\file\SDL_asyncio_c.h" />
+ <ClInclude Include="..\..\src\file\SDL_sysasyncio.h" />
<ClInclude Include="..\..\src\haptic\SDL_haptic_c.h" />
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
@@ -517,6 +520,8 @@
<ClCompile Include="..\..\src\dialog\SDL_dialog_utils.c" />
<ClCompile Include="..\..\src\filesystem\SDL_filesystem.c" />
<ClCompile Include="..\..\src\filesystem\windows\SDL_sysfsops.c" />
+ <ClCompile Include="..\..\src\file\generic\SDL_asyncio_generic.c" />
+ <ClCompile Include="..\..\src\file\SDL_asyncio.c" />
<ClCompile Include="..\..\src\main\gdk\SDL_sysmain_runapp.cpp" />
<ClCompile Include="..\..\src\main\generic\SDL_sysmain_callbacks.c" />
<ClCompile Include="..\..\src\main\SDL_main_callbacks.c" />
diff --git a/VisualC-GDK/SDL/SDL.vcxproj.filters b/VisualC-GDK/SDL/SDL.vcxproj.filters
index 866d073e0f899..b6ff2e12fa17e 100644
--- a/VisualC-GDK/SDL/SDL.vcxproj.filters
+++ b/VisualC-GDK/SDL/SDL.vcxproj.filters
@@ -13,6 +13,12 @@
<ClCompile Include="..\..\src\filesystem\windows\SDL_sysfsops.c">
<Filter>filesystem\windows</Filter>
</ClCompile>
+ <ClCompile Include="..\..\src\file\generic\SDL_asyncio_generic.c">
+ <Filter>file\generic</Filter>
+ </ClCompile>
+ <ClCompile Include="..\..\src\file\SDL_asyncio.c">
+ <Filter>file</Filter>
+ </ClCompile>
<ClCompile Include="..\..\src\render\direct3d12\SDL_render_d3d12_xbox.cpp" />
<ClCompile Include="..\..\src\render\direct3d12\SDL_shaders_d3d12_xboxone.cpp" />
<ClCompile Include="..\..\src\render\direct3d12\SDL_shaders_d3d12_xboxseries.cpp" />
@@ -262,6 +268,9 @@
<ClInclude Include="..\..\include\SDL3\SDL_haptic.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hints.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hidapi.h" />
+ <ClInclude Include="..\..\include\SDL3\SDL_asyncio.h">
+ <Filter>API Headers</Filter>
+ </ClInclude>
<ClInclude Include="..\..\include\SDL3\SDL_joystick.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keyboard.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keycode.h" />
@@ -353,6 +362,12 @@
<Filter>filesystem</Filter>
</ClInclude>
<ClInclude Include="..\..\src\gpu\SDL_sysgpu.h" />
+ <ClInclude Include="..\..\src\file\SDL_asyncio_c.h">
+ <Filter>file</Filter>
+ </ClInclude>
+ <ClInclude Include="..\..\src\file\SDL_sysasyncio.h">
+ <Filter>file</Filter>
+ </ClInclude>
<ClInclude Include="..\..\src\haptic\SDL_haptic_c.h" />
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
diff --git a/VisualC/SDL/SDL.vcxproj b/VisualC/SDL/SDL.vcxproj
index 91fde679c2706..6aae9e2eb8c97 100644
--- a/VisualC/SDL/SDL.vcxproj
+++ b/VisualC/SDL/SDL.vcxproj
@@ -259,6 +259,7 @@
<ClInclude Include="..\..\include\SDL3\SDL_haptic.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hints.h" />
<ClInclude Include="..\..\include\SDL3\SDL_hidapi.h" />
+ <ClInclude Include="..\..\include\SDL3\SDL_asyncio.h" />
<ClInclude Include="..\..\include\SDL3\SDL_joystick.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keyboard.h" />
<ClInclude Include="..\..\include\SDL3\SDL_keycode.h" />
@@ -352,6 +353,8 @@
<ClInclude Include="..\..\src\filesystem\SDL_sysfilesystem.h" />
<ClInclude Include="..\..\src\gpu\SDL_sysgpu.h" />
<ClInclude Include="..\..\src\gpu\vulkan\SDL_gpu_vulkan_vkfuncs.h" />
+ <ClInclude Include="..\..\src\file\SDL_asyncio_c.h" />
+ <ClInclude Include="..\..\src\file\SDL_sysasyncio.h" />
<ClInclude Include="..\..\src\haptic\SDL_haptic_c.h" />
<ClInclude Include="..\..\src\haptic\SDL_syshaptic.h" />
<ClInclude Include="..\..\src\haptic\windows\SDL_dinputhaptic_c.h" />
@@ -415,6 +418,8 @@
<ClCompile Include="..\..\src\gpu\SDL_gpu.c" />
<ClCompile Include="..\..\src\gpu\d3d12\SDL_gpu_d3d12.c" />
<ClCompile Include="..\..\src\gpu\vulkan\SDL_gpu_vulkan.c" />
+ <ClCompile Include="..\..\src\file\generic\SDL_asyncio_generic.c" />
+ <ClCompile Include="..\..\src\file\SDL_asyncio.c" />
<ClCompile Include="..\..\src\main\generic\SDL_sysmain_callbacks.c" />
<ClCompile Include="..\..\src\main\SDL_main_callbacks.c" />
<ClCompile Include="..\..\src\main\SDL_runapp.c" />
diff --git a/VisualC/SDL/SDL.vcxproj.filters b/VisualC/SDL/SDL.vcxproj.filters
index 8cd2691322fad..bfbd815fc7b96 100644
--- a/VisualC/SDL/SDL.vcxproj.filters
+++ b/VisualC/SDL/SDL.vcxproj.filters
@@ -211,6 +211,9 @@
<Filter Include="main\windows">
<UniqueIdentifier>{00009d5ded166cc6c6680ec771a30000}</UniqueIdentifier>
</Filter>
+ <Filter Include="file\generic">
+ <UniqueIdentifier>{00004d6806b6238cae0ed62db5440000}</UniqueIdentifier>
+ </Filter>
</ItemGroup>
<ItemGroup>
<ClInclude Include="..\..\include\SDL3\SDL_begin_code.h">
@@ -279,6 +282,9 @@
<ClInclude Include="..\..\include\SDL3\SDL_hidapi.h">
<Filter>API Headers</Filter>
</ClInclude>
+ <ClInclude Include="..\..\include\SDL3\SDL_asyncio.h">
+ <Filter>API Headers</Filter>
+ </ClInclude>
<ClInclude Include="..\..\include\SDL3\SDL_joystick.h">
<Filter>API Headers</Filter>
</ClInclude>
@@ -438,6 +444,12 @@
<ClInclude Include="..\..\src\filesystem\SDL_sysfilesystem.h">
<Filter>filesystem</Filter>
</ClInclude>
+ <ClInclude Include="..\..\src\file\SDL_asyncio_c.h">
+ <Filter>file</Filter>
+ </ClInclude>
+ <ClInclude Include="..\..\src\file\SDL_sysasyncio.h">
+ <Filter>file</Filter>
+ </ClInclude>
<ClInclude Include="..\..\src\main\SDL_main_callbacks.h">
<Filter>main</Filter>
</ClInclude>
@@ -944,6 +956,12 @@
<ClCompile Include="..\..\src\filesystem\windows\SDL_sysfsops.c">
<Filter>filesystem\windows</Filter>
</ClCompile>
+ <ClCompile Include="..\..\src\file\generic\SDL_asyncio_generic.c">
+ <Filter>file\generic</Filter>
+ </ClCompile>
+ <ClCompile Include="..\..\src\file\SDL_asyncio.c">
+ <Filter>file</Filter>
+ </ClCompile>
<ClCompile Include="..\..\src\main\generic\SDL_sysmain_callbacks.c">
<Filter>main\generic</Filter>
</ClCompile>
diff --git a/Xcode/SDL/SDL.xcodeproj/project.pbxproj b/Xcode/SDL/SDL.xcodeproj/project.pbxproj
index 2513ef271ba72..e26d575c8ab92 100644
--- a/Xcode/SDL/SDL.xcodeproj/project.pbxproj
+++ b/Xcode/SDL/SDL.xcodeproj/project.pbxproj
@@ -545,6 +545,13 @@
F3FD042E2C9B755700824C4C /* SDL_hidapi_nintendo.h in Headers */ = {isa = PBXBuildFile; fileRef = F3FD042C2C9B755700824C4C /* SDL_hidapi_nintendo.h */; };
F3FD042F2C9B755700824C4C /* SDL_hidapi_steam_hori.c in Sources */ = {isa = PBXBuildFile; fileRef = F3FD042D2C9B755700824C4C /* SDL_hidapi_steam_hori.c */; };
FA73671D19A540EF004122E4 /* CoreVideo.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = FA73671C19A540EF004122E4 /* CoreVideo.framework */; platformFilters = (ios, maccatalyst, macos, tvos, watchos, ); };
+ 0000E5D7110DFF81FF660000 /* SDL_cocoapen.h in Headers */ = {isa = PBXBuildFile; fileRef = 00002F2F5496FA184A0F0000 /* SDL_cocoapen.h */; };
+ 0000D5B526B85DE7AB1C0000 /* SDL_cocoapen.m in Sources */ = {isa = PBXBuildFile; fileRef = 0000CCA310B73A7B59910000 /* SDL_cocoapen.m */; };
+ 0000AEB9AE90228CA2D60000 /* SDL_asyncio.c in Sources */ = {isa = PBXBuildFile; fileRef = 00003928A612EC33D42C0000 /* SDL_asyncio.c */; };
+ 000062F9C843687F50F70000 /* SDL_asyncio_c.h in Headers */ = {isa = PBXBuildFile; fileRef = 0000919399B1A908267F0000 /* SDL_asyncio_c.h */; };
+ 00005081394CCF8322BE0000 /* SDL_sysasyncio.h in Headers */ = {isa = PBXBuildFile; fileRef = 0000585B2CAB450B40540000 /* SDL_sysasyncio.h */; };
+ 000018AF97C08F2DAFFD0000 /* SDL_asyncio.h in Headers */ = {isa = PBXBuildFile; fileRef = 00004945A946DF5B1AED0000 /* SDL_asyncio.h */; settings = {ATTRIBUTES = (Public, ); }; };
+ 00004D0B73767647AD550000 /* SDL_asyncio_generic.c in Sources */ = {isa = PBXBuildFile; fileRef = 0000FB02CDE4BE34A87E0000 /* SDL_asyncio_generic.c */; };
/* End PBXBuildFile section */
/* Begin PBXContainerItemProxy section */
@@ -1120,6 +1127,13 @@
F59C710600D5CB5801000001 /* SDL.info */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = text; path = SDL.info; sourceTree = "<group>"; };
F5A2EF3900C6A39A01000001 /* BUGS.txt */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = text; name = BUGS.txt; path = ../../BUGS.txt; sourceTree = SOURCE_ROOT; };
FA73671C19A540EF004122E4 /* CoreVideo.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreVideo.framework; path = System/Library/Frameworks/CoreVideo.framework; sourceTree = SDKROOT; };
+ 00002F2F5496FA184A0F0000 /* SDL_cocoapen.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDL_cocoapen.h; path = SDL_cocoapen.h; sourceTree = "<group>"; };
+ 0000CCA310B73A7B59910000 /* SDL_cocoapen.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = SDL_cocoapen.m; path = SDL_cocoapen.m; sourceTree = "<group>"; };
+ 00003928A612EC33D42C0000 /* SDL_asyncio.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = SDL_asyncio.c; path = SDL_asyncio.c; sourceTree = "<group>"; };
+ 0000919399B1A908267F0000 /* SDL_asyncio_c.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDL_asyncio_c.h; path = SDL_asyncio_c.h; sourceTree = "<group>"; };
+ 0000585B2CAB450B40540000 /* SDL_sysasyncio.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDL_sysasyncio.h; path = SDL_sysasyncio.h; sourceTree = "<group>"; };
+ 00004945A946DF5B1AED0000 /* SDL_asyncio.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SDL_asyncio.h; path = SDL3/SDL_asyncio.h; sourceTree = "<group>"; };
+ 0000FB02CDE4BE34A87E0000 /* SDL_asyncio_generic.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = SDL_asyncio_generic.c; path = SDL_asyncio_generic.c; sourceTree = "<group>"; };
/* End PBXFileReference section */
/* Begin PBXFrameworksBuildPhase section */
@@ -1295,6 +1309,7 @@
F3F7D8C52933074B00816151 /* SDL_video.h */,
F3F7D8D42933074C00816151 /* SDL_vulkan.h */,
F3F7D8CF2933074C00816151 /* SDL.h */,
+ 00004945A946DF5B1AED0000 /* SDL_asyncio.h */,
);
name = "Public Headers";
path = ../../include;
@@ -1928,6 +1943,10 @@
isa = PBXGroup;
children = (
A7D8A7DB23E2513F00DCD162 /* SDL_iostream.c */,
+ 00003928A612EC33D42C0000 /* SDL_asyncio.c */,
+ 0000919399B1A908267F0000 /* SDL_asyncio_c.h */,
+ 0000585B2CAB450B40540000 /* SDL_sysasyncio.h */,
+ 000013C0F2EADC24ADC10000 /* generic */,
);
path = file;
sourceTree = "<group>";
@@ -2420,6 +2439,14 @@
path = resources;
sourceTree = "<group>";
};
+ 000013C0F2EADC24ADC10000 /* generic */ = {
+ isa = PBXGroup;
+ children = (
+ 0000FB02CDE4BE34A87E0000 /* SDL_asyncio_generic.c */,
+ );
+ path = generic;
+ sourceTree = "<group>";
+ };
/* End PBXGroup section */
/* Begin PBXHeadersBuildPhase section */
@@ -3044,6 +3071,8 @@
0000140640E77F73F1DF0000 /* SDL_dialog_utils.c in Sources */,
0000D5B526B85DE7AB1C0000 /* SDL_cocoapen.m in Sources */,
6312C66D2B42341400A7BB00 /* SDL_murmur3.c in Sources */,
+ 0000AEB9AE90228CA2D60000 /* SDL_asyncio.c in Sources */,
+ 00004D0B73767647AD550000 /* SDL_asyncio_generic.c in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 39bb253f616b0..23d91ff1c7bf8 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -144,6 +144,7 @@ add_sdl_example_executable(input-joystick-polling SOURCES input/01-joystick-poll
add_sdl_example_executable(input-joystick-events SOURCES input/02-joystick-events/joystick-events.c)
add_sdl_example_executable(camera-read-and-draw SOURCES camera/01-read-and-draw/read-and-draw.c)
add_sdl_example_executable(pen-drawing-lines SOURCES pen/01-drawing-lines/drawing-lines.c)
+add_sdl_example_executable(asyncio-load-bitmaps SOURCES asyncio/01-load-bitmaps/load-bitmaps.c DATAFILES ${CMAKE_CURRENT_SOURCE_DIR}/../test/sample.bmp ${CMAKE_CURRENT_SOURCE_DIR}/../test/gamepad_front.bmp ${CMAKE_CURRENT_SOURCE_DIR}/../test/speaker.bmp ${CMAKE_CURRENT_SOURCE_DIR}/../test/icon2x.bmp)
add_sdl_example_executable(demo-snake SOURCES demo/01-snake/snake.c)
add_sdl_example_executable(demo-woodeneye-008 SOURCES demo/02-woodeneye-008/woodeneye-008.c)
add_sdl_example_executable(demo-infinite-monkeys SOURCES demo/03-infinite-monkeys/infinite-monkeys.c)
diff --git a/examples/asyncio/01-load-bitmaps/README.txt b/examples/asyncio/01-load-bitmaps/README.txt
new file mode 100644
index 0000000000000..e4283d46a27fc
--- /dev/null
+++ b/examples/asyncio/01-load-bitmaps/README.txt
@@ -0,0 +1,6 @@
+This example code loads a few bitmap files from disk using the asynchronous
+i/o, and then draws it to the window. It uses a task group to watch multiple
+reads and deal with them in whatever order they finish.
+
+Note that for a single tiny file like this, you'd probably not want to bother
+with async i/o in real life, but this is just an example of how to do it.
diff --git a/examples/asyncio/01-load-bitmaps/load-bitmaps.c b/examples/asyncio/01-load-bitmaps/load-bitmaps.c
new file mode 100644
index 0000000000000..44c2abf7ec23c
--- /dev/null
+++ b/examples/asyncio/01-load-bitmaps/load-bitmaps.c
@@ -0,0 +1,125 @@
+/*
+ * This example code loads a bitmap with asynchronous i/o and renders it.
+ *
+ * This code is public domain. Feel free to use it for any purpose!
+ */
+
+#define SDL_MAIN_USE_CALLBACKS 1 /* use the callbacks instead of main() */
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+
+/* We will use this renderer to draw into this window every frame. */
+static SDL_Window *window = NULL;
+static SDL_Renderer *renderer = NULL;
+static SDL_AsyncIOQueue *queue = NULL;
+
+#define TOTAL_TEXTURES 4
+static const char * const bmps[TOTAL_TEXTURES] = { "sample.bmp", "gamepad_front.bmp", "speaker.bmp", "icon2x.bmp" };
+static SDL_Texture *textures[TOTAL_TEXTURES];
+static const SDL_FRect texture_rects[TOTAL_TEXTURES] = {
+ { 116, 156, 408, 167 },
+ { 20, 200, 96, 60 },
+ { 525, 180, 96, 96 },
+ { 288, 375, 64, 64 }
+};
+
+/* This function runs once at startup. */
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[])
+{
+ int i;
+
+ if (!SDL_Init(SDL_INIT_VIDEO)) {
+ SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Couldn't initialize SDL!", SDL_GetError(), NULL);
+ return SDL_APP_FAILURE;
+ }
+
+ if (!SDL_CreateWindowAndRenderer("examples/asyncio/load-bitmaps", 640, 480, 0, &window, &renderer)) {
+ SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Couldn't create window/renderer!", SDL_GetError(), NULL);
+ return SDL_APP_FAILURE;
+ }
+
+ queue = SDL_CreateAsyncIOQueue();
+ if (!queue) {
+ SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Couldn't create async i/o queue!", SDL_GetError(), NULL);
+ return SDL_APP_FAILURE;
+ }
+
+ /* Load some .bmp files asynchronously from wherever the app is being run from, put them in the same queue. */
+ for (i = 0; i < SDL_arraysize(bmps); i++) {
+ char *path = NULL;
+ SDL_asprintf(&path, "%s%s", SDL_GetBasePath(), bmps[i]); /* allocate a string of the full file path */
+ /* you _should) check for failure, but we'll just go on without files here. */
+ SDL_LoadFileAsync(path, queue, (void *) bmps[i]); /* attach the filename as app-specific data, so we can see it later. */
+ SDL_free(path);
+ }
+
+ return SDL_APP_CONTINUE; /* carry on with the program! */
+}
+
+/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
+{
+ if (event->type == SDL_EVENT_QUIT) {
+ return SDL_APP_SUCCESS; /* end the program, reporting success to the OS. */
+ }
+
+ return SDL_APP_CONTINUE; /* carry on with the program! */
+}
+
+/* This function runs once per frame, and is the heart of the program. */
+SDL_AppResult SDL_AppIterate(void *appstate)
+{
+ SDL_AsyncIOOutcome outcome;
+ int i;
+
+ if (SDL_GetAsyncIOResult(queue, &outcome)) { /* a .bmp file load has finished? */
+ if (outcome.result == SDL_ASYNCIO_COMPLETE) {
+ /* this might be _any_ of the bmps; they might finish loading in any order. */
+ for (i = 0; i < SDL_arraysize(bmps); i++) {
+ /* this doesn't need a strcmp because we gave the pointer from this array to SDL_LoadFileAsync */
+ if (outcome.userdata == bmps[i]) {
+ break;
+ }
+ }
+
+ if (i < SDL_arraysize(bmps)) { /* (just in case.) */
+ SDL_Surface *surface = SDL_LoadBMP_IO(SDL_IOFromConstMem(outcome.buffer, (size_t) outcome.bytes_transferred), true);
+ if (surface) { /* the renderer is not multithreaded, so create the texture here once the data loads. */
+ textures[i] = SDL_CreateTextureFromSurface(renderer, surface);
+ if (!textures[i]) {
+ SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Couldn't create texture!", SDL_GetError(), NULL);
+ return SDL_APP_FAILURE;
+ }
+ SDL_DestroySurface(surface);
+ }
+ }
+ }
+ SDL_free(outcome.buffer);
+ }
+
+ SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+ SDL_RenderClear(renderer);
+
+ for (i = 0; i < SDL_arraysize(textures); i++) {
+ SDL_RenderTexture(renderer, textures[i], NULL, &texture_rects[i]);
+ }
+
+ SDL_RenderPresent(renderer);
+
+ return SDL_APP_CONTINUE; /* carry on with the program! */
+}
+
+/* This function runs once at shutdown. */
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
+{
+ int i;
+
+ SDL_DestroyAsyncIOQueue(queue);
+
+ for (i = 0; i < SDL_arraysize(textures); i++) {
+ SDL_DestroyTexture(textures[i]);
+ }
+
+ /* SDL will clean up the window/renderer for us. */
+}
+
diff --git a/include/SDL3/SDL.h b/include/SDL3/SDL.h
index c7fa36677b8c5..e309929a122c1 100644
--- a/include/SDL3/SDL.h
+++ b/include/SDL3/SDL.h
@@ -30,6 +30,7 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_assert.h>
+#include <SDL3/SDL_asyncio.h>
#include <SDL3/SDL_atomic.h>
#include <SDL3/SDL_audio.h>
#include <SDL3/SDL_bits.h>
diff --git a/include/SDL3/SDL_asyncio.h b/include/SDL3/SDL_asyncio.h
new file mode 100644
index 0000000000000..13afdce7c3aa2
--- /dev/null
+++ b/include/SDL3/SDL_asyncio.h
@@ -0,0 +1,506 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+/* WIKI CATEGORY: AsyncIO */
+
+/**
+ * # CategoryAsyncIO
+ *
+ * SDL offers a way to perform I/O asynchronously. This allows an app to
+ * read or write files without waiting for data to actually transfer; the
+ * functions that request I/O never block while the request is fulfilled.
+ *
+ * Instead, the data moves in the background and the app can check for
+ * results at their leisure.
+ *
+ * This is more complicated that just reading and writing files in a
+ * synchronous way, but it can allow for more efficiency, and never having
+ * framerate drops as the hard drive catches up, etc.
+ *
+ * The general usage pattern for async I/O is:
+ *
+ * - Create one or more SDL_AsyncIOQueue objects.
+ * - Open files with SDL_AsyncIOFromFile.
+ * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO,
+ * putting those tasks into one of the queues.
+ * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task
+ * is finished without blocking. Tasks might finish in any order with
+ * success or failure.
+ * - When all your tasks are done, close the file with SDL_CloseAsyncIO.
+ * This also generates a task, since it might flush data to disk!
+ *
+ * This all works, without blocking, in a single thread, but one can also
+ * wait on a queue in a background thread, sleeping until new results
+ * have arrived:
+ *
+ * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block
+ * until new tasks complete.
+ * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping
+ * threads despite there being no new tasks completed.
+ *
+ * And, of course, to match the synchronous SDL_LoadFile, we offer
+ * SDL_LoadFileAsync as a convenience function. This will handle allocating
+ * a buffer, slurping in the file data, and null-terminating it; you still
+ * get a task handle to check later.
+ */
+
+#ifndef SDL_asyncio_h_
+#define SDL_asyncio_h_
+
+#include <SDL3/SDL_stdinc.h>
+
+#include <SDL3/SDL_begin_code.h>
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * The asynchronous I/O operation structure.
+ *
+ * This operates as an opaque handle. One can then request read or write
+ * operations on it.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_AsyncIOFromFile
+ */
+typedef struct SDL_AsyncIO SDL_AsyncIO;
+
+/**
+ * Types of asynchronous I/O tasks.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_AsyncIOTaskType
+{
+ SDL_ASYNCIO_TASK_READ, /**< A read operation. */
+ SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */
+ SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */
+} SDL_AsyncIOTaskType;
+
+/**
+ * Possible outcomes of an asynchronous I/O task.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_AsyncIOResult
+{
+ SDL_ASYNCIO_COMPLETE, /**< request was completed without error */
+ SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */
+ SDL_ASYNCIO_CANCELLED /**< request was cancelled before completing. */
+} SDL_AsyncIOResult;
+
+/**
+ * Information about a completed asynchronous I/O request.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
+typedef struct SDL_AsyncIOOutcome
+{
+ SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */
+ SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */
+ SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */
+ void *buffer; /**< buffer where data was read/written. */
+ Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */
+ Uint64 bytes_requested; /**< number of bytes the task was to read/write. */
+ Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */
+ void *userdata; /**< pointer provided by the app when starting the task */
+} SDL_AsyncIOOutcome;
+
+/**
+ * An opaque handle for asynchronous I/O tasks.
+ *
+ * Each asynchronous read or write operation generates a task, which will
+ * complete at some time in the future. This handle is used to track the
+ * progress of that task.
+ *
+ * Tasks are added to an SDL_AsyncIOQueue, where they can be queried for
+ * completion later.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_ReadAsyncIO
+ * \sa SDL_WriteAsyncIO
+ */
+typedef struct SDL_AsyncIOTask SDL_AsyncIOTask;
+
+/**
+ * A queue of completed asynchronous I/O tasks.
+ *
+ * When starting an asynchronous operation, you specify a queue for the new
+ * task. A queue can be asked later if any tasks in it have completed,
+ * allowing an app to manage multiple pending tasks in one place, in
+ * whatever order they complete.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateAsyncIOQueue
+ * \sa SDL_ReadAsyncIO
+ * \sa SDL_WriteAsyncIO
+ * \sa SDL_GetAsyncIOResult
+ * \sa SDL_WaitAsyncIOResult
+ */
+typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue;
+
+/**
+ * Use this function to create a new SDL_AsyncIO object for reading from
+ * and/or writing to a named file.
+ *
+ * The `mode` string understands the following values:
+ *
+ * - "r": Open a file for reading only. It must exist.
+ * - "w": Open a file for writing only. It will create missing files or truncate existing ones.
+ * - "r+": Open a file for update both reading and writing. The file must
+ * exist.
+ * - "w+": Create an empty file for both reading and writing. If a file with
+ * the same name already exists its content is erased and the file is
+ * treated as a new empty file.
+ *
+ * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode
+ * for appending, since you specify the position when starting a task.
+ *
+ * This function supports Unicode filenames, but they must be encoded in UTF-8
+ * format, regardless of the underlying operating system.
+ *
+ * This call is _not_ asynchronous; it will open the file before returning,
+ * under the assumption that doing so is generally a fast operation. Future
+ * reads and writes to the opened file will be async, however.
+ *
+ * \param file a UTF-8 string representing the filename to open.
+ * \param mode an ASCII string representing the mode to be used for opening
+ * the file.
+ * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CloseAsyncIO
+ * \sa SDL_ReadAsyncIO
+ * \sa SDL_WriteAsyncIO
+ */
+extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode);
+
+/**
+ * Use this function to get the size of the data stream in an SDL_AsyncIO.
+ *
+ * This call is _not_ asynchronous; it assumes that obtaining this info
+ * is a non-blocking operation in most reasonable cases.
+ *
+ * \param asyncio the SDL_AsyncIO to get the size of the data stream from.
+ * \returns the size of the data stream in the SDL_IOStream on success or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio);
+
+/**
+ * Start an async read.
+ *
+ * This function reads up to `size` bytes from `offset` position in the data
+ * source to the area pointed at by `ptr`. This function may read less bytes
+ * than requested.
+ *
+ * This function returns as quickly as possible; it does not wa
(Patch may be truncated, please check the link at the top of this post.)