expose low-level colorkey info

buildconfig/stubs/pygame/surface.pyi

@@ -109,7 +109,10 @@ class Surface:
     def set_colorkey(self, color: ColorValue, flags: int = 0, /) -> None: ...
     @overload
     def set_colorkey(self, color: None, /) -> None: ...
+    def set_colorkey_raw(self, color: int) -> None: ...
     def get_colorkey(self) -> Optional[RGBAOutput]: ...
+    def get_colorkey_raw(self) -> int: ...
+    def has_colorkey(self) -> bool: ...
     @overload
     def set_alpha(self, value: int, flags: int = 0, /) -> None: ...
     @overload

docs/reST/ref/surface.rst

@@ -352,7 +352,49 @@
       set then ``None`` is returned.
 
       .. ## Surface.get_colorkey ##
+
+   .. method:: set_colorkey_raw
 
+      | :sl:`Set the transparent colorkey`
+      | :sg:`set_colorkey_raw(color) -> None`
+
+      Low-level method to set the color key for the Surface.
+      The color parameter must be a be an integer that represents a valid
+      mapped color value or palette index for the surface. This is mainly
+      useful for edge cases in indexed surfaces.
+
+      Most use cases should be covered by `get_colorkey()`
+
+      .. versionadded:: 2.5.0
+
+      .. ## Surface.set_colorkey_raw ##
+
+   .. method:: get_colorkey_raw
+
+      | :sl:`Get the mapped value of the current transparent colorkey`
+      | :sg:`get_colorkey_raw() -> int`
+
+      Return the current colorkey value for the Surface. If the colorkey is not
+      set, an exception is raised.
+
+      This function is mainly of interest for low-level manipulation of
+      indexed surfaces. Most use cases should be covered by `get_colorkey()`
+
+      .. versionadded:: 2.5.0
+
+      .. ## Surface.get_colorkey_raw ##
+
+   .. method:: has_colorkey
+
+      | :sl:`Check whether the surface has a colorkey`
+      | :sg:`has_colorkey() -> bool`
+
+      If the colorkey is set, return ``True``, otherwise ``False``.
+
+      .. versionadded:: 2.5.0
+
+      .. ## Surface.has_colorkey ##
+
    .. method:: set_alpha
 
       | :sl:`set the alpha value for the full Surface image`

src_c/doc/surface_doc.h

@@ -10,6 +10,9 @@
 #define DOC_SURFACE_SCROLL "scroll(dx=0, dy=0, /) -> None\nShift the surface image in place"
 #define DOC_SURFACE_SETCOLORKEY "set_colorkey(color, flags=0, /) -> None\nset_colorkey(None) -> None\nSet the transparent colorkey"
 #define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> RGB or None\nGet the current transparent colorkey"
+#define DOC_SURFACE_SETCOLORKEYRAW "set_colorkey_raw(color) -> None\nSet the transparent colorkey"
+#define DOC_SURFACE_GETCOLORKEYRAW "get_colorkey_raw() -> int\nGet the mapped value of the current transparent colorkey"
+#define DOC_SURFACE_HASCOLORKEY "has_colorkey() -> bool\nCheck whether the surface has a colorkey"
 #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0, /) -> None\nset_alpha(None) -> None\nset the alpha value for the full Surface image"
 #define DOC_SURFACE_GETALPHA "get_alpha() -> int_value\nget the current Surface transparency value"
 #define DOC_SURFACE_LOCK "lock() -> None\nlock the Surface memory for pixel access"

src_c/surface.c

@@ -154,6 +154,12 @@ surf_set_colorkey(pgSurfaceObject *self, PyObject *args);
 static PyObject *
 surf_get_colorkey(pgSurfaceObject *self, PyObject *args);
 static PyObject *
+surf_set_colorkey_raw(pgSurfaceObject *self, PyObject *args);
+static PyObject *
+surf_get_colorkey_raw(pgSurfaceObject *self, PyObject *args);
+static PyObject *
+surf_has_colorkey(pgSurfaceObject *self, PyObject *args);
+static PyObject *
 surf_set_alpha(pgSurfaceObject *self, PyObject *args);
 static PyObject *
 surf_get_alpha(pgSurfaceObject *self, PyObject *args);
@@ -293,8 +299,14 @@ static struct PyMethodDef surface_methods[] = {
 
     {"set_colorkey", (PyCFunction)surf_set_colorkey, METH_VARARGS,
      DOC_SURFACE_SETCOLORKEY},
+    {"set_colorkey_raw", (PyCFunction)surf_set_colorkey_raw, METH_VARARGS,
+     DOC_SURFACE_SETCOLORKEYRAW},
     {"get_colorkey", (PyCFunction)surf_get_colorkey, METH_NOARGS,
      DOC_SURFACE_GETCOLORKEY},
+    {"get_colorkey_raw", (PyCFunction)surf_get_colorkey_raw, METH_NOARGS,
+     DOC_SURFACE_GETCOLORKEYRAW},
+    {"has_colorkey", (PyCFunction)surf_has_colorkey, METH_NOARGS,
+     DOC_SURFACE_HASCOLORKEY},
     {"set_alpha", (PyCFunction)surf_set_alpha, METH_VARARGS,
      DOC_SURFACE_SETALPHA},
     {"get_alpha", (PyCFunction)surf_get_alpha, METH_NOARGS,
@@ -1259,6 +1271,28 @@ surf_set_colorkey(pgSurfaceObject *self, PyObject *args)
     Py_RETURN_NONE;
 }
 
+static PyObject *
+surf_set_colorkey_raw(pgSurfaceObject *self, PyObject *args)
+{
+    SDL_Surface *surf = pgSurface_AsSurface(self);
+    Uint32 color = 0;
+    int result;
+
+    if (!PyArg_ParseTuple(args, "I", &color))
+        return NULL;
+
+    SURF_INIT_CHECK(surf)
+
+    pgSurface_Prep(self);
+    result = SDL_SetColorKey(surf, SDL_TRUE, color);
+    pgSurface_Unprep(self);
+
+    if (result == -1)
+        return RAISE(pgExc_SDLError, SDL_GetError());
+
+    Py_RETURN_NONE;
+}
+
 static PyObject *
 surf_get_colorkey(pgSurfaceObject *self, PyObject *_null)
 {
@@ -1282,6 +1316,36 @@ surf_get_colorkey(pgSurfaceObject *self, PyObject *_null)
     return Py_BuildValue("(bbbb)", r, g, b, a);
 }
 
+static PyObject *
+surf_get_colorkey_raw(pgSurfaceObject *self, PyObject *_null)
+{
+    SDL_Surface *surf = pgSurface_AsSurface(self);
+    Uint32 mapped_color;
+
+    SURF_INIT_CHECK(surf)
+
+    if (SDL_GetColorKey(surf, &mapped_color) != 0) {
+        return RAISE(pgExc_SDLError, SDL_GetError());
+    }
+
+    return PyLong_FromLong(mapped_color);
+}
+
+static PyObject *
+surf_has_colorkey(pgSurfaceObject *self, PyObject *_null)
+{
+    SDL_Surface *surf = pgSurface_AsSurface(self);
+
+    SURF_INIT_CHECK(surf)
+
+    if (SDL_HasColorKey(surf)) {
+        Py_RETURN_TRUE;
+    }
+    else {
+        Py_RETURN_FALSE;
+    }
+}
+
 static PyObject *
 surf_set_alpha(pgSurfaceObject *self, PyObject *args)
 {