SDL: README-migration.md: Fixed some RWops mistakes.

From 5440fd7d12f9e78e98aa4bc8345b2f402fc08bdb Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 14 Mar 2024 23:13:26 -0400
Subject: [PATCH] README-migration.md: Fixed some RWops mistakes.

---
 docs/README-migration.md | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/README-migration.md b/docs/README-migration.md
index 7c62e18453acd..4b950bdb87ecc 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -1157,7 +1157,7 @@ The following symbols have been renamed:
 * RW_SEEK_END => SDL_IO_SEEK_END
 * RW_SEEK_SET => SDL_IO_SEEK_SET
 
-SDL_RWops is now an opaque structure, and has been renamed to SDL_IOStream. The SDL3 APIs to create an SDL_IOStream (SDL_IOFromFile, etc) are renamed but otherwise still function as they did in SDL2. However, to make a custom SDL_IOStream with app-provided function pointers, call SDL_OpenIO and provide the function pointers through there. To call into an SDL_IOStream's functionality, use the standard APIs (SDL_ReadIO, etc), as the function pointers are concealed.
+SDL_RWops is now an opaque structure, and has been renamed to SDL_IOStream. The SDL3 APIs to create an SDL_IOStream (SDL_IOFromFile, etc) are renamed but otherwise still function as they did in SDL2. However, to make a custom SDL_IOStream with app-provided function pointers, call SDL_OpenIO and provide the function pointers through there. To call into an SDL_IOStream's functionality, use the standard APIs (SDL_ReadIO, etc), as the function pointers are internal.
 
 The RWops function pointers are now in a separate structure called SDL_IOStreamInterface, which is provided to SDL_OpenIO when creating a custom SDL_IOStream implementation. All the functions now take a `void *` userdata argument for their first parameter instead of an SDL_IOStream, since that's now an opaque structure.
 
@@ -1166,8 +1166,8 @@ SDL_RWread and SDL_RWwrite (and the read and write function pointers) have a dif
 Previously they looked more like stdio:
 
 ```c
-size_t SDL_RWread(SDL_IOStream *context, void *ptr, size_t size, size_t maxnum);
-size_t SDL_RWwrite(SDL_IOStream *context, const void *ptr, size_t size, size_t maxnum);
+size_t SDL_RWread(SDL_RWops *context, void *ptr, size_t size, size_t maxnum);
+size_t SDL_RWwrite(SDL_RWops *context, const void *ptr, size_t size, size_t maxnum);

But now they look more like POSIX:
@@ -1179,14 +1179,14 @@ size_t SDL_WriteIO(void *userdata, const void *ptr, size_t size);

Code that used to look like this:

-size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_IOStream *stream)
+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:

-size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_IOStream *stream, SDL_IOStatus *status)
+size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_IOStream *stream)
{
    if (size > 0 && nitems > 0) {
        return SDL_ReadIO(stream, ptr, size * nitems) / size;
@@ -1195,7 +1195,7 @@ size_t custom_read(void *ptr, size_t size, size_t nitems, SDL_IOStream *stream,
}

-SDL_IOStream::type was removed; it wasn’t meaningful for app-provided implementations at all, and wasn’t much use for SDL’s internal implementations, either. If you have to identify the type, you can examine the SDL_IOStream’s properties to detect built-in implementations.
+SDL_RWops::type was removed; it wasn’t meaningful for app-provided implementations at all, and wasn’t much use for SDL’s internal implementations, either. If you have to identify the type, you can examine the SDL_IOStream’s properties to detect built-in implementations.

SDL_IOStreamInterface::close implementations should clean up their own userdata, but not call SDL_CloseIO on themselves; now the contract is always that SDL_CloseIO is called, which calls ->close before freeing the opaque object.

@@ -1309,7 +1309,6 @@ The internal FILE * is available through a standard SDL_IOStream property, for
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_CloseRW() => SDL_CloseIO()

  • SDL_RWFromConstMem() => SDL_IOFromConstMem()
  • SDL_RWFromFile() => SDL_IOFromFile()
  • SDL_RWFromMem() => SDL_IOFromMem()