Merge branch 'main' into fix-premul-alpha-bytewidth

Author: MyreMylar

.gitattributes

@@ -0,0 +1,12 @@
+# define files/directories that won't be exported in an sdist
+# Keep in sync with MANIFEST.in
+.circleci/ export-ignore
+.github/ export-ignore
+buildconfig/ci/ export-ignore
+buildconfig/macdependencies/ export-ignore
+buildconfig/manylinux-build/ export-ignore
+
+.editorconfig export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.pre-commit-config.yaml export-ignore

.github/workflows/build-manylinux.yml

@@ -77,7 +77,7 @@ jobs:
     - uses: actions/checkout@v4.1.6
 
     - name: Log in to the Container registry
-      uses: docker/login-action@e92390c5fb421da1463c202d546fed0ec5c39f20
+      uses: docker/login-action@0d4c9c5ea7693da7b068278f7b52bda2a190a446
       with:
         registry: ghcr.io
         username: ${{ github.actor }}

.github/workflows/build-ubuntu-sdist.yml

@@ -60,15 +60,14 @@ jobs:
       # https://github.com/orgs/community/discussions/47863
       run: |
         sudo apt-get update --fix-missing
-        sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libfreetype6-dev libportmidi-dev python3-setuptools python3-dev
+        sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libfreetype6-dev libportmidi-dev python3-dev
         pip3 install --upgrade pip
-        pip3 install sphinx"<7.2.0" numpy>=1.21.0
+        pip3 install build numpy>=1.21.0
 
     - name: Make sdist and install it
       run: |
-        python3 buildconfig/make_docs.py
-        python3 setup.py sdist
-        pip3 install dist/pygame-*.tar.gz -vv
+        python3 -m build --sdist --outdir dist .
+        pip3 install dist/pygame_ce-*.tar.gz -vv
 
     - name: Run tests
       env:

README.rst

@@ -3,7 +3,7 @@
   :target: https://pyga.me/
 
 
-|DocsStatus| 
+|DocsStatus|
 |PyPiVersion| |PyPiLicense|
 |Python3| |GithubCommits| |BlackFormatBadge|
 
@@ -47,7 +47,7 @@ locally, it'll launch the online website instead.
 
 The online documentation stays up to date with the development version
 of pygame on github.  This may be a bit newer than the version of pygame
-you are using. To upgrade to the latest full release, run 
+you are using. To upgrade to the latest full release, run
 ``pip install pygame-ce --upgrade`` in your terminal.
 
 Best of all, the examples directory has many playable small programs
@@ -101,7 +101,7 @@ Tyler, Nathaniel Pryce, Dave Wallace, John Popplewell, Michael Urman,
 Andrew Straw, Michael Hudson, Ole Martin Bjoerndalen, Herve Cauwelier,
 James Mazer, Lalo Martins, Timothy Stranex, Chad Lester, Matthias
 Spiller, Bo Jangeborg, Dmitry Borisov, Campbell Barton, Diego Essaya,
-Eyal Lotem, Regis Desgroppes, Emmanuel Hainry, Randy Kaelber
+Eyal Lotem, Regis Desgroppes, Emmanuel Hainry, Randy Kaelber,
 Matthew L Daniel, Nirav Patel, Forrest Voight, Charlie Nolan,
 Frankie Robertson, John Krukoff, Lorenz Quack, Nick Irvine,
 Michael George, Saul Spatz, Thomas Ibbotson, Tom Rothamel, Evan Kroske,
@@ -132,7 +132,7 @@ Pygame is obviously strongly dependent on SDL and Python. It also
 links to and embeds several other smaller libraries. The font
 module relies on SDL_ttf, which is dependent on freetype. The mixer
 (and mixer.music) modules depend on SDL_mixer. The image module
-depends on SDL_image. Transform.rotozoom has an embedded version 
+depends on SDL_image. Transform.rotozoom has an embedded version
 of SDL_rotozoom, and gfxdraw has an embedded version of SDL_gfx.
 Dependency versions:
 
@@ -176,12 +176,12 @@ See docs/licenses for licenses of dependencies.
 
 .. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg?v=1
 
-.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.3.0.svg
-   :target: https://github.com/pygame-community/pygame-ce/compare/2.3.0...main
+.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.4.1.svg
+   :target: https://github.com/pygame-community/pygame-ce/compare/2.4.1...main
 
 .. |DocsStatus| image:: https://img.shields.io/website?down_message=offline&label=docs&up_message=online&url=https%3A%2F%2Fpyga.me%2Fdocs%2F
    :target: https://pyga.me/docs/
-   
+
 .. |BlackFormatBadge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 

buildconfig/manylinux-build/docker_base/sdl_libs/build-sdl2-libs.sh

@@ -3,20 +3,21 @@ set -e -x
 
 cd $(dirname `readlink -f "$0"`)
 
-SDL2="SDL2-2.30.3"
-IMG2="SDL2_image-2.8.2"
-TTF2="SDL2_ttf-2.22.0"
-MIX2="SDL2_mixer-2.8.0"
+SDL2_VER="2.30.3"
+SDL2="SDL2-$SDL2_VER"
+IMG2_VER="2.8.2"
+IMG2="SDL2_image-$IMG2_VER"
+TTF2_VER="2.22.0"
+TTF2="SDL2_ttf-$TTF2_VER"
+MIX2_VER="2.8.0"
+MIX2="SDL2_mixer-$MIX2_VER"
 
 
 # Download
