SDL: rwops: Reworked RWops for SDL3.

From 525919b315198f9f919cc574cef7d90f5b37aba5 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 12 Mar 2024 01:14:38 -0400
Subject: [PATCH] rwops: Reworked RWops for SDL3.

- SDL_RWops is now an opaque struct.
- SDL_AllocRW is gone. If an app is creating a custom RWops, they pass the
  function pointers to SDL_CreateRW(), which are stored internally.
- SDL_RWclose is gone, there is only SDL_DestroyRW(), which calls the
  implementation's `->close` method before freeing other things.
- There is only one path to create and use RWops now, so we don't have to
  worry about whether `->close` will call SDL_DestroyRW, or if this will
  risk any Properties not being released, etc.
- SDL_RWFrom* still works as expected, for getting a RWops without having
  to supply your own implementation. Objects from these functions are also
  destroyed with SDL_DestroyRW.
- Lots of other cleanup and SDL3ization of the library code.
---
 docs/README-migration.md          |  96 ++++---
 include/SDL3/SDL_audio.h          |   2 +-
 include/SDL3/SDL_gamepad.h        |   2 +-
 include/SDL3/SDL_rwops.h          | 163 +++--------
 include/SDL3/SDL_surface.h        |   4 +-
 src/audio/SDL_wave.c              |   8 +-
 src/audio/disk/SDL_diskaudio.c    |   4 +-
 src/core/android/SDL_android.c    |  35 +--
 src/core/android/SDL_android.h    |  12 +-
 src/dynapi/SDL_dynapi.sym         |   1 -
 src/dynapi/SDL_dynapi_overrides.h |   1 -
 src/dynapi/SDL_dynapi_procs.h     |   5 +-
 src/file/SDL_rwops.c              | 446 +++++++++++++++++-------------
 src/test/SDL_test_common.c        |   4 +-
 src/video/SDL_bmp.c               |   4 +-
 test/testautomation_rwops.c       |  75 ++---
 test/testfile.c                   |  20 +-
 test/testime.c                    |   2 +-
 test/testoverlay.c                |   2 +-
 test/testresample.c               |   2 +-
 test/teststreaming.c              |   2 +-
 test/testutils.c                  |   2 +-
 22 files changed, 423 insertions(+), 469 deletions(-)

diff --git a/docs/README-migration.md b/docs/README-migration.md
index c5f279c8f9555..59e1de2e4bf5f 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -1156,7 +1156,11 @@ The following symbols have been renamed:
 * RW_SEEK_END => SDL_RW_SEEK_END
 * RW_SEEK_SET => SDL_RW_SEEK_SET
 
-SDL_RWread and SDL_RWwrite (and SDL_RWops::read, SDL_RWops::write) have a different function signature in SDL3.
+SDL_RWops is now an opaque structure. The existing APIs to create a RWops (SDL_RWFromFile, etc) still function as expected, but to make a custom RWops with app-provided function pointers, call SDL_CreateRW and provide the function pointers through there. To call into a RWops's functionality, use the standard APIs (SDL_RWread, etc) instead of calling into function pointers directly.
+
+The RWops function pointers are now in a separate structure called SDL_RWopsInteface, which is provided to SDL_CreateRW. All the functions now take a `void *` userdata argument for their first parameter instead of an SDL_RWops, since that's now an opaque structure.
+
+SDL_RWread and SDL_RWwrite (and SDL_RWopsInterface::read, SDL_RWopsInterface::write) have a different function signature in SDL3.
 
 Previously they looked more like stdio:
 
