SDL: Define SDL_PLATFORM_* macros instead of underscored ones (#8875)

From 31d133db40bf9d3140e91259502ab6025e879e0d Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Wed, 24 Jan 2024 02:40:51 +0100
Subject: [PATCH] Define SDL_PLATFORM_* macros instead of underscored ones
 (#8875)

---
 VisualC-GDK/tests/testgdk/src/testgdk.cpp     |   2 +-
 WhatsNew.txt                                  |   4 +-
 build-scripts/SDL_migration.cocci             |   1 +
 build-scripts/rename_headers.py               |  26 ++--
 build-scripts/rename_macros.py                | 139 ++++++++++++++++++
 cmake/sdlchecks.cmake                         |   2 +-
 docs/README-gdk.md                            |   4 +-
 docs/README-ios.md                            |   2 +-
 docs/README-migration.md                      |  60 +++++++-
 docs/README-winrt.md                          |   2 +-
 include/SDL3/SDL_assert.h                     |   6 +-
 include/SDL3/SDL_atomic.h                     |   6 +-
 include/SDL3/SDL_begin_code.h                 |   4 +-
 include/SDL3/SDL_egl.h                        |   8 +-
 include/SDL3/SDL_endian.h                     |   8 +-
 include/SDL3/SDL_intrin.h                     |   2 +-
 include/SDL3/SDL_main.h                       |  43 +++---
 include/SDL3/SDL_main_impl.h                  |  18 +--
 include/SDL3/SDL_oldnames.h                   |  16 --
 include/SDL3/SDL_opengl.h                     |  12 +-
 include/SDL3/SDL_opengles.h                   |   2 +-
 include/SDL3/SDL_opengles2.h                  |   2 +-
 include/SDL3/SDL_platform_defines.h           | 119 +++++++--------
 include/SDL3/SDL_rwops.h                      |   4 +-
 include/SDL3/SDL_stdinc.h                     |  22 +--
 include/SDL3/SDL_system.h                     |  32 ++--
 include/SDL3/SDL_test_common.h                |   4 +-
 include/SDL3/SDL_thread.h                     |   4 +-
 include/build_config/SDL_build_config.h       |  18 +--
 include/build_config/SDL_build_config.h.cmake |   2 +-
 include/build_config/SDL_build_config_ios.h   |   2 +-
 .../build_config/SDL_build_config_windows.h   |   2 +-
 src/SDL.c                                     |  82 +++++------
 src/SDL_assert.c                              |  10 +-
 src/SDL_internal.h                            |   2 +-
 src/SDL_log.c                                 |  36 ++---
 src/atomic/SDL_atomic.c                       |  30 ++--
 src/atomic/SDL_spinlock.c                     |  18 +--
 src/audio/SDL_audiodev.c                      |   2 +-
 src/audio/SDL_audiotypecvt.c                  |   8 +-
 src/audio/coreaudio/SDL_coreaudio.h           |   2 +-
 src/audio/coreaudio/SDL_coreaudio.m           |   2 +-
 src/audio/wasapi/SDL_wasapi.c                 |   2 +-
 src/audio/wasapi/SDL_wasapi_win32.c           |   4 +-
 src/audio/wasapi/SDL_wasapi_winrt.cpp         |   4 +-
 src/core/SDL_core_unsupported.c               |  12 +-
 src/core/SDL_runapp.c                         |   2 +-
 src/core/android/SDL_android.c                |   4 +-
 src/core/gdk/SDL_gdk.cpp                      |   2 +-
 src/core/haiku/SDL_BeApp.cc                   |   4 +-
 src/core/linux/SDL_fcitx.c                    |   8 +-
 src/core/linux/SDL_threadprio.c               |   4 +-
 src/core/n3ds/SDL_n3ds.c                      |   2 +-
 src/core/ngage/SDL_ngage_runapp.cpp           |   4 +-
 src/core/openbsd/SDL_wscons_kbd.c             |  10 +-
 src/core/ps2/SDL_ps2.c                        |   4 +-
 src/core/psp/SDL_psp.c                        |   4 +-
 src/core/unix/SDL_appid.c                     |   8 +-
 src/core/windows/SDL_hid.c                    |   4 +-
 src/core/windows/SDL_hid.h                    |   4 +-
 src/core/windows/SDL_immdevice.c              |   4 +-
 src/core/windows/SDL_windows.c                |  32 ++--
 src/core/windows/SDL_windows.h                |   8 +-
 src/core/windows/SDL_xinput.c                 |   6 +-
 src/core/windows/SDL_xinput.h                 |   2 +-
 src/cpuinfo/SDL_cpuinfo.c                     |  70 ++++-----
 src/dynapi/SDL_dynapi.c                       |   6 +-
 src/dynapi/SDL_dynapi.h                       |  18 +--
 src/dynapi/SDL_dynapi_procs.h                 |   4 +-
 src/dynapi/SDL_dynapi_unsupported.h           |  10 +-
 src/dynapi/gendynapi.py                       |   2 +-
 src/events/SDL_events.c                       |   2 +-
 src/events/SDL_mouse.c                        |  20 +--
 src/events/SDL_mouse_c.h                      |   2 +-
 src/events/SDL_pen.c                          |   2 +-
 src/events/SDL_touch.c                        |   2 +-
 src/file/SDL_rwops.c                          |  38 ++---
 src/file/cocoa/SDL_rwopsbundlesupport.h       |   2 +-
 src/file/cocoa/SDL_rwopsbundlesupport.m       |   4 +-
 src/filesystem/unix/SDL_sysfilesystem.c       |  16 +-
 src/filesystem/winrt/SDL_sysfilesystem.cpp    |   4 +-
 src/hidapi/SDL_hidapi.c                       |  56 +++----
 src/hidapi/SDL_hidapi_libusb.h                |   4 +-
 src/hidapi/ios/hid.m                          |   4 +-
 src/joystick/SDL_gamepad.c                    |  26 ++--
 src/joystick/SDL_gamepad_db.h                 |   8 +-
 src/joystick/SDL_joystick.c                   |   8 +-
 src/joystick/SDL_steam_virtual_gamepad.c      |   4 +-
 src/joystick/apple/SDL_mfijoystick.m          |  10 +-
 src/joystick/bsd/SDL_bsdjoystick.c            |  34 ++---
 src/joystick/hidapi/SDL_hidapi_luna.c         |   2 +-
 src/joystick/hidapi/SDL_hidapi_ps3.c          |   6 +-
 src/joystick/hidapi/SDL_hidapi_steam.c        |   6 +-
 src/joystick/hidapi/SDL_hidapi_wii.c          |   2 +-
 src/joystick/hidapi/SDL_hidapi_xbox360.c      |   6 +-
 src/joystick/hidapi/SDL_hidapi_xboxone.c      |   4 +-
 src/joystick/hidapi/SDL_hidapijoystick.c      |   4 +-
 src/joystick/windows/SDL_rawinputjoystick.c   |   2 +-
 .../windows/SDL_windows_gaming_input.c        |   6 +-
 src/joystick/windows/SDL_windowsjoystick.c    |  26 ++--
 src/joystick/windows/SDL_xinputjoystick.c     |   2 +-
 src/libm/math_private.h                       |   2 +-
 src/loadso/windows/SDL_sysloadso.c            |   2 +-
 src/main/generic/SDL_sysmain_callbacks.c      |   4 +-
 src/main/ios/SDL_sysmain_callbacks.m          |   2 +-
 src/misc/ios/SDL_sysurl.m                     |   4 +-
 src/misc/macos/SDL_sysurl.m                   |   4 +-
 src/misc/windows/SDL_sysurl.c                 |   2 +-
 src/render/SDL_render.c                       |  10 +-
 src/render/direct3d11/SDL_render_d3d11.c      |  28 ++--
 src/render/direct3d12/SDL_render_d3d12.c      |  40 ++---
 .../direct3d12/SDL_render_d3d12_xbox.cpp      |   4 +-
 src/render/direct3d12/SDL_render_d3d12_xbox.h |   4 +-
 src/render/direct3d12/SDL_shaders_d3d12.c     |   4 +-
 .../direct3d12/SDL_shaders_d3d12_xboxone.cpp  |   4 +-
 .../SDL_shaders_d3d12_xboxseries.cpp          |   4 +-
 src/render/metal/SDL_render_metal.m           |  22 +--
 src/render/opengl/SDL_render_gl.c             |  16 +-
 src/render/opengles2/SDL_render_gles2.c       |   4 +-
 src/render/software/SDL_rotate.c              |   2 +-
 src/stdlib/SDL_getenv.c                       |  12 +-
 src/stdlib/SDL_iconv.c                        |   2 +-
 src/stdlib/SDL_malloc.c                       |  18 +--
 src/stdlib/SDL_string.c                       |   4 +-
 src/stdlib/SDL_vacopy.h                       |   2 +-
 src/test/SDL_test_common.c                    |   2 +-
 src/test/SDL_test_memory.c                    |   6 +-
 src/thread/pthread/SDL_syssem.c               |   4 +-
 src/thread/pthread/SDL_systhread.c            |  44 +++---
 src/thread/stdcpp/SDL_systhread.cpp           |   6 +-
 src/thread/windows/SDL_syscond_cv.c           |   6 +-
 src/thread/windows/SDL_sysmutex.c             |   6 +-
 src/thread/windows/SDL_sysrwlock_srw.c        |   6 +-
 src/thread/windows/SDL_syssem.c               |   6 +-
 src/thread/windows/SDL_systhread.c            |   4 +-
 src/timer/SDL_timer.c                         |   6 +-
 src/timer/unix/SDL_systimer.c                 |  14 +-
 src/timer/windows/SDL_systimer.c              |   2 +-
 src/video/SDL_blit.c                          |   4 +-
 src/video/SDL_blit_N.c                        |   6 +-
 src/video/SDL_egl.c                           |   6 +-
 src/video/SDL_stretch.c                       |   2 +-
 src/video/SDL_video.c                         |  32 ++--
 src/video/SDL_video_capture.c                 |   6 +-
 src/video/SDL_video_capture_apple.m           |  10 +-
 src/video/SDL_video_capture_v4l2.c            |   2 +-
 src/video/SDL_video_unsupported.c             |   8 +-
 src/video/android/SDL_android_video_capture.c |   2 +-
 src/video/arm/pixman-arm-neon-asm.S           |   2 +-
 src/video/arm/pixman-arm-simd-asm.S           |   2 +-
 src/video/khronos/EGL/eglplatform.h           |   6 +-
 src/video/khronos/KHR/khrplatform.h           |   2 +-
 src/video/khronos/vulkan/vk_platform.h        |   4 +-
 src/video/kmsdrm/SDL_kmsdrmvideo.c            |   6 +-
 src/video/kmsdrm/SDL_kmsdrmvulkan.c           |   2 +-
 src/video/wayland/SDL_waylandvulkan.c         |   2 +-
 src/video/windows/SDL_windowsclipboard.c      |   2 +-
 src/video/windows/SDL_windowsevents.c         |  56 +++----
 src/video/windows/SDL_windowsframebuffer.c    |   2 +-
 src/video/windows/SDL_windowskeyboard.c       |   2 +-
 src/video/windows/SDL_windowsmessagebox.c     |   2 +-
 src/video/windows/SDL_windowsmodes.c          |   2 +-
 src/video/windows/SDL_windowsmouse.c          |   2 +-
 src/video/windows/SDL_windowsopengl.c         |   6 +-
 src/video/windows/SDL_windowsopengl.h         |   4 +-
 src/video/windows/SDL_windowsopengles.c       |   2 +-
 src/video/windows/SDL_windowsvideo.c          |  44 +++---
 src/video/windows/SDL_windowsvideo.h          |   8 +-
 src/video/windows/SDL_windowswindow.c         |  66 ++++-----
 src/video/windows/SDL_windowswindow.h         |   4 +-
 src/video/x11/SDL_x11opengl.c                 |   4 +-
 src/video/x11/SDL_x11sym.h                    |   2 +-
 src/video/x11/SDL_x11vulkan.c                 |   2 +-
 test/checkkeys.c                              |  14 +-
 test/checkkeysthreads.c                       |  18 +--
 test/testaudio.c                              |   2 +-
 test/testaudiohotplug.c                       |  22 +--
 test/testaudiostreamdynamicresample.c         |   6 +-
 test/testautomation_rwops.c                   |   8 +-
 test/testautomation_stdlib.c                  |   2 +-
 test/testcontroller.c                         |  12 +-
 test/testcustomcursor.c                       |  13 +-
 test/testdraw.c                               |  16 +-
 test/testdrawchessboard.c                     |  14 +-
 test/testffmpeg.c                             |  36 ++---
 test/testfile.c                               |   2 +-
 test/testgeometry.c                           |  16 +-
 test/testgles.c                               |   4 +-
 test/testgles2.c                              |  21 +--
 test/testgles2_sdf.c                          |  19 +--
 test/testime.c                                |   4 +-
 test/testintersections.c                      |  14 +-
 test/testmouse.c                              |   8 +-
 test/testmultiaudio.c                         |  16 +-
 test/testoffscreen.c                          |  22 +--
 test/testoverlay.c                            |  18 +--
 test/testpopup.c                              |  14 +-
 test/testrelative.c                           |  12 +-
 test/testrendercopyex.c                       |  14 +-
 test/testrendertarget.c                       |  14 +-
 test/testscale.c                              |  14 +-
 test/testspriteminimal.c                      |  14 +-
 test/teststreaming.c                          |  16 +-
 test/testvideocapture.c                       |  13 +-
 test/testvideocaptureminimal.c                |   5 +-
 test/testviewport.c                           |  20 +--
 test/testvulkan.c                             |   2 +-
 test/testwm.c                                 |  12 +-
 208 files changed, 1284 insertions(+), 1129 deletions(-)
 create mode 100755 build-scripts/rename_macros.py

diff --git a/VisualC-GDK/tests/testgdk/src/testgdk.cpp b/VisualC-GDK/tests/testgdk/src/testgdk.cpp
index bc4895bdce44..bddecf3c52d4 100644
--- a/VisualC-GDK/tests/testgdk/src/testgdk.cpp
+++ b/VisualC-GDK/tests/testgdk/src/testgdk.cpp
@@ -311,7 +311,7 @@ loop()
         if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
             SDL_Log("Initial SDL_EVENT_KEY_DOWN: %s", SDL_GetScancodeName(event.key.keysym.scancode));
         }
-#if defined(__XBOXONE__) || defined(__XBOXSERIES__)
+#if defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES)
         /* On Xbox, ignore the keydown event because the features aren't supported */
         if (event.type != SDL_EVENT_KEY_DOWN) {
             SDLTest_CommonEvent(state, &event, &done);
diff --git a/WhatsNew.txt b/WhatsNew.txt
index a84f59b7e1ae..2c4b517cdf5b 100644
--- a/WhatsNew.txt
+++ b/WhatsNew.txt
@@ -8,8 +8,8 @@ This is a list of major changes in SDL's version history.
 General:
 * SDL headers should now be included as `#include <SDL3/SDL.h>`
 * Many functions and symbols have changed since SDL 2.0, see the [migration guide](docs/README-migration.md) for details
-* The preprocessor symbol __MACOSX__ has been renamed __MACOS__
-* The preprocessor symbol __IPHONEOS__ has been renamed __IOS__
+* The preprocessor symbol __MACOSX__ has been renamed SDL_PLATFORM_MACOS
+* The preprocessor symbol __IPHONEOS__ has been renamed SDL_PLATFORM_IOS
 * SDL_stdinc.h no longer includes stdio.h, stdlib.h, etc., it only provides the SDL C runtime functionality
 * SDL_intrin.h now includes the intrinsics headers that were in SDL_cpuinfo.h
 * Added SDL_GetSystemTheme() to return whether the system is using a dark or light color theme, and SDL_EVENT_SYSTEM_THEME_CHANGED is sent when this changes
diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index e0b90e91e1f2..9b732532f7bc 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -2903,3 +2903,4 @@ expression e1, e2, e3, e4;
 @@
 - SDL_threadID
 + SDL_ThreadID
+  (...)
diff --git a/build-scripts/rename_headers.py b/build-scripts/rename_headers.py
index e09d8dade688..b61e47730ff4 100755
--- a/build-scripts/rename_headers.py
+++ b/build-scripts/rename_headers.py
@@ -7,17 +7,22 @@
 import re
 
 
-def main():
+def do_include_replacements(paths):
     replacements = [
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_image.h(?:[\">])"), r"<SDL3_image/SDL_image.h>" ),
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_mixer.h(?:[\">])"), r"<SDL3_mixer/SDL_mixer.h>" ),
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_net.h(?:[\">])"), r"<SDL3_net/SDL_net.h>" ),
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_rtf.h(?:[\">])"), r"<SDL3_rtf/SDL_rtf.h>" ),
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_ttf.h(?:[\">])"), r"<SDL3_ttf/SDL_ttf.h>" ),
         ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_gamecontroller.h(?:[\">])"), r"<SDL3/SDL_gamepad.h>" ),
         ( re.compile(r"(?:[\"<])(?:SDL2/)?begin_code.h(?:[\">])"), r"<SDL3/SDL_begin_code.h>" ),
         ( re.compile(r"(?:[\"<])(?:SDL2/)?close_code.h(?:[\">])"), r"<SDL3/SDL_close_code.h>" ),
         ( re.compile(r"(?:[\"<])(?:SDL2/)?(SDL[_a-z0-9]*\.h)(?:[\">])"), r"<SDL3/\1>" )
     ]
-    for entry in args.args:
+    for entry in paths:
         path = pathlib.Path(entry)
         if not path.exists():
-            print("%s doesn't exist, skipping" % entry)
+            print("{} does not exist, skipping".format(entry))
             continue
 
         replace_headers_in_path(path, replacements)
@@ -55,17 +60,16 @@ def replace_headers_in_path(path, replacements):
             replace_headers_in_file(path, replacements)
 
 
-if __name__ == "__main__":
-
-    parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
-    parser.add_argument("args", nargs="*")
+def main():
+    parser = argparse.ArgumentParser(fromfile_prefix_chars='@', description="Rename #include's for SDL3.")
+    parser.add_argument("args", metavar="PATH", nargs="*", help="Input source file")
     args = parser.parse_args()
 
     try:
-        main()
+        do_include_replacements(args.args)
     except Exception as e:
         print(e)
-        exit(-1)
-
-    exit(0)
+        return 1
 
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/build-scripts/rename_macros.py b/build-scripts/rename_macros.py
new file mode 100755
index 000000000000..66243fcd0db6
--- /dev/null
+++ b/build-scripts/rename_macros.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+#
+# This script renames SDL macros in the specified paths
+
+import argparse
+import pathlib
+import re
+
+
+class PlatformMacrosCheck:
+    RENAMED_MACROS = {
+        "__AIX__": "SDL_PLATFORM_AIX",
+        "__HAIKU__": "SDL_PLATFORM_HAIKU",
+        "__BSDI__": "SDL_PLATFORM_BSDI",
+        "__FREEBSD__": "SDL_PLATFORM_FREEBSD",
+        "__HPUX__": "SDL_PLATFORM_HPUX",
+        "__IRIX__": "SDL_PLATFORM_IRIX",
+        "__LINUX__": "SDL_PLATFORM_LINUX",
+        "__OS2__": "SDL_PLATFORM_OS2",
+        # "__ANDROID__": "SDL_PLATFORM_ANDROID,
+        "__NGAGE__": "SDL_PLATFORM_NGAGE",
+        "__APPLE__": "SDL_PLATFORM_APPLE",
+        "__TVOS__": "SDL_PLATFORM_TVOS",
+        "__IPHONEOS__": "SDL_PLATFORM_IOS",
+        "__MACOSX__": "SDL_PLATFORM_MACOS",
+        "__NETBSD__": "SDL_PLATFORM_NETBSD",
+        "__OPENBSD__": "SDL_PLATFORM_OPENBSD",
+        "__OSF__": "SDL_PLATFORM_OSF",
+        "__QNXNTO__": "SDL_PLATFORM_QNXNTO",
+        "__RISCOS__": "SDL_PLATFORM_RISCOS",
+        "__SOLARIS__": "SDL_PLATFORM_SOLARIS",
+        "__PSP__": "SDL_PLATFORM_PSP",
+        "__PS2__": "SDL_PLATFORM_PS2",
+        "__VITA__": "SDL_PLATFORM_VITA",
+        "__3DS__": "SDL_PLATFORM_3DS",
+        # "__unix__": "SDL_PLATFORM_UNIX,
+        "__WINRT__": "SDL_PLATFORM_WINRT",
+        "__XBOXSERIES__": "SDL_PLATFORM_XBOXSERIES",
+        "__XBOXONE__": "SDL_PLATFORM_XBOXONE",
+        "__WINDOWS__": "SDL_PLATFORM_WINDOWS",
+        "__WIN32__": "SDL_PLATFORM_WINRT",
+        # "__CYGWIN_": "SDL_PLATFORM_CYGWIN",
+        "__WINGDK__": "SDL_PLATFORM_WINGDK",
+        "__GDK__": "SDL_PLATFORM_GDK",
+        # "__EMSCRIPTEN__": "SDL_PLATFORM_EMSCRIPTEN",
+    }
+
+    DEPRECATED_MACROS = {
+        "__DREAMCAST__",
+        "__NACL__",
+        "__PNACL__",
+    }
+
+    def __init__(self):
+        self.re_pp_command = re.compile(r"^[ \t]*#[ \t]*(\w+).*")
+        self.re_platform_macros = re.compile(r"\W(" + "|".join(self.RENAMED_MACROS.keys()) + r")(?:\W|$)")
+        self.re_deprecated_macros = re.compile(r"\W(" + "|".join(self.DEPRECATED_MACROS) + r")(?:\W|$)")
+
+    def run(self, contents):
+        def cb(m):
+            macro = m.group(1)
+            original = m.group(0)
+            match_start, _ = m.span(0)
+            platform_start, platform_end = m.span(1)
+            new_text = "{0} /* FIXME: use '#ifdef {0}' or 'defined({0})' */".format(self.RENAMED_MACROS[macro])
+            r = original[:(platform_start-match_start)] + new_text + original[platform_end-match_start:]
+            return r
+        contents, _ = self.re_platform_macros.subn(cb, contents)
+
+        def cb(m):
+            macro = m.group(1)
+            original = m.group(0)
+            match_start, _ = m.span(0)
+            platform_start, platform_end = m.span(1)
+            new_text = "{0} /* FIXME: {0} has been removed in SDL3 */".format(macro)
+            r = original[:(platform_start-match_start)] + new_text + original[platform_end-match_start:]
+            return r
+        contents, _ = self.re_deprecated_macros.subn(cb, contents)
+        return contents
+
+
+def apply_checks(paths):
+    checks = (
+        PlatformMacrosCheck(),
+    )
+
+    for entry in paths:
+        path = pathlib.Path(entry)
+        if not path.exists():
+            print("{} does not exist, skipping".format(entry))
+            continue
+        apply_checks_in_path(path, checks)
+
+
+def apply_checks_in_file(file, checks):
+    try:
+        with file.open("r", encoding="UTF-8", newline="") as rfp:
+            original = rfp.read()
+            contents = original
+            for check in checks:
+                contents = check.run(contents)
+            if contents != original:
+                with file.open("w", encoding="UTF-8", newline="") as wfp:
+                    wfp.write(contents)
+    except UnicodeDecodeError:
+        print("%s is not text, skipping" % file)
+    except Exception as err:
+        print("%s" % err)
+
+
+def apply_checks_in_dir(path, checks):
+    for entry in path.glob("*"):
+        if entry.is_dir():
+            apply_checks_in_dir(entry, checks)
+        else:
+            print("Processing %s" % entry)
+            apply_checks_in_file(entry, checks)
+
+
+def apply_checks_in_path(path, checks):
+        if path.is_dir():
+            apply_checks_in_dir(path, checks)
+        else:
+            apply_checks_in_file(path, checks)
+
+
+def main():
+    parser = argparse.ArgumentParser(fromfile_prefix_chars='@', description="Rename macros for SDL3")
+    parser.add_argument("args", nargs="*", help="Input source files")
+    args = parser.parse_args()
+
+    try:
+        apply_checks(args.args)
+    except Exception as e:
+        print(e)
+        return 1
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/cmake/sdlchecks.cmake b/cmake/sdlchecks.cmake
index c91df3f395e2..b40464210416 100644
--- a/cmake/sdlchecks.cmake
+++ b/cmake/sdlchecks.cmake
@@ -849,7 +849,7 @@ macro(CheckPTHREAD)
         check_c_source_compiles("
             #include <pthread.h>
             int main(int argc, char **argv) {
-              #ifdef __APPLE__
+              #ifdef SDL_PLATFORM_APPLE
               pthread_setname_np(\"\");
               #else
               pthread_setname_np(pthread_self(),\"\");
diff --git a/docs/README-gdk.md b/docs/README-gdk.md
index 9a948583f275..7c447039cab8 100644
--- a/docs/README-gdk.md
+++ b/docs/README-gdk.md
@@ -21,7 +21,7 @@ Windows GDK Status
 The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.
 
 * Additionally, the GDK port adds the following:
-  * Compile-time platform detection for SDL programs. The `__GDK__` is `#define`d on every GDK platform, and the  `__WINGDK__` is `#define`d on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
+  * Compile-time platform detection for SDL programs. The `SDL_PLATFORM_GDK` is `#define`d on every GDK platform, and the  `SDL_PLATFORM_WINGDK` is `#define`d on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
   * GDK-specific setup:
     * Initializing/uninitializing the game runtime, and initializing Xbox Live services
     * Creating a global task queue and setting it as the default for the process. When running any async operations, passing in `NULL` as the task queue will make the task get added to the global task queue.
@@ -149,7 +149,7 @@ Xbox GDKX Setup
 In general, the same process in the Windows GDK instructions work. There are just a few additional notes:
 * For Xbox One consoles, use the Gaming.Xbox.XboxOne.x64 target
 * For Xbox Series consoles, use the Gaming.Xbox.Scarlett.x64 target
-* The Xbox One target sets the `__XBOXONE__` define and the Xbox Series target sets the `__XBOXSERIES__` define
+* The Xbox One target sets the `SDL_PLATFORM_XBOXONE` define and the Xbox Series target sets the `SDL_PLATFORM_XBOXSERIES` define
 * You don't need to link against the Xbox.Services Thunks lib nor include that dll in your package (it doesn't exist for Xbox)
 * The shader blobs for Xbox are created in a pre-build step for the Xbox targets, rather than included in the source (due to NDA and version compatability reasons)
 * To create a package, use:
diff --git a/docs/README-ios.md b/docs/README-ios.md
index 221cb27d68a1..ff991ad00bf7 100644
--- a/docs/README-ios.md
+++ b/docs/README-ios.md
@@ -238,7 +238,7 @@ e.g.
     {
         ... initialize game ...
 
-    #ifdef __IOS__
+    #ifdef SDL_PLATFORM_IOS
         // Initialize the Game Center for scoring and matchmaking
         InitGameCenter();
 
diff --git a/docs/README-migration.md b/docs/README-migration.md
index aaff18c24403..7cd385f0f203 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -13,11 +13,17 @@ rename_symbols.py --all-symbols source_code_path
 
 It's also possible to apply a semantic patch to migrate more easily to SDL3: [SDL_migration.cocci](https://github.com/libsdl-org/SDL/blob/main/build-scripts/SDL_migration.cocci)
 
-SDL headers should now be included as `#include <SDL3/SDL.h>`. Typically that's the only header you'll need in your application unless you are using OpenGL or Vulkan functionality. We have provided a handy Python script [rename_headers.py](https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_headers.py) to rename SDL2 headers to their SDL3 counterparts:
+SDL headers should now be included as `#include <SDL3/SDL.h>`. Typically that's the only SDL header you'll need in your application unless you are using OpenGL or Vulkan functionality. SDL_image, SDL_mixer, SDL_net, SDL_ttf and SDL_rtf have also their preferred include path changed: for SDL_image, it becomes `#include <SDL3_image/SDL_image.h>`. We have provided a handy Python script [rename_headers.py](https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_headers.py) to rename SDL2 headers to their SDL3 counterparts:
 ```sh
 rename_headers.py source_code_path

+Some macros are renamed and/or removed in SDL3. We have provided a handy Python script rename_macros.py to replace these, and also add fixme comments on how to further improve the code:
+sh +rename_macros.py source_code_path +
+
+
CMake users should use this snippet to include SDL support in their project:

find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)
@@ -932,7 +938,49 @@ The following symbols have been renamed:

## SDL_platform.h

-The preprocessor symbol `__MACOSX__` has been renamed `__MACOS__`, and `__IPHONEOS__` has been renamed `__IOS__`
+The following platform preprocessor macros have been removed:
+* __DREAMCAST__
+* __NACL__
+* __PNACL__
+
+The following platform preprocessor macros have been renamed:
+
+| SDL2              | SDL3                      |
+|-------------------|---------------------------|
+| `__3DS__`         | `SDL_PLATFORM_3DS`        |
+| `__AIX__`         | `SDL_PLATFORM_AIX`        |
+| `__ANDROID__`     | `SDL_PLATFORM_ANDROID`    |
+| `__APPLE__`       | `SDL_PLATFORM_APPLE`      |
+| `__BSDI__`        | `SDL_PLATFORM_BSDI`       |
+| `__CYGWIN_`       | `SDL_PLATFORM_CYGWIN`     |
+| `__EMSCRIPTEN__`  | `SDL_PLATFORM_EMSCRIPTEN` |
+| `__FREEBSD__`     | `SDL_PLATFORM_FREEBSD`    |
+| `__GDK__`         | `SDL_PLATFORM_GDK`        |
+| `__HAIKU__`       | `SDL_PLATFORM_HAIKU`      |
+| `__HPUX__`        | `SDL_PLATFORM_HPUX`       |
+| `__IPHONEOS__`    | `SDL_PLATFORM_IOS`        |
+| `__IRIX__`        | `SDL_PLATFORM_IRIX`       |
+| `__LINUX__`       | `SDL_PLATFORM_LINUX`      |
+| `__MACOSX__`      | `SDL_PLATFORM_MACOS`      |
+| `__NETBSD__`      | `SDL_PLATFORM_NETBSD`     |
+| `__NGAGE__`       | `SDL_PLATFORM_NGAGE`      |
+| `__OPENBSD__`     | `SDL_PLATFORM_OPENBSD`    |
+| `__OS2__`         | `SDL_PLATFORM_OS2`        |
+| `__OSF__`         | `SDL_PLATFORM_OSF`        |
+| `__PS2__`         | `SDL_PLATFORM_PS2`        |
+| `__PSP__`         | `SDL_PLATFORM_PSP`        |
+| `__QNXNTO__`      | `SDL_PLATFORM_QNXNTO`     |
+| `__RISCOS__`      | `SDL_PLATFORM_RISCOS`     |
+| `__SOLARIS__`     | `SDL_PLATFORM_SOLARIS`    |
+| `__TVOS__`        | `SDL_PLATFORM_TVOS`       |
+| `__unix__`        | `SDL_PLATFORM_UNI`        |
+| `__VITA__`        | `SDL_PLATFORM_VITA`       |
+| `__WIN32__`       | `SDL_PLATFORM_WINRT`      |
+| `__WINDOWS__`     | `SDL_PLATFORM_WINDOWS`    |
+| `__WINGDK__`      | `SDL_PLATFORM_WINGDK`     |
+| `__WINRT__`       | `SDL_PLATFORM_WINRT`      |
+| `__XBOXONE__`     | `SDL_PLATFORM_XBOXONE`    |
+| `__XBOXSERIES__`  | `SDL_PLATFORM_XBOXSERIES` |

## SDL_rect.h

@@ -1360,7 +1408,7 @@ The information previously available in SDL_GetWindowWMInfo() is now available a
    if (nswindow) {
        ...
    }
-#elif defined(__LINUX__)
+#elif defined(SDL_PLATFORM_LINUX)
    if (SDL_GetWindowWMInfo(window, &info)) {
        if (info.subsystem == SDL_SYSWM_X11) {
            Display *xdisplay = info.info.x11.display;
@@ -1380,17 +1428,17 @@ The information previously available in SDL_GetWindowWMInfo() is now available a

becomes:

-#if defined(__WIN32__)
+#if defined(SDL_PLATFORM_WIN32)
    HWND hwnd = (HWND)SDL_GetProperty(SDL_GetWindowProperties(window), SDL_PROPERTY_WINDOW_WIN32_HWND_POINTER, NULL);
    if (hwnd) {
        ...
    }
-#elif defined(__MACOS__)
+#elif defined(SDL_PLATFORM_MACOS)
    NSWindow *nswindow = (__bridge NSWindow *)SDL_GetProperty(SDL_GetWindowProperties(window), SDL_PROPERTY_WINDOW_COCOA_WINDOW_POINTER, NULL);
    if (nswindow) {
        ...
    }
-#elif defined(__LINUX__)
+#elif defined(SDL_PLATFORM_LINUX)
    if (SDL_strcmp(SDL_GetCurrentVideoDriver(), "x11") == 0) {
        Display *xdisplay = (Display *)SDL_GetProperty(SDL_GetWindowProperties(window), SDL_PROPERTY_WINDOW_X11_DISPLAY_POINTER, NULL);
        Window xwindow = (Window)SDL_GetNumberProperty(SDL_GetWindowProperties(window), SDL_PROPERTY_WINDOW_X11_WINDOW_NUMBER, 0);
diff --git a/docs/README-winrt.md b/docs/README-winrt.md
index a41b21eb6f39..6e73c93f520c 100644
--- a/docs/README-winrt.md
+++ b/docs/README-winrt.md
@@ -33,7 +33,7 @@ Here is a rough list of what works, and what doesn't:
* What works:
  * compilation via Visual C++ 2019.
  * compile-time platform detection for SDL programs.  The C/C++ #define,
-    `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
+    `SDL_PLATFORM_WINRT`, will be set to 1 (by SDL) when compiling for WinRT.
  * GPU-accelerated 2D rendering, via SDL_Renderer.
  * OpenGL ES 2, via the ANGLE library (included separately from SDL)
  * software rendering, via either SDL_Surface (optionally in conjunction with
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index e4f553e4f6b8..c2ecadbcf748 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -66,9 +66,9 @@ assert can have unique static variables associated with it.
    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
#elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv)
    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\n\t" )
-#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) )  /* this might work on other ARM targets, but this is a known quantity... */
+#elif ( defined(SDL_PLATFORM_APPLE) && (defined(__arm64__) || defined(__aarch64__)) )  /* this might work on other ARM targets, but this is a known quantity... */
    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" )
-#elif defined(__APPLE__) && defined(__arm__)
+#elif defined(SDL_PLATFORM_APPLE) && defined(__arm__)
    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
#elif defined(__386_

(Patch may be truncated, please check the link at the top of this post.)