-curl -sL --retry 10 https://www.libsdl.org/release/${SDL2}.tar.gz > ${SDL2}.tar.gz
-# curl -sL --retry 10 https://www.libsdl.org/tmp/release/SDL2-2.0.14.tar.gz > SDL2-2.0.14.tar.gz
-# curl -sL --retry 10 https://hg.libsdl.org/SDL/archive/tip.tar.gz > ${SDL2}.tar.gz
-
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_image/release/${IMG2}.tar.gz > ${IMG2}.tar.gz
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_ttf/release/${TTF2}.tar.gz > ${TTF2}.tar.gz
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_mixer/release/${MIX2}.tar.gz > ${MIX2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL/releases/download/release-$SDL2_VER/$SDL2.tar.gz > ${SDL2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_image/releases/download/release-$IMG2_VER/$IMG2.tar.gz > ${IMG2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_mixer/releases/download/release-$MIX2_VER/$MIX2.tar.gz > ${MIX2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_ttf/releases/download/release-$TTF2_VER/$TTF2.tar.gz > ${TTF2}.tar.gz
 sha512sum -c sdl2.sha512
 
 

buildconfig/stubs/pygame/math.pyi

@@ -333,7 +333,9 @@ class Vector3(_GenericVector):
     def update(self, x: int, y: int, z: int) -> None: ...
 
 
-def lerp(a: float, b: float, weight: float, do_clamp: bool = True, /) -> float: ...
+def lerp(a: float, b: float, value: float, do_clamp: bool = True, /) -> float: ...
+def invlerp(a: float, b: float, value: float, /) -> float: ...
+def remap(i_min: float, i_max: float, o_min: float, o_max: float, value: float, /) -> float: ...
 def smoothstep(a: float, b: float, weight: float, /) -> float: ...
 
 

buildconfig/stubs/pygame/transform.pyi

@@ -65,3 +65,10 @@ def gaussian_blur(
     repeat_edge_pixels: bool = True,
     dest_surface: Optional[Surface] = None
 ) -> Surface: ...
+def hsl(
+    surface: Surface,
+    hue: float = 0,
+    saturation: float = 0,
+    lightness: float = 0,
+    dest_surface: Optional[Surface] = None,
+) -> Surface: ...

docs/__main__.py

@@ -1,7 +1,9 @@
 import platform
 
-from pygame.docs.serve import main as serve
-from pygame.docs.static import main as static
+# use relative import here and not absolute, so that `python -m docs` works at
+# development time
+from .serve import main as serve
+from .static import main as static
 
 
 def main():

docs/reST/ref/math.rst

@@ -79,6 +79,37 @@ Multiple coordinates can be set using slices or swizzling
 
    .. ## math.lerp ##
 
+.. function:: invlerp
+
+   | :sl:`returns value inverse interpolated between a and b`
+   | :sg:`invlerp(a, b, value, /) -> float`
+
+   Returns a number which is an inverse interpolation between ``a``
+   and ``b``. The third parameter ``value`` is the result of the linear interpolation
+   between a and b with a certain coefficient. In other words, this coefficient
+   will be the result of this function.
+   If ``b`` and ``a`` are equal, it raises a ``ValueError``.
+
+   The formula is:
+
+   ``(v - a)/(b - a)``.
+
+   This is an example explaining what is above :
+
+   .. code-block:: python
+
+      > a = 10
+      > b = 20
+      > pygame.math.invlerp(10, 20, 11.5)
+      > 0.15
+      > pygame.math.lerp(10, 20, 0.15)
+      > 11.5
+
+
+   .. versionadded:: 2.5.0
+
+   .. ## math.invlerp ##
+
 .. function:: smoothstep
 
    | :sl:`returns value smoothly interpolated between a and b.`
@@ -102,6 +133,28 @@ Multiple coordinates can be set using slices or swizzling
 
    .. ## math.smoothstep ##
 
+.. function:: remap
+
+   | :sl:`remaps value from given input range to given output range`
+   | :sg:`remap(i_min, i_max, o_min, o_max, value, /) -> float`
+
+   Returns a number which is the value remapped from ``[i_min, i_max]`` range to
+   ``[o_min, o_max]`` range.
+   If ``i_min`` and ``i_max`` are equal, it raises a ``ValueError``.
+
+   Example:
+
+   .. code-block:: python
+      
+      > value = 50
+      > pygame.math.remap(0, 100, 0, 200, value)
+      > 100.0
+      
+
+   .. versionadded:: 2.5.0
+
+   .. ## math.remap ##
+
 .. class:: Vector2
 
    | :sl:`a 2-Dimensional Vector`

docs/reST/ref/mixer.rst

@@ -576,6 +576,23 @@ The following file formats are supported
       `angle`: Angle is in degrees.
 
       `distance`: Range from 0 to 255.
+
+      .. warning:: This function currently fails and raises a
+         :exc:`pygame.error` when using 7.1 surround sound. 
+         By default, the mixer module will use what the hardware is best
+         suited for, so this leads to hardware specific exceptions when using
+         this function.
+
+         One way of avoiding this is only using :func:`set_source_location`
+         with forced stereo. For example:
+
+         ::
+
+            pygame.mixer.pre_init(
+               channels=2,
+               allowedchanges=pygame.AUDIO_ALLOW_FREQUENCY_CHANGE,
+            )
+            pygame.init()
       
       .. versionadded:: 2.3.0