@@ -1168,19 +1172,19 @@ size_t SDL_RWwrite(SDL_RWops *context, const void *ptr, size_t size, size_t maxn
 But now they look more like POSIX:
 
 ```c
-size_t SDL_RWread(SDL_RWops *context, void *ptr, size_t size);
-size_t SDL_RWwrite(SDL_RWops *context, const void *ptr, size_t size);
+size_t SDL_RWread(void *userdata, void *ptr, size_t size);
+size_t SDL_RWwrite(void *userdata, const void *ptr, size_t size);

Code that used to look like this:
- +c
size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_RWops *stream)
{
return SDL_RWread(stream, ptr, size, nitems);
}

should be changed to:
-```
+```c
size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_RWops *stream)
{
    if (size > 0 && nitems > 0) {
@@ -1190,15 +1194,28 @@ size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_RWops *stream)
}

+SDL_RWops::type was removed and has no replacement; it wasn’t meaningful for app-provided implementations at all, and wasn’t much use for SDL’s internal implementations, either.
+
+SDL_RWopsInterface::close implementations should clean up their own userdata, but not call SDL_DestroyRW on themselves; now the contract is always that SDL_DestroyRW is called, which calls ->close and then frees the opaque object.
+
SDL_RWFromFP has been removed from the API, due to issues when the SDL library uses a different C runtime from the application.

+SDL_AllocRW(), SDL_FreeRW(), SDL_RWclose() and direct access to the ->close function pointer have been removed from the API, so there’s only one path to manage RWops lifetimes now: SDL_CreateRW() and SDL_DestroyRW().
+
+
You can implement this in your own code easily:

#include <stdio.h>

+typedef struct RWopsStdioFPData
+{
+    FILE *fp;
+    SDL_bool autoclose;
+} RWopsStdioFPData;

-static Sint64 SDLCALL stdio_seek(SDL_RWops *context, Sint64 offset, int whence)
+static Sint64 SDLCALL stdio_seek(void *userdata, Sint64 offset, int whence)
{
+    FILE *fp = ((RWopsStdioFPData *) userdata)->fp;
    int stdiowhence;

    switch (whence) {
@@ -1215,8 +1232,8 @@ static Sint64 SDLCALL stdio_seek(SDL_RWops *context, Sint64 offset, int whence)
        return SDL_SetError("Unknown value for 'whence'");
    }

-    if (fseek((FILE *)context->hidden.stdio.fp, (fseek_off_t)offset, stdiowhence) == 0) {
-        Sint64 pos = ftell((FILE *)context->hidden.stdio.fp);
+    if (fseek(fp, (fseek_off_t)offset, stdiowhence) == 0) {
+        const Sint64 pos = ftell(fp);
        if (pos < 0) {
            return SDL_SetError("Couldn't get stream offset");
        }
@@ -1225,53 +1242,62 @@ static Sint64 SDLCALL stdio_seek(SDL_RWops *context, Sint64 offset, int whence)
    return SDL_Error(SDL_EFSEEK);
}

-static size_t SDLCALL stdio_read(SDL_RWops *context, void *ptr, size_t size)
+static size_t SDLCALL stdio_read(void *userdata, void *ptr, size_t size)
{
-    size_t bytes;
-
-    bytes = fread(ptr, 1, size, (FILE *)context->hidden.stdio.fp);
-    if (bytes == 0 && ferror((FILE *)context->hidden.stdio.fp)) {
+    FILE *fp = ((RWopsStdioFPData *) userdata)->fp;
+    const size_t bytes = fread(ptr, 1, size, fp);
+    if (bytes == 0 && ferror(fp)) {
        SDL_Error(SDL_EFREAD);
    }
    return bytes;
}

-static size_t SDLCALL stdio_write(SDL_RWops *context, const void *ptr, size_t size)
+static size_t SDLCALL stdio_write(void *userdata, const void *ptr, size_t size)
{
-    size_t bytes;
-
-    bytes = fwrite(ptr, 1, size, (FILE *)context->hidden.stdio.fp);
-    if (bytes == 0 && ferror((FILE *)context->hidden.stdio.fp)) {
+    FILE *fp = ((RWopsStdioFPData *) userdata)->fp;
+    const size_t bytes = fwrite(ptr, 1, size, fp);
+    if (bytes == 0 && ferror(fp)) {
        SDL_Error(SDL_EFWRITE);
    }
    return bytes;
}

-static int SDLCALL stdio_close(SDL_RWops *context)
+static int SDLCALL stdio_close(void *userdata)
{
+    RWopsStdioData *rwopsdata = (RWopsStdioData *) userdata;
    int status = 0;
-    if (context->hidden.stdio.autoclose) {
-        if (fclose((FILE *)context->hidden.stdio.fp) != 0) {
+    if (rwopsdata->autoclose) {
+        if (fclose(rwopsdata->fp) != 0) {
            status = SDL_Error(SDL_EFWRITE);
        }
    }
-    SDL_DestroyRW(context);
    return status;
}

-SDL_RWops *SDL_RWFromFP(void *fp, SDL_bool autoclose)
+SDL_RWops *SDL_RWFromFP(FILE *fp, SDL_bool autoclose)
{
-    SDL_RWops *rwops = NULL;
-
-    rwops = SDL_CreateRW();
-    if (rwops != NULL) {
-        rwops->seek = stdio_seek;
-        rwops->read = stdio_read;
-        rwops->write = stdio_write;
-        rwops->close = stdio_close;
-        rwops->hidden.stdio.fp = fp;
-        rwops->hidden.stdio.autoclose = autoclose;
-        rwops->type = SDL_RWOPS_STDFILE;
+    SDL_RWopsInterface iface;
+    RWopsStdioFPData *rwopsdata;
+    SDL_RWops *rwops;
+
+    rwopsdata = (RWopsStdioFPData *) SDL_malloc(sizeof (*rwopsdata));
+    if (!rwopsdata) {
+        return NULL;
+    }
+
+    SDL_zero(iface);
+    /* There's no stdio_size because SDL_RWsize emulates it the same way we'd do it for stdio anyhow. */
+    iface.seek = stdio_seek;
+    iface.read = stdio_read;
+    iface.write = stdio_write;
+    iface.close = stdio_close;
+
+    rwopsdata->fp = fp;
+    rwopsdata->autoclose = autoclose;
+
+    rwops = SDL_CreateRW(&iface, rwopsdata);
+    if (!rwops) {
+        iface.close(rwopsdata);
    }
    return rwops;
}
@@ -1280,8 +1306,6 @@ SDL_RWops *SDL_RWFromFP(void *fp, SDL_bool autoclose)
The functions SDL_ReadU8(), SDL_ReadU16LE(), SDL_ReadU16BE(), SDL_ReadU32LE(), SDL_ReadU32BE(), SDL_ReadU64LE(), and SDL_ReadU64BE() now return SDL_TRUE if the read succeeded and SDL_FALSE if it didn't, and store the data in a pointer passed in as a parameter.

The following functions have been renamed:
-* SDL_AllocRW() => SDL_CreateRW()
-* SDL_FreeRW() => SDL_DestroyRW()
* SDL_ReadBE16() => SDL_ReadU16BE()
* SDL_ReadBE32() => SDL_ReadU32BE()
* SDL_ReadBE64() => SDL_ReadU64BE()
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 1dbfcb117af4b..60eb3e7dcf130 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -1317,7 +1317,7 @@ extern DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid,
 * ```
 *
 * \param src The data source for the WAVE data
- * \param freesrc If SDL_TRUE, calls SDL_RWclose() on `src` before returning,
+ * \param freesrc If SDL_TRUE, calls SDL_DestroyRW() on `src` before returning,
 *                even in the case of an error
 * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
 *             data's format details on successful return
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 4be8ee0ba3f61..68bdaa37a03f8 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -268,7 +268,7 @@ extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
 * constrained environment.
 *
 * \param src the data stream for the mappings to be added
- * \param freesrc if SDL_TRUE, calls SDL_RWclose() on `src` before returning,
+ * \param freesrc if SDL_TRUE, calls SDL_DestroyRW() on `src` before returning,
 *                even in the case of an error
 * \returns the number of mappings added or -1 on error; call SDL_GetError()
 *          for more information.
diff --git a/include/SDL3/SDL_rwops.h b/include/SDL3/SDL_rwops.h
index 37a1b806d82b1..8fef464ff9218 100644
--- a/include/SDL3/SDL_rwops.h
+++ b/include/SDL3/SDL_rwops.h
@@ -39,15 +39,8 @@
extern "C" {
#endif

-/* RWops types */
-#define SDL_RWOPS_UNKNOWN   0   /**< Unknown stream type */
-#define SDL_RWOPS_WINFILE   1   /**< Win32 file */
-#define SDL_RWOPS_STDFILE   2   /**< Stdio file */
-#define SDL_RWOPS_JNIFILE   3   /**< Android asset */
-#define SDL_RWOPS_MEMORY    4   /**< Memory stream */
-#define SDL_RWOPS_MEMORY_RO 5   /**< Read-Only memory stream */
-
/* RWops status, set by a read or write operation */
+/* !!! FIXME: make this an enum? */
#define SDL_RWOPS_STATUS_READY          0   /**< Everything is ready */
#define SDL_RWOPS_STATUS_ERROR          1   /**< Read or write I/O error */
#define SDL_RWOPS_STATUS_EOF            2   /**< End of file */
@@ -55,17 +48,14 @@ extern "C" {
#define SDL_RWOPS_STATUS_READONLY       4   /**< Tried to write a read-only buffer */
#define SDL_RWOPS_STATUS_WRITEONLY      5   /**< Tried to read a write-only buffer */

-/**
- * This is the read/write operation structure -- very basic.
- */
-typedef struct SDL_RWops
+typedef struct SDL_RWopsInterface
{
    /**
     *  Return the number of bytes in this rwops
     *
     *  \return the total size of the data stream, or -1 on error.
     */
-    Sint64 (SDLCALL *size)(struct SDL_RWops *context);
+    Sint64 (SDLCALL *size)(void *userdata);

    /**
     *  Seek to \c offset relative to \c whence, one of stdio's whence values:
@@ -73,7 +63,7 @@ typedef struct SDL_RWops
     *
     *  \return the final offset in the data stream, or -1 on error.
     */
-    Sint64 (SDLCALL *seek)(struct SDL_RWops *context, Sint64 offset, int whence);
+    Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, int whence);

    /**
     *  Read up to \c size bytes from the data stream to the area pointed
@@ -81,7 +71,7 @@ typedef struct SDL_RWops
     *
     *  \return the number of bytes read
     */
-    size_t (SDLCALL *read)(struct SDL_RWops *context, void *ptr, size_t size);
+    size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size);

    /**
     *  Write exactly \c size bytes from the area pointed at by \c ptr
@@ -89,61 +79,24 @@ typedef struct SDL_RWops
     *
     *  \return the number of bytes written
     */
-    size_t (SDLCALL *write)(struct SDL_RWops *context, const void *ptr, size_t size);
+    size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size);

    /**
-     *  Close and free an allocated SDL_RWops structure.
+     *  Close and free any allocated resources.
+     *
+     *  The RWops is still destroyed even if this fails, so clean up anything
+     *  even if flushing to disk returns an error.
     *
     *  \return 0 if successful or -1 on write error when flushing data.
     */
-    int (SDLCALL *close)(struct SDL_RWops *context);
-
-    Uint32 type;
-    Uint32 status;
-    SDL_PropertiesID props;
-    union
-    {
-#ifdef SDL_PLATFORM_ANDROID
-        struct
-        {
-            void *asset;
-        } androidio;
-
-#elif defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_WINRT)
-        struct
-        {
-            SDL_bool append;
-            void *h;
-            struct
-            {
-                void *data;
-                size_t size;
-                size_t left;
-            } buffer;
-        } windowsio;
-#endif
-
-        struct
-        {
-            SDL_bool autoclose;
-            void *fp;
-        } stdio;
-
-        struct
-        {
-            Uint8 *base;
-            Uint8 *here;
-            Uint8 *stop;
-        } mem;
+    int (SDLCALL *close)(void *userdata);
+} SDL_RWopsInterface;

-        struct
-        {
-            void *data1;
-            void *data2;
-        } unknown;
-    } hidden;

