From 60ed914c6656cdafa1f755ce515df7e474acb877 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Wed, 10 Jul 2024 13:19:46 -0700
Subject: [PATCH] Added notes for migrating SDL_GetRGBA()/SDL_MapRGBA() code

---
 docs/README-migration.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/docs/README-migration.md b/docs/README-migration.md
index 9c9501a26..7f2013059 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -349,13 +349,13 @@ The SDL_EVENT_WINDOW_SIZE_CHANGED event has been removed, and you can use SDL_EV
 
 The keysym field of key events has been removed to remove one level of indirection, and `sym` has been renamed `key`.
 
-Code that looked like this:
+Code that used to look like this:
 ```c
     SDL_Event event;
     SDL_Keycode key = event.key.keysym.sym;
     SDL_Keymod mod = event.key.keysym.mod;
 ```
-now looks like this:
+should be changed to:
 ```c
     SDL_Event event;
     SDL_Keycode key = event.key.key;
@@ -1098,6 +1098,24 @@ SDL_PixelFormatEnum has been renamed SDL_PixelFormat and is used instead of Uint
 
 SDL_MapRGB(), SDL_MapRGBA(), SDL_GetRGB(), and SDL_GetRGBA() take an optional palette parameter for indexed color lookups.
 
+Code that used to look like this:
+```c
+    SDL_GetRGBA(pixel, surface->format, &r, &g, &b, &a);
+```
+should be changed to:
+```c
+    SDL_GetRGBA(pixel, SDL_GetPixelFormatDetails(surface->format), SDL_GetSurfacePalette(surface), &r, &g, &b, &a);
+```
+
+Code that used to look like this:
+```c
+    pixel = SDL_MapRGBA(surface->format, r, g, b, a);
+```
+should be changed to:
+```c
+    pixel = SDL_MapSurfaceRGBA(surface, r, g, b, a);
+```
+
 SDL_GetMasksForPixelFormat() now returns the standard int error code.
 
 SDL_CalculateGammaRamp has been removed, because SDL_SetWindowGammaRamp has been removed as well due to poor support in modern operating systems (see [SDL_video.h](#sdl_videoh)).