deprecate old rawmodes for 16-bit RGB data

docs/deprecations.rst

@@ -175,6 +175,31 @@ deprecated and will be removed in Pillow 12 (2025-10-15). They were used for obt
 raw pointers to ``ImagingCore`` internals. To interact with C code, you can use
 ``Image.Image.getim()``, which returns a ``Capsule`` object.
 
+16-Bit RGB/BGR Rawmodes
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 11.0.0
+
+The following rawmodes have been deprecated and replaced with better-named rawmodes.
+Additionally, the 5 and 6 bit conversions are slightly more accurate, so there will be
+some differences in the output. The difference is only ever by 1, so you are unlikely
+to notice the difference visually.
+
+============  ==============
+Deprecated    Use instead
+============  ==============
+``RGB;15``    ``XBGR;1555``
+``RGB;16``    ``BGR;565``
+``BGR;5``     ``XRGB;1555``
+``BGR;15``    ``XRGB;1555``
+``BGR;16``    ``RGB;565``
+``RGB;4B``    ``XBGR;4``
+``RGBA;4B``   ``ABGR;4``
+``RGBA;15``   ``ABGR;1555``
+``BGRA;15``   ``ARGB;1555``
+``BGRA;15Z``  ``ARGB;1555Z``
+============  ==============
+
 Removed features
 ----------------
 

docs/releasenotes/11.0.0.rst

@@ -113,6 +113,29 @@ Specific WebP Feature Checks
 ``True`` if the WebP module is installed, until they are removed in Pillow
 12.0.0 (2025-10-15).
 
+16-Bit RGB/BGR Rawmodes
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following rawmodes have been deprecated and replaced with better-named rawmodes.
+Additionally, the 5 and 6 bit conversions are slightly more accurate, so there will be
+some differences in the output. The difference is only ever by 1, so you are unlikely
+to notice the difference visually.
+
+============  ==============
+Deprecated    Use instead
+============  ==============
+``RGB;15``    ``XBGR;1555``
+``RGB;16``    ``BGR;565``
+``BGR;5``     ``XRGB;1555``
+``BGR;15``    ``XRGB;1555``
+``BGR;16``    ``RGB;565``
+``RGB;4B``    ``XBGR;4``
+``RGBA;4B``   ``ABGR;4``
+``RGBA;15``   ``ABGR;1555``
+``BGRA;15``   ``ARGB;1555``
+``BGRA;15Z``  ``ARGB;1555Z``
+============  ==============
+
 API Changes
 ===========
 

src/PIL/Image.py

@@ -283,6 +283,20 @@ MODES = [
 # may have to modify the stride calculation in map.c too!
 _MAPMODES = ("L", "P", "RGBX", "RGBA", "CMYK", "I;16", "I;16L", "I;16B")
 
+# map of old deprecated rawmode to new replacement rawmode
+_DEPRECATED_RAWMODES = {
+    "RGB;15": "XBGR;1555",
+    "RGB;16": "BGR;565",
+    "BGR;5": "XRGB;1555",
+    "BGR;15": "XRGB;1555",
+    "BGR;16": "RGB;565",
+    "RGB;4B": "XBGR;4",
+    "RGBA;4B": "ABGR;4",
+    "RGBA;15": "ABGR;1555",
+    "BGRA;15": "ARGB;1555",
+    "BGRA;15Z": "ARGB;1555Z",
+}
+
 
 def getmodebase(mode: str) -> str:
     """
@@ -426,6 +440,13 @@ def _getdecoder(
     elif not isinstance(args, tuple):
         args = (args,)
 
+    if decoder_name == "raw" and args[0] in _DEPRECATED_RAWMODES:
+        deprecate(
+            f"rawmode {args[0]}",
+            12,
+            replacement=f"rawmode {_DEPRECATED_RAWMODES[args[0]]}",
+        )
+
     try:
         decoder = DECODERS[decoder_name]
     except KeyError:
@@ -1636,6 +1657,12 @@ class Image:
             mode = self.im.getpalettemode()
         except ValueError:
             return None  # no palette
+        if rawmode in _DEPRECATED_RAWMODES:
+            deprecate(
+                f"rawmode {rawmode}",
+                12,
+                replacement=f"rawmode {_DEPRECATED_RAWMODES[rawmode]}",
+            )
         if rawmode is None:
             rawmode = mode
         return list(self.im.getpalette(mode, rawmode))