-} SDL_RWops;
+/**
+ * This is the read/write operation structure -- opaque, as of SDL3!
+ */
+typedef struct SDL_RWops SDL_RWops;


/**
@@ -195,7 +148,7 @@ typedef struct SDL_RWops
 * As a fallback, SDL_RWFromFile() will transparently open a matching filename
 * in an Android app's `assets`.
 *
- * Closing the SDL_RWops will close the file handle SDL is holding internally.
+ * Destroying the SDL_RWops will close the file handle SDL is holding internally.
 *
 * \param file a UTF-8 string representing the filename to open
 * \param mode an ASCII string representing the mode to be used for opening
@@ -205,7 +158,6 @@ typedef struct SDL_RWops
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromMem
 * \sa SDL_RWread
@@ -236,7 +188,6 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file, const char *
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -270,7 +221,6 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, size_t size);
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -284,20 +234,14 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem, size_t si


/**
- * Use this function to allocate an empty, unpopulated SDL_RWops structure.
+ * Use this function to allocate a SDL_RWops structure.
 *
 * Applications do not need to use this function unless they are providing
 * their own SDL_RWops implementation. If you just need an SDL_RWops to
 * read/write a common data source, you should use the built-in
 * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc.
 *
- * You must free the returned pointer with SDL_DestroyRW(). Depending on your
- * operating system and compiler, there may be a difference between the
- * malloc() and free() your program uses and the versions SDL calls
- * internally. Trying to mix the two can cause crashing such as segmentation
- * faults. Since all SDL_RWops must free themselves when their **close**
- * method is called, all SDL_RWops must be allocated through this function, so
- * they can all be freed correctly with SDL_DestroyRW().
+ * You must free the returned pointer with SDL_DestroyRW().
 *
 * \returns a pointer to the allocated memory on success, or NULL on failure;
 *          call SDL_GetError() for more information.
@@ -306,32 +250,33 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem, size_t si
 *
 * \sa SDL_DestroyRW
 */
-extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(void);
+extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(const SDL_RWopsInterface *iface, void *userdata);

/**
- * Use this function to free an SDL_RWops structure allocated by
- * SDL_CreateRW().
+ * Close and free an allocated SDL_RWops structure.
 *
- * Applications do not need to use this function unless they are providing
- * their own SDL_RWops implementation. If you just need an SDL_RWops to
- * read/write a common data source, you should use the built-in
- * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc, and
- * call the **close** method on those SDL_RWops pointers when you are done
- * with them.
+ * SDL_DestroyRW() closes and cleans up the SDL_RWops stream. It releases any
+ * resources used by the stream and frees the SDL_RWops itself with
+ * SDL_DestroyRW(). This returns 0 on success, or -1 if the stream failed to
+ * flush to its output (e.g. to disk).
 *
- * Only use SDL_DestroyRW() on pointers returned by SDL_CreateRW(). The
- * pointer is invalid as soon as this function returns. Any extra memory
- * allocated during creation of the SDL_RWops is not freed by SDL_DestroyRW();
- * the programmer must be responsible for managing that memory in their
- * **close** method.
+ * Note that if this fails to flush the stream to disk, this function reports
+ * an error, but the SDL_RWops is still invalid once this function returns.
 *
- * \param context the SDL_RWops structure to be freed
+ * \param context SDL_RWops structure to close
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_CreateRW
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
 */
-extern DECLSPEC void SDLCALL SDL_DestroyRW(SDL_RWops *context);
+extern DECLSPEC int SDLCALL SDL_DestroyRW(SDL_RWops *context);

/**
 * Get the properties associated with an SDL_RWops.
@@ -389,7 +334,6 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -413,7 +357,6 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, Sint64 offset, int
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -444,7 +387,6 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -482,7 +424,6 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, void *ptr, size_t
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -506,7 +447,6 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, const void *ptr,
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -529,7 +469,6 @@ extern DECLSPEC size_t SDLCALL SDL_RWprintf(SDL_RWops *context, SDL_PRINTF_FORMA
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_RWclose
 * \sa SDL_RWFromConstMem
 * \sa SDL_RWFromFile
 * \sa SDL_RWFromMem
@@ -539,32 +478,6 @@ extern DECLSPEC size_t SDLCALL SDL_RWprintf(SDL_RWops *context, SDL_PRINTF_FORMA
 */
extern DECLSPEC size_t SDLCALL SDL_RWvprintf(SDL_RWops *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);

-/**
- * Close and free an allocated SDL_RWops structure.
- *
- * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
- * resources used by the stream and frees the SDL_RWops itself with
- * SDL_DestroyRW(). This returns 0 on success, or -1 if the stream failed to
- * flush to its output (e.g. to disk).
- *
- * Note that if this fails to flush the stream to disk, this function reports
- * an error, but the SDL_RWops is still invalid once this function returns.
- *
- * \param context SDL_RWops structure to close
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_RWFromConstMem
- * \sa SDL_RWFromFile
- * \sa SDL_RWFromMem
- * \sa SDL_RWread
- * \sa SDL_RWseek
- * \sa SDL_RWwrite
- */
-extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
-
/**
 * Load all the data from an SDL data stream.
 *
@@ -576,7 +489,7 @@ extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
 *
 * \param src the SDL_RWops to read all available data from
 * \param datasize if not NULL, will store the number of bytes read
- * \param freesrc if SDL_TRUE, calls SDL_RWclose() on `src` before returning,
+ * \param freesrc if SDL_TRUE, calls SDL_DestroyRW() on `src` before returning,
 *                even in the case of an error
 * \returns the data, or NULL if there was an error.
 *
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index d42604fad69e1..63300b70c29aa 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -328,7 +328,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
 * will result in a memory leak.
 *
 * \param src the data stream for the surface
- * \param freesrc if SDL_TRUE, calls SDL_RWclose() on `src` before returning,
+ * \param freesrc if SDL_TRUE, calls SDL_DestroyRW() on `src` before returning,
 *                even in the case of an error
 * \returns a pointer to a new SDL_Surface structure or NULL if there was an
 *          error; call SDL_GetError() for more information.
@@ -370,7 +370,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP(const char *file);
 *
 * \param surface the SDL_Surface structure containing the image to be saved
 * \param dst a data stream to save to
- * \param freedst if SDL_TRUE, calls SDL_RWclose() on `dst` before returning,
+ * \param freedst if SDL_TRUE, calls SDL_DestroyRW() on `dst` before returning,
 *                even in the case of an error
 * \returns 0 on success or a negative error code on failure; call
 *          SDL_GetError() for more information.
diff --git a/src/audio/SDL_wave.c b/src/audio/SDL_wave.c
index 633783af43301..755e49b1b19d6 100644
--- a/src/audio/SDL_wave.c
+++ b/src/audio/SDL_wave.c
@@ -1629,7 +1629,7 @@ static int WaveReadFormat(WaveFile *file)
            return -1;
        }
    } else if (format->encoding == PCM_CODE) {
-        SDL_RWclose(fmtsrc);
+        SDL_DestroyRW(fmtsrc);
        return SDL_SetError("Missing wBitsPerSample field in WAVE fmt chunk");
    }

@@ -1649,7 +1649,7 @@ static int WaveReadFormat(WaveFile *file)

        /* Extensible header must be at least 22 bytes. */
        if (fmtlen < 40 || format->extsize < 22) {
-            SDL_RWclose(fmtsrc);
+            SDL_DestroyRW(fmtsrc);
            return SDL_SetError("Extensible WAVE header too small");
        }

@@ -1661,7 +1661,7 @@ static int WaveReadFormat(WaveFile *file)
        format->encoding = WaveGetFormatGUIDEncoding(format);
    }

-    SDL_RWclose(fmtsrc);
+    SDL_DestroyRW(fmtsrc);

    return 0;
}
@@ -2117,7 +2117,7 @@ int SDL_LoadWAV_RW(SDL_RWops *src, SDL_bool freesrc, SDL_AudioSpec *spec, Uint8
    SDL_free(file.decoderdata);
done:
    if (freesrc && src) {
-        SDL_RWclose(src);
+        SDL_DestroyRW(src);
    }
    return result;
}
diff --git a/src/audio/disk/SDL_diskaudio.c b/src/audio/disk/SDL_diskaudio.c
index e0fd415fa2c18..9c2e5651c0421 100644
--- a/src/audio/disk/SDL_diskaudio.c
+++ b/src/audio/disk/SDL_diskaudio.c
@@ -68,7 +68,7 @@ static int DISKAUDIO_CaptureFromDevice(SDL_AudioDevice *device, void *buffer, in
        buflen -= br;
        buffer = ((Uint8 *)buffer) + br;
        if (buflen > 0) { // EOF (or error, but whatever).
-            SDL_RWclose(h->io);
+            SDL_DestroyRW(h->io);
            h->io = NULL;
        }
    }
@@ -88,7 +88,7 @@ static void DISKAUDIO_CloseDevice(SDL_AudioDevice *device)
{
    if (device->hidden) {
        if (device->hidden->io) {
-            SDL_RWclose(device->hidden->io);
+            SDL_DestroyRW(device->hidden->io);
        }
        SDL_free(device->hidden->mixbuf);
        SDL_free(device->hidden);
diff --git a/src/core/android/SDL_android.c b/src/core/android/SDL_android.c
index dd53f687b6855..092b5d8857aa6 100644
--- a/src/core/android/SDL_android.c
+++ b/src/core/android/SDL_android.c
@@ -1956,11 +1956,12 @@ static void Internal_Android_Destroy_AssetManager()
    }
}

-int Android_JNI_FileOpen(SDL_RWops *ctx,
-                         const char *fileName, const char *mode)
+int Android_JNI_FileOpen(void **puserdata, const char *fileName, const char *mode)
{
+    SDL_assert(puserdata != NULL);
+
    AAsset *asset = NULL;
-    ctx->hidden.androidio.asset = NULL;
+    *puserdata = NULL;

    if (!asset_manager) {
        Internal_Android_Create_AssetManager();
@@ -1975,14 +1976,13 @@ int Android_JNI_FileOpen(SDL_RWops *ctx,
        return SDL_SetError("Couldn't open asset '%s'", fileName);
    }

-    ctx->hidden.androidio.asset = (void *)asset;
+    *puserdata = (void *)asset;
    return 0;
}

-size_t Android_JNI_FileRead(SDL_RWops *ctx, void *buffer, size_t size)
+size_t Android_JNI_FileRead(void *userdata, void *buffer, size_t size)
{
-    AAsset *asset = (AAsset *)ctx->hidden.androidio.asset;
-    int bytes = AAsset_read(asset, buffer, size);
+    const int bytes = AAsset_read((AAsset *)userdata, buffer, size);
    if (bytes < 0) {
        SDL_SetError("AAsset_read() failed");
        return 0;
@@ -1990,31 +1990,24 @@ size_t Android_JNI_FileRead(SDL_RWops *ctx, void *buffer, size_t size)
    return (size_t)bytes;
}

-size_t Android_JNI_FileWrite(SDL_RWops *ctx, const void *buffer, size_t size)
+size_t Android_JNI_FileWrite(void *userdata, const void *buffer, size_t size)
{
    return SDL_SetError("Cannot write to Android package filesystem");
}

-Sint64 Android_JNI_FileSize(SDL_RWops *ctx)
+Sint64 Android_JNI_FileSize(void *userdata)
{
-    off64_t result;
-    AAsset *asset = (AAsset *)ctx->hidden.androidio.asset;
-    result = AAsset_getLength64(asset);
-    return result;
+    return (Sint64) AAsset_getLength64((AAsset *)userdata);
}

-Sint64 Android_JNI_FileSeek(SDL_RWops *ctx, Sint64 offset, int whence)
+Sint64 Android_JNI_FileSeek(void *userdata, Sint64 offset, int whence)
{
-    off64_t result;
-    AAsset *asset = (AAsset *)ctx->hidden.androidio.asset;
-    result = AAsset_seek64(asset, offset, whence);
-    return result;
+    return (Sint64) AAsset_seek64((AAsset *)userdata, offset, whence);
}

-int Android_JNI_FileClose(SDL_RWops *ctx)
+int Android_JNI_FileClose(void *userdata)
{
-    AAsset *asset = (AAsset *)ctx->hidden.androidio.asset;
-    AAsset_close(asset);
+    AAsset_close((AAsset *)userdata);
    return 0;
}

diff --git a/src/core/android/SDL_android.h b/src/core/android/SDL_android.h
index c51fb4db9aca4..e86c9846d91f4 100644
--- a/src/core/android/SDL_android.h
+++ b/src/core/android/SDL_android.h
@@ -66,12 +66,12 @@ extern void Android_JNI_CloseAudioDevice(const int iscapture);
extern SDL_bool Android_IsDeXMode(void);
extern SDL_bool Android_IsChromebook(void);

-int Android_JNI_FileOpen(SDL_RWops *ctx, const char *fileName, const char *mode);
-Sint64 Android_JNI_FileSize(SDL_RWops *ctx);
-Sint64 Android_JNI_FileSeek(SDL_RWops *ctx, Sint64 offset, int whence);
-size_t Android_JNI_FileRead(SDL_RWops *ctx, void *buffer, size_t size);
-size_t Android_JNI_FileWrite(SDL_RWops *ctx, const void *buffer, size_t size);
-int Android_JNI_FileClose(SDL_RWops *ctx);
+int Android_JNI_FileOpen(void **puserdata, const char *fileName, const char *mode);
+Sint64 Android_JNI_FileSize(void *userdata);
+Sint64 Android_JNI_FileSeek(void *userdata, Sint64 offset, int whence);
+size_t Android_JNI_FileRead(void *userdata, void *buffer, size_t size);
+size_t Android_JNI_FileWrite(void *userdata, const void *buffer, size_t size);
+int Android_JNI_FileClose(void *userdata);

/* Environment support */
void Android_JNI_GetManifestEnvironmentVariables(void);
diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym
index 9e3c0f7a84af9..00c0d7abc0ced 100644
--- a/src/dynapi/SDL_dynapi.sym
+++ b/src/dynapi/SDL_dynapi.sym
@@ -469,7 +469,6 @@ SDL3_0.0.0 {
    SDL_RWFromConstMem;
    SDL_RWFromFile;
    SDL_RWFromMem;
-    SDL_RWclose;
    SDL_RWread;
    SDL_RWseek;
    SDL_RWsize;
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index 14eaed1d3d4c0..75dec01de654b 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -493,7 +493,6 @@
#define SDL_RWFromConstMem SDL_RWFromConstMem_REAL
#define SDL_RWFromFile SDL_RWFromFile_REAL
#define SDL_RWFromMem SDL_RWFromMem_REAL
-#define SDL_RWclose SDL_RWclose_REAL
#define SDL_RWread SDL_RWread_REAL
#define SDL_RWseek SDL_RWseek_REAL
#define SDL_RWsize SDL_RWsize_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index e08c5f2d2f366..8a72f8db673b1 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -142,7 +142,7 @@ SDL_DYNAPI_PROC(SDL_Mutex*,SDL_CreateMutex,(void),(),return)
SDL_DYNAPI_PROC(SDL_Palette*,SDL_CreatePalette,(int a),(a),return)
SDL_DYNAPI_PROC(SDL_PixelFormat*,SDL_CreatePixelFormat,(SDL_PixelFormatEnum a),(a),return)
SDL_DYNAPI_PROC(SDL_Window*,SDL_CreatePopupWindow,(SDL_Window *a, int b, int c, int d, int e, Uint32 f),(a,b,c,d,e,f),return)
-SDL_DYNAPI_PROC(SDL_RWops*,SDL_CreateRW,(void),(),return)
+SDL_DYNAPI_PROC(SDL_RWops*,SDL_CreateRW,(const SDL_RWopsInterface *a, void *b),(a,b),return)
SDL_DYNAPI_PROC(SDL_RWLock*,SDL_CreateRWLock,(void),(),return)
SDL_DYNAPI_PROC(SDL_Renderer*,SDL_CreateRenderer,(SDL_Window *a, const char *b, Uint32 c),(a,b,c),return)
SDL_DYNAPI_PROC(SDL_Semaphore*,SDL_CreateSemaphore,(Uint32 a),(a),return)
@@ -166,7 +166,7 @@ SDL_DYNAPI_PROC(void,SDL_DestroyCursor,(SDL_Cursor *a),(a),)
SDL_DYNAPI_PROC(void,SDL_DestroyMutex,(SDL_Mutex *a),(a),)
SDL_DYNAPI_PROC(void,SDL_DestroyPalette,(SDL_Palette *a),(a),)
SDL_DYNAPI_PROC(void,SDL_DestroyPixelF

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