README-migration.md: Fixed some RWops mistakes.

This commit is contained in:
Ryan C. Gordon 2024-03-14 23:13:26 -04:00
parent 3a344cf877
commit 5440fd7d12
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 6 additions and 7 deletions

View File

@ -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:
```c
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:
```c